Yjs

https://docs.yjs.dev
Admin
Yjs is a high-performance CRDT library for building collaborative applications that automatically...
Tokens:23,021
Snippets:266
Trust Score:9
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Provider Packages

Source: https://docs.yjs.dev/getting-started/a-collaborative-editor.md

Commands to install the necessary provider packages via npm.

```bash
npm i y-webrtc # or
npm i y-websocket # or
npm i y-dat
```

--------------------------------

### Install Yjs and Quill Binding

Source: https://docs.yjs.dev/getting-started/a-collaborative-editor.md

Install the necessary Yjs packages for editor synchronization.

```bash
npm i yjs y-quill
```

--------------------------------

### Install Monaco and Yjs dependencies

Source: https://docs.yjs.dev/ecosystem/editor-bindings/monaco.md

Install the necessary packages to enable collaborative editing in Monaco.

```bash
npm i monaco-editor yjs y-monaco
```

--------------------------------

### Initialize Quill Editor

Source: https://docs.yjs.dev/getting-started/a-collaborative-editor.md

Setup the Quill editor instance with required modules and configuration.

```javascript
import Quill from 'quill'
import QuillCursors from 'quill-cursors'

Quill.register('modules/cursors', QuillCursors);

const quill = new Quill(document.querySelector('#editor'), {
  modules: {
    cursors: true,
    toolbar: [
      // adding some basic Quill content features
      [{ header: [1, 2, false] }],
      ['bold', 'italic', 'underline'],
      ['image', 'code-block']
    ],
    history: {
      // Local undo shouldn't undo changes
      // from remote users
      userOnly: true
    }
  },
  placeholder: 'Start collaborating...',
  theme: 'snow' // 'bubble' is also great
})
```

```markup
<link href="https://cdn.quilljs.com/1.3.6/quill.snow.css" rel="stylesheet">

<div id="editor" />
```

```bash
npm i quill quill-cursors
```

--------------------------------

### Initialize Yjs Providers

Source: https://docs.yjs.dev/getting-started/a-collaborative-editor.md

Examples of initializing different communication providers to sync Yjs documents.

```javascript
import { WebrtcProvider } from 'y-webrtc'

const provider = new WebrtcProvider('quill-demo-room', ydoc)
```

```javascript
import { WebsocketProvider } from 'y-websocket'

// connect to the public demo server (not in production!)
const provider = new WebsocketProvider(
  'wss://demos.yjs.dev/ws', 'quill-demo-room', ydoc
)
```

```javascript
import { DatProvider } from 'y-dat'

// set null in order to create a fresh
const datKey = '7b0d584fcdaf1de2e8c473393a31f52327793931e03b330f7393025146dc02fb'
const provider = new DatProvider(datKey, ydoc)
```

--------------------------------

### Initialize WebsocketProvider

Source: https://docs.yjs.dev/ecosystem/connection-provider/y-websocket.md

Basic setup for connecting a Yjs document to a WebSocket server.

```javascript
import * as Y from 'yjs'
import { WebsocketProvider } from 'y-websocket'

const doc = new Y.Doc()
const wsProvider = new WebsocketProvider('ws://localhost:1234', 'my-roomname', doc)

wsProvider.on('status', event => {
  console.log(event.status) // logs "connected" or "disconnected"
})
```

```bash
npm i y-websocket
```

--------------------------------

### Start a y-websocket server with LevelDB persistence

Source: https://docs.yjs.dev/ecosystem/connection-provider/y-websocket.md

Persist document updates to a local directory using LevelDB.

```bash
PORT=1234 YPERSISTENCE=./dbDir node ./node_modules/y-websocket/bin/server.js
```

--------------------------------

### Install y-indexeddb

Source: https://docs.yjs.dev/ecosystem/database-provider/y-indexeddb.md

Install the package via npm to begin using the IndexedDB persistence provider.

```bash
npm i --save y-indexeddb
```

--------------------------------

### Query documentation via HTTP GET

Source: https://docs.yjs.dev/llms.txt

Perform an HTTP GET request to the documentation index to retrieve answers based on a specific question and optional end goal.

```http
GET https://docs.yjs.dev/api/shared-types/y.text.md?ask=<question>&goal=<end_goal>
```

--------------------------------

### Start a y-websocket server with HTTP callback

Source: https://docs.yjs.dev/ecosystem/connection-provider/y-websocket.md

Configure the server to send debounced HTTP POST callbacks when document updates occur.

```bash
CALLBACK_URL=http://localhost:3000/ CALLBACK_OBJECTS='{"prosemirror":"XmlFragment"}' npm start
```

--------------------------------

### Base64 Encoding and Installation

Source: https://docs.yjs.dev/api/document-updates.md

Use the js-base64 library to convert binary Uint8Array updates to strings and back. Requires the js-base64 package.

```javascript
import { fromUint8Array, toUint8Array } from 'js-base64'

const documentState = Y.encodeStateAsUpdate(ydoc) // is a Uint8Array
// Transform Uint8Array to a Base64-String
const base64Encoded = fromUint8Array(documentState)
// Transform Base64-String back to an Uint8Array
const binaryEncoded = toUint8Array(base64Encoded)
```

```bash
npm install js-base64
```

--------------------------------

### Start a y-websocket server

Source: https://docs.yjs.dev/ecosystem/connection-provider/y-websocket.md

Run the y-websocket server using npx, which defaults to port 1234.

```bash
HOST=localhost PORT=1234 npx y-websocket
```

--------------------------------

### Initialize and use Y.UndoManager

Source: https://docs.yjs.dev/api/undo-manager.md

Basic setup for tracking changes on a shared text type and performing undo/redo operations.

```javascript
import * as Y from 'yjs'

const ytext = doc.getText('text')
const undoManager = new Y.UndoManager(ytext)

ytext.insert(0, 'abc')
undoManager.undo()
ytext.toString() // => ''
undoManager.redo()
ytext.toString() // => 'abc'
```

--------------------------------

### Duplicate subdocuments using GUIDs

