0
# Shared Data Types
1

2
Observable CRDT types for different collaborative editing scenarios with automatic conflict resolution. These types form the core of Yjs's collaborative functionality, enabling multiple users to edit the same data structures simultaneously without conflicts.
3

4
## Capabilities
5

6
### YArray
7

8
Shared array type that supports collaborative insertions, deletions, and modifications with automatic conflict resolution.
9

10
```typescript { .api }
11
/**
12
 * Shared array implementation that maintains order across concurrent modifications
13
 */
14
class YArray<T = any> {
15
  constructor();
16
  
17
  /** Number of items in the array */
18
  readonly length: number;
19
  
20
  /** Create YArray from existing JavaScript array */
21
  static from<T>(items: Array<T>): YArray<T>;
22
}
23
```
24

25
**Array Modification Methods:**
26

27
```typescript { .api }
28
/**
29
 * Insert items at the specified index
30
 * @param index - Position to insert at
31
 * @param content - Array of items to insert
32
 */
33
insert(index: number, content: Array<T>): void;
34

35
/**
36
 * Append items to the end of the array
37
 * @param content - Array of items to append
38
 */
39
push(content: Array<T>): void;
40

41
/**
42
 * Prepend items to the beginning of the array
43
 * @param content - Array of items to prepend
44
 */
45
unshift(content: Array<T>): void;
46

47
/**
48
 * Delete items starting at index
49
 * @param index - Starting position for deletion
50
 * @param length - Number of items to delete (default: 1)
51
 */
52
delete(index: number, length?: number): void;
53
```
54

55
**Array Access Methods:**
56

57
```typescript { .api }
58
/**
59
 * Get item at the specified index
60
 * @param index - Index of item to retrieve
61
 * @returns Item at index or undefined
62
 */
63
get(index: number): T;
64

65
/**
66
 * Convert to JavaScript Array
67
 * @returns JavaScript array with current contents
68
 */
69
toArray(): Array<T>;
70

71
/**
72
 * Get slice of array as JavaScript Array
73
 * @param start - Start index (default: 0)
74
 * @param end - End index (default: length)
75
 * @returns Slice as JavaScript array
76
 */
77
slice(start?: number, end?: number): Array<T>;
78

79
/**
80
 * Convert to JSON representation
81
 * @returns JSON array
82
 */
83
toJSON(): Array<any>;
84
```
85

86
**Array Iteration Methods:**
87

88
```typescript { .api }
89
/**
90
 * Execute function for each item in the array
91
 * @param f - Function to execute for each item
92
 */
93
forEach(f: (item: T, index: number, array: YArray<T>) => void): void;
94

95
/**
96
 * Create new array with results of calling function on every item
97
 * @param f - Function to call on each item
98
 * @returns New JavaScript array with mapped values
99
 */
100
map<M>(f: (item: T, index: number, array: YArray<T>) => M): Array<M>;
101

102
/**
103
 * Iterator support for for...of loops
104
 */
105
[Symbol.iterator](): IterableIterator<T>;
106
```
107

108
**Usage Examples:**
109

110
```typescript
111
import * as Y from "yjs";
112

113
const doc = new Y.Doc();
114
const yarray = doc.getArray<string>("fruits");
115

116
// Add items
117
yarray.push(["apple", "banana"]);
118
yarray.insert(1, ["orange"]);
119
yarray.unshift(["grape"]);
120

121
// Access items
122
console.log(yarray.get(0)); // "grape"
123
console.log(yarray.toArray()); // ["grape", "apple", "orange", "banana"]
124

125
// Iterate
126
yarray.forEach((fruit, index) => {
127
  console.log(`${index}: ${fruit}`);
128
});
129

130
// Use with for...of
131
for (const fruit of yarray) {
132
  console.log(fruit);
133
}
134

135
// Create from existing array
136
const existingFruits = ["cherry", "peach"];
137
const yarrFromExisting = Y.Array.from(existingFruits);
138
```
139

140
### YMap
141

142
Shared map/object type that supports collaborative key-value operations with automatic conflict resolution.
143

