0
# Shared Types
1

2
CRDT-based collaborative data structures that automatically synchronize across all connected peers. These types form the core of Yjs's collaborative editing capabilities.
3

4
## Capabilities
5

6
### Array Type
7

8
Collaborative array supporting insertion, deletion, and observation of changes.
9

10
```javascript { .api }
11
/**
12
 * Shared Array interface for collaborative list operations
13
 */
14
interface SharedArray {
15
  /** Number of items in the array */
16
  length: number;
17
  
18
  /**
19
   * Add items to the end of the array
20
   * @param {any[]} items - Items to add
21
   */
22
  push(items: any[]): void;
23
  
24
  /**
25
   * Remove items from the array
26
   * @param {number} index - Starting index
27
   * @param {number} length - Number of items to remove (defaults to 1)
28
   */
29
  delete(index: number, length?: number): void;
30
  
31
  /**
32
   * Get item at specific index
33
   * @param {number} index - Array index
34
   * @returns {any} Item at index
35
   */
36
  get(index: number): any;
37
  
38
  /**
39
   * Insert items at specific position
40
   * @param {number} index - Insertion index
41
   * @param {any[]} items - Items to insert
42
   */
43
  insert(index: number, items: any[]): void;
44
  
45
  /**
46
   * Convert to regular JavaScript array
47
   * @returns {any[]} Regular array copy
48
   */
49
  toArray(): any[];
50
  
51
  /**
52
   * Listen for changes to the array
53
   * @param {function} callback - Change event handler
54
   */
55
  observe(callback: (event: ArrayEvent) => void): void;
56
}
57
```
58

59
**Usage Examples:**
60

61
```javascript
62
// Basic array operations
63
Y({
64
  db: { name: 'memory' },
65
  connector: { name: 'test', room: 'array-demo' },
66
  share: { list: 'Array' }
67
}).then(function (y) {
68
  const list = y.share.list;
69
  
70
  // Add items
71
  list.push(['item1', 'item2']);
72
  list.insert(1, ['inserted']);
73
  
74
  // Listen for changes
75
  list.observe(function(event) {
76
    if (event.type === 'insert') {
77
      console.log('Items inserted:', event.values);
78
    } else if (event.type === 'delete') {
79
      console.log('Items deleted at index:', event.index);
80
    }
81
  });
82
  
83
  // Get current state
84
  console.log('Current array:', list.toArray());
85
});
86

87
// Chat system example
88
Y({
89
  db: { name: 'indexeddb' },
90
  connector: { name: 'websockets-client', room: 'chat', url: 'ws://localhost:1234' },
91
  share: { messages: 'Array' }
92
}).then(function (y) {
93
  const messages = y.share.messages;
94
  
95
  // Add new message
96
  messages.push([{
97
    user: 'Alice',
98
    text: 'Hello everyone!',
99
    timestamp: Date.now()
100
  }]);
101
  
102
  // Display messages
103
  messages.observe(function(event) {
104
    if (event.type === 'insert') {
105
      event.values.forEach(function(message) {
106
        displayMessage(message);
107
      });
108
    }
109
  });
110
});
111
```
112

113
### Map Type
114

115
Collaborative map for key-value storage with automatic synchronization.
116

117
```javascript { .api }
118
/**
119
 * Shared Map interface for collaborative key-value operations
120
 */
121
interface SharedMap {
122
  /**
123
   * Set a key-value pair
124
   * @param {string} key - Map key
125
   * @param {any} value - Value to store
126
   */
127
  set(key: string, value: any): void;
128
  
129
  /**
130
   * Get value by key
131
   * @param {string} key - Map key
132
   * @returns {any} Value at key
133
   */
134
  get(key: string): any;
135
  
136
  /**
137
   * Delete a key-value pair
138
   * @param {string} key - Key to delete
139
   */
140
  delete(key: string): void;
141
  
142
  /**
143
   * Listen for changes to the map
144
   * @param {function} callback - Change event handler
145
   */
146
  observe(callback: (event: MapEvent) => void): void;
147
}
148
```
149

150
**Usage Examples:**
151

152
```javascript
153
// Configuration sharing
154
Y({
155
  db: { name: 'memory' },
156
  connector: { name: 'webrtc', room: 'config-sync' },
157
  share: { settings: 'Map' }
158
}).then(function (y) {
159
  const settings = y.share.settings;
160
  
161
  // Update settings
162
  settings.set('theme', 'dark');
163
  settings.set('fontSize', 14);
164
  settings.set('autoSave', true);
165
  
166
  // Listen for setting changes
167
  settings.observe(function(event) {
168
    console.log('Setting changed:', event.name, event.value);
169
    updateUI(event.name, event.value);
170
  });
171
});
172

173
// Collaborative drawing state
174
Y({
175
  db: { name: 'indexeddb' },
176
  connector: { name: 'websockets-client', room: 'drawing', url: 'ws://localhost:1234' },
177
  share: { canvas: 'Map' }
178
}).then(function (y) {
179
  const canvas = y.share.canvas;
180
  
181
  // Add drawing elements
182
  canvas.set('stroke_1', {
183
    type: 'path',
184
    points: [{x: 10, y: 20}, {x: 30, y: 40}],
185
    color: 'blue',
186
    width: 2
187
  });
188
  
189
  canvas.set('shape_1', {
190
    type: 'rectangle',
191
    x: 50, y: 50, width: 100, height: 80,
192
    fill: 'red'
193
  });
194
  
195
  // Sync drawing changes
196
  canvas.observe(function(event) {
197
    if (event.type === 'add' || event.type === 'update') {
198
      renderElement(event.name, event.value);
199
    } else if (event.type === 'delete') {
200
      removeElement(event.name);
201
    }
202
  });
203
});
204
```
205