Source: https://docs.yjs.dev/api/subdocuments.md

Sync multiple document instances by assigning them the same GUID.

```javascript
const rootDoc = new Y.Doc()

const doc = new Y.Doc()
doc.guid // => "123e4567-e89b-12d3-a456-426614174000" - A random UUIDv4

rootDoc.getMap().set('file.txt', doc)

// we can include a copy of a subdocument by giving it the same UUIDv4
const copy = new Y.Doc({ guid: doc.guid })
rootDoc.getMap().set('copy.txt', copy)

// `doc` and `copy` will automatically sync because they have the same guid
```

--------------------------------

### Observe Changes with Y.TextEvent

Source: https://docs.yjs.dev/api/shared-types/y.text.md

Example of registering an observer to track changes in a shared type, including handling additions, updates, and deletions.

```javascript
yarray.observe(yarrayEvent => {
  yarrayEvent.target === yarray // => true

  // Find out what changed: 
  // Option 1: A set of keys that changed
ymapEvent.keysChanged // => Set<strings>
  // Option 2: Compute the differences
ymapEvent.changes.keys // => Map<string, { action: 'add'|'update'|'delete', oldValue: any}>
  
  // sample code.
  yarrayEvent.changes.keys.forEach((change, key) => {
    if (change.action === 'add') {
      console.log(`Property "${key}" was added. Initial value: "${ymap.get(key)}".`)
    } else if (change.action === 'update') {
      console.log(`Property "${key}" was updated. New value: "${ymap.get(key)}". Previous value: "${change.oldValue}".`)
    } else if (change.action === 'delete') {
      console.log(`Property "${key}" was deleted. New value: undefined. Previous value: "${change.oldValue}".`)
    }
  })
})

ymap.set('key', 'value') // => Property "key" was added. Initial value: "value".
ymap.set('key', 'new') // => Property "key" was updated. New value: "new". Previous value: "value".
ymap.delete('key') // => Property "key" was deleted. New value: undefined. Previous Value: "new".
```

--------------------------------

### GET /api/shared-types/y.text.md

Source: https://docs.yjs.dev/llms.txt

Performs a natural language query against the documentation index to retrieve an answer and relevant excerpts.

```APIDOC
## GET /api/shared-types/y.text.md

### Description
Perform an HTTP GET request on the documentation index with the `ask` parameter to retrieve a direct answer and relevant excerpts from the documentation.

### Method
GET

### Endpoint
https://docs.yjs.dev/api/shared-types/y.text.md

### Parameters
#### Query Parameters
- **ask** (string) - Required - The immediate question to ask, written in natural language.
- **goal** (string) - Optional - Describes the broader end goal to help tailor the answer.
```

--------------------------------

### yarray.delete

Source: https://docs.yjs.dev/api/shared-types/y.array.md

Removes a specified number of elements from the Y.Array starting at a given index.

```APIDOC
## yarray.delete(index, length)

### Description
Delete length Y.Array elements starting from index.

### Parameters
- **index** (number) - Required - The starting index for deletion.
- **length** (number) - Required - The number of elements to remove.
```

--------------------------------

### Initialize Awareness Instance

Source: https://docs.yjs.dev/api/about-awareness.md

Create a new awareness instance or access it via an existing provider.

```javascript
awareness = new awarenessProtocol.Awareness(ydoc)

// It is usually created & maintained by the provider
awareness = provider.awareness
```

--------------------------------

### Initialize a Y.Doc instance

Source: https://docs.yjs.dev/api/y.doc.md

Create a new Y.Doc instance to serve as the container for shared data.

```javascript
import * as Y from 'yjs'

const doc = new Y.Doc()
```

--------------------------------

### provider.on('synced', ...)

Source: https://docs.yjs.dev/ecosystem/database-provider/y-indexeddb.md

Event listener for when the database connection is established and content is loaded.

```APIDOC
## provider.on('synced', callback)

### Description
The 'synced' event is fired when the connection to the database has been established and all available content has been loaded. This event also fires if no content is currently available.
```

--------------------------------

### Initialize and Use Y.Map

Source: https://docs.yjs.dev/api/shared-types/y.map.md

Demonstrates how to define top-level and nested Y.Map instances and perform basic CRUD operations.

```javascript
import * as Y from 'yjs'

const ydoc = new Y.Doc()

// You can define a Y.Map as a top-level type or a nested type

// Method 1: Define a top-level type
const ymap = ydoc.getMap('my map type') 
// Method 2: Define Y.Map that can be included into the Yjs document
const ymapNested = new Y.Map()

// Nested types can be included as content into any other shared type
ymap.set('my nested map', ymapNested)

// Common methods
ymap.set('prop-name', 'value') // value can be anything json-encodable
ymap.get('prop-name') // => 'value'
ymap.delete('prop-name')
```

--------------------------------

### Initialize and embed a subdocument

Source: https://docs.yjs.dev/api/subdocuments.md

Create a root document and insert a new subdocument into a shared map.

```javascript
// Client One
const rootDoc = new Y.Doc()
const folder = rootDoc.getMap()

const subDoc = new Y.Doc()
subDoc.getText().insert(0, 'some initial content')
folder.set('my-document.txt', subDoc)
```

--------------------------------

### Listen to update events and apply them on a remote client

Source: https://docs.yjs.dev/api/document-updates.md

Demonstrates basic synchronization by listening to 'update' events on two Y.Doc instances and applying updates to the other.

```javascript
const doc1 = new Y.Doc()
const doc2 = new Y.Doc()

doc1.on('update', update => {
  Y.applyUpdate(doc2, update)
})

doc2.on('update', update => {
  Y.applyUpdate(doc1, update)
})

// All changes are also applied to the other document
doc1.getArray('myarray').insert(0, ['Hello doc2, you got this?'])
doc2.getArray('myarray').get(0) // => 'Hello doc2, you got this?'
```

--------------------------------

### Initialize IndexedDB Persistence

Source: https://docs.yjs.dev/getting-started/allowing-offline-editing.md

Configure the IndexeddbPersistence provider to sync document updates to the local browser database.

