n8n/packages/@n8n/crdt/README.md

# @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.