CRDT entry points
What edytor/crdt, edytor/crdt/edytor and edytor/protocol export, what bindCrdt(Y) returns, and when you need them instead of the document API.
Most apps never import the CRDT engine: createDocument, the sync factories and the <Edytor> component cover documents, persistence and collaboration. Reach for these entry points when you run edytor where Svelte cannot load, manage raw CRDT documents yourself, or build your own server or provider.
Entry points
| Import | Contents | Runs in |
|---|---|---|
edytor |
The <Edytor> component, plugins, the document API with its errors and JSON types, and the sync factories. |
A Svelte bundler |
edytor/crdt/edytor |
The document API (createDocument, loadDocument, attachDocument), the document’s full vocabulary, bindCrdt and attribution. No Svelte. |
Browser, Node, SSR, Workers |
edytor/protocol |
The wire vocabulary: bindCrdt, frames, message types, codecs, generation records, the admission gates, the raw provider classes. No Svelte. |
Browser, Node, SSR, Workers |
edytor/crdt |
The CRDT engine itself: edytor’s fork of Yjs v14. Import it as a namespace. | Anywhere |
edytor/cloudflare |
DocumentRoom, attachRoom(this, options) (a document in your own Durable Object) and routeDocumentSocket. See the server. |
Cloudflare Workers |
Import the engine only through edytor/crdt, so your app holds exactly one engine instance.
edytor/crdt: the engine
import * as Y from 'edytor/crdt';
import { bindCrdt } from 'edytor/crdt/edytor';
const crdt = bindCrdt(Y);
export function catchUp(stored: Uint8Array<ArrayBuffer>, updates: Uint8Array<ArrayBuffer>[], otherDoc: Y.Doc) {
// An edytor document: createDoc() carries edytor's rules, a bare new Y.Doc() does not.
const doc = crdt.createDoc();
Y.applyUpdate(doc, stored);
const merged = Y.mergeUpdates(updates);
const missing = Y.encodeStateAsUpdate(doc, Y.encodeStateVector(otherDoc));
return { merged, missing };
}
edytor/crdt is edytor’s own fork of Yjs v14, based on @y/y 14.0.0-rc.26. It is not the yjs package from npm: v13 documents and peers are not compatible with it, and you should not install yjs next to it expecting the two to share documents.
What it ships:
- documents (
Doc), nodes and transactions; - one update encoding (the columnar one upstream Yjs calls v2):
applyUpdate,encodeStateAsUpdate,mergeUpdates,diffUpdate,decodeUpdate,UpdateEncoder,UpdateDecoder,encodeStateVector,decodeStateVector; - positions as ids:
idAtIndex(node, index, assoc)(the id a position binds) andindexOfId(doc, id, assoc)(its live index and node); - id sets with their codec, and
RangeCursor.
A node’s writes are its methods (insert, delete, mark, setAttr, deleteAttr); its attributes read with getAttr, forEachAttr and attrKeys, its content with new Y.RangeCursor(node).read(from, to), the pieces of a range with their marks. A mark is a paired operation, mark(index, length, name, value, startSide, endSide) (value null removes it; each side, 0 or 1, decides whether an insert at that edge lands inside). A commit is told by the document’s events: commit (once per transaction, with transaction.changed), then afterTransaction; nodes have no observers.
import * as Y from 'edytor/crdt';
export function boldText(node: Y.Node): string[] {
const out: string[] = [];
for (const piece of new Y.RangeCursor(node).read(0, node.length)) {
if (piece.formats?.bold === true && piece.content instanceof Y.ContentString) {
out.push(piece.content.str.slice(piece.offset, piece.offset + piece.len));
}
}
return out;
}
What was pruned: the delta layer (toDelta, applyDelta, node.delta, a node’s 'delta' event, event.delta, Node.from), the renderers, the schemas ($doc, $nodeAny, $idSet), id maps and content maps, snapshots, the v1 update encoding, the undo manager, the update logging and obfuscation helpers, relative-position objects, id-set algebra beyond the basics, the content-id helpers, plain formats and their cleanup, observers and events on nodes, subdocuments and the load state, the JSON, embed and subdocument contents, and a node’s renderings (toJSON, toString, toArray). Edytor never used them at run time; without the delta layer every app ships about 54 KB less JavaScript. A document built from an update is a new document followed by Y.applyUpdate(doc, update): bindCrdt(Y).createDoc() when the update holds edytor content (see the keep-replaced rule below), new Y.Doc() only for a document that never holds any.
What was added: the struct primitives edytor’s own undo manager replays a step with (redoItem, keepItem, followRedone). The history is edytor’s (document.history): it decides how deleted text comes back and keeps a block a peer wrote into when its creation is undone, which is what makes concurrent undo behave.
The fork also lets a document keep the node a concurrent write of the same map key replaced, with its subtree (doc.keepReplaced, a predicate, null by default). Every edytor document carries edytor’s rule (two writers creating one block id at once keep both texts): the documents createDocument, attachDocument and bindCrdt(Y).createDoc() give you, and any document a facade binds. The engine’s class default stays null, so another document of the same engine in your app keeps the upstream behavior. A document must carry the rule before it integrates edytor content: build it with createDoc() rather than new Y.Doc() followed by Y.applyUpdate. A document that holds state without the rule is refused: attachDocument and a facade throw a TypeError instead of adopting it.
edytor/crdt/edytor
The same document surface as edytor, safe to import in Node, SSR and Workers:
import { createDocument, loadDocument, attachDocument, bindCrdt } from 'edytor/crdt/edytor';
It exports the document factories and errors (SchemaMismatchError, SyncRefusedError, …), the document vocabulary types (BlockSpec, Destination, ProjectedDoc, DocChange, OpResult, DocAnchor, JSONDoc, …), the block roles (defaultSemantics, semanticsOf), Awareness, the sync types, attribution and bindCrdt. The document factories are already bound to the engine: you do not need bindCrdt to create, load or edit documents.
edytor/protocol
The wire and coordinator vocabulary: the protocol helpers (frames, message types, the chunk and awareness codecs, the lib0 readers and writers, the generation records, CLOSE), the admission gates (assertAdmission, inspectAdmission, checkSchema, isInitialized, …), bindCrdt and the raw provider classes IndexeddbPersistence and WebsocketProvider with their option and event types. A server of your own, a relay or a test client imports it; an application does not.
import { IndexeddbPersistence, inspectAdmission } from 'edytor/protocol';
attachDocument(doc, options?) builds an EdytorDocument around a raw CRDT document you own. It starts pending and never seeds; destroy() releases the document services but leaves your doc alive. Attaching the same raw document twice returns the same EdytorDocument (each attach needs its own destroy()).
bindCrdt(Y)
bindCrdt binds edytor’s CRDT services to an engine namespace. Use it when you need the provider classes or the sync protocol on documents you manage yourself.
import * as Y from 'edytor/crdt';
import { bindCrdt } from 'edytor/crdt/edytor';
const crdt = bindCrdt(Y);
const doc = crdt.createDoc();
const awareness = new crdt.Awareness(doc);
const provider = new crdt.providers.IndexeddbPersistence('notes/today', doc, { awareness });
await provider.whenSynced;
| Member | Contents |
|---|---|
createDoc(options?) |
A new document on the bound engine (new Y.Doc(options)) carrying edytor’s keep-replaced rule. Build every raw document that holds edytor content with it; a bare new Y.Doc() is for documents that never do. |
Awareness |
The presence class. |
.doc |
The document-model layer over a raw doc: create(doc, config?) returns a bare facade with no history and no attribution, plus init, seed, restore, isInitialized, schemaVersion, checkSchema, assertSchema and the schema constants. |
.providers |
IndexeddbPersistence, WebsocketProvider, createIndexeddbSync, createWebsocketSync, clearDocument, storeState. |
.sync |
The sync protocol readers and writers, applyRemote, lacks, writeSaved, readSaved. See the protocol. |
.admission |
admitUpdate(update, name?): decode bytes onto a scratch document, check them, and return the document, or throw. |
.attribution |
The attribution service that documents attach automatically. |
When you need which
| You want to | Use |
|---|---|
| Edit documents in the browser | edytor: <Edytor> and createDocument. |
| Read or write documents in Node, SSR or a Worker | edytor/crdt/edytor: createDocument, loadDocument. |
| Persist or sync a raw doc outside the document API | bindCrdt(Y).providers, or the provider classes of edytor/protocol. |
| Store, merge or inspect updates on a server | edytor/crdt (mergeUpdates, encodeStateVector, …) with bindCrdt(Y).sync. |
| Run the collaboration server | edytor/cloudflare, or edytor/protocol (the protocol) for another platform. |