```javascript
import { IndexeddbPersistence } from 'y-indexeddb'

const ydoc = new Y.Doc()
const roomName = 'my-room-name'
const persistence = new IndexeddbPersistence(roomName, ydoc)

// The persistence provider works similarly to the network providers:
// const network = new WebrtcProvider(roomName)
```

--------------------------------

### Configure WebsocketProvider Options

Source: https://docs.yjs.dev/ecosystem/connection-provider/y-websocket.md

Default configuration object for the WebsocketProvider constructor.

```javascript
wsOpts = {
  // Set this to `false` if you want to connect manually using wsProvider.connect()
  connect: true,
  // Specify a query-string that will be url-encoded and attached to the `serverUrl`
  // I.e. params = { auth: "bearer" } will be transformed to "?auth=bearer"
  params: {}, // Object<string,string>
  // You may polyill the Websocket object (https://developer.mozilla.org/en-US/docs/Web/API/WebSocket).
  // E.g. In nodejs, you could specify WebsocketPolyfill = require('ws')
  WebsocketPolyfill: Websocket,
  // Specify an existing Awareness instance - see https://github.com/yjs/y-protocols
  awareness: new awarenessProtocol.Awareness(ydoc)
}
```

--------------------------------

### Initialize and Sync Shared Types

Source: https://docs.yjs.dev/

Demonstrates creating a Yjs document, defining a shared map, and merging updates from a remote document instance.

```javascript
import * as Y from 'yjs'

// Yjs documents are collections of
// shared objects that sync automatically.
const ydoc = new Y.Doc()
// Define a shared Y.Map instance
const ymap = ydoc.getMap()
ymap.set('keyA', 'valueA')

// Create another Yjs document (simulating a remote user)
// and create some conflicting changes
const ydocRemote = new Y.Doc()
const ymapRemote = ydocRemote.getMap()
ymapRemote.set('keyB', 'valueB')

// Merge changes from remote
const update = Y.encodeStateAsUpdate(ydocRemote)
Y.applyUpdate(ydoc, update)

// Observe that the changes have merged
console.log(ymap.toJSON()) // => { keyA: 'valueA', keyB: 'valueB' }
```

--------------------------------

### Initializing and Using Y.XmlText

Source: https://docs.yjs.dev/api/shared-types/y.xmltext.md

Demonstrates how to define Y.XmlText as a top-level or nested type, perform text insertion and formatting, and serialize to XML string.

```javascript
import * as Y from 'yjs'

const ydoc = new Y.Doc()

// You can define a Y.XmlText as a top-level type or a nested type

// Method 1: Define a top-level type
const yxmlText = ydoc.get('my xmltext type', Y.XmlText) 
// Method 2: Define Y.XmlText that can be included into the Yjs document
const yxmltextNested = new Y.XmlText()

// Nested types can be included as content into any other shared type
yxmlText.set('my nested text', ytextNested)

// Common methods (also available in Y.Text)
yxmlText.insert(0, 'abc') // insert three elements
yxmlText.format(1, 2, { bold: true }) // delete second element 
yxmlText.toDelta() // => [{ insert: 'a' }, { insert: 'bc', attributes: { bold: true }}]

// Methods specific to Y.XmlText
yxmlText.prevSibling
yxmlText.nextSibling
yxmlText.toString() // => "a<bold>bc</bold>"
```

--------------------------------

### WebsocketProvider Constructor

Source: https://docs.yjs.dev/ecosystem/connection-provider/y-websocket.md

Creates a new instance of the WebsocketProvider to sync a Y.Doc with a remote server.

```APIDOC
## new WebsocketProvider(serverUrl, room, ydoc, [wsOpts])

### Description
Creates a new websocket-provider instance. As long as this provider, or the connected ydoc, is not destroyed, the changes will be synced to other clients via the connected server.

### Parameters
- **serverUrl** (string) - Required - The URL of the websocket server.
- **room** (string) - Required - The room name to join.
- **ydoc** (Y.Doc) - Required - The Yjs document instance to sync.
- **wsOpts** (Object) - Optional - Configuration object:
  - **connect** (boolean) - Whether to connect automatically.
  - **params** (Object<string,string>) - Query parameters to attach to the URL.
  - **WebsocketPolyfill** (Object) - A WebSocket implementation (e.g., 'ws' for Node.js).
  - **awareness** (Awareness) - An existing Awareness instance.
```

--------------------------------

### Initialize MonacoBinding

Source: https://docs.yjs.dev/ecosystem/editor-bindings/monaco.md

Configure the MonacoBinding to sync a Yjs text type with the Monaco editor model. Note that the editor requires a webpack build-step.

```javascript
import * as Y from 'yjs'
import { WebrtcProvider } from 'y-webrtc'
import { MonacoBinding } from 'y-monaco'

const ydoc = new Y.Doc()
const provider = new WebrtcProvider('monaco', ydoc)
const type = ydoc.getText('monaco')

// There are some steps missing to initialize the editor
// The editor requires a webpack build-step
// See the complete example:
//   https://github.com/yjs/yjs-demos/blob/master/monaco/monaco.js
const editor = monaco.editor.create(
  document.getElementById('monaco-editor'),
  {
    value: '',
    language: 'javascript',
    theme: 'vs-dark'
  }
)
const monacoBinding = new MonacoBinding(
  type,
  editor.getModel(),
  new Set([editor]),
  provider.awareness
)
```

--------------------------------

### Bundle changes with doc.transact

Source: https://docs.yjs.dev/api/y.doc.md

Use transactions to group multiple operations into a single change event, reducing observer overhead.

```javascript
doc.transact(() => { yarray.insert(..); ymap.set(..) })
```

--------------------------------

### Initialize QuillBinding with Awareness

Source: https://docs.yjs.dev/getting-started/adding-awareness.md

Pass the awareness instance to an editor binding to enable automatic cursor rendering and presence features.

```javascript
const binding = new QuillBinding(ytext, quill, provider.awareness)
```

--------------------------------

### Connection and Cleanup Methods

