Yjs

https://github.com/yjs/docs
Admin
Yjs is a high-performance CRDT library for building collaborative applications that automatically...
Tokens:55,446
Snippets:555
Trust Score:8.1
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install js-base64 (Bash)

Source: https://github.com/yjs/docs/blob/main/api/document-updates.md

Installs the js-base64 library via npm, which is required for the Base64 encoding example.

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

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

### Create a provider for each loaded subdocument

Source: https://github.com/yjs/docs/blob/main/api/subdocuments.md

Shows how to create a WebRTC provider for each loaded subdocument using its GUID as the room name, and how to get all subdocuments.

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

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

### JavaScript setup for Monaco with y-monaco

Source: https://github.com/yjs/docs/blob/main/ecosystem/editor-bindings/monaco.md

Initializes a Yjs document, WebRTC provider, and MonacoBinding to make the Monaco editor collaborative. Requires a webpack build step and a complete example is linked.

```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
)

```

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

### Install Yjs providers: y-webrtc, y-websocket, y-dat

Source: https://github.com/yjs/docs/blob/main/getting-started/a-collaborative-editor.md

Installs the y-webrtc, y-websocket, or y-dat provider packages. Each command installs a separate provider for syncing Yjs documents.

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

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

### Install dependencies for Monaco

Source: https://github.com/yjs/docs/blob/main/ecosystem/editor-bindings/monaco.md

Command to install the required packages for using Monaco with yjs and y-monaco.

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

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

### Quick Start: Syncing shared types with Yjs

Source: https://github.com/yjs/docs/blob/main/README.md

This example demonstrates how to create a Y.Doc, add data to a shared Y.Map, and merge changes from a remote document using Y.encodeStateAsUpdate and Y.applyUpdate. It shows that changes from different clients merge automatically, as seen in the console output.

```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' }
```

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

### Install y-indexeddb

Source: https://github.com/yjs/docs/blob/main/getting-started/allowing-offline-editing.md

Install the y-indexeddb package via npm.

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

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

### Start y-websocket server with npx

Source: https://github.com/yjs/docs/blob/main/ecosystem/connection-provider/y-websocket.md

Starts the y-websocket server using npx. The PORT environment variable defaults to 1234 if not set.

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

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

### Set up Quill editor with cursors and toolbar

Source: https://github.com/yjs/docs/blob/main/getting-started/a-collaborative-editor.md

Sets up the Quill editor with the cursors module, a toolbar, and user-only history. The HTML block provides the required stylesheet and editor container, and the install command installs the necessary packages.

```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
```

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

### Create and manipulate a Y.XmlFragment

Source: https://github.com/yjs/docs/blob/main/api/shared-types/y.xmlfragment.md

Shows how to create a Y.XmlFragment as a top-level type or nested type, and demonstrates common methods like insert, insertAfter, get, and toDOM. The example logs the DOM representation to the console.

```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())
```

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

### Start y-websocket server with HTTP callback

Source: https://github.com/yjs/docs/blob/main/ecosystem/connection-provider/y-websocket.md

Starts the y-websocket server with an HTTP callback that sends a debounced POST request to the specified URL on document updates. The CALLBACK_OBJECTS variable specifies shared objects to include.

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

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

### Start y-websocket server with LevelDB persistence

Source: https://github.com/yjs/docs/blob/main/ecosystem/connection-provider/y-websocket.md

Starts the y-websocket server with persistence enabled, storing document updates in a LevelDB database. The YPERSISTENCE environment variable specifies the database directory.

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

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

### Install Yjs and bind Quill editor to Y.Text

Source: https://github.com/yjs/docs/blob/main/getting-started/a-collaborative-editor.md

Installs Yjs and the y-quill binding, then creates a Y.Doc, a shared text type, and binds it to the Quill editor. The binding keeps the editor and the shared text in sync.

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

```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)
```

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

### Create a copy of a subdocument with the same GUID

Source: https://github.com/yjs/docs/blob/main/api/subdocuments.md

Shows how to create a copy of a subdocument by assigning the same GUID, causing them to sync automatically.

```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
```

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

### awareness.getStates()

Source: https://github.com/yjs/docs/blob/main/api/about-awareness/README.md

Gets all awareness states (remote and local). Maps from clientID to awareness state.

