Design Patterns

Proven patterns for structuring collaborative data that scales and handles concurrent edits gracefully.

Overview

These patterns emerge from real-world collaborative applications. They solve common problems like maintaining order while allowing concurrent edits, organizing complex hierarchies, and keeping data structures efficient.

Topics

ID-Based Storage - Store content by ID, reference by ID (most important pattern)
JSON vs Y.Map Tradeoffs - When to use plain JSON vs nested Y.Maps
Separate Content Maps - Splitting data by type for performance
Ordering with Arrays - Using Y.Array for element order
Style Inheritance - Prototype chains for theming and defaults

Pattern Selection Guide

Your Need	Recommended Pattern
Items that can be reordered	ID-Based Storage + Ordering Arrays
Many small entities vs complex objects	JSON vs Y.Map Tradeoffs
Hierarchical data (trees)	ID-Based Storage with parent references
Large documents with many object types	Separate Content Maps
Theming or default values	Style Inheritance
Simple key-value storage	Direct Y.Map (no special pattern needed)

The Most Important Rule

Never store complex objects in arrays that will be reordered.

This single rule prevents the most common and destructive CRDT bugs. When you need to reorder items:

Store the actual content in a Y.Map keyed by ID
Store only the IDs in a Y.Array for ordering
Reorder by moving IDs in the array, not the content

See ID-Based Storage for complete examples.