Source: https://docs.yjs.dev/ecosystem/database-provider/y-indexeddb.md

Methods for managing the database connection and clearing stored data.

```APIDOC
## provider.destroy()
### Description
Closes the connection to the database and stops syncing the document. This is called automatically when the associated Yjs document is destroyed.

## provider.clearData()
### Description
Destroys the database and removes the stored document along with all related meta-information.
```

--------------------------------

### Y.Doc Properties and Methods

Source: https://docs.yjs.dev/api/y.doc.md

Core properties and methods for interacting with a Y.Doc instance.

```APIDOC
## doc.clientID

### Description
A unique identifier for the client session. This property is readonly.

## doc.gc

### Description
Boolean flag to enable or disable garbage collection. Set to false to preserve old content.

## doc.transact(f, origin)

### Description
Executes a function within a single transaction. Bundling changes reduces the number of event calls.

## doc.get(name, TypeClass)

### Description
Retrieves a top-level shared type instance by name and type class.

## doc.getArray(name)

### Description
Defines or retrieves a shared Y.Array.

## doc.getMap(name)

### Description
Defines or retrieves a shared Y.Map.

## doc.getXmlFragment(name)

### Description
Defines or retrieves a shared Y.XmlFragment.

## doc.destroy()

### Description
Destroys the Y.Doc instance, clearing event handlers and memory references.
```

--------------------------------

### Initialize IndexedDB Persistence

Source: https://docs.yjs.dev/ecosystem/database-provider/y-indexeddb.md

Create an instance of IndexeddbPersistence to sync a Yjs document with the browser's IndexedDB storage.

```javascript
import { IndexeddbPersistence } from 'y-indexeddb'

const provider = new IndexeddbPersistence(docName, ydoc)

provider.on('synced', () => {
  console.log('content from the database is loaded')
})
```

--------------------------------

### Y.XmlFragment Methods

Source: https://docs.yjs.dev/api/shared-types/y.xmlfragment.md

Methods for initializing and manipulating Y.XmlFragment instances.

```APIDOC
## Y.XmlFragment

### Description
Represents an XML fragment in a Yjs document. It can be defined as a top-level type or a nested type.

### Methods
- **ydoc.getXmlFragment(name)**: Retrieves or creates a top-level Y.XmlFragment.
- **new Y.XmlFragment()**: Creates a new nested Y.XmlFragment.
- **insert(index, content)**: Inserts content at the specified index.
- **insertAfter(reference, content)**: Inserts content after a specific node.
- **get(index)**: Retrieves the node at the specified index.
- **toDOM()**: Converts the fragment to a DOM representation.
```

--------------------------------

### Sync two clients by computing the differences

Source: https://docs.yjs.dev/api/document-updates.md

Reduces bandwidth usage by exchanging only the differences between two clients based on their state vectors.

```javascript
const stateVector1 = Y.encodeStateVector(ydoc1)
const stateVector2 = Y.encodeStateVector(ydoc2)
const diff1 = Y.encodeStateAsUpdate(ydoc1, stateVector2)
const diff2 = Y.encodeStateAsUpdate(ydoc2, stateVector1)
Y.applyUpdate(ydoc1, diff2)
Y.applyUpdate(ydoc2, diff1)
```

--------------------------------

### Initialize and manipulate Y.XmlFragment

Source: https://docs.yjs.dev/api/shared-types/y.xmlfragment.md

Demonstrates defining top-level and nested XML fragments, along with basic insertion and retrieval operations.

```javascript
import * as Y from 'yjs'

const ydoc = new Y.Doc()

// You can define a Y.XmlFragment as a top-level type or a nested type

// Method 1: Define a top-level type
const yxmlFragment = ydoc.getXmlFragment('my xml fragment')
// Method 2: Define Y.XmlFragment that can be included into the Yjs document
const yxmlNested = new Y.XmlFragment()

// Common methods
const yxmlText = new Y.XmlText()
yxmlFragment.insert(0, [yxmlText])
yxmlFragment.firstChild === yxmlText
yxmlFragment.insertAfter(yxmlText, [new Y.XmlElement('node-name')])
yxmlFragment.get(0) === yxmlText // => true

//show result in dev console
console.log(yxmlFragment.toDOM())
```

--------------------------------

### Transform to RelativePosition and back

Source: https://docs.yjs.dev/api/relative-positions.md

Demonstrates the basic round-trip conversion between a type index and a relative position, then back to an absolute position.

```javascript
const relPos = Y.createRelativePositionFromTypeIndex(ytext, 2)
const pos = Y.createAbsolutePositionFromRelativePosition(relPos, doc)
pos.type === ytext // => true
pos.index === 2 // => true
```

--------------------------------

### Syncing clients without loading the Y.Doc

Source: https://docs.yjs.dev/api/document-updates.md

Performs synchronization using only binary updates and state vectors, bypassing the need to keep the Y.Doc objects in memory.

```javascript
// encode the current state as a binary buffer
let currentState1 = Y.encodeStateAsUpdate(ydoc1)
let currentState2 = Y.encodeStateAsUpdate(ydoc2)
// now we can continue syncing clients without
// using the Y.Doc
ydoc1.destroy()
ydoc2.destroy()

const stateVector1 = Y.encodeStateVectorFromUpdate(currentState1)
const stateVector2 = Y.encodeStateVectorFromUpdate(currentState2)
const diff1 = Y.diffUpdate(currentState1, stateVector2)
const diff2 = Y.diffUpdate(currentState2, stateVector1)

// sync clients
currentState1 = Y.mergeUpdates([currentState1, diff2])
currentState2 = Y.mergeUpdates([currentState2, diff1])
```

--------------------------------

### Use y-websocket in Node.js

Source: https://docs.yjs.dev/ecosystem/connection-provider/y-websocket.md

Configure the provider with a WebSocket polyfill for Node.js environments.

```javascript
const ws = require('ws')

const wsProvider = new WebsocketProvider(
  'ws://localhost:1234', 'my-roomname',
  doc,
  { WebSocketPolyfill: ws }
)
```