```APIDOC
## awareness.getStates()

### Description
Gets all awareness states (remote and local). Maps from clientID to awareness state.

### Method
getStates

### Parameters
None

### Returns
- **Map<string, Object<string, any>>** - A map from clientID to awareness state. The clientID is usually the ydoc.clientID.

```

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

### Create and use a Y.Map

Source: https://github.com/yjs/docs/blob/main/api/shared-types/y.map.md

Shows how to create a Y.Map as a top-level type or a nested type, and demonstrates common methods like set, get, and delete.

```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')
```

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

### yxmlFragment.slice([start, end])

Source: https://github.com/yjs/docs/blob/main/api/shared-types/y.xmlfragment.md

Retrieves a range of content.

```APIDOC
## yxmlFragment.slice([start, end])

### Description
Retrieves a range of content starting from index `start` (inclusive) to index `end` (exclusive). Negative indexes can be used to indicate offsets from the end. Works similarly to `Array.slice`.

### Method
`yxmlFragment.slice([start: number [, end: number]]): Array<Y.XmlElement | Y.XmlText>`

### Parameters
- **start** (number) - Optional - The starting index (inclusive). Defaults to 0.
- **end** (number) - Optional - The ending index (exclusive). Defaults to the length of the fragment.

### Returns
- **Array<Y.XmlElement | Y.XmlText>** - The sliced array of elements.
```

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

### Connect to a WebSocket server with y-websocket

Source: https://github.com/yjs/docs/blob/main/ecosystem/connection-provider/y-websocket.md

Create a Yjs document and connect it to a WebSocket server using the WebsocketProvider. The status event logs 'connected' or 'disconnected'. Install the y-websocket package with npm.

```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
```

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

### Creating explicit transactions with ydoc.transact()

Source: https://github.com/yjs/docs/blob/main/getting-started/working-with-shared-types.md

Shows how to explicitly create a transaction with ydoc.transact() to bundle multiple changes. Observers are called after each transaction, and the example logs the resulting changes map.

```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' } })
```

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

### Y.Array usage example

Source: https://github.com/yjs/docs/blob/main/api/shared-types/y.array.md

Shows how to create a Y.Array as a top-level type or nested type, insert elements, delete elements, and convert to a plain array. Demonstrates that a shared type can only exist once in a document.

```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]
```

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

### Creating and using Y.XmlElement

Source: https://github.com/yjs/docs/blob/main/api/shared-types/y.xmlelement.md

Shows how to define a Y.XmlElement as a top-level or nested type, and demonstrates common methods like insert, insertAfter, and get. Note that top-level XmlElement nodeName is always 'undefined'.

```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())
```

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

### Use y-websocket in Node.js with ws polyfill

Source: https://github.com/yjs/docs/blob/main/ecosystem/connection-provider/y-websocket.md

Use the ws package as a WebSocket polyfill in Node.js. Install ws with npm before using the WebSocketPolyfill option.

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

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

```bash
npm i ws
```

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

### awareness.on('change', callback)

Source: https://github.com/yjs/docs/blob/main/api/about-awareness.md

Listens to remote and local state changes. Get notified when a state is either added, updated, or removed.

```APIDOC
## awareness.on('change', callback)

### Description
Listens to remote and local state changes. Get notified when a state is either added, updated, or removed.

### Method
Event Listener

### Parameters
#### Parameters
- **event** (Object) - Required - The event object containing added, updated, and removed arrays of client IDs.
- **transactionOrigin** (any) - Optional - The origin of the transaction.

### Returns
- **undefined** - No return value.

### Example
```javascript
awareness.on('change', ({ added, updated, removed }, transactionOrigin) => {
  // handle change
})
```
```

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

### Listen to subdocs events

Source: https://github.com/yjs/docs/blob/main/api/subdocuments.md

Shows how to listen to the 'subdocs' event to get notified when subdocuments are added, removed, or loaded.

```typescript
doc.on('subdocs', ({ added: Set<Y.Doc>, removed: Set<Y.Doc>, loaded: Set<Y.Doc> }) => {
  // use added / removed to sync documents in the background
  // use loaded to fill document content
})
```

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

### Create and use Y.XmlText with common and specific methods

Source: https://github.com/yjs/docs/blob/main/api/shared-types/y.xmltext.md

Shows how to create a Y.XmlText as a top-level type or nested type, and demonstrates common methods inherited from Y.Text (insert, format, toDelta) plus Y.XmlText-specific properties (prevSibling, nextSibling) and toString(). Note the example uses 'ytextNested' but defines 'yxmltextNested'.

