y-protocols

What is y-protocols?

The y-protocols npm package provides a set of protocols for building collaborative applications using Yjs, a high-performance CRDT (Conflict-free Replicated Data Type) framework. It includes protocols for awareness, WebRTC, and WebSocket communication, enabling real-time collaboration features such as shared editing and presence awareness.

What are y-protocols's main functionalities?

Awareness Protocol

The Awareness protocol allows you to manage and track the presence and state of users in a collaborative session. This can be used to show who is online and their current activity or status.

const { Awareness } = require('y-protocols/awareness');
const awareness = new Awareness(doc);

// Set user state
awareness.setLocalStateField('user', { name: 'Alice' });

// Listen for changes in awareness
awareness.on('change', changes => {
  console.log('Awareness changed:', changes);
});

WebRTC Protocol

The WebRTC protocol enables peer-to-peer communication for real-time collaboration. It allows users to connect directly to each other without the need for a central server.

const { WebrtcProvider } = require('y-protocols/webrtc');
const provider = new WebrtcProvider('my-room-name', doc);

// Listen for connection events
provider.on('synced', () => {
  console.log('Synced with WebRTC peers');
});

WebSocket Protocol

The WebSocket protocol facilitates real-time communication over WebSocket connections. This is useful for scenarios where a central server is required to manage connections and data synchronization.

const { WebsocketProvider } = require('y-protocols/websocket');
const provider = new WebsocketProvider('wss://my-websocket-server', 'my-room-name', doc);

// Listen for connection events
provider.on('status', event => {
  console.log('WebSocket connection status:', event.status);
});

Other packages similar to y-protocols

automerge

Automerge is a library for building collaborative applications using CRDTs. It provides similar functionality to Yjs and y-protocols, allowing for real-time collaboration and conflict resolution. However, Automerge focuses more on simplicity and ease of use, while Yjs and y-protocols offer higher performance and more advanced features.

sharedb

ShareDB is a real-time database backend based on Operational Transformation (OT). It allows multiple users to collaborate on the same data in real-time. While ShareDB uses OT instead of CRDTs, it provides similar real-time collaboration features and can be used with WebSocket for communication.

gun

Gun is a decentralized, real-time, graph database that supports real-time data synchronization and offline-first capabilities. It provides similar real-time collaboration features as y-protocols but focuses on decentralized data storage and peer-to-peer communication.

README

Yjs Protocols

Binary encoding protocols for syncing, awareness, and history inforamtion

This API is unstable and subject to change.

API

Awareness Protocoll

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

awarenessProtocol.Awareness Class

The Awareness class implements a simple network agnostic protocol to propagate awareness information like cursor, username, or status. Each client can update its own local state and listen to state changes of remote clients.

const awareness = new awarenessProtocol.Awareness()

getLocalState():Object<string,any>|null

Get the local awareness state.

setLocalState(Object<string,any>|null)

Set/Update the local awareness state. Set `null` to mark the local client as offline.

setLocalStateField(string, any)

Only update a single field on the local awareness object. Does not do anything if the local state is not set.

getStates():Map<number,Object<string,any>>

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

on('change', ({ added: Array<number>, updated: Array<number> removed: Array<number> }, [transactionOrigin:any]) => ..)

Listen to remote and local changes on the awareness instance.

License

The MIT License © Kevin Jahns