```bash
npm i ws
```

--------------------------------

### Send relative position to a remote client (JSON)

Source: https://docs.yjs.dev/api/relative-positions.md

Shows how to serialize a relative position using JSON for transmission to a remote client and resolve it against a remote document.

```javascript
const relPos = Y.createRelativePositionFromTypeIndex(ytext, 2)
const encodedRelPos = JSON.stringify(relPos)
// send encodedRelPos to remote client..
const parsedRelPos = JSON.parse(encodedRelPos)
const pos = Y.createAbsolutePositionFromRelativePosition(parsedRelPos, remoteDoc)
pos.type === remoteytext // => true
pos.index === 2 // => true
```

--------------------------------

### Y.Text Constructor

Source: https://docs.yjs.dev/api/shared-types/y.text.md

Creates a new instance of Y.Text, optionally initialized with content.

```APIDOC
## new Y.Text(initialContent)

### Description
Create an instance of Y.Text with existing content.

### Parameters
- **initialContent** (string) - Optional - The initial string content for the Y.Text instance.
```

--------------------------------

### Import WebsocketProvider

Source: https://docs.yjs.dev/ecosystem/connection-provider/y-websocket.md

Import the WebsocketProvider class from the y-websocket package.

```javascript
import { WebsocketProvider } from 'y-websocket'
```

--------------------------------

### Sync and Broadcast Awareness Updates

Source: https://docs.yjs.dev/api/about-awareness.md

Encodes the current awareness state for new connections and listens for local changes to broadcast updates to all clients.

```javascript
// Encode the complete Awareness state
const encodedAwState = awarenessProtocol.encodeAwarenessUpdate(
  provider.awareness,
  Array.from(provider.awareness.getStates().keys())
)
// Make sure to share the complete awareness state whenever you
// connect to a new client. Similarly to the Yjs CRDT, it doesn't
// matter if the remote client receives the same state-updates several
// times. What is important is that the state is distributed.

// Whenever the local state changes, communicate that change to all connected clients
awareness.on('update', ({ added, updated, removed }) => {
  const changedClients = added.concat(updated).concat(removed)
  broadcastAwarenessMessage(awarenessProtocol.encodeAwarenessUpdate(awareness, changedClients))
})
```

--------------------------------

### Import Awareness Protocol

Source: https://docs.yjs.dev/api/about-awareness.md

Import the awareness protocol module from y-protocols.

```javascript
import * as awarenessProtocol from 'y-protocols/awareness.js'
```

--------------------------------

### Initialize and Manipulate Y.Array

Source: https://docs.yjs.dev/api/shared-types/y.array.md

Demonstrates creating a Y.Array as a top-level or nested type and performing basic operations like insertion and deletion.

```javascript
import * as Y from 'yjs'

const ydoc = new Y.Doc()

// You can define a Y.Array as a top-level type or a nested type

// Method 1: Define a top-level type
const yarray = ydoc.getArray('my array type') 
// Method 2: Define Y.Array that can be included into the Yjs document
const yarrayNested = new Y.Array()

// Nested types can be included as content into any other shared type,
// notice that a shared type can only exist once in a document.
yarray.insert(0, [yarrayNested])

// Common methods
yarray.insert(0, [1, 2, 3]) // insert three elements
yarray.delete(1, 1) // delete second element 
yarray.toArray() // => [1, 3]
```

--------------------------------

### Implement lazy-loading with providers

Source: https://docs.yjs.dev/api/subdocuments.md

Attach a provider to a subdocument upon loading and retrieve all active subdocuments.

```javascript
doc.on('subdocs', ({ loaded }) => {
  loaded.forEach(subdoc => {
    new WebrtcProvider(subdoc.guid, subdoc)
  })
})
doc.getSubdocs() // Get the Set<Y.Doc> of all subdocuments
```

--------------------------------

### Initialize and manipulate Y.XmlElement

Source: https://docs.yjs.dev/api/shared-types/y.xmlelement.md

Demonstrates defining top-level and nested XML elements, along with basic insertion and DOM conversion methods.

```javascript
import * as Y from 'yjs'

const ydoc = new Y.Doc()

// You can define a Y.XmlElement as a top-level type or a nested type

// Method 1: Define a top-level type
// Note that the nodeName is always "undefined"
// when defining an XmlElement as a top-level type.
const yxmlElement = ydoc.get('prop-name', Y.XmlElement)
// Method 2: Define Y.XmlFragment that can be included into the Yjs document
const yxmlNested = new Y.XmlElement('node-name')

// Common methods
const yxmlText = new Y.XmlText()
yxmlFragment.insert(0, [yxmlText])
yxmlFragment.firstChild === yxmlText
yxmlFragment.insertAfter(yxmlText, [new Y.XmlElement('node-name')])
yxmlFragment.get(0) === yxmlText // => true

//show result in dev console
console.log(yxmlFragment.toDOM())
```

--------------------------------

### Y.XmlText Constructor

Source: https://docs.yjs.dev/api/shared-types/y.xmltext.md

Creates a new instance of Y.XmlText.

```APIDOC
## Y.XmlText()

### Description
Creates a new Y.XmlText instance that can be used as a top-level type or nested within other Yjs shared types.

### Signature
`const yxmlText = new Y.XmlText()`
```

--------------------------------

### Y.XmlText Constructor

Source: https://docs.yjs.dev/api/shared-types/y.xmltext

Creates a new instance of Y.XmlText.

```APIDOC
## Y.XmlText()

### Description
Creates a new Y.XmlText instance that can be used as a top-level type or nested within other shared types.

### Signature
`const yxmlText = new Y.XmlText()`
```

--------------------------------

### Executing Explicit Transactions

Source: https://docs.yjs.dev/getting-started/working-with-shared-types.md

Shows how to group multiple mutations into a single transaction to reduce observer calls and update messages.