```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>"
```

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

### Observe Y.Map changes with Y.MapEvent

Source: https://github.com/yjs/docs/blob/main/api/shared-types/y.map.md

Observe changes on a Y.Map instance. The callback receives a Y.MapEvent with `target`, `keysChanged`, and `changes.keys` to inspect add/update/delete actions. The example also shows the console output for each mutation.

```javascript
ymap.observe(ymapEvent => {
  ymapEvent.target === ymap // => 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.
  ymapEvent.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".

```

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

### wsProvider.connect()

Source: https://github.com/yjs/docs/blob/main/ecosystem/connection-provider/y-websocket.md

Establishes a websocket connection to the server.

```APIDOC
## Method: `wsProvider.connect()`

### Description
Establish a websocket connection to the websocket-server. Call this if you recently disconnected or if you set `wsOpts.connect = false`.

### Parameters
None

### Returns
None
```

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

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

Source: https://github.com/yjs/docs/blob/main/ecosystem/connection-provider/y-websocket.md

Registers a listener for the 'sync' event.

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

### Description
Add an event listener for the `sync` event that is fired when the client received content from the server.

### Parameters
- **eventName** (string) - Required - The event name, must be `'sync'`.
- **callback** (function(isSynced: boolean)) - Required - The callback function that receives a boolean indicating whether the client is synced.

### Returns
None
```

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

### yarray.slice

Source: https://github.com/yjs/docs/blob/main/api/shared-types/y.array.md

Retrieve a range of content starting from index start (inclusive) to index end (exclusive).

```APIDOC
## yarray.slice

### Description
Retrieve a range of content starting from index start (inclusive) to index end (exclusive). Negative indexes can be used to indicate offsets from the end of the Y.Array.

### Method
`yarray.slice([start: number [, end: number]]): Array<JSON | Uint8Array | Y.AbstractType>`

### Parameters
- **start** (number) - Optional - The starting index (inclusive). Defaults to 0.
- **end** (number) - Optional - The ending index (exclusive). Defaults to the length of the array.

### Returns
- **Array<JSON | Uint8Array | Y.AbstractType>** - A new array containing the selected elements.
```

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

### new WebsocketProvider(serverUrl, room, ydoc, wsOpts)

Source: https://github.com/yjs/docs/blob/main/ecosystem/connection-provider/y-websocket.md

Constructor for creating a new WebsocketProvider instance.

```APIDOC
## Constructor: `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 connect to.
- **ydoc** (Y.Doc) - Required - The Yjs document to sync.
- **wsOpts** (WsOpts) - Optional - Configuration object with the following defaults:
  - **connect** (boolean) - Default `true` - Set to `false` to connect manually using `wsProvider.connect()`.
  - **params** (Object<string,string>) - Default `{}` - Query-string parameters that will be url-encoded and attached to the `serverUrl`.
  - **WebsocketPolyfill** (Websocket) - Default `Websocket` - Polyfill for the Websocket object (e.g., in Node.js use `require('ws')`).
  - **awareness** (Awareness) - Default `new awarenessProtocol.Awareness(ydoc)` - An existing Awareness instance.

### Example
```javascript
import { WebsocketProvider } from 'y-websocket'
const wsProvider = new WebsocketProvider(serverUrl, room, ydoc, wsOpts)
```
```

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

### Choose a provider: y-webrtc or y-websocket

Source: https://github.com/yjs/docs/blob/main/getting-started/a-collaborative-editor.md

Shows two provider options for syncing the Yjs document: y-webrtc for peer-to-peer without a server, and y-websocket for connecting to a server (the public demo server is not for production). Both use the same interface.

```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
)
```

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

### toJSON() output example

Source: https://github.com/yjs/docs/blob/main/api/shared-types/y.xmlfragment.md

Example output of toJSON() when the fragment contains two XML elements. The result is a concatenated string of XML elements and is not valid XML unless wrapped in a container element.

```xml
<element1>foo</element1><element2>bar</element2>
```

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

### Create Awareness instance

Source: https://github.com/yjs/docs/blob/main/api/about-awareness/README.md

Create a new Awareness instance with a Y.Doc, or access the instance typically created and maintained by the provider.

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

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

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

### awareness.getLocalState()

Source: https://github.com/yjs/docs/blob/main/api/about-awareness/README.md

Gets the local awareness state.

```APIDOC
## awareness.getLocalState()

