@doubling/compound-sync 1.12.4 → 1.12.6

package/yjs-file-binding.js

@@ -16,221 +16,234 @@
 // touching the filesystem and so the daemon can plumb its existing
 // suppressLocal set (avoids the disk write feeding back through
 // chokidar as a fake user edit).
-
 import * as Y from 'yjs';
 import fastDiff from 'fast-diff';
 import { YjsProvider } from './yjs-provider.js';
-
 export class YjsFileBinding {
-  constructor(store, {
-    debounceMs = 300, onDiskWrite, onDocStateChange,
-    initialDocState = null, currentDiskText = null,
-  }) {
-    if (!onDiskWrite) throw new Error('YjsFileBinding: onDiskWrite is required');
-    this.doc = new Y.Doc();
-    this.ytext = this.doc.getText('content');
-    this.store = store;
-    this.provider = new YjsProvider(this.doc, store);
-    this.debounceMs = debounceMs;
-    this.onDiskWrite = onDiskWrite;
-    // Called after every Y.Doc mutation reaches a stable state, with
-    // the encoded Y.Doc binary state. The daemon persists this to
-    // disk so the next startup can restore the baseline and merge
-    // offline disk edits without losing offline cloud edits (DOU-209).
-    this.onDocStateChange = onDocStateChange ?? null;
-    // Restore options for offline-merge (DOU-209).
-    this.initialDocState = initialDocState;
-    this.currentDiskText = currentDiskText;
-    this.flushTimer = null;
-    this.lastDiskText = null;
-    this.observer = null;
-    this.stopped = false;
-  }
-
-  async start() {
-    // DOU-209: offline-merge startup. Three-step process that turns the
-    // daemon's restart into a deterministic CRDT merge:
-    //
-    //   1. Restore Y.Doc from the daemon's last-saved binary state (if
-    //      any). After this, ytext equals what disk was at the daemon's
-    //      last write. This is the common ancestor for any divergence
-    //      that happened while the daemon was offline.
-    //   2. If the current disk content differs from the restored ytext,
-    //      the difference is disk-only edits made during downtime.
-    //      Apply them as Y.Doc operations (positions are valid in the
-    //      restored ytext since restored-ytext == lastDisk == fast-diff
-    //      input).
-    //   3. provider.loadInitial() pulls cloud's yupdates on top. Y.applyUpdate
-    //      is idempotent (Yjs's state-vector dedup), so already-known
-    //      ops are no-ops. Only NEW cloud ops (offline web edits) take
-    //      effect. They CRDT-merge with the disk ops from step 2.
-    //
-    // Without step 1, fast-diff(post-loadInitial-ytext, currentDisk)
-    // treats web's offline insertions as "things present in ytext but
-    // missing from disk" and DELETES them. That's the bug this fixes.
-    // Seed lastDiskText from the disk content we observed at construction
-    // time so the initial flush is a no-op when ytext already matches
-    // what's on disk. Without this, the binding's initial flush always
-    // wrote ytext to disk on startup, which clobbered any content the
-    // daemon's legacy contentHash + Storage blob pull (the fallthrough
-    // path in handleFirestoreChange) may have written first for non-Yjs
-    // cloud edits. Regression case: "after restart, pulls a web edit
-    // made while stopped despite a fresh local mtime" in
-    // sync/org-sync.test.js.
-    this.lastDiskText = this.currentDiskText;
-
-    if (this.initialDocState) {
-      Y.applyUpdate(this.doc, this.initialDocState);
+    doc;
+    ytext;
+    store;
+    provider;
+    debounceMs;
+    onDiskWrite;
+    onDocStateChange;
+    initialDocState;
+    currentDiskText;
+    flushTimer = null;
+    lastDiskText = null;
+    observer = null;
+    stopped = false;
+    constructor(store, { debounceMs = 300, onDiskWrite, onDocStateChange, initialDocState = null, currentDiskText = null, }) {
+        if (!onDiskWrite)
+            throw new Error('YjsFileBinding: onDiskWrite is required');
+        this.doc = new Y.Doc();
+        this.ytext = this.doc.getText('content');
+        this.store = store;
+        this.provider = new YjsProvider(this.doc, store);
+        this.debounceMs = debounceMs;
+        this.onDiskWrite = onDiskWrite;
+        // Called after every Y.Doc mutation reaches a stable state, with
+        // the encoded Y.Doc binary state. The daemon persists this to
+        // disk so the next startup can restore the baseline and merge
+        // offline disk edits without losing offline cloud edits (DOU-209).
+        this.onDocStateChange = onDocStateChange ?? null;
+        // Restore options for offline-merge (DOU-209).
+        this.initialDocState = initialDocState;
+        this.currentDiskText = currentDiskText;
     }
-
-    // Disk-merge ops emitted below need to reach the store so other
-    // clients see the offline disk edits. The provider's local-update
-    // handler isn't attached yet (it's wired in startSubscription,
-    // which we can't call until after loadInitial), so we capture the
-    // updates synchronously here and push them after the subscription
-    // is set up. Capture by Y.Doc 'update' event with a 'disk' origin
-    // filter so we only grab the ops from our own _applyTextDiff and
-    // not anything spurious.
-    //
-    // The disk-merge is only safe when we have an `initialDocState`:
-    // that gives ytext a known baseline (the daemon's last view of the
-    // file) before we diff against currentDiskText, so fast-diff
-    // positions are valid AND the resulting ops are scoped to JUST the
-    // disk-only changes. Without a baseline, applying currentDiskText
-    // as fresh inserts on top of an empty ytext would then collide
-    // with whatever loadInitial pulls from the cloud: Yjs would see
-    // both the daemon's "fresh insert" and the cloud's "original
-    // insert" as concurrent ops, producing duplicated content. So on
-    // first contact (no saved state) we skip the disk merge and let
-    // loadInitial + initial flush behave the same as before DOU-209.
-    const capturedDiskUpdates = [];
-    if (this.initialDocState && this.currentDiskText != null) {
-      const restored = this.ytext.toString();
-      if (this.currentDiskText !== restored) {
-        const captureHandler = (update, origin) => {
-          if (origin === 'disk') capturedDiskUpdates.push(update);
+    async start() {
+        // DOU-209: offline-merge startup. Three-step process that turns the
+        // daemon's restart into a deterministic CRDT merge:
+        //
+        //   1. Restore Y.Doc from the daemon's last-saved binary state (if
+        //      any). After this, ytext equals what disk was at the daemon's
+        //      last write. This is the common ancestor for any divergence
+        //      that happened while the daemon was offline.
+        //   2. If the current disk content differs from the restored ytext,
+        //      the difference is disk-only edits made during downtime.
+        //      Apply them as Y.Doc operations (positions are valid in the
+        //      restored ytext since restored-ytext == lastDisk == fast-diff
+        //      input).
+        //   3. provider.loadInitial() pulls cloud's yupdates on top. Y.applyUpdate
+        //      is idempotent (Yjs's state-vector dedup), so already-known
+        //      ops are no-ops. Only NEW cloud ops (offline web edits) take
+        //      effect. They CRDT-merge with the disk ops from step 2.
+        //
+        // Without step 1, fast-diff(post-loadInitial-ytext, currentDisk)
+        // treats web's offline insertions as "things present in ytext but
+        // missing from disk" and DELETES them. That's the bug this fixes.
+        // Seed lastDiskText from the disk content we observed at construction
+        // time so the initial flush is a no-op when ytext already matches
+        // what's on disk. Without this, the binding's initial flush always
+        // wrote ytext to disk on startup, which clobbered any content the
+        // daemon's legacy contentHash + Storage blob pull (the fallthrough
+        // path in handleFirestoreChange) may have written first for non-Yjs
+        // cloud edits. Regression case: "after restart, pulls a web edit
+        // made while stopped despite a fresh local mtime" in
+        // sync/org-sync.test.js.
+        this.lastDiskText = this.currentDiskText;
+        if (this.initialDocState) {
+            Y.applyUpdate(this.doc, this.initialDocState);
+        }
+        // Disk-merge ops emitted below need to reach the store so other
+        // clients see the offline disk edits. The provider's local-update
+        // handler isn't attached yet (it's wired in startSubscription,
+        // which we can't call until after loadInitial), so we capture the
+        // updates synchronously here and push them after the subscription
+        // is set up. Capture by Y.Doc 'update' event with a 'disk' origin
+        // filter so we only grab the ops from our own _applyTextDiff and
+        // not anything spurious.
+        //
+        // The disk-merge is only safe when we have an `initialDocState`:
+        // that gives ytext a known baseline (the daemon's last view of the
+        // file) before we diff against currentDiskText, so fast-diff
+        // positions are valid AND the resulting ops are scoped to JUST the
+        // disk-only changes. Without a baseline, applying currentDiskText
+        // as fresh inserts on top of an empty ytext would then collide
+        // with whatever loadInitial pulls from the cloud: Yjs would see
+        // both the daemon's "fresh insert" and the cloud's "original
+        // insert" as concurrent ops, producing duplicated content. So on
+        // first contact (no saved state) we skip the disk merge and let
+        // loadInitial + initial flush behave the same as before DOU-209.
+        const capturedDiskUpdates = [];
+        if (this.initialDocState && this.currentDiskText != null) {
+            const restored = this.ytext.toString();
+            if (this.currentDiskText !== restored) {
+                const captureHandler = (update, origin) => {
+                    if (origin === 'disk')
+                        capturedDiskUpdates.push(update);
+                };
+                this.doc.on('update', captureHandler);
+                // Same diff-and-apply shape as applyDiskText, but we call the
+                // internal helper directly: applyDiskText is the live-chokidar
+                // path and also touches lastDiskText / _emitDocState in ways
+                // that aren't appropriate during the startup-merge phase.
+                this._applyTextDiff(restored, this.currentDiskText);
+                this.doc.off('update', captureHandler);
+            }
+        }
+        // DOU-204: two-phase provider start. Phase 1 loads snapshot +
+        // initial updates without subscribing. We then attach the
+        // Y.Text observer that drives the debounced disk write. Phase 2
+        // subscribes to remote updates; the first listener fire is the
+        // initial query result (re-applies the already-loaded docs
+        // idempotently), and any update that lands after loadInitial
+        // routes through the now-attached observer instead of mutating
+        // Y.Text silently between provider.start and observer attach.
+        await this.provider.loadInitial();
+        this.observer = () => {
+            if (this.stopped)
+                return;
+            if (this.flushTimer)
+                clearTimeout(this.flushTimer);
+            this.flushTimer = setTimeout(() => this._flushNow(), this.debounceMs);
         };
-        this.doc.on('update', captureHandler);
-        // Same diff-and-apply shape as applyDiskText, but we call the
-        // internal helper directly: applyDiskText is the live-chokidar
-        // path and also touches lastDiskText / _emitDocState in ways
-        // that aren't appropriate during the startup-merge phase.
-        this._applyTextDiff(restored, this.currentDiskText);
-        this.doc.off('update', captureHandler);
-      }
+        this.ytext.observe(this.observer);
+        this.provider.startSubscription();
+        // Push the disk-side updates captured above so the store records
+        // the offline disk edits and other clients receive them. Y.applyUpdate
+        // is idempotent so the daemon's own subscription echo (when the
+        // store fires its own append back through subscribeUpdates) is a
+        // no-op on our local Y.Doc.
+        for (const update of capturedDiskUpdates) {
+            try {
+                await this.store.appendUpdate(update);
+            }
+            catch (err) {
+                console.error('YjsFileBinding: disk-merge appendUpdate failed:', err?.message);
+            }
+        }
+        // Initial flush: ytext may be non-empty after replay (file has
+        // existing Yjs state). Writes the loaded content to disk so the
+        // local file is up-to-date the moment the binding is wired in.
+        if (this.ytext.length > 0)
+            this._flushNow();
+        // Persist the merged baseline so the next restart has the right
+        // anchor (the binding's state right now == disk after the flush
+        // above; future disk-side edits should diff against this state).
+        this._emitDocState();
     }
-
-    // DOU-204: two-phase provider start. Phase 1 loads snapshot +
-    // initial updates without subscribing. We then attach the
-    // Y.Text observer that drives the debounced disk write. Phase 2
-    // subscribes to remote updates; the first listener fire is the
-    // initial query result (re-applies the already-loaded docs
-    // idempotently), and any update that lands after loadInitial
-    // routes through the now-attached observer instead of mutating
-    // Y.Text silently between provider.start and observer attach.
-    await this.provider.loadInitial();
-    this.observer = () => {
-      if (this.stopped) return;
-      if (this.flushTimer) clearTimeout(this.flushTimer);
-      this.flushTimer = setTimeout(() => this._flushNow(), this.debounceMs);
-    };
-    this.ytext.observe(this.observer);
-    this.provider.startSubscription();
-
-    // Push the disk-side updates captured above so the store records
-    // the offline disk edits and other clients receive them. Y.applyUpdate
-    // is idempotent so the daemon's own subscription echo (when the
-    // store fires its own append back through subscribeUpdates) is a
-    // no-op on our local Y.Doc.
-    for (const update of capturedDiskUpdates) {
-      try { await this.store.appendUpdate(update); }
-      catch (err) { console.error('YjsFileBinding: disk-merge appendUpdate failed:', err && err.message); }
+    _applyTextDiff(fromText, toText) {
+        if (fromText === toText)
+            return;
+        const diffs = fastDiff(fromText, toText);
+        this.doc.transact(() => {
+            let idx = 0;
+            for (const [op, str] of diffs) {
+                if (op === 0) {
+                    idx += str.length;
+                }
+                else if (op === 1) {
+                    this.ytext.insert(idx, str);
+                    idx += str.length;
+                }
+                else {
+                    this.ytext.delete(idx, str.length);
+                }
+            }
+        }, 'disk');
     }
-
-    // Initial flush: ytext may be non-empty after replay (file has
-    // existing Yjs state). Writes the loaded content to disk so the
-    // local file is up-to-date the moment the binding is wired in.
-    if (this.ytext.length > 0) this._flushNow();
-    // Persist the merged baseline so the next restart has the right
-    // anchor (the binding's state right now == disk after the flush
-    // above; future disk-side edits should diff against this state).
-    this._emitDocState();
-  }
-
-  _applyTextDiff(fromText, toText) {
-    if (fromText === toText) return;
-    const diffs = fastDiff(fromText, toText);
-    this.doc.transact(() => {
-      let idx = 0;
-      for (const [op, str] of diffs) {
-        if (op === 0) {
-          idx += str.length;
-        } else if (op === 1) {
-          this.ytext.insert(idx, str);
-          idx += str.length;
-        } else {
-          this.ytext.delete(idx, str.length);
+    _emitDocState() {
+        if (this.stopped || !this.onDocStateChange)
+            return;
+        try {
+            this.onDocStateChange(Y.encodeStateAsUpdate(this.doc));
+        }
+        catch (err) {
+            console.error('YjsFileBinding: onDocStateChange failed:', err?.message);
         }
-      }
-    }, 'disk');
-  }
-
-  _emitDocState() {
-    if (this.stopped || !this.onDocStateChange) return;
-    try {
-      this.onDocStateChange(Y.encodeStateAsUpdate(this.doc));
-    } catch (err) {
-      console.error('YjsFileBinding: onDocStateChange failed:', err && err.message);
     }
-  }
-
-  // Sync flush used by both the debounced observer and the final
-  // drain in stop().
-  _flushNow() {
-    if (this.stopped) return;
-    if (this.flushTimer) {
-      clearTimeout(this.flushTimer);
-      this.flushTimer = null;
+    // Sync flush used by both the debounced observer and the final
+    // drain in stop().
+    _flushNow() {
+        if (this.stopped)
+            return;
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        const text = this.ytext.toString();
+        if (text === this.lastDiskText)
+            return;
+        this.lastDiskText = text;
+        this.onDiskWrite(text);
+        // The disk now matches ytext: snapshot the Y.Doc state so the next
+        // restart has the right baseline for offline-merge (DOU-209).
+        this._emitDocState();
     }
-    const text = this.ytext.toString();
-    if (text === this.lastDiskText) return;
-    this.lastDiskText = text;
-    this.onDiskWrite(text);
-    // The disk now matches ytext: snapshot the Y.Doc state so the next
-    // restart has the right baseline for offline-merge (DOU-209).
-    this._emitDocState();
-  }
-
-  // The local disk file changed (chokidar). Diff against the current
-  // ytext and apply as a sequence of inserts/deletes inside one
-  // transaction. Using a distinct origin ('disk') keeps the provider's
-  // local-update listener pushing the resulting yupdate to Firestore.
-  applyDiskText(newText) {
-    if (this.stopped) return;
-    const oldText = this.ytext.toString();
-    if (oldText === newText) return;
-    this._applyTextDiff(oldText, newText);
-    // Suppress the debounced echo: lastDiskText now matches the disk
-    // content the caller just observed, so the observer's pending
-    // flush is a no-op.
-    this.lastDiskText = newText;
-    // Snapshot the Y.Doc state so the next restart's baseline includes
-    // this disk-originated edit (DOU-209).
-    this._emitDocState();
-  }
-
-  async stop() {
-    if (this.stopped) return;
-    this.stopped = true;
-    if (this.observer) {
-      this.ytext.unobserve(this.observer);
-      this.observer = null;
+    // The local disk file changed (chokidar). Diff against the current
+    // ytext and apply as a sequence of inserts/deletes inside one
+    // transaction. Using a distinct origin ('disk') keeps the provider's
+    // local-update listener pushing the resulting yupdate to Firestore.
+    applyDiskText(newText) {
+        if (this.stopped)
+            return;
+        const oldText = this.ytext.toString();
+        if (oldText === newText)
+            return;
+        this._applyTextDiff(oldText, newText);
+        // Suppress the debounced echo: lastDiskText now matches the disk
+        // content the caller just observed, so the observer's pending
+        // flush is a no-op.
+        this.lastDiskText = newText;
+        // Snapshot the Y.Doc state so the next restart's baseline includes
+        // this disk-originated edit (DOU-209).
+        this._emitDocState();
     }
-    if (this.flushTimer) {
-      clearTimeout(this.flushTimer);
-      this.flushTimer = null;
+    async stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        if (this.observer) {
+            this.ytext.unobserve(this.observer);
+            this.observer = null;
+        }
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        this.provider.stop();
+        this.doc.destroy();
     }
-    this.provider.stop();
-    this.doc.destroy();
-  }
 }
+//# sourceMappingURL=yjs-file-binding.js.map

package/yjs-firestore-update-store.d.ts

@@ -0,0 +1,13 @@
+import { type Firestore, type Unsubscribe } from 'firebase/firestore';
+import type { YjsSnapshot, YjsUpdateListener, YjsUpdateRecord, YjsUpdateStore } from './yjs-provider.js';
+export declare class FirestoreUpdateStore implements YjsUpdateStore {
+    private readonly updatesCol;
+    private readonly snapshotDoc;
+    constructor(db: Firestore, orgId: string, fileId: string);
+    loadSnapshot(): Promise<YjsSnapshot | null>;
+    loadUpdatesAfter(baselineId: string | null): Promise<YjsUpdateRecord[]>;
+    appendUpdate(update: Uint8Array): Promise<YjsUpdateRecord>;
+    subscribeUpdates(onUpdate: YjsUpdateListener): Unsubscribe;
+    saveSnapshotAndCompact(state: Uint8Array, newBaselineId: string): Promise<void>;
+}
+//# sourceMappingURL=yjs-firestore-update-store.d.ts.map