```javascript
const ydoc = new Y.Doc()
const ymap = ydoc.getMap('favorites')

// set an initial value - to demonstrate the how changes in ymap are represented
ymap.set('food', 'pizza')

// observers are called after each transaction
ymap.observe(event => {
  console.log('changes', event.changes.keys)
})

ydoc.transact(() => {
  ymap.set('food', 'pencake')
  ymap.set('number', 31)
}) // => changes: Map({ number: { action: 'added' }, food: { action: 'updated', oldValue: 'pizza' } })
```

--------------------------------

### Define and observe a Y.Array shared type

Source: https://docs.yjs.dev/getting-started/working-with-shared-types.md

Demonstrates initializing a Y.Array, registering observers for changes, and handling nested shared types.

```javascript
import * as Y from 'yjs'

const ydoc = new Y.Doc()
// Define an instance of Y.Array named "my array"
// Every peer that defines "my array" like this will sync content with this peer.
const yarray = ydoc.getArray('my array')

// We can register change-observers like this
yarray.observe(event => {
  // Log a delta every time the type changes
  // Learn more about the delta format here: https://quilljs.com/docs/delta/
  console.log('delta:', event.changes.delta)
})

// There are a few caveats that you need to understand when working with shared types
// It is best to explain this in a few lines of code:

// We can insert & delete content
yarray.insert(0, ['some content']) // => delta: [{ insert: ['some content'] }]
// Note that the above method accepts an array of content to insert. 
// So the final document will look like this:
yarray.toArray() // => ['some content']
// We can insert anything that is JSON-encodable. Uint8Arrays also work.
yarray.insert(0, [1, { bool: true }, new Uint8Array([1,2,3])]) // => delta: [{ insert: [1, { bool: true }, Uint8Array([1,2,3])] }]
yarray.toArray() // => [1, { bool: true }, Uint8Array([1,2,3]), 'some content']
// You can even insert Yjs types, enabling you to create nested structures
const subArray = new Y.Array()
yarray.insert(0, [subArray]) // => delta: [{ insert: [subArray] }]
// Note that the above observer doesn't fire when you insert content into subArray
subArray.insert(0, ['nope']) // [observer not called]
// You need to create an observer on subArray instead
subArray.observe(event => { .. })
// Alternatively, you can observe deep changes on yarray (allowing you to observe child events as well)
yarray.observeDeep(events => { console.log('All deep events: ', events) })
subArray.insert(0, ['this works']) // => All deep events: [..]
// You can't insert the array at another place. A shared type can only exist in one place.
yarray.insert(0, [subArray]) // Throws exception!
```

--------------------------------

### Y.Array.from

Source: https://docs.yjs.dev/api/shared-types/y.array.md

Creates a new Y.Array instance initialized with the provided content.

```APIDOC
## Y.Array.from(content)

### Description
An alternative factory function to create a Y.Array based on existing content.

### Parameters
- **content** (Array<JSON | Uint8Array | Y.AbstractType>) - Required - The initial elements to populate the Y.Array.
```

--------------------------------

### Formatting Attributes as XML Tags

Source: https://docs.yjs.dev/api/shared-types/y.xmltext.md

Shows how formatting attributes are transformed into XML tags, where object values become XML attributes.

```javascript
ymxlText.insert(0, "my link", { a: { href: 'https://..' } })
ymxlText.toString() // => <a href="https://..">my link</a>
```

--------------------------------

### Y.logUpdate

Source: https://docs.yjs.dev/api/document-updates.md

Experimental utility to log update contents.

```APIDOC
## Y.logUpdate(update)

### Description
Log the contents of a document update to the console. This utility function is only meant for debugging and understanding the Yjs document format.

### Parameters
- **update** (Uint8Array) - Required - The binary update to log.
```

--------------------------------

### Listen for Synced Events

Source: https://docs.yjs.dev/getting-started/allowing-offline-editing.md

Handle the synced event to detect when the document has successfully loaded content from IndexedDB.

```javascript
persistence.once('synced', () => { console.log('initial content loaded') })
```

--------------------------------

### ydoc.on('update')

Source: https://docs.yjs.dev/api/document-updates.md

Event listener for incremental document updates.

```APIDOC
## ydoc.on('update', eventHandler)

### Description
Listen to incremental updates on the Yjs document. Send the computed incremental update to all connected clients, or store it in a database.

### Parameters
- **eventHandler** (function) - Required - Callback function with signature (update: Uint8Array, origin: any, doc: Y.Doc).
```

--------------------------------

### Y.applyUpdate

Source: https://docs.yjs.dev/api/document-updates.md

Applies a binary document update to a Y.Doc instance.

```APIDOC
## Y.applyUpdate(ydoc, update, [transactionOrigin])

### Description
Apply a document update on the shared document. Optionally you can specify `transactionOrigin` that will be stored on `transaction.origin` and `ydoc.on('update', (update, origin) => ..)`.

### Parameters
- **ydoc** (Y.Doc) - Required - The shared document instance.
- **update** (Uint8Array) - Required - The binary update to apply.
- **transactionOrigin** (any) - Optional - An origin identifier for the transaction.
```

--------------------------------

### Event Listeners

Source: https://docs.yjs.dev/ecosystem/connection-provider/y-websocket.md

Methods to subscribe to provider events.

```APIDOC
## wsProvider.on('sync', callback)

### Description
Registers a listener for the 'sync' event, which triggers when the client has received content from the server.

### Parameters
- **callback** (function(isSynced: boolean)) - The function to execute when the sync state changes.
```

--------------------------------

### Y.XmlFragment Methods

Source: https://docs.yjs.dev/api/shared-types/y.xmlfragment.md

A collection of methods available on the Y.XmlFragment instance for managing its content and observing changes.