### Description
Gets the local awareness state.

### Method
getLocalState

### Parameters
None

### Returns
- **Object<string, any> | null** - The local awareness state, or null if not set.

```

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

### yarray.delete

Source: https://github.com/yjs/docs/blob/main/api/shared-types/y.array.md

Delete length Y.Array elements starting from index.

```APIDOC
## yarray.delete

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

### Method
`yarray.delete(index: number, length: number)`

### Parameters
- **index** (number) - Required - The starting index of the elements to delete.
- **length** (number) - Required - The number of elements to delete.
```

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

### new Y.Text(initialContent)

Source: https://github.com/yjs/docs/blob/main/api/shared-types/y.text.md

Creates a new Y.Text instance with optional initial content.

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

### Description
Creates a new Y.Text instance with optional initial content.

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

### Parameters
- **initialContent** (string) - Optional - The initial content of the text.

### Returns
- **Y.Text** - The newly created Y.Text instance.

### Example
```javascript
const ytext = new Y.Text('hello')
```
```

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

### y-dat: Create DatProvider

Source: https://github.com/yjs/docs/blob/main/getting-started/a-collaborative-editor.md

Creates a DatProvider to sync a Yjs document over the Dat protocol. The datKey is a public key for a Dat archive; setting it to null creates a fresh archive. This provider uses the room-name concept to connect Yjs documents.

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

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

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

### doc.getXmlFragment(name?)

Source: https://github.com/yjs/docs/blob/main/api/y.doc.md

Gets or defines a shared Y.XmlFragment type.

```APIDOC
## doc.getXmlFragment(string = ''): Y.XmlFragment

### Description
Defines or retrieves a shared Y.XmlFragment type. Equivalent to `doc.get(name, Y.XmlFragment)`.

### Method
Method

### Endpoint
`doc.getXmlFragment(name?)`

### Parameters
- **name** (string) - Optional - The name of the XML fragment type. Defaults to empty string.

### Request Example
```javascript
const yxml = doc.getXmlFragment('myxml')
```

### Response
Returns a Y.XmlFragment instance.

```

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

### doc.getMap(name?)

Source: https://github.com/yjs/docs/blob/main/api/y.doc.md

Gets or defines a shared Y.Map type.

```APIDOC
## doc.getMap(string = ''): Y.Map

### Description
Defines or retrieves a shared Y.Map type. Equivalent to `doc.get(name, Y.Map)`.

### Method
Method

### Endpoint
`doc.getMap(name?)`

### Parameters
- **name** (string) - Optional - The name of the map type. Defaults to empty string.

### Request Example
```javascript
const ymap = doc.getMap('mymap')
```

### Response
Returns a Y.Map instance.

```

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

### Create a Y.Doc instance

Source: https://github.com/yjs/docs/blob/main/api/y.doc.md

Imports the Yjs library and creates a new Y.Doc instance. This is the entry point for using Yjs shared types.

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

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

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

### doc.getArray(name?)

Source: https://github.com/yjs/docs/blob/main/api/y.doc.md

Gets or defines a shared Y.Array type.

```APIDOC
## doc.getArray(string = ''): Y.Array

### Description
Defines or retrieves a shared Y.Array type. Equivalent to `doc.get(name, Y.Array)`.

### Method
Method

### Endpoint
`doc.getArray(name?)`

### Parameters
- **name** (string) - Optional - The name of the array type. Defaults to empty string.

### Request Example
```javascript
const yarray = doc.getArray('myarray')
```

### Response
Returns a Y.Array instance.

```

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

### doc.get(name, TypeClass)

Source: https://github.com/yjs/docs/blob/main/api/y.doc.md

Gets a top-level shared type instance by name and type class.

```APIDOC
## doc.get(string, Y.[TypeClass]): [Type]

### Description
Gets a top-level instance of a shared type. The type class must be one of Y.Array, Y.Map, Y.XmlFragment, etc.

### Method
Method

### Endpoint
`doc.get(name, TypeClass)`

### Parameters
- **name** (string) - Required - The name of the top-level type.
- **TypeClass** (Y.TypeClass) - Required - The shared type class (e.g., Y.Array, Y.Map).

### Request Example
```javascript
const yarray = doc.get('myarray', Y.Array)
```

### Response
Returns the shared type instance.

```

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