206
### Text Type
207

208
Collaborative text editing with editor bindings for popular text editors.
209

210
```javascript { .api }
211
/**
212
 * Shared Text interface for collaborative text editing
213
 */
214
interface SharedText {
215
  /**
216
   * Bind to a DOM text element for two-way synchronization
217
   * @param {HTMLElement} element - Text input or textarea element
218
   */
219
  bind(element: HTMLElement): void;
220
  
221
  /**
222
   * Bind to Monaco Editor
223
   * @param {any} editor - Monaco editor instance
224
   */
225
  bindMonaco(editor: any): void;
226
  
227
  /**
228
   * Bind to Ace Editor
229
   * @param {any} editor - Ace editor instance
230
   */
231
  bindAce(editor: any): void;
232
  
233
  /**
234
   * Bind to CodeMirror Editor
235
   * @param {any} editor - CodeMirror editor instance
236
   */
237
  bindCodeMirror(editor: any): void;
238
  
239
  /**
240
   * Listen for text changes
241
   * @param {function} callback - Change event handler
242
   */
243
  observe(callback: (event: TextEvent) => void): void;
244
}
245
```
246

247
**Usage Examples:**
248

249
```javascript
250
// Basic text collaboration
251
Y({
252
  db: { name: 'indexeddb' },
253
  connector: { name: 'websockets-client', room: 'document', url: 'ws://localhost:1234' },
254
  share: { doc: 'Text' }
255
}).then(function (y) {
256
  const doc = y.share.doc;
257
  
258
  // Bind to textarea
259
  const textarea = document.getElementById('editor');
260
  doc.bind(textarea);
261
  
262
  // Listen for changes
263
  doc.observe(function(event) {
264
    console.log('Text changed:', event);
265
  });
266
});
267

268
// Monaco Editor integration
269
Y({
270
  db: { name: 'memory' },
271
  connector: { name: 'webrtc', room: 'code-editor' },
272
  share: { code: 'Text' }
273
}).then(function (y) {
274
  const code = y.share.code;
275
  
276
  // Initialize Monaco Editor
277
  const editor = monaco.editor.create(document.getElementById('container'), {
278
    value: '',
279
    language: 'javascript'
280
  });
281
  
282
  // Bind Yjs to Monaco
283
  code.bindMonaco(editor);
284
});
285
```
286

287
### XML Type
288

289
Collaborative DOM manipulation with two-way binding to browser DOM.
290

291
```javascript { .api }
292
/**
293
 * Shared XML interface for collaborative DOM operations
294
 */
295
interface SharedXml {
296
  /**
297
   * Listen for XML structure changes
298
   * @param {function} callback - Change event handler
299
   */
300
  observe(callback: (event: XmlEvent) => void): void;
301
}
302
```
303

304
### RichText Type
305

306
Rich text collaboration with Quill editor binding for formatted text editing.
307

308
```javascript { .api }
309
/**
310
 * Shared RichText interface for collaborative rich text editing
311
 */
312
interface SharedRichText {
313
  /**
314
   * Listen for rich text changes
315
   * @param {function} callback - Change event handler
316
   */
317
  observe(callback: (event: RichTextEvent) => void): void;
318
}
319
```
320

321
## Event Types
322

323
### Array Events
324

325
```javascript { .api }
326
interface ArrayEvent {
327
  /** Type of array operation */
328
  type: 'insert' | 'delete';
329
  /** Index where change occurred */
330
  index: number;
331
  /** Number of items affected */
332
  length: number;
333
  /** Items that were inserted (only for insert events) */
334
  values?: any[];
335
}
336
```
337

338
### Map Events
339

340
```javascript { .api }
341
interface MapEvent {
342
  /** Type of map operation */
343
  type: 'add' | 'update' | 'delete';
344
  /** Key that was changed */
345
  name: string;
346
  /** New value (for add/update events) */
347
  value?: any;
348
  /** Previous value (for update events) */
349
  oldValue?: any;
350
}
351
```
352

353
### Text Events
354

355
```javascript { .api }
356
interface TextEvent {
357
  /** Type of text operation */
358
  type: 'insert' | 'delete';
359
  /** Character index where change occurred */
360
  index: number;
361
  /** Number of characters affected */
362
  length: number;
363
  /** Text that was inserted (only for insert events) */
364
  values?: string[];
365
}
366
```
367

368
### XML Events
369

370
```javascript { .api }
371
interface XmlEvent {
372
  /** Type of XML operation */
373
  type: 'insert' | 'delete' | 'attribute';
374
  /** Path to the changed element */
375
  path: string[];
376
  /** Details of the change */
377
  details: any;
378
}
379
```
380

381
### RichText Events
382

383
```javascript { .api }
384
interface RichTextEvent {
385
  /** Type of rich text operation */
386
  type: 'insert' | 'delete' | 'format';
387
  /** Character index where change occurred */
388
  index: number;
389
  /** Number of characters affected */
390
  length: number;
391
  /** Formatting attributes */
392
  attributes?: { [key: string]: any };
393
}
394
```