144
```typescript { .api }
145
/**
146
 * Shared map implementation for key-value storage
147
 */
148
class YMap<T = any> {
149
  constructor(entries?: Iterable<readonly [string, any]>);
150
  
151
  /** Number of key-value pairs in the map */
152
  readonly size: number;
153
}
154
```
155

156
**Map Modification Methods:**
157

158
```typescript { .api }
159
/**
160
 * Set a key-value pair in the map
161
 * @param key - Key to set
162
 * @param value - Value to associate with key
163
 * @returns The value that was set
164
 */
165
set<VAL>(key: string, value: VAL): VAL;
166

167
/**
168
 * Delete a key-value pair from the map
169
 * @param key - Key to delete
170
 */
171
delete(key: string): void;
172

173
/**
174
 * Remove all key-value pairs from the map
175
 */
176
clear(): void;
177
```
178

179
**Map Access Methods:**
180

181
```typescript { .api }
182
/**
183
 * Get value associated with key
184
 * @param key - Key to look up
185
 * @returns Value or undefined if key doesn't exist
186
 */
187
get(key: string): T | undefined;
188

189
/**
190
 * Check if key exists in the map
191
 * @param key - Key to check for
192
 * @returns True if key exists
193
 */
194
has(key: string): boolean;
195

196
/**
197
 * Convert to JSON object
198
 * @returns Plain JavaScript object
199
 */
200
toJSON(): { [key: string]: any };
201
```
202

203
**Map Iteration Methods:**
204

205
```typescript { .api }
206
/**
207
 * Get iterator over all keys
208
 * @returns Iterator of keys
209
 */
210
keys(): IterableIterator<string>;
211

212
/**
213
 * Get iterator over all values
214
 * @returns Iterator of values
215
 */
216
values(): IterableIterator<T>;
217

218
/**
219
 * Get iterator over all key-value pairs
220
 * @returns Iterator of [key, value] pairs
221
 */
222
entries(): IterableIterator<[string, T]>;
223

224
/**
225
 * Execute function for each key-value pair
226
 * @param f - Function to execute for each entry
227
 */
228
forEach(f: (value: T, key: string, map: YMap<T>) => void): void;
229

230
/**
231
 * Iterator support for for...of loops over entries
232
 */
233
[Symbol.iterator](): IterableIterator<[string, T]>;
234
```
235

236
**Usage Examples:**
237

238
```typescript
239
import * as Y from "yjs";
240

241
const doc = new Y.Doc();
242
const ymap = doc.getMap<any>("settings");
243

244
// Set values
245
ymap.set("theme", "dark");
246
ymap.set("fontSize", 14);
247
ymap.set("autoSave", true);
248

249
// Get values
250
console.log(ymap.get("theme")); // "dark"
251
console.log(ymap.has("fontSize")); // true
252

253
// Iterate over entries
254
ymap.forEach((value, key) => {
255
  console.log(`${key}: ${value}`);
256
});
257

258
// Use for...of with entries
259
for (const [key, value] of ymap) {
260
  console.log(`${key} = ${value}`);
261
}
262

263
// Create from existing entries
264
const initialSettings = [
265
  ["language", "en"],
266
  ["region", "US"]
267
] as const;
268
const ymapFromEntries = new Y.Map(initialSettings);
269
```
270

271
### YText
272

273
Rich text type with formatting support for collaborative text editing scenarios.
274

275
```typescript { .api }
276
/**
277
 * Shared text implementation with rich formatting support
278
 */
279
class YText {
280
  constructor(string?: string);
281
  
282
  /** Length of the text in characters */
283
  readonly length: number;
284
}
285
```
286

287
**Text Modification Methods:**
288

289
```typescript { .api }
290
/**
291
 * Insert text at the specified position
292
 * @param index - Position to insert at
293
 * @param text - Text to insert
294
 * @param attributes - Optional formatting attributes
295
 */
296
insert(index: number, text: string, attributes?: TextAttributes): void;
297

298
/**
299
 * Insert an embedded object at the specified position
300
 * @param index - Position to insert at
301
 * @param embed - Object or AbstractType to embed
302
 * @param attributes - Optional formatting attributes
303
 */
304
insertEmbed(index: number, embed: Object | AbstractType<any>, attributes?: TextAttributes): void;
305

306
/**
307
 * Delete text starting at index
308
 * @param index - Starting position for deletion
309
 * @param length - Number of characters to delete
310
 */
311
delete(index: number, length: number): void;
312

313
/**
314
 * Apply formatting to a range of text
315
 * @param index - Starting position
316
 * @param length - Length of range to format
317
 * @param attributes - Formatting attributes to apply
318
 */
319
format(index: number, length: number, attributes: TextAttributes): void;
320
```
321