### Y.Map

Source: https://github.com/yjs/docs/blob/main/api/shared-types/y.map.md

Complete API reference for the Y.Map shared type, including properties, methods, and usage examples.

```APIDOC
## Y.Map

### Description
A shared type with a similar API to global.Map. It can be used as a top-level type or nested within other shared types.

### Constructor
`new Y.Map()`

### Properties
- **`doc`** (Y.Doc | null) - readonly - The Yjs document that this type is bound to. Is `null` when it is not bound yet.
- **`parent`** (Y.AbstractType | null) - The parent that holds this type. Is `null` if this `ymap` is a top-level type.
- **`size`** (number) - Returns the number of key/value pairs.

### Methods

#### `set(key: string, value: object|boolean|string|number|Uint8Array|Y.AbstractType)`
Add or update an entry with a specified key. This method works similarly to the [Map.set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/set) method. The value can be a shared type, an Uint8Array, or anything JSON-encodable.

#### `get(key: string): object|boolean|Array|string|number|Uint8Array|Y.AbstractType`
Returns an entry with the specified key. This method works similarly to the [Map.get](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/get) method.

#### `delete(key: string)`
Deletes an entry with the specified key. This method works similarly to the [Map.delete](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/delete) method.

#### `has(key: string): boolean`
Returns true if an entry with the specified key exists. This method works similarly to the [Map.has](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/has) method.

#### `clear()`
Removes all elements from this `ymap`.

#### `toJSON(): Object<string,object|boolean|Array|string|number|Uint8Array>`
Copies the `[key,value]` pairs of this Y.Map to a new Object. It transforms all shared types to JSON using their `toJSON` method.

#### `forEach(value: any, key: string, map: Y.Map)`
Execute the provided function once on every key-value pair.

#### `[Symbol.Iterator]: Iterator`
Returns an [Iterator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) of `[key, value]` pairs. This allows you to iterate over the `ymap` using a for..of loop: `for (const [key, value] of ymap) { .. }`

#### `entries(): Iterator`
Returns an [Iterator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) of `[key, value]` pairs.

#### `values(): Iterator`
Returns an [Iterator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) of values only. This allows you to iterate through the values only `for (const value of ymap.values()) { ... }` or insert all values into an array `Array.from(ymap.values())`.

#### `keys(): Iterator`
Returns an [Iterator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) of keys only. This allows you to iterate through the keys only `for (const key of ymap.keys()) { ... }` or insert all keys into an array `Array.from(ymap.keys())`.

#### `clone(): Y.Map`
Clone all values into a fresh Y.Map instance. The returned type can be included into the Yjs document.

#### `observe(function(YMapEvent, Transaction))`
Registers a change observer that will be called synchronously every time this shared type is modified. In the case this type is modified in the observer call, the event listener will be called again after the current event listener returns.

#### `unobserve(function)`
Unregisters a change observer that has been registered with `ymap.observe`.

#### `observeDeep(function(Array<Y.Event>, Transaction))`
Registers a change observer that will be called synchronously every time this type or any of its children is modified. In the case this type is modified in the event listener, the event listener will be called again after the current event listener returns. The event listener receives all Events created by itself or any of its children.

#### `unobserveDeep(function)`
Unregisters a change observer that has been registered with `ymap.observeDeep`.

### Example
```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')
```
```

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

### Default websocket provider options (wsOpts)

Source: https://github.com/yjs/docs/blob/main/ecosystem/connection-provider/y-websocket.md

The default options object that can be passed to the constructor. Override these values to customize connection behavior, such as setting connect: false or providing a custom awareness instance.

```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)
}
```

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

### Insert Delta on Y.Text

Source: https://github.com/yjs/docs/blob/main/api/delta-format.md

Shows the insert delta format for Y.Text, including formatting attributes, and an example of applying it.

```javascript
delta = [{
  retain: 1
}, {
  insert: 'abc', attributes: { bold: true }
}, {
  retain: 1
}, {
  insert: 'xyz'
}]
```

```javascript
ytext.insert(0, '123')
ytext.applyDelta(delta)
ytext.toDelta() // => [{ insert: '1' },
                //     { insert: 'abc', attributes: { bold: true } },
                //     { insert: '2xyz3' }]
```

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

### doc.on('updateV2', handler)

