@convex-localfirst/yjs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fanzzzd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,12 @@
+# @convex-localfirst/yjs
+
+Ship a [Yjs](https://github.com/yjs/yjs) CRDT (rich text, nested lists) over the
+convex-localfirst append-only log: each Yjs update is one insert-only row, so concurrent
+rich-text edits **merge** instead of last-writer-wins clobbering. Includes a framework-
+agnostic base64 codec, snapshot compaction, and a React `useCollaborativeDoc` hook.
+
+```bash
+npm install @convex-localfirst/yjs
+```
+
+Peer dependencies: `react`, `yjs`. MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { bytesToBase64, base64ToBytes, applyUpdateSafe, makeSnapshot, REMOTE_ORIGIN } from "./yjsSync.js";
+export { useCollaborativeDoc, type CollaborativeDocRow, type UseCollaborativeDocOptions } from "./useCollaborativeDoc.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+// @convex-localfirst/yjs — wire a Yjs CRDT (rich text, nested lists) onto a
+// local-first append-only log. The codec is framework-agnostic; the hook is React.
+export { bytesToBase64, base64ToBytes, applyUpdateSafe, makeSnapshot, REMOTE_ORIGIN } from "./yjsSync.js";
+export { useCollaborativeDoc } from "./useCollaborativeDoc.js";

package/dist/useCollaborativeDoc.d.ts

@@ -0,0 +1,51 @@
+import * as Y from "yjs";
+/** One persisted Yjs update row, as your backend stores it. `_id` is any stable
+ *  per-row identity (used to dedupe applied rows); `update` is a base64 update. */
+export interface CollaborativeDocRow {
+    readonly _id: string;
+    readonly update: string;
+}
+export interface UseCollaborativeDocOptions {
+    /** Document identity — the Y.Doc is keyed on this alone, so it must uniquely identify the
+     *  document across EVERY scope this hook is used in. If your ids are only unique per
+     *  workspace/project, pass a composite (e.g. `` `${workspaceId}:${docId}` ``) or the doc
+     *  could merge rows across scopes. Changing it rebuilds the Y.Doc; also pass `key={docId}`
+     *  to the editor component so it remounts. */
+    readonly docId: string;
+    /** Live rows for THIS document, from your own reactive query. The hook applies EVERY row you
+     *  pass — it has no docId field to filter on — so scope/`.where` your query to exactly this
+     *  document; a stray row from another doc would merge into this Y.Doc. Pass a stable reference
+     *  when unchanged (a local-first `useLiveQuery` does this) so the apply effect only fires on new rows. */
+    readonly updates: ReadonlyArray<CollaborativeDocRow>;
+    /** Persist a local edit as a new insert-only row. Receives the base64 update;
+     *  bind your docId/scope in the closure. May return a promise (awaited during compaction). */
+    readonly append: (updateBase64: string) => unknown;
+    /** Delete a row subsumed by a snapshot. Provide it to enable compaction; omit to disable —
+     *  then both the row log AND the in-memory applied-set grow unbounded over the doc's lifetime.
+     *  May return a promise. */
+    readonly prune?: (rowId: string) => unknown;
+    /** Compact once the row count crosses this many (default 50). No effect without `prune`. */
+    readonly compactThreshold?: number;
+}
+/**
+ * A Y.Doc whose content syncs through a local-first append-only log: every Yjs
+ * update is one insert-only row. Local edits become rows (via `append`); rows from
+ * other clients (or this client's reload) are applied back into the Y.Doc. Offline
+ * edits queue as pending rows and flush on reconnect — fully local-first.
+ *
+ * Backend-agnostic: YOU supply the live `updates` and the `append`/`prune` callbacks,
+ * so it works with any table name / scope shape. Bind an editor to the returned doc,
+ * e.g. BlockNote → `doc.getXmlFragment("blocknote")`, TipTap → a `y-prosemirror` binding.
+ *
+ * ```ts
+ * const updates = useLiveQuery(collection("doc_updates").scope({ workspaceId }).where(u => u.docId === docId)) ?? [];
+ * const appendRow = useMutation(api.docUpdates.append);
+ * const pruneRow = useMutation(api.docUpdates.prune);
+ * const doc = useCollaborativeDoc({
+ *   docId, updates,
+ *   append: (update) => appendRow({ workspaceId, docId, update }).local,
+ *   prune: (id) => pruneRow({ id }).local
+ * });
+ * ```
+ */
+export declare function useCollaborativeDoc(options: UseCollaborativeDocOptions): Y.Doc;

package/dist/useCollaborativeDoc.js

@@ -0,0 +1,86 @@
+import { useEffect, useMemo, useRef } from "react";
+import * as Y from "yjs";
+import { REMOTE_ORIGIN, applyUpdateSafe, bytesToBase64, makeSnapshot } from "./yjsSync.js";
+/**
+ * A Y.Doc whose content syncs through a local-first append-only log: every Yjs
+ * update is one insert-only row. Local edits become rows (via `append`); rows from
+ * other clients (or this client's reload) are applied back into the Y.Doc. Offline
+ * edits queue as pending rows and flush on reconnect — fully local-first.
+ *
+ * Backend-agnostic: YOU supply the live `updates` and the `append`/`prune` callbacks,
+ * so it works with any table name / scope shape. Bind an editor to the returned doc,
+ * e.g. BlockNote → `doc.getXmlFragment("blocknote")`, TipTap → a `y-prosemirror` binding.
+ *
+ * ```ts
+ * const updates = useLiveQuery(collection("doc_updates").scope({ workspaceId }).where(u => u.docId === docId)) ?? [];
+ * const appendRow = useMutation(api.docUpdates.append);
+ * const pruneRow = useMutation(api.docUpdates.prune);
+ * const doc = useCollaborativeDoc({
+ *   docId, updates,
+ *   append: (update) => appendRow({ workspaceId, docId, update }).local,
+ *   prune: (id) => pruneRow({ id }).local
+ * });
+ * ```
+ */
+export function useCollaborativeDoc(options) {
+    const { docId, updates, compactThreshold = 50 } = options;
+    // Latest callbacks via a ref so the update-handler effect doesn't re-subscribe on
+    // every render when the caller passes fresh closures.
+    const cbs = useRef(options);
+    cbs.current = options;
+    // Fresh Y.Doc (and applied-set) per document. Pairing them in one memo keeps the
+    // dedup set tied to the exact doc instance it tracks.
+    const { doc, applied } = useMemo(() => ({ doc: new Y.Doc(), applied: new Set() }), [docId]);
+    useEffect(() => () => doc.destroy(), [doc]);
+    // Apply not-yet-applied rows (initial hydrate + live remote edits). Applying in any
+    // order, or the same row twice, is safe (Yjs is a CRDT). REMOTE_ORIGIN marks these
+    // so our own "update" handler below doesn't re-broadcast them as new rows.
+    useEffect(() => {
+        for (const u of updates) {
+            if (applied.has(u._id))
+                continue;
+            applied.add(u._id); // mark seen even on failure — a corrupt row is permanently bad
+            applyUpdateSafe(doc, u.update, REMOTE_ORIGIN);
+        }
+    }, [updates, doc, applied]);
+    // Compaction: when the row count crosses the threshold, write one snapshot row (the
+    // whole doc state) and prune the rows it subsumes. Runs AFTER the apply effect above
+    // (so `doc` already reflects every row we're about to subsume). Guarded so it fires
+    // once per crossing; safe to race with other clients.
+    const compacting = useRef(false);
+    useEffect(() => {
+        const prune = cbs.current.prune;
+        if (!prune || compacting.current || updates.length <= compactThreshold)
+            return;
+        compacting.current = true;
+        const subsumed = updates.map((u) => u._id); // every row now folded into `doc`
+        const snapshot = makeSnapshot(doc); // = the full state these rows produced
+        void (async () => {
+            try {
+                // Snapshot first (lower row position) so any peer that sees the deletes also
+                // sees the snapshot that preserves their content.
+                await cbs.current.append(snapshot);
+                await Promise.all(subsumed.map((id) => prune(id)));
+                // Drop dedup entries for pruned rows so `applied` can't grow without bound across
+                // a doc's lifetime (the rows are gone; re-applying would be a no-op anyway).
+                for (const id of subsumed)
+                    applied.delete(id);
+            }
+            finally {
+                compacting.current = false;
+            }
+        })();
+    }, [updates, doc, applied, compactThreshold]);
+    // Persist local edits as rows. Skip REMOTE-origin updates (those just came from the
+    // apply effect) — otherwise we'd echo every remote edit back as a new row.
+    useEffect(() => {
+        const handler = (update, origin) => {
+            if (origin === REMOTE_ORIGIN)
+                return;
+            void cbs.current.append(bytesToBase64(update));
+        };
+        doc.on("update", handler);
+        return () => doc.off("update", handler);
+    }, [doc]);
+    return doc;
+}

package/dist/yjsSync.d.ts

@@ -0,0 +1,6 @@
+import * as Y from "yjs";
+export declare function bytesToBase64(bytes: Uint8Array): string;
+export declare function base64ToBytes(b64: string): Uint8Array;
+export declare const REMOTE_ORIGIN: unique symbol;
+export declare function makeSnapshot(doc: Y.Doc): string;
+export declare function applyUpdateSafe(doc: Y.Doc, base64: string, origin: unknown): boolean;

package/dist/yjsSync.js

@@ -0,0 +1,46 @@
+import * as Y from "yjs";
+// The glue that lets a Yjs CRDT ride an append-only local-first log.
+//
+// A Yjs document emits binary "updates" on every change. We store each update as
+// ONE insert-only row (base64 string). Yjs updates are commutative + idempotent,
+// so rows delivered in any order, at least once, always converge to the same
+// document — which is exactly what an append-only, no-conflict row stream gives.
+// Isomorphic base64 <-> bytes. The op log serializes values as JSON strings, so
+// binary updates travel as base64. A simple per-byte loop (no fromCharCode.apply)
+// avoids call-stack limits on large updates.
+export function bytesToBase64(bytes) {
+    let bin = "";
+    for (let i = 0; i < bytes.length; i++)
+        bin += String.fromCharCode(bytes[i]);
+    return btoa(bin);
+}
+export function base64ToBytes(b64) {
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+// Tags updates we applied FROM the row stream so the Y.Doc "update" handler does
+// not re-append them as new rows (which would loop forever). Any non-local origin
+// value works; a stable symbol is unambiguous.
+export const REMOTE_ORIGIN = Symbol("convex-localfirst-remote");
+// A compaction snapshot: the entire doc state encoded as ONE update. Applied to a
+// fresh Y.Doc it reproduces the full document, so it can replace (subsume) all the
+// incremental update rows merged into `doc` so far.
+export function makeSnapshot(doc) {
+    return bytesToBase64(Y.encodeStateAsUpdate(doc));
+}
+// Apply one base64 update, isolating failures: a single corrupt or incompatible
+// row (bad base64, a truncated/garbage update, a future-format update) must NOT
+// throw and brick the whole document — skip it and keep the rest. Returns whether
+// it applied, so callers can still mark it "seen" and not retry a permanently-bad row.
+export function applyUpdateSafe(doc, base64, origin) {
+    try {
+        Y.applyUpdate(doc, base64ToBytes(base64), origin);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@convex-localfirst/yjs",
+  "version": "0.1.0",
+  "description": "Yjs CRDT over the convex-localfirst append-only log: base64 codec, snapshot compaction, useCollaborativeDoc hook.",
+  "license": "MIT",
+  "keywords": [
+    "convex",
+    "local-first",
+    "yjs",
+    "crdt",
+    "collaborative"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "yjs": ">=13.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "jsdom": "^29.1.1",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0",
+    "yjs": "^13.6.31"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit false --emitDeclarationOnly false",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}