@syncular/crdt-yjs 0.2.0

package/README.md

@@ -0,0 +1,10 @@
+# @syncular/crdt-yjs
+
+Yjs CRDT integration for Syncular columns.
+
+Part of [Syncular](https://syncular.dev) — an offline-first sync framework.
+See the [Syncular repository](https://github.com/syncular/syncular) for docs.
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @syncular/crdt-yjs — the reference Yjs binding for CRDT columns
+ * (SPEC.md §5.10). Two faces of one Yjs integration:
+ *
+ * - the SERVER-side `yjsDocMerger` (§5.10.2): a `CrdtMerger` for `crdtType`
+ *   `'yjs-doc'` — this is where Yjs is *required*, so it lives here, never in
+ *   `@syncular/core` or `@syncular/server` (the blob-store rule,
+ *   §5.9.2);
+ * - the CLIENT-side `YjsColumn` helper (§5.10.4): a thin `Y.Doc` wrapper an
+ *   app uses to produce update bytes for a `crdt` column and to apply
+ *   server-merged bytes back. Codegen has no Yjs dependency; this accessor
+ *   does.
+ *
+ * Yjs enters the dependency tree exactly here.
+ */
+import type { CrdtMerger, CrdtMergerRegistry } from '@syncular/server';
+import * as Y from 'yjs';
+/** The one built-in `crdtType` this rung defines (§5.10.1). */
+export declare const YJS_DOC_CRDT_TYPE = "yjs-doc";
+/**
+ * §5.10.2 merger for `crdtType` `'yjs-doc'`. `stored` and `incoming` are Yjs
+ * updates (or a full doc state — a state is a legal update). Merge = apply
+ * both into a fresh doc and re-encode the whole state as one update. This is
+ * commutative, associative, and idempotent (the Yjs CRDT contract), so
+ * concurrent pushes converge order-independently and a replayed update is a
+ * no-op (§5.10.3).
+ */
+export declare const yjsDocMerger: CrdtMerger;
+/** A registry pre-wired with the `yjs-doc` merger — pass to the server ctx
+ * `crdtMergers` (§5.10.2). Spread to add host mergers. */
+export declare const yjsCrdtMergers: CrdtMergerRegistry;
+/**
+ * §5.10.4 client helper: a `Y.Doc` bound to one `crdt` column value. The app
+ * mutates the doc (its shared types) and reads `columnBytes()` to store in a
+ * `mutate` (baseVersion-less, §5.10.3); on delivery of server-merged bytes it
+ * calls `applyServerBytes()`. The raw bytes are the transport; the doc is the
+ * app-visible collaborative value.
+ */
+export declare class YjsColumn {
+    readonly doc: Y.Doc;
+    constructor(initial?: Uint8Array | null);
+    /** A shared text (the common collaborative-text case). */
+    text(name?: string): Y.Text;
+    /** A shared map. */
+    map(name?: string): Y.Map<unknown>;
+    /** The bytes to store in the `crdt` column (the full doc state as an
+     * update). Idempotent on the server merger, so pushing the whole state is
+     * safe even though it is larger than a per-edit delta — apps that want the
+     * minimal delta can diff with `Y.encodeStateAsUpdate(doc, stateVector)`. */
+    columnBytes(): Uint8Array;
+    /** Apply server-merged bytes (a pull COMMIT upsert, a segment row, or a
+     * conflict `serverRow`) into the local doc — idempotent (§5.10.4). */
+    applyServerBytes(bytes: Uint8Array): void;
+    destroy(): void;
+}
+export { Y };

package/dist/index.js

@@ -0,0 +1,85 @@
+/**
+ * @syncular/crdt-yjs — the reference Yjs binding for CRDT columns
+ * (SPEC.md §5.10). Two faces of one Yjs integration:
+ *
+ * - the SERVER-side `yjsDocMerger` (§5.10.2): a `CrdtMerger` for `crdtType`
+ *   `'yjs-doc'` — this is where Yjs is *required*, so it lives here, never in
+ *   `@syncular/core` or `@syncular/server` (the blob-store rule,
+ *   §5.9.2);
+ * - the CLIENT-side `YjsColumn` helper (§5.10.4): a thin `Y.Doc` wrapper an
+ *   app uses to produce update bytes for a `crdt` column and to apply
+ *   server-merged bytes back. Codegen has no Yjs dependency; this accessor
+ *   does.
+ *
+ * Yjs enters the dependency tree exactly here.
+ */
+import * as Y from 'yjs';
+/** The one built-in `crdtType` this rung defines (§5.10.1). */
+export const YJS_DOC_CRDT_TYPE = 'yjs-doc';
+/**
+ * §5.10.2 merger for `crdtType` `'yjs-doc'`. `stored` and `incoming` are Yjs
+ * updates (or a full doc state — a state is a legal update). Merge = apply
+ * both into a fresh doc and re-encode the whole state as one update. This is
+ * commutative, associative, and idempotent (the Yjs CRDT contract), so
+ * concurrent pushes converge order-independently and a replayed update is a
+ * no-op (§5.10.3).
+ */
+export const yjsDocMerger = (stored, incoming) => {
+    const doc = new Y.Doc();
+    try {
+        if (stored !== null && stored.length > 0)
+            Y.applyUpdate(doc, stored);
+        if (incoming.length > 0)
+            Y.applyUpdate(doc, incoming);
+        return Y.encodeStateAsUpdate(doc);
+    }
+    finally {
+        doc.destroy();
+    }
+};
+/** A registry pre-wired with the `yjs-doc` merger — pass to the server ctx
+ * `crdtMergers` (§5.10.2). Spread to add host mergers. */
+export const yjsCrdtMergers = {
+    [YJS_DOC_CRDT_TYPE]: yjsDocMerger,
+};
+/**
+ * §5.10.4 client helper: a `Y.Doc` bound to one `crdt` column value. The app
+ * mutates the doc (its shared types) and reads `columnBytes()` to store in a
+ * `mutate` (baseVersion-less, §5.10.3); on delivery of server-merged bytes it
+ * calls `applyServerBytes()`. The raw bytes are the transport; the doc is the
+ * app-visible collaborative value.
+ */
+export class YjsColumn {
+    doc;
+    constructor(initial) {
+        this.doc = new Y.Doc();
+        if (initial !== undefined && initial !== null && initial.length > 0) {
+            Y.applyUpdate(this.doc, initial);
+        }
+    }
+    /** A shared text (the common collaborative-text case). */
+    text(name = 'text') {
+        return this.doc.getText(name);
+    }
+    /** A shared map. */
+    map(name = 'map') {
+        return this.doc.getMap(name);
+    }
+    /** The bytes to store in the `crdt` column (the full doc state as an
+     * update). Idempotent on the server merger, so pushing the whole state is
+     * safe even though it is larger than a per-edit delta — apps that want the
+     * minimal delta can diff with `Y.encodeStateAsUpdate(doc, stateVector)`. */
+    columnBytes() {
+        return Y.encodeStateAsUpdate(this.doc);
+    }
+    /** Apply server-merged bytes (a pull COMMIT upsert, a segment row, or a
+     * conflict `serverRow`) into the local doc — idempotent (§5.10.4). */
+    applyServerBytes(bytes) {
+        if (bytes.length > 0)
+            Y.applyUpdate(this.doc, bytes);
+    }
+    destroy() {
+        this.doc.destroy();
+    }
+}
+export { Y };

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@syncular/crdt-yjs",
+  "version": "0.2.0",
+  "description": "Yjs CRDT integration for Syncular columns",
+  "license": "Apache-2.0",
+  "author": "Benjamin Kniffler",
+  "homepage": "https://syncular.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/syncular/syncular.git",
+    "directory": "packages/crdt-yjs"
+  },
+  "bugs": {
+    "url": "https://github.com/syncular/syncular/issues"
+  },
+  "keywords": [
+    "sync",
+    "offline-first",
+    "realtime",
+    "database",
+    "typescript"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "browser": "./src/index.ts",
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts"
+  ],
+  "dependencies": {
+    "@syncular/core": "0.2.0",
+    "yjs": "^13.6.0"
+  },
+  "devDependencies": {
+    "@syncular/server": "0.2.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,94 @@
+/**
+ * @syncular/crdt-yjs — the reference Yjs binding for CRDT columns
+ * (SPEC.md §5.10). Two faces of one Yjs integration:
+ *
+ * - the SERVER-side `yjsDocMerger` (§5.10.2): a `CrdtMerger` for `crdtType`
+ *   `'yjs-doc'` — this is where Yjs is *required*, so it lives here, never in
+ *   `@syncular/core` or `@syncular/server` (the blob-store rule,
+ *   §5.9.2);
+ * - the CLIENT-side `YjsColumn` helper (§5.10.4): a thin `Y.Doc` wrapper an
+ *   app uses to produce update bytes for a `crdt` column and to apply
+ *   server-merged bytes back. Codegen has no Yjs dependency; this accessor
+ *   does.
+ *
+ * Yjs enters the dependency tree exactly here.
+ */
+
+import type { CrdtMerger, CrdtMergerRegistry } from '@syncular/server';
+import * as Y from 'yjs';
+
+/** The one built-in `crdtType` this rung defines (§5.10.1). */
+export const YJS_DOC_CRDT_TYPE = 'yjs-doc';
+
+/**
+ * §5.10.2 merger for `crdtType` `'yjs-doc'`. `stored` and `incoming` are Yjs
+ * updates (or a full doc state — a state is a legal update). Merge = apply
+ * both into a fresh doc and re-encode the whole state as one update. This is
+ * commutative, associative, and idempotent (the Yjs CRDT contract), so
+ * concurrent pushes converge order-independently and a replayed update is a
+ * no-op (§5.10.3).
+ */
+export const yjsDocMerger: CrdtMerger = (stored, incoming) => {
+  const doc = new Y.Doc();
+  try {
+    if (stored !== null && stored.length > 0) Y.applyUpdate(doc, stored);
+    if (incoming.length > 0) Y.applyUpdate(doc, incoming);
+    return Y.encodeStateAsUpdate(doc);
+  } finally {
+    doc.destroy();
+  }
+};
+
+/** A registry pre-wired with the `yjs-doc` merger — pass to the server ctx
+ * `crdtMergers` (§5.10.2). Spread to add host mergers. */
+export const yjsCrdtMergers: CrdtMergerRegistry = {
+  [YJS_DOC_CRDT_TYPE]: yjsDocMerger,
+};
+
+/**
+ * §5.10.4 client helper: a `Y.Doc` bound to one `crdt` column value. The app
+ * mutates the doc (its shared types) and reads `columnBytes()` to store in a
+ * `mutate` (baseVersion-less, §5.10.3); on delivery of server-merged bytes it
+ * calls `applyServerBytes()`. The raw bytes are the transport; the doc is the
+ * app-visible collaborative value.
+ */
+export class YjsColumn {
+  readonly doc: Y.Doc;
+
+  constructor(initial?: Uint8Array | null) {
+    this.doc = new Y.Doc();
+    if (initial !== undefined && initial !== null && initial.length > 0) {
+      Y.applyUpdate(this.doc, initial);
+    }
+  }
+
+  /** A shared text (the common collaborative-text case). */
+  text(name = 'text'): Y.Text {
+    return this.doc.getText(name);
+  }
+
+  /** A shared map. */
+  map(name = 'map'): Y.Map<unknown> {
+    return this.doc.getMap(name);
+  }
+
+  /** The bytes to store in the `crdt` column (the full doc state as an
+   * update). Idempotent on the server merger, so pushing the whole state is
+   * safe even though it is larger than a per-edit delta — apps that want the
+   * minimal delta can diff with `Y.encodeStateAsUpdate(doc, stateVector)`. */
+  columnBytes(): Uint8Array {
+    return Y.encodeStateAsUpdate(this.doc);
+  }
+
+  /** Apply server-merged bytes (a pull COMMIT upsert, a segment row, or a
+   * conflict `serverRow`) into the local doc — idempotent (§5.10.4). */
+  applyServerBytes(bytes: Uint8Array): void {
+    if (bytes.length > 0) Y.applyUpdate(this.doc, bytes);
+  }
+
+  destroy(): void {
+    this.doc.destroy();
+  }
+}
+
+export { Y };