Source: https://github.com/yjs/docs/blob/main/api/y.doc.md

Event handler for the experimental updateV2 format.

```APIDOC
## doc.on('updateV2', function(update: Uint8Array, origin: any, doc: Y.Doc, tr: Transaction))

### Description
Registers an event handler for the experimental updateV2 message format, which is more efficient but not for production use.

### Method
Event Handler

### Endpoint
`doc.on('updateV2', handler)`

### Parameters
- **handler** (function) - Required - Callback receiving `update` (Uint8Array), `origin` (any), `doc` (Y.Doc), and `tr` (Transaction).

### Request Example
```javascript
doc.on('updateV2', (update, origin, doc, tr) => { ... })
```

### Response
No return value.

```

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

### Retain and Delete Delta

Source: https://github.com/yjs/docs/blob/main/api/delta-format.md

Shows a delta that retains one item and then deletes three, with an example of applying it to a Y.Text.

```javascript
delta = [{
  retain: 1
}, {
  delete: 3
}]
```

```javascript
ytext.insert(0, '12345')
ytext.applyDelta(delta)
ytext.toDelta() // => { insert: '15' }
```

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

### new Y.Doc()

Source: https://github.com/yjs/docs/blob/main/api/y.doc.md

Constructor for creating a new Y.Doc instance.

```APIDOC
## Y.Doc

### Description
Creates a new Y.Doc instance, the root for all shared types and transactions.

### Method
Constructor

### Endpoint
`new Y.Doc()`

### Parameters
None

### Request Example
```javascript
import * as Y from 'yjs'
const doc = new Y.Doc()
```

### Response
Returns a new Y.Doc instance.

```

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

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

Source: https://github.com/yjs/docs/blob/main/ecosystem/database-provider/y-indexeddb.md

Registers a listener for the 'synced' event, which is fired when the connection to the database has been established and all available content has been loaded.

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

### Description
Registers a listener for the 'synced' event, which is fired when the connection to the database has been established and all available content has been loaded. The event is also fired when no content is available yet.

### Event
`'synced'`

### Callback Parameters
- **idbPersistence** (IndexeddbPersistence) - The provider instance that fired the event.

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

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

### awareness.on('update', callback)

Source: https://github.com/yjs/docs/blob/main/api/about-awareness/README.md

Listens to remote and local state changes. Gets notified when a state is either added, updated, or removed.

```APIDOC
## awareness.on('update', callback)

### Description
Listens to remote and local state changes. Gets notified when a state is either added, updated, or removed.

### Method
on

### Parameters
- **event** (string) - Required - The event name, 'update'.
- **callback** (function) - Required - The callback function with signature ({ added: Array, updated: Array, removed: Array }, [transactionOrigin:any]) => ..

### Returns
None

```

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

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

Source: https://github.com/yjs/docs/blob/main/api/document-updates.md

Sync two clients by exchanging the complete document structure. Both clients send their full state as an update and apply the received update to their local document.

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

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

### Use y-indexeddb provider with IndexeddbPersistence

Source: https://github.com/yjs/docs/blob/main/ecosystem/database-provider/y-indexeddb.md

Create an IndexeddbPersistence provider that loads available content from the database when the 'synced' event is fired. The provider instance is created with a document name and a Y.Doc instance.

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

const provider = new IndexeddbPersistence(docName, ydoc)

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

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

### Delta Changes in Transactions

Source: https://github.com/yjs/docs/blob/main/api/delta-format.md

Shows how delta format expresses multiple changes in a single event within a transaction, with examples of insert and delete operations.

```javascript
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'] }]
```

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

### Base64 Encoding with js-base64 (JavaScript)

Source: https://github.com/yjs/docs/blob/main/api/document-updates.md

Shows how to convert a Yjs document update (Uint8Array) to a Base64 string and back using the js-base64 library. Requires the js-base64 package to be installed.

```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)
```

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

### Create and embed a subdocument in a root document

Source: https://github.com/yjs/docs/blob/main/api/subdocuments.md

Shows how to create a root document, add a subdocument to a map, and insert initial content into the subdocument's text type.

```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)
```

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

### Transform to RelativePosition and back

Source: https://github.com/yjs/docs/blob/main/api/relative-positions.md

Creates a relative position from a type and index, then converts it back to an absolute position. The example checks that the resulting type and index match the original values.

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