```APIDOC
## Y.XmlFragment Methods

### insert(index, content)
Inserts an array of Y.XmlElement or Y.XmlText at the specified index.

### insertAfter(ref, content)
Inserts content after a reference element. If ref is null, inserts at the beginning.

### delete(index, length)
Deletes a specified number of elements starting from the given index.

### push(content)
Appends content to the end of the fragment.

### unshift(content)
Prepends content to the beginning of the fragment.

### get(index)
Retrieves the element at the specified index.

### slice([start[, end]])
Returns a shallow copy of a portion of the fragment into a new array.

### toJSON()
Returns a string representation of the XML elements contained in the fragment.

### createTreeWalker(filter)
Creates an iterable that walks through all children (including nested) that match the filter function.

### clone()
Creates a deep clone of the fragment.

### toDOM()
Transforms the fragment and its children into a DOM DocumentFragment.

### observe(callback)
Registers a synchronous observer for changes to this type.

### unobserve(callback)
Unregisters an observer.

### observeDeep(callback)
Registers a synchronous observer for changes to this type or any of its children.

### unobserveDeep(callback)
Unregisters a deep observer.
```

--------------------------------

### Load and observe subdocument content

Source: https://docs.yjs.dev/api/subdocuments.md

Retrieve a subdocument from a map and trigger loading. Use observers to track data changes rather than relying on sync events.

```javascript
// Client Two
const subDoc = rootDoc.getMap().get('my-document.txt')
const subDocText = subDoc.getText()
subDocText.toString() // => "" - content is empty

// Data needs to be loaded first..
subDoc.load()

// Then the providers will fetch data from the database / network
// and eventually fill the content
subDoc.on('synced', () => {
  subDocText.toString() // => "some initial content"
})

// It is hard to determine when data was actually synced.
// The synced event is still helpful to show the user that this user synced
// with other users.
// It is safer to observe the data types and don't listen
// to an explicit sync event.
subDocText.observe(() => {
  // data changed..
})
```

--------------------------------

### Connection Management Methods

Source: https://docs.yjs.dev/ecosystem/connection-provider/y-websocket.md

Methods to control the lifecycle of the WebSocket connection.

```APIDOC
## wsProvider.connect()

### Description
Establishes a websocket connection to the server. Use this if you disconnected or set connect: false in options.

## wsProvider.disconnect()

### Description
Disconnects from the server and prevents automatic reconnection.

## wsProvider.destroy()

### Description
Destroys the provider instance, disconnects from the server, and removes all event handlers.
```

--------------------------------

### Sync two clients by exchanging the complete document structure

Source: https://docs.yjs.dev/api/document-updates.md

Synchronizes two Y.Doc instances by encoding the full state of each and applying it to the other.

```javascript
const state1 = Y.encodeStateAsUpdate(ydoc1)
const state2 = Y.encodeStateAsUpdate(ydoc2)
Y.applyUpdate(ydoc1, state2)
Y.applyUpdate(ydoc2, state1)
```

--------------------------------

### Y.XmlElement Constructor

Source: https://docs.yjs.dev/api/shared-types/y.xmlelement.md

Creates a new instance of Y.XmlElement with a specified node name.

```APIDOC
## Y.XmlElement(nodeName: string)

### Description
Creates a new Y.XmlElement instance with the given node name.

### Signature
`const yxmlElement = new Y.XmlElement(nodeName: string)`
```

--------------------------------

### Serialization

Source: https://docs.yjs.dev/api/shared-types/y.xmlelement.md

Method to convert the element to an XML string.

```APIDOC
## toString()

### Description
Returns the XML-string representation of the element (e.g., '<div height="30px"></div>').
```

--------------------------------

### Element Properties

Source: https://docs.yjs.dev/api/shared-types/y.xmlelement.md

Accessors for element metadata and sibling navigation.

```APIDOC
## Properties

### nodeName
Returns the name of the Y.XmlElement as a string.

### prevSibling
Returns the previous sibling (Y.XmlElement, Y.XmlText, or null).

### nextSibling
Returns the next sibling (Y.XmlElement, Y.XmlText, or null).
```

--------------------------------

### Custom Provider Implementation Template

Source: https://docs.yjs.dev/api/document-updates.md

A template for a Yjs provider that uses transaction origins to prevent infinite loops when synchronizing updates.

```javascript
import * as Y from 'yjs'
import { Observable } from 'lib0/observable'

class Provider extends Observable {
  /**
   * @param {Y.Doc} ydoc
   */
  constructor (ydoc) {
    super()

    ydoc.on('update', (update, origin) => {
      // ignore updates applied by this provider
      if (origin !== this) {
        // this update was produced either locally or by another provider. 
        this.emit('update', [update])
      }
    })
    // listen to an event that fires when a remote update is received
    this.on('update', update => {
      Y.applyUpdate(ydoc, update, this) // the third parameter sets the transaction-origin
    })
  }
  ..
}
```

--------------------------------

### Representing State with Delta

Source: https://docs.yjs.dev/api/delta-format.md

Demonstrates how to retrieve the current state of a Y.Text instance as a Delta array.

```javascript
const ytext = ydoc.getText()

ytext.toDelta() // => []
ytext.insert(0, 'World', { bold: true })
ytext.insert(0, 'Hello ')
ytext.toDelta() // => [{ insert: 'Hello ' }, { insert: 'World', attributes: { bold: true } }]
```

--------------------------------

### undoManager.redo()

Source: https://docs.yjs.dev/api/undo-manager.md

Re-applies the last operation from the redo stack.

```APIDOC
## undoManager.redo()

### Description
Redo the last operation on the redo-stack. I.e. the previous undo is reversed.
```

--------------------------------

### Retain Delta with Formatting

Source: https://docs.yjs.dev/api/delta-format.md

Applies formatting attributes to existing text using the retain operation.

```javascript
delta = [{
  retain: 5, attributes: { italic: true }
}]
```

--------------------------------

### Applying Delta Operations

Source: https://docs.yjs.dev/api/delta-format.md

Shows how to apply a Delta array to a Y.Text instance to perform complex document modifications.

```javascript
ytext.insert(0, 'Hello ')
ytext.insert(6, 'World', { bold: true })
// is equivalent to 
ytext.applyDelta([{ insert: 'Hello ' }, { insert: 'World', attributes: { bold: true } }])
```

--------------------------------

### Access and Update Awareness State

Source: https://docs.yjs.dev/getting-started/adding-awareness.md

