first commit

packages/@n8n/crdt/README.md

@@ -0,0 +1,155 @@
+# @n8n/crdt
+
+CRDT abstraction layer for n8n collaborative editing. Provides a unified API
+built on Yjs for real-time document synchronization.
+
+## Quick Start
+
+```typescript
+import { createCRDTProvider, CRDTEngine } from '@n8n/crdt';
+
+// Create provider
+const provider = createCRDTProvider({ engine: CRDTEngine.yjs });
+
+// Create document
+const doc = provider.createDoc('workflow-123');
+
+// Use data structures
+const nodes = doc.getMap('nodes');
+nodes.set('node-1', { position: { x: 100, y: 200 } });
+
+// Plain objects are returned as-is (no automatic CRDT wrapping)
+const node = nodes.get('node-1'); // Returns { position: { x: 100, y: 200 } }
+
+// To update nested data, replace the whole object
+nodes.set('node-1', { position: { x: 150, y: 200 } });
+
+// Observe changes
+nodes.onDeepChange((changes) => {
+    for (const change of changes) {
+        console.log(change.path, change.action, change.value);
+        // ['node-1'], 'update', { position: { x: 150, y: 200 } }
+    }
+});
+```
+
+## Plain Objects and Sync
+
+Plain objects stored in CRDT structures **do sync** across peers, but they sync as
+**atomic values** (last-write-wins), not as collaborative structures:
+
+```typescript
+// Both peers start synced
+mapA.set('node', { x: 100, y: 200 });
+// After sync: mapB.get('node') → { x: 100, y: 200 }
+
+// Concurrent edits to the same key = conflict (one wins)
+mapA.set('node', { x: 150, y: 200 });  // Peer A changes x
+mapB.set('node', { x: 100, y: 250 });  // Peer B changes y
+// After sync: both get { x: 150, y: 200 } OR { x: 100, y: 250 }
+// One write wins entirely - changes are NOT merged
+
+// For fine-grained collaborative editing, use explicit CRDT structures:
+const nodeX = doc.getMap('node-x');  // Separate CRDT map for x values
+const nodeY = doc.getMap('node-y');  // Separate CRDT map for y values
+```
+
+This "no magic" design matches raw Yjs behavior and keeps the API predictable.
+
+## Sync
+
+```typescript
+import { createSyncProvider, MockTransport } from '@n8n/crdt';
+
+// Create linked transports
+const transportA = new MockTransport();
+const transportB = new MockTransport();
+MockTransport.link(transportA, transportB);
+
+// Create sync providers
+const syncA = createSyncProvider(docA, transportA);
+const syncB = createSyncProvider(docB, transportB);
+
+// Start sync
+await syncA.start();
+await syncB.start();
+
+// Changes now propagate automatically
+```
+
+## API
+
+### Core Types
+
+- `CRDTProvider` - Factory for creating documents
+- `CRDTDoc` - Document container with `getMap()`, `getArray()`, `transact()`
+- `CRDTMap<T>` - Key-value CRDT structure with deep change observation
+- `CRDTArray<T>` - Ordered list CRDT structure
+
+### Change Events
+
+- `DeepChangeEvent` - Map changes with `path`, `action`, `value`, `oldValue`
+- `ArrayChangeEvent` - Array changes in Quill delta format (`retain`, `insert`, `delete`)
+
+### Sync
+
+- `SyncProvider` - Manages document synchronization
+- `SyncTransport` - Transport interface for moving binary data
+- `MockTransport` - In-memory transport for testing
+- `MessagePortTransport` - SharedWorker/Worker/MessageChannel communication
+- `WebSocketTransport` - Server sync with auto-reconnect
+
+## Transports
+
+All transports implement the same `SyncTransport` interface:
+
+```typescript
+interface SyncTransport {
+  send(data: Uint8Array): void;
+  onReceive(handler: (data: Uint8Array) => void): Unsubscribe;
+  connect(): Promise<void>;
+  disconnect(): void;
+  readonly connected: boolean;
+}
+```
+
+### WebSocket Transport
+
+```typescript
+import { WebSocketTransport, createSyncProvider } from '@n8n/crdt';
+
+const transport = new WebSocketTransport({
+  url: 'wss://server/sync',
+  reconnect: true,
+  reconnectDelay: 1000,
+  maxReconnectAttempts: 10,
+});
+
+transport.onConnectionChange((connected) => {
+  console.log('Connection state:', connected);
+});
+
+const sync = createSyncProvider(doc, transport);
+await sync.start();
+```
+
+### MessagePort Transport (SharedWorker)
+
+```typescript
+import { MessagePortTransport, createSyncProvider } from '@n8n/crdt';
+
+// In main thread
+const worker = new SharedWorker('worker.js');
+const transport = new MessagePortTransport(worker.port);
+const sync = createSyncProvider(doc, transport);
+await sync.start();
+```
+
+## Not Yet Implemented
+
+The following CRDT types are not yet part of this abstraction:
+
+- **Text** - For collaborative text editing (rich text, code editors)
+- **Counter** - For conflict-free increment/decrement operations
+
+These can be added in future phases if needed.