y-webxdc

Check API docs Repository

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.

• 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).

• 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.

Technical Limitations

Since Webxdc is inherently an unreliable channel messages can get lost. To force consistency over unreliable message delivery, the entire application state is sent every update. Incoming state is merged into the local state using yjs.

This may lead to issues if the application state gets large.Yjs provides more sophisticated mechanisms to send updates, but those provide challenges over a lossy broadcast network that this library has not solved as of yet.

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.

Editor running Delta Chat desktop

Showing edit information in chat

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