0
# Yjs
1
2
Yjs is a Conflict-free Replicated Data Type (CRDT) framework that enables real-time collaborative editing without conflicts. It provides shared data types that multiple users can edit simultaneously, with automatic synchronization and conflict resolution. Yjs is network-agnostic and supports peer-to-peer synchronization, offline editing, undo/redo functionality, and efficient binary serialization.
3
4
## Package Information
5
6
- **Package Name**: yjs
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install yjs`
10
11
## Core Imports
12
13
```typescript
14
import * as Y from "yjs";
15
```
16
17
For individual imports:
18
19
```typescript
20
import { Doc, Array as YArray, Map as YMap, Text as YText } from "yjs";
21
```
22
23
CommonJS:
24
25
```javascript
26
const Y = require("yjs");
27
const { Doc, Array: YArray, Map: YMap, Text: YText } = require("yjs");
28
```
29
30
## Basic Usage
31
32
```typescript
33
import * as Y from "yjs";
34
35
// Create a new document
36
const doc = new Y.Doc();
37
38
// Get shared types
39
const yarray = doc.getArray("my-array");
40
const ymap = doc.getMap("my-map");
41
const ytext = doc.getText("my-text");
42
43
// Use shared types
44
yarray.push(["hello", "world"]);
45
ymap.set("key", "value");
46
ytext.insert(0, "Hello collaborative world!");
47
48
// Observe changes
49
yarray.observe((event) => {
50
console.log("Array changed:", event.changes);
51
});
52
53
// Create updates for synchronization
54
const update = Y.encodeStateAsUpdate(doc);
55
56
// Apply updates from other clients
57
const otherDoc = new Y.Doc();
58
Y.applyUpdate(otherDoc, update);
59
```
60
61
## Architecture
62
63
Yjs is built around several key components:
64
65
- **Document (Doc)**: Central container managing shared types and synchronization state
66
- **Shared Data Types**: Observable CRDT types (YArray, YMap, YText, YXmlElement) for collaborative editing
67
- **Transaction System**: Atomic change batching for consistent updates and event handling
68
- **Position System**: Relative positions that survive concurrent edits and structural changes
69
- **Update System**: Binary serialization and merging for efficient network synchronization
70
- **Snapshot System**: Time-travel functionality for document state at specific points
71
- **Undo/Redo System**: Multi-level undo/redo with scope management and origin tracking
72
73
## Capabilities
74
75
### Document Management
76
77
Core document functionality for creating, managing, and synchronizing collaborative documents.
78
79
```typescript { .api }
80
class Doc {
81
constructor(options?: DocOpts);
82
readonly clientID: number;
83
readonly guid: string;
84
readonly isLoaded: boolean;
85
readonly isSynced: boolean;
86
readonly isDestroyed: boolean;
87
readonly whenLoaded: Promise<Doc>;
88
readonly whenSynced: Promise<void>;
89
readonly subdocs: Set<Doc>;
90
get<Type>(name: string, TypeConstructor?: Type): InstanceType<Type>;
91
getArray<T>(name?: string): YArray<T>;
92
getText(name?: string): YText;
93
getMap<T>(name?: string): YMap<T>;
94
getXmlElement(name?: string): YXmlElement;
95
getXmlFragment(name?: string): YXmlFragment;
96
transact<T>(f: (transaction: Transaction) => T, origin?: any): T;
97
load(): void;
98
getSubdocs(): Set<Doc>;
99
getSubdocGuids(): Set<string>;
100
destroy(): void;
101
toJSON(): any;
102
}
103
104
interface DocOpts {
105
clientID?: number;
106
guid?: string;
107
collectionid?: string | null;
108
gc?: boolean;
109
gcFilter?: (item: Item) => boolean;
110
meta?: any;
111
autoLoad?: boolean;
112
shouldLoad?: boolean;
113
}
114
```
115
116
[Document Management](./document-management.md)
117
118
### Shared Data Types
119
120
Observable CRDT types for different collaborative editing scenarios with automatic conflict resolution.
121
122
```typescript { .api }
123
class YArray<T> {
124
constructor();
125
static from<T>(items: Array<T>): YArray<T>;
126
readonly length: number;
127
insert(index: number, content: Array<T>): void;
128
push(content: Array<T>): void;
129
unshift(content: Array<T>): void;
130
delete(index: number, length?: number): void;
131
get(index: number): T;
132
toArray(): Array<T>;
133
}
134
135
class YMap<T> {
136
constructor(entries?: Iterable<readonly [string, any]>);
137
readonly size: number;
138
set<VAL>(key: string, value: VAL): VAL;
139
get(key: string): T | undefined;
140
has(key: string): boolean;
141
delete(key: string): void;
142
clear(): void;
143
}
144
145
class YText {
146
constructor(string?: string);
147
readonly length: number;
148
insert(index: number, text: string, attributes?: TextAttributes): void;
149
insertEmbed(index: number, embed: Object | AbstractType<any>, attributes?: TextAttributes): void;
150
delete(index: number, length: number): void;
151
format(index: number, length: number, attributes: TextAttributes): void;
152
removeAttribute(attributeName: string): void;
153
setAttribute(attributeName: string, attributeValue: any): void;
154
getAttribute(attributeName: string): any;
155
getAttributes(): {[key: string]: any};
156
toString(): string;
157
}
158
```
159
160
[Shared Data Types](./shared-data-types.md)
161
162
### XML Types
163
164
XML-aware collaborative types for structured document editing with DOM integration.
165
166
```typescript { .api }
167
class YXmlElement<KV = { [key: string]: any }> {
168
constructor(nodeName?: string);
169
readonly nodeName: string;
170
setAttribute<KEY>(attributeName: KEY, attributeValue: KV[KEY]): void;
171
getAttribute<KEY>(attributeName: KEY): KV[KEY] | undefined;
172
hasAttribute(attributeName: string): boolean;
173
toDOM(document?: Document): Element;
174
}
175
176
class YXmlFragment {
177
constructor();
178
readonly length: number;
179
insert(index: number, content: Array<YXmlElement | YXmlText>): void;
180
insertAfter(ref: null | Item | YXmlElement | YXmlText, content: Array<YXmlElement | YXmlText>): void;
181
querySelector(query: string): YXmlElement | YXmlText | YXmlHook | null;
182
querySelectorAll(query: string): Array<YXmlElement | YXmlText | YXmlHook>;
183
createTreeWalker(filter?: (node: AbstractType<any>) => boolean): YXmlTreeWalker;
184
}
185
```
186
187
[XML Types](./xml-types.md)
188
189
### Transaction System
190
191
Atomic change batching for consistent updates and coordinated event handling.
192
193
```typescript { .api }
194
class Transaction {
195
readonly doc: Doc;
196
readonly origin: any;
197
readonly local: boolean;
198
readonly beforeState: Map<number, number>;
199
readonly afterState: Map<number, number>;
200
}
201
202
function transact<T>(doc: Doc, f: (transaction: Transaction) => T, origin?: any): T;
203
```
204
205
[Transaction System](./transaction-system.md)
206
207
### Event System
208
209
Comprehensive event handling for observing changes to shared types with detailed change information.
210
211
```typescript { .api }
212
abstract class YEvent<T> {
213
readonly target: T;
214
readonly transaction: Transaction;
215
readonly path: Array<string | number>;
216
readonly changes: {
217
added: Set<Item>;
218
deleted: Set<Item>;
219
keys: Map<string, any>;
220
delta: Array<any>;
221
};
222
}
223
224
interface AbstractType<EventType> {
225
observe(f: (event: EventType, transaction: Transaction) => void): void;
226
unobserve(f: (event: EventType, transaction: Transaction) => void): void;
227
observeDeep(f: (events: Array<YEvent<any>>, transaction: Transaction) => void): void;
228
}
229
```
230
231
[Event System](./event-system.md)
232
233
### Position Tracking
234
235
Position system that maintains references across concurrent edits and structural changes.
236
237
```typescript { .api }
238
class RelativePosition {
239
readonly type: ID | null;
240
readonly tname: string | null;
241
readonly item: ID | null;
242
readonly assoc: number;
243
}
244
245
class AbsolutePosition {
246
readonly type: AbstractType<any>;
247
readonly index: number;
248
readonly assoc: number;
249
}
250
251
function createRelativePositionFromTypeIndex(
252
type: AbstractType<any>,
253
index: number,
254
assoc?: number
255
): RelativePosition;
256
257
function createAbsolutePositionFromRelativePosition(
258
rpos: RelativePosition,
259
doc: Doc
260
): AbsolutePosition | null;
261
262
function createRelativePositionFromJSON(json: any): RelativePosition;
263
function encodeRelativePosition(rpos: RelativePosition): Uint8Array;
264
function decodeRelativePosition(encoded: Uint8Array): RelativePosition;
265
function relativePositionToJSON(rpos: RelativePosition): any;
266
function compareRelativePositions(a: RelativePosition, b: RelativePosition): number;
267
```
268
269
[Position Tracking](./position-tracking.md)
270
271
### Synchronization
272
273
Binary update system for efficient network synchronization and state management.
274
275
```typescript { .api }
276
function encodeStateAsUpdate(doc: Doc, encodedTargetStateVector?: Uint8Array): Uint8Array;
277
function encodeStateAsUpdateV2(doc: Doc, encodedTargetStateVector?: Uint8Array): Uint8Array;
278
function applyUpdate(doc: Doc, update: Uint8Array, transactionOrigin?: any): void;
279
function applyUpdateV2(doc: Doc, update: Uint8Array, transactionOrigin?: any): void;
280
function mergeUpdates(updates: Array<Uint8Array>): Uint8Array;
281
function mergeUpdatesV2(updates: Array<Uint8Array>): Uint8Array;
282
function readUpdate(decoder: UpdateDecoder, doc: Doc, transactionOrigin?: any): void;
283
function readUpdateV2(decoder: UpdateDecoder, doc: Doc, transactionOrigin?: any): void;
284
function encodeStateVector(doc: Doc): Uint8Array;
285
function decodeStateVector(stateVector: Uint8Array): Map<number, number>;
286
function parseUpdateMeta(update: Uint8Array): { from: Map<number, number>; to: Map<number, number> };
287
function parseUpdateMetaV2(update: Uint8Array): { from: Map<number, number>; to: Map<number, number> };
288
function encodeStateVectorFromUpdate(update: Uint8Array): Uint8Array;
289
function encodeStateVectorFromUpdateV2(update: Uint8Array): Uint8Array;
290
function diffUpdate(update: Uint8Array, stateVector: Uint8Array): Uint8Array;
291
function diffUpdateV2(update: Uint8Array, stateVector: Uint8Array): Uint8Array;
292
function convertUpdateFormatV1ToV2(update: Uint8Array): Uint8Array;
293
function convertUpdateFormatV2ToV1(update: Uint8Array): Uint8Array;
294
function logUpdate(update: Uint8Array): void;
295
function logUpdateV2(update: Uint8Array): void;
296
```
297
298
[Synchronization](./synchronization.md)
299
300
### Snapshot System
301
302
Time-travel functionality for document state at specific points with diff capabilities.
303
304
```typescript { .api }
305
class Snapshot {
306
readonly ds: DeleteSet;
307
readonly sv: Map<number, number>;
308
}
309
310
function snapshot(doc: Doc): Snapshot;
311
function createSnapshot(doc: Doc): Snapshot;
312
function createDocFromSnapshot(originDoc: Doc, snapshot: Snapshot, newDoc?: Doc): Doc;
313
function equalSnapshots(snap1: Snapshot, snap2: Snapshot): boolean;
314
function encodeSnapshot(snapshot: Snapshot): Uint8Array;
315
function decodeSnapshot(encoded: Uint8Array): Snapshot;
316
function encodeSnapshotV2(snapshot: Snapshot): Uint8Array;
317
function decodeSnapshotV2(encoded: Uint8Array): Snapshot;
318
function snapshotContainsUpdate(snapshot: Snapshot, update: Uint8Array): boolean;
319
```
320
321
[Snapshot System](./snapshot-system.md)
322
323
### Undo/Redo System
324
325
Multi-level undo/redo functionality with scope management and origin tracking.
326
327
```typescript { .api }
328
class UndoManager {
329
constructor(
330
typeScope: Doc | AbstractType<any> | Array<AbstractType<any>>,
331
options?: UndoManagerOptions
332
);
333
readonly undoStack: Array<StackItem>;
334
readonly redoStack: Array<StackItem>;
335
undo(): StackItem | null;
336
redo(): StackItem | null;
337
canUndo(): boolean;
338
canRedo(): boolean;
339
clear(clearUndoStack?: boolean, clearRedoStack?: boolean): void;
340
}
341
342
interface UndoManagerOptions {
343
captureTimeout?: number;
344
captureTransaction?: (transaction: Transaction) => boolean;
345
deleteFilter?: (item: Item) => boolean;
346
trackedOrigins?: Set<any>;
347
}
348
```
349
350
[Undo/Redo System](./undo-redo-system.md)
351
352
### Utility Functions
353
354
Essential utility functions for working with Yjs internals and advanced operations.
355
356
```typescript { .api }
357
// Item and structure utilities
358
function getItem(store: StructStore, id: ID): Item;
359
function getItemCleanStart(transaction: Transaction, id: ID): Item;
360
function getItemCleanEnd(transaction: Transaction, id: ID): Item;
361
function isDeleted(deleteSet: DeleteSet, id: ID): boolean;
362
function isParentOf(parent: AbstractType<any>, child: Item): boolean;
363
364
// ID utilities
365
function createID(client: number, clock: number): ID;
366
function compareIDs(a: ID | null, b: ID | null): boolean;
367
function getState(store: StructStore, client: number): number;
368
369
// Delete set utilities
370
function createDeleteSet(): DeleteSet;
371
function createDeleteSetFromStructStore(store: StructStore): DeleteSet;
372
function equalDeleteSets(ds1: DeleteSet, ds2: DeleteSet): boolean;
373
function mergeDeleteSets(deleteSets: Array<DeleteSet>): DeleteSet;
374
375
// Advanced operations
376
function transact<T>(doc: Doc, f: (transaction: Transaction) => T, origin?: any): T;
377
function tryGc(deleteSet: DeleteSet, store: StructStore, gcFilter: Function): void;
378
function cleanupYTextFormatting(type: YText): number;
379
function findRootTypeKey(type: AbstractType<any>): string;
380
function getTypeChildren(type: AbstractType<any>): Array<AbstractType<any>>;
381
```
382
383
## Types
384
385
```typescript { .api }
386
interface ID {
387
readonly client: number;
388
readonly clock: number;
389
}
390
391
interface DeleteSet {
392
readonly clients: Map<number, Array<DeleteItem>>;
393
}
394
395
interface TextAttributes {
396
[key: string]: any;
397
}
398
399
interface UpdateDecoder {
400
readUint8(): number;
401
readUint32(): number;
402
readVarUint(): number;
403
readVarString(): string;
404
}
405
406
interface UpdateEncoder {
407
writeUint8(value: number): void;
408
writeUint32(value: number): void;
409
writeVarUint(value: number): void;
410
writeVarString(value: string): void;
411
toUint8Array(): Uint8Array;
412
}
413
414
interface DeleteItem {
415
clock: number;
416
len: number;
417
}
418
419
interface StructStore {
420
clients: Map<number, Array<AbstractStruct>>;
421
pendingStructs: null | { missing: Map<number, number>; update: Uint8Array };
422
}
423
424
interface Item {
425
readonly id: ID;
426
readonly left: Item | null;
427
readonly right: Item | null;
428
readonly origin: ID | null;
429
readonly rightOrigin: ID | null;
430
readonly parent: AbstractType<any> | ID | null;
431
readonly parentSub: string | null;
432
readonly content: AbstractContent;
433
}
434
435
// Abstract base classes
436
abstract class AbstractType<EventType> {
437
observe(f: (event: EventType, transaction: Transaction) => void): void;
438
unobserve(f: (event: EventType, transaction: Transaction) => void): void;
439
observeDeep(f: (events: Array<YEvent<any>>, transaction: Transaction) => void): void;
440
clone(): AbstractType<EventType>;
441
toJSON(): any;
442
}
443
444
abstract class AbstractStruct {
445
readonly id: ID;
446
readonly length: number;
447
}
448
449
class YXmlTreeWalker {
450
filter: (node: AbstractType<any>) => boolean;
451
nextNode(): AbstractType<any> | null;
452
}
453
```