322
**Text Attribute Methods:**
323

324
```typescript { .api }
325
/**
326
 * Remove an attribute from the entire text type
327
 * @param attributeName - Name of attribute to remove
328
 */
329
removeAttribute(attributeName: string): void;
330

331
/**
332
 * Set an attribute on the entire text type
333
 * @param attributeName - Name of attribute to set
334
 * @param attributeValue - Value to set
335
 */
336
setAttribute(attributeName: string, attributeValue: any): void;
337

338
/**
339
 * Get an attribute from the text type
340
 * @param attributeName - Name of attribute to get
341
 * @returns Attribute value or undefined
342
 */
343
getAttribute(attributeName: string): any;
344

345
/**
346
 * Get all attributes from the text type
347
 * @returns Object with all attributes
348
 */
349
getAttributes(): { [key: string]: any };
350
```
351

352
**Delta Integration Methods:**
353

354
```typescript { .api }
355
/**
356
 * Apply a Quill Delta to the text
357
 * @param delta - Delta operations to apply
358
 * @param options - Options for applying delta
359
 */
360
applyDelta(delta: Array<any>, options?: { sanitize?: boolean }): void;
361

362
/**
363
 * Convert text to Quill Delta format
364
 * @param snapshot - Optional snapshot for historical state
365
 * @param prevSnapshot - Optional previous snapshot for diff
366
 * @param computeYChange - Optional function to compute Y-specific changes
367
 * @returns Delta representation
368
 */
369
toDelta(snapshot?: Snapshot, prevSnapshot?: Snapshot, computeYChange?: Function): any;
370
```
371

372
**Text Access Methods:**
373

374
```typescript { .api }
375
/**
376
 * Get plain text content without formatting
377
 * @returns Plain text string
378
 */
379
toString(): string;
380

381
/**
382
 * Convert to JSON (returns plain text)
383
 * @returns Plain text string
384
 */
385
toJSON(): string;
386

387
/**
388
 * Create a copy of the text
389
 * @returns New YText instance with same content
390
 */
391
clone(): YText;
392
```
393

394
**Usage Examples:**
395

396
```typescript
397
import * as Y from "yjs";
398

399
const doc = new Y.Doc();
400
const ytext = doc.getText("document");
401

402
// Insert plain text
403
ytext.insert(0, "Hello World!");
404

405
// Insert with formatting
406
ytext.insert(5, " Beautiful", { bold: true, color: "blue" });
407

408
// Apply formatting to existing text
409
ytext.format(0, 5, { italic: true });
410

411
// Delete text
412
ytext.delete(5, 10); // Remove " Beautiful"
413

414
// Work with embeds
415
const imageEmbed = { type: "image", src: "photo.jpg" };
416
ytext.insertEmbed(ytext.length, imageEmbed);
417

418
// Convert to plain text
419
console.log(ytext.toString()); // "Hello World!"
420

421
// Work with Quill Delta
422
const delta = [
423
  { insert: "Hello " },
424
  { insert: "World", attributes: { bold: true } },
425
  { insert: "!\n" }
426
];
427
ytext.applyDelta(delta);
428

429
// Get as delta
430
const currentDelta = ytext.toDelta();
431
console.log(currentDelta);
432
```
433

434
## Types
435

436
```typescript { .api }
437
interface TextAttributes {
438
  [key: string]: any;
439
  bold?: boolean;
440
  italic?: boolean;
441
  underline?: boolean;
442
  color?: string;
443
  backgroundColor?: string;
444
  fontSize?: number;
445
  fontFamily?: string;
446
}
447

448
interface ArraySearchMarker {
449
  readonly p: Item;
450
  readonly index: number;
451
  readonly timestamp: number;
452
}
453
```