Retrieve the awareness instance from a provider and update local state fields to propagate user information to other clients.

```javascript
// All of our network providers implement the awareness crdt
const awareness = provider.awareness

// You can observe when a user updates their awareness information
awareness.on('change', changes => {
  // Whenever somebody updates their awareness information,
  // we log all awareness information from all users.
  console.log(Array.from(awareness.getStates().values()))
})

// You can think of your own awareness information as a key-value store.
// We update our "user" field to propagate relevant user information.
awareness.setLocalStateField('user', {
  // Define a print name that should be displayed
  name: 'Emmanuelle Charpentier',
  // Define a color that should be associated to the user:
  color: '#ffb61e' // should be a hex color
})
```

--------------------------------

### Observe Y.XmlFragment changes

Source: https://docs.yjs.dev/api/shared-types/y.xmlfragment.md

Use the observe callback to monitor child-element insertions and deletions, logging the delta format for change tracking.

```javascript
yxmlFragment.observe(yxmlElent => {
  yxmlEvent.target === yarray // => true

  // Observe when child-elements are added or deleted. 
  // Log the Xml-Delta Format to calculate the difference to the last observe-event
  console.log(yxmlEvent.changes.delta)
})

yxmlFragment.insert(0, [new Y.XmlText()]) // => [{ insert: [yxmlText] }]
yxmlFragment.delete(0, 1) // [{ delete: 1 }]
```

--------------------------------

### Apply updates with origin filtering

Source: https://docs.yjs.dev/api/document-updates.md

Uses transactions and origin filtering to prevent redundant update loops between synchronized clients.

```javascript
doc1.on('update', (update, origin) => {
  if (origin !== 'doc1') {
    return
  }
  Y.applyUpdate(doc2, update)
})

doc2.on('update', (update, origin) => {
  if (origin !== 'doc2') {
    return
  }
  Y.applyUpdate(doc1, update)
})

doc1.transact( ()=> {
  doc1.getArray('myarray').insert(0, ['Hello doc2, you got this?'])
}, 'doc1')
```

--------------------------------

### Event Handling

Source: https://docs.yjs.dev/api/y.doc.md

Methods for registering and unregistering event listeners on the Y.Doc instance.

```APIDOC
## doc.on(eventName, handler)

### Description
Registers an event handler for the specified event.

## doc.once(eventName, handler)

### Description
Registers an event handler that is called only once.

## doc.off(eventName, handler)

### Description
Unregisters an event handler.
```

--------------------------------

### Delta Operations in Transactions

Source: https://docs.yjs.dev/api/delta-format.md

Demonstrates how multiple changes within a single transaction are represented as a combined Delta.

```javascript
yarray.observe(event => { console.log(event.changes.delta) })

ydoc.transact(() => {
  // perform all changes in a single transaction
  yarray.insert(0, [1, 2, 3]) // => [{ insert: [1, 2, 3] }]
  yarray.insert(2, ["abc"]) // => [{ retain: 2 }, { insert: ["abc"] }]
  yarray.delete(0, 1) // => [{ delete: 1 }]
}) // => [{ insert: [2, "abc", 3] }]

ydoc.transact(() => {
  yarray.insert(0, ['x'])
  yarray.insert(2, ['y'])
}) // => [{ insert: ['x'] }, { retain: 1 }, { insert: ['y'] }]
```

--------------------------------

### Data Management Methods

Source: https://docs.yjs.dev/ecosystem/database-provider/y-indexeddb.md

Methods for setting, retrieving, and deleting custom meta-information within the provider.

```APIDOC
## provider.set(key: any, value: any)
### Description
Sets a custom property on the provider instance to store meta-information. Note that this content is not synced with other peers.

## provider.get(key: any)
### Description
Retrieves a value previously stored with the specified key.

## provider.del(key: any)
### Description
Deletes a stored value associated with the specified key.
```

--------------------------------

### Send relative position to a remote client (Uint8Array)

Source: https://docs.yjs.dev/api/relative-positions.md

Demonstrates binary encoding of a relative position, which is the preferred format for document updates, and its subsequent decoding and resolution.

```javascript
const relPos = Y.createRelativePositionFromTypeIndex(ytext, 2)
const encodedRelPos = Y.encodeRelativePosition(relPos)
// send encodedRelPos to remote client..
const parsedRelPos = Y.decodeRelativePosition(encodedRelPos)
const pos = Y.createAbsolutePositionFromRelativePosition(parsedRelPos, remoteDoc)
pos.type === remoteytext // => true
pos.index === 2 // => true
```

--------------------------------

### Bind Quill to Yjs Document

Source: https://docs.yjs.dev/getting-started/a-collaborative-editor.md

Create a Yjs document and bind it to the Quill editor instance.

```javascript
import * as Y from 'yjs'
import { QuillBinding } from 'y-quill'

// A Yjs document holds the shared data
const ydoc = new Y.Doc()
// Define a shared text type on the document
const ytext = ydoc.getText('quill')

// Create an editor-binding which
// "binds" the quill editor to a Y.Text type.
const binding = new QuillBinding(ytext, quill)
```

--------------------------------

### Initialize and Manipulate Y.Text

Source: https://docs.yjs.dev/api/shared-types/y.text.md

Demonstrates defining Y.Text as a top-level or nested type and performing basic operations like insertion, formatting, and serialization.

```javascript
import * as Y from 'yjs'

const ydoc = new Y.Doc()

// You can define a Y.Text as a top-level type or a nested type

// Method 1: Define a top-level type
const ytext = ydoc.getText('my text type') 
// Method 2: Define Y.Text that can be included into the Yjs document
const ytextNested = new Y.Text()

// Nested types can be included as content into any other shared type
ydoc.getMap('another shared structure').set('my nested text', ytextNested)

// Common methods
ytext.insert(0, 'abc') // insert three elements
ytext.format(1, 2, { bold: true }) // delete second element 
ytext.toString() // => 'abc'
ytext.toDelta() // => [{ insert: 'a' }, { insert: 'bc', attributes: { bold: true }}]
```
Tokens:
Raw