y-webxdc

Webxdc applications can be shared in chat with messengers like Delta Chat and Cheogram.

Webxdc applications can support collaborative editing: multiple users, each running their own application instance (a "chat peer") over a shared chat channel all editing the same document, or interacting with the same database.

Synchronizing arbitrary application state is an advanced computer science problem. One popular solution is the conflict-free replicated data type, or CRDT for short.

Yjs is a JavaScript library that implements CRDT for JavaScript data structures such as text, arrays and maps.

This library, y-webxdc, provides an integration of Yjs with Webxdc. It tries to make building collaborative live editing more approachable for Webxdc. It ensures that updates to your application's state are distributed to other chat peers of that same application in a shared chat channel.

What does y-webxdc provide?

• You use Yjs shared data types for your application state, and WebxdcProvider in this lib makes it work with Webxdc.

• You can also use Yjs awareness to share ephemeral awareness and presence information (such as user status information, cursor locations, etc).

• Receiving updates to application state from chat peers.

• Autosave: automatically send application state changes periodically to chat peers.

• Manual save: call syncToChatPeers() to cause an immediate save (it's fine to mix manual with autosave).

• Realtime support: by using a protocol that supports realtime, apps can send and receive application updates as well as awareness information more quickly.

• Control which metadata is shown in a chat by setting document, summary and chat-message information (see the screenshots below).

• Reliably save any pending application state changes when the app window closes, on all webxdc-supporting platforms.

Protocols

Webxdc is inherently an unreliable channel, so messages can get lost and be reordered. We support different protocols in which applications transmit state, each with different trade-offs. We list the most important protocols here.

We are working on new protocols that ensure applications stay in sync yet also send small updates.

sendAllProtocol

The default protocol, sendAllProtocol, forces consistency over unreliable message delivery by sending the entire application state sent every update. Incoming state is merged into the local state using yjs.

This guarantees that application instances synchronize eventually, but also means that if application state gets large, the update messages may become unwieldy.

incrementalProtocol

This protocol was the previous default behavior of y-webxdc before version 1.3.0. Only the edits are sent over the network, meaning that the update messages do not become large. But the major drawback is that if an update message is lost, applications can become permanently desynchronized.

realtimeProtocol

This protocol has the behavior of sendAllProtocol, sending the source of truth as regular webxdc updates. In addition, it sends information over the realtime channel as well if this channel is available. The information it sends over the realtime channel consists of incremental updates (using incrementalProtocol) as well as awareness/presence information.

Because it behaves like sendAllProtocol, this protocol guarantees application instances stay in sync, but also shares it drawback of potential update messages of unwieldy size.

Setup

Install

npm i y-webxdc

API docs

For a complete overview of the API, see API docs.

Client code

import * as Y from "yjs";
import { WebxdcProvider } from "y-webxdc";

// provided by messengers or webxdc-dev tool
// see https://docs.webxdc.org/spec.html
const webxdc = window.webxdc;

const ydoc = new Y.Doc();
const yarray = ydoc.get("array", Y.Array);
const provider = new WebxdcProvider({
  webxdc,
  ydoc,
  getEditInfo: () => {
    const document = "webxdc yjs provider";
    const summary = `Last edit: ${webxdc.selfName}`;
    const startinfo = `${webxdc.selfName} editing ${document}`;
    return { document, summary, startinfo };
  },
});

See the following example for the meaning of document, summary and startinfo as returned by the getEditInfo callback passed into the provider.

Example

The webxdc editor uses y-webxdc to implement a collaborative editor.

Development

This project is written in TypeScript and uses pnpm. Install dependencies with:

pnpm install

Test

Run the test suite (vitest):

pnpm test

Build

Compile src/ to dist/ (JavaScript plus type declarations):

pnpm build

Type check

Check types without emitting any output:

pnpm typecheck

Code Style

Linting with eslint and formatting with prettier:

pnpm lint
pnpm lint:fix
pnpm format

pnpm lint:fix applies eslint fixes; pnpm format reformats with prettier.

Check everything

pnpm check runs the formatting check, the type checker, the linter and the tests together:

pnpm check