yrby-client 0.4.3 → 0.6.0

package/dist/cjs/reliable_sync.d.ts

@@ -14,45 +14,32 @@ export interface ReliableSyncOptions {
     setInterval?: (handler: () => void, ms: number) => TimerHandle;
     clearInterval?: (handle: TimerHandle) => void;
 }
-interface Pending {
-    seq: number;
-    update: Uint8Array;
+/** One queued update and the sequence number an ack must reach to remove it. */
+export interface Pending {
+    readonly seq: number;
+    readonly update: Uint8Array;
 }
 export declare class ReliableSync {
     #private;
-    /** Unacked local updates, in order. */
-    pending: Pending[];
     constructor(opts: ReliableSyncOptions);
+    /** A snapshot of unacknowledged local updates, oldest first. Editing it does not change the queue. */
+    get pending(): readonly Pending[];
     /** True while there are unacknowledged local updates. */
     get hasPending(): boolean;
-    /**
-     * Record a local document update. It is queued and the unacked tail is
-     * flushed; the update remains retained until the server acknowledges it.
-     */
+    /** Queue a local update and, while connected, send the tail. Ignored after destroy(). */
     enqueue(update: Uint8Array): void;
     /**
-     * Send the whole unacked tail as one merged delta. The id is the highest seq
-     * in the batch, so a single { ack } cumulatively confirms everything up to it.
-     * No-op while disconnected (the tail is replayed on the next onConnect).
-     */
-    flush(): void;
-    /**
-     * Confirm delivery up to `id`: prune every queued update with seq <= id.
-     * Acks arrive over the wire, so validate before pruning. A malformed value
-     * (NaN/string/negative) or an impossible future id must not silently drop the
-     * queue; invalid acks are ignored.
-     */
-    onAck(id: number): void;
-    /** Transport (re)connected: replay the unacked tail and resume retransmits. */
-    onConnect(): void;
-    /** Transport dropped: keep the queue (for reconnect replay), pause the timer. */
-    onDisconnect(): void;
-    /**
-     * One retransmit tick. Exposed for deterministic testing; normally driven by
-     * the internal timer.
+     * Confirm delivery through `id`, removing every queued update with
+     * seq <= id. Acks come off the wire, so ignore a malformed value or an id
+     * beyond anything sent.
      */
-    onTick(): void;
-    /** Stop timers and drop references. Call when the provider is destroyed. */
+    acknowledge(id: number): void;
+    /** Call when the transport is up. Replays the tail and keeps retransmitting until it is acknowledged. */
+    resume(): void;
+    /** Call when the transport is down. Keeps the queue and stops retransmitting. */
+    pause(): void;
+    /** Send the tail again if anything is unacknowledged. The internal timer calls this, and a host with its own scheduler can too. */
+    retransmit(): void;
+    /** Stop the timer and drop the queue. Later enqueues are ignored. */
     destroy(): void;
 }
-export {};

package/dist/cjs/reliable_sync.js

@@ -1,142 +1,172 @@
 "use strict";
-// Transport-agnostic reliable-delivery core for the yrby y-websocket
-// protocol: an ack-tracked queue of unacknowledged local updates,
-// sync-since-last-ack (the unacked tail goes out as one merged, causally-complete
-// delta so the server never sees an internal gap), cumulative acks, periodic
-// retransmit, and reconnect replay.
+// Transport-agnostic reliable delivery for the yrby y-websocket protocol.
 //
-// It doesn't touch the transport, the Yjs binding, or wire encoding. Inject two
-// functions:
-// send(update, id) transmits one update (raw merged bytes plus a cumulative
-// sequence id; you frame, base64, and put it on the socket), and merge(updates)
-// merges update byte-arrays into one (usually Y.mergeUpdates). Drive it from the
-// provider lifecycle: enqueue(update) on each local edit, onAck(id) when an
-// { ack: id } frame arrives, and onConnect()/onDisconnect() on transport changes.
+// Each local update gets a sequence number and sits in an ordered queue until
+// the server acknowledges it. While the transport is up, ReliableSync sends the
+// whole unacknowledged tail as one merged, causally complete delta so the
+// server never sees an internal gap, and resends it on a timer until an ack
+// arrives. Acks are cumulative, so one { ack: n } clears everything up to n.
+// While the transport is down, ReliableSync sends nothing and drops nothing,
+// and it replays the tail when the transport reconnects.
+//
+// It doesn't touch the transport or Yjs itself. You inject two functions.
+// send(update, id) transmits one delta with the sequence id the server should
+// acknowledge, and merge(updates) combines update byte arrays into one (usually
+// Y.mergeUpdates). Call enqueue(update) on each local edit, acknowledge(id) when
+// an { ack: id } envelope arrives, resume() when the transport connects, and
+// pause() when it drops.
 //
 // Awareness/presence stays out of scope; it's fire-and-forget in the provider.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ReliableSync = void 0;
-const DEFAULTS = { resendInterval: 1000 };
+const DEFAULT_RESEND_INTERVAL = 1000;
 class ReliableSync {
-    /** Unacked local updates, in order. */
-    pending = [];
+    #pending = [];
     #send;
     #merge;
     #resendInterval;
     #setInterval;
     #clearInterval;
     #nextSeq = 1;
-    #connected = false;
-    #timer = undefined;
-    // Memoized merge of the unacked tail. The tail only changes on enqueue/ack, so
-    // retransmit ticks reuse this instead of re-merging the whole queue each time.
-    #tailCache = undefined;
+    #phase = "paused";
+    #timer;
+    // Incremented on every queue or phase change. Injected send/merge/timer
+    // functions can call back into this object, so code that calls one compares
+    // the version afterwards to detect changes made during the call.
+    #version = 0;
+    // The queue merged into one delta. It's memoized until the queue changes so
+    // retransmit ticks don't re-merge the whole queue every second.
+    #tail;
     constructor(opts) {
-        const { send, merge, resendInterval } = opts ?? {};
+        const { send, merge, resendInterval, setInterval: setTimer, clearInterval: clearTimer } = opts ?? {};
         if (typeof send !== "function")
             throw new TypeError("ReliableSync requires a send(update, id) function");
         if (typeof merge !== "function")
             throw new TypeError("ReliableSync requires a merge(updates) function");
-        this.#send = send;
-        this.#merge = merge;
-        const interval = resendInterval ?? DEFAULTS.resendInterval;
+        const interval = resendInterval ?? DEFAULT_RESEND_INTERVAL;
         if (!Number.isFinite(interval) || interval <= 0) {
             throw new TypeError("ReliableSync resendInterval must be a positive number");
         }
+        this.#send = send;
+        this.#merge = merge;
         this.#resendInterval = interval;
-        // Injectable timer hooks make the resend loop testable; default to globals.
-        this.#setInterval = opts.setInterval ?? ((fn, ms) => setInterval(fn, ms));
-        this.#clearInterval = opts.clearInterval ?? ((h) => clearInterval(h));
+        this.#setInterval = setTimer ?? ((fn, ms) => setInterval(fn, ms));
+        this.#clearInterval = clearTimer ?? ((h) => clearInterval(h));
+    }
+    /** A snapshot of unacknowledged local updates, oldest first. Editing it does not change the queue. */
+    get pending() {
+        return this.#pending.map(({ seq, update }) => ({ seq, update: update.slice() }));
     }
     /** True while there are unacknowledged local updates. */
     get hasPending() {
-        return this.pending.length > 0;
+        return this.#pending.length > 0;
     }
-    /**
-     * Record a local document update. It is queued and the unacked tail is
-     * flushed; the update remains retained until the server acknowledges it.
-     */
+    /** Queue a local update and, while connected, send the tail. Ignored after destroy(). */
     enqueue(update) {
-        this.pending.push({ seq: this.#nextSeq++, update });
-        this.#tailCache = undefined; // tail changed
-        if (this.#connected)
-            this.#startTimer();
-        this.flush();
+        if (this.#phase === "destroyed")
+            return;
+        this.#pending.push({ seq: this.#nextSeq++, update: new Uint8Array(update) });
+        this.#queueChanged();
+        this.#flush();
     }
     /**
-     * Send the whole unacked tail as one merged delta. The id is the highest seq
-     * in the batch, so a single { ack } cumulatively confirms everything up to it.
-     * No-op while disconnected (the tail is replayed on the next onConnect).
+     * Confirm delivery through `id`, removing every queued update with
+     * seq <= id. Acks come off the wire, so ignore a malformed value or an id
+     * beyond anything sent.
      */
-    flush() {
-        if (!this.#connected || this.pending.length === 0)
+    acknowledge(id) {
+        if (this.#phase === "destroyed" || !Number.isSafeInteger(id) || id < 0)
+            return;
+        const newest = this.#pending.at(-1);
+        if (newest && id > newest.seq)
             return;
-        this.#send(this.#mergedTail(), this.pending[this.pending.length - 1].seq);
+        this.#pending = this.#pending.filter((p) => p.seq > id);
+        this.#queueChanged();
     }
-    /**
-     * Confirm delivery up to `id`: prune every queued update with seq <= id.
-     * Acks arrive over the wire, so validate before pruning. A malformed value
-     * (NaN/string/negative) or an impossible future id must not silently drop the
-     * queue; invalid acks are ignored.
-     */
-    onAck(id) {
-        if (!Number.isSafeInteger(id) || id < 0)
-            return; // malformed / impossible
-        if (this.pending.length > 0 && id > this.pending[this.pending.length - 1].seq)
-            return; // future ack
-        this.pending = this.pending.filter((p) => p.seq > id);
-        this.#tailCache = undefined; // tail changed
-        if (this.pending.length === 0)
-            this.#stopTimer();
+    /** Call when the transport is up. Replays the tail and keeps retransmitting until it is acknowledged. */
+    resume() {
+        if (this.#phase === "destroyed")
+            return;
+        this.#phase = "live";
+        this.#version++;
+        this.#updateTimer();
+        this.#flush();
     }
-    /** Transport (re)connected: replay the unacked tail and resume retransmits. */
-    onConnect() {
-        this.#connected = true;
-        this.flush();
-        if (this.pending.length > 0)
-            this.#startTimer();
+    /** Call when the transport is down. Keeps the queue and stops retransmitting. */
+    pause() {
+        if (this.#phase === "destroyed")
+            return;
+        this.#phase = "paused";
+        this.#version++;
+        this.#updateTimer();
     }
-    /** Transport dropped: keep the queue (for reconnect replay), pause the timer. */
-    onDisconnect() {
-        this.#connected = false;
-        this.#stopTimer();
+    /** Send the tail again if anything is unacknowledged. The internal timer calls this, and a host with its own scheduler can too. */
+    retransmit() {
+        this.#flush();
     }
-    /**
-     * One retransmit tick. Exposed for deterministic testing; normally driven by
-     * the internal timer.
-     */
-    onTick() {
-        if (!this.#connected || this.pending.length === 0)
+    /** Stop the timer and drop the queue. Later enqueues are ignored. */
+    destroy() {
+        if (this.#phase === "destroyed")
             return;
-        this.flush();
+        this.#phase = "destroyed";
+        this.#pending = [];
+        this.#queueChanged();
     }
-    /** Stop timers and drop references. Call when the provider is destroyed. */
-    destroy() {
-        this.#connected = false;
-        this.#stopTimer();
-        this.pending = [];
-        this.#tailCache = undefined;
+    #queueChanged() {
+        this.#version++;
+        this.#tail = undefined;
+        this.#updateTimer();
     }
-    /** The unacked tail merged into one delta (memoized between tail changes). */
-    #mergedTail() {
-        if (this.#tailCache === undefined) {
-            const updates = this.pending.map((p) => p.update);
-            this.#tailCache = updates.length === 1 ? updates[0] : this.#merge(updates);
+    // Start or stop the retransmit timer so it runs only while live with work queued.
+    #updateTimer() {
+        const wanted = this.#phase === "live" && this.hasPending;
+        if (wanted === (this.#timer !== undefined))
+            return;
+        if (!wanted) {
+            const timer = this.#timer;
+            this.#timer = undefined;
+            timer.stop();
+            return;
         }
-        return this.#tailCache;
-    }
-    #startTimer() {
-        if (this.#timer !== undefined)
+        // Install the timer before calling setInterval so a tick during that call
+        // finds its own timer. Stopping it before the handle exists is a no-op, and
+        // the check after setInterval returns cancels the real handle.
+        const timer = this.#timer = { stop: () => { } };
+        let handle;
+        try {
+            handle = this.#setInterval(() => { if (this.#timer === timer)
+                this.#flush(); }, this.#resendInterval);
+        }
+        catch (error) {
+            // The queue is untouched, and the next resume or queue change tries again.
+            if (this.#timer === timer)
+                this.#timer = undefined;
+            throw error;
+        }
+        timer.stop = () => this.#clearInterval(handle);
+        // An injected timer may tick before returning its handle, and that tick
+        // can pause or drain delivery.
+        if (this.#timer !== timer) {
+            timer.stop();
             return;
-        this.#timer = this.#setInterval(() => this.onTick(), this.#resendInterval);
-        const t = this.#timer;
-        if (t && typeof t.unref === "function")
-            t.unref();
+        }
+        handle?.unref?.();
     }
-    #stopTimer() {
-        if (this.#timer !== undefined)
-            this.#clearInterval(this.#timer);
-        this.#timer = undefined;
+    // Send the whole tail as one delta, tagged with its highest seq so one ack
+    // covers all of it. Does nothing while disconnected.
+    #flush() {
+        if (this.#phase !== "live" || !this.#pending.length)
+            return;
+        if (this.#tail === undefined) {
+            const version = this.#version;
+            const updates = this.#pending.map((p) => p.update);
+            const tail = updates.length === 1 ? updates[0] : this.#merge(updates);
+            // merge may have changed the queue, paused, or already sent through a nested resume.
+            if (this.#version !== version)
+                return;
+            this.#tail = tail;
+        }
+        this.#send(this.#tail, this.#pending.at(-1).seq);
     }
 }
 exports.ReliableSync = ReliableSync;

package/dist/cjs/turbo_adapter.d.ts

@@ -0,0 +1,9 @@
+export interface DocumentMount {
+    readonly ownerDocument: Document;
+    readonly isConnected: boolean;
+    activate(): void;
+    deactivate(): void;
+}
+export declare function registerDocumentMount(mount: DocumentMount): () => void;
+/** Tears down the adapter, for application shutdown or tests. */
+export declare function disconnectTurbo(document: Document): void;

package/dist/cjs/turbo_adapter.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerDocumentMount = registerDocumentMount;
+exports.disconnectTurbo = disconnectTurbo;
+const adapters = new WeakMap();
+// Turbo (Hotwire) and Turbolinks 5 fire the same lifecycle events under different names.
+const CACHE_EVENTS = ["turbo:before-cache", "turbolinks:before-cache"];
+const RENDER_EVENTS = ["turbo:render", "turbo:load", "turbo:fetch-request-error", "turbolinks:render", "turbolinks:load"];
+const PREVIEW_ATTRIBUTES = ["data-turbo-preview", "data-turbolinks-preview"];
+function registerDocumentMount(mount) {
+    let adapter = adapters.get(mount.ownerDocument);
+    if (!adapter)
+        adapters.set(mount.ownerDocument, adapter = new TurboAdapter(mount.ownerDocument));
+    adapter.mounts.add(mount);
+    adapter.reconcile();
+    return () => {
+        adapter.mounts.delete(mount);
+        if (!adapter.mounts.size)
+            adapter.destroy();
+    };
+}
+/** Tears down the adapter, for application shutdown or tests. */
+function disconnectTurbo(document) { adapters.get(document)?.destroy(); }
+class TurboAdapter {
+    document;
+    mounts = new Set();
+    #state = { phase: "active" };
+    constructor(document) {
+        this.document = document;
+        for (const event of CACHE_EVENTS)
+            document.addEventListener(event, this.#beforeCache);
+        for (const event of RENDER_EVENTS)
+            document.addEventListener(event, this.reconcile);
+    }
+    reconcile = () => {
+        if (this.#state.phase !== "active")
+            return;
+        const html = this.document.documentElement;
+        const preview = PREVIEW_ATTRIBUTES.some(attribute => html?.hasAttribute(attribute));
+        for (const mount of this.mounts) {
+            if (!mount.isConnected || preview)
+                mount.deactivate();
+            else
+                mount.activate();
+        }
+    };
+    #beforeCache = () => {
+        const state = this.#state;
+        if (state.phase !== "active")
+            return;
+        for (const mount of this.mounts)
+            mount.deactivate();
+        if (this.#state !== state)
+            return;
+        // A canceled or failed navigation fires no render or load event, so we
+        // reconcile ourselves after Turbo finishes cloning the snapshot. The clone
+        // takes two turns, which is why the timers are nested.
+        clearTimeout(state.timer);
+        state.timer = setTimeout(() => {
+            if (this.#state === state)
+                state.timer = setTimeout(this.reconcile, 0);
+        }, 0);
+    };
+    destroy() {
+        const state = this.#state;
+        if (state.phase === "destroyed")
+            return;
+        this.#state = { phase: "destroyed" };
+        clearTimeout(state.timer);
+        // Leave the registry first so cleanup callbacks can register a replacement
+        // adapter for this document.
+        adapters.delete(this.document);
+        for (const event of CACHE_EVENTS)
+            this.document.removeEventListener(event, this.#beforeCache);
+        for (const event of RENDER_EVENTS)
+            this.document.removeEventListener(event, this.reconcile);
+        for (const mount of this.mounts)
+            mount.deactivate();
+        this.mounts.clear();
+    }
+}

package/dist/cjs/y_protocol_session.d.ts

@@ -37,10 +37,10 @@ export declare class YProtocolSession {
     get synced(): boolean;
     /** True while there are unacknowledged local document updates in flight. */
     get hasPending(): boolean;
-    /** Transport connected: send the opening handshake and replay the unacked tail. */
-    onConnect(): void;
-    /** Transport dropped: pause retransmits (queue kept) and clear remote presence. */
-    onDisconnect(): void;
+    /** Call when the transport is up. Sends the opening handshake, re-announces presence, and replays the unacked tail. */
+    resume(): void;
+    /** Call when the transport is down. Keeps the queue, stops retransmits, and clears peers' presence. */
+    pause(): void;
     /**
      * Broadcast that our local presence is gone (sets local state to null, which
      * emits a removal awareness frame through `send`). Call this while the
@@ -48,15 +48,8 @@ export declare class YProtocolSession {
      * waiting for the awareness timeout. A no-op when there's no local state.
      */
     removeLocalAwareness(): void;
-    /**
-     * A reliable-delivery `{ ack: id }` envelope arrived. `dropped` is set when
-     * the server settled the update WITHOUT recording it (rejected as an
-     * unhealable causal gap after repeated resyncs). The queue is pruned either
-     * way — retransmitting an unhealable update would loop forever — but a
-     * dropped settle is surfaced via onError ("ack-dropped") so the app can warn
-     * or reload instead of silently reporting synced over lost data.
-     */
-    ack(id: number, dropped?: boolean): void;
+    /** A reliable-delivery `{ ack: id }` envelope arrived. */
+    acknowledge(id: number): void;
     /**
      * Apply an update without treating it as a local edit, so it isn't queued for
      * re-delivery to the server. Use it for bootstrap/restore: initial state loaded
@@ -67,7 +60,7 @@ export declare class YProtocolSession {
      * keystroke becomes an outbound frame), so a bare `Y.applyUpdate(doc, update)`
      * would look like a local edit and get echoed back on the next connect. Going
      * through here applies under the session's own origin, which the outbound
-     * filter skips. Safe to call before `onConnect()`: the state folds into the
+     * filter skips. Safe to call before `resume()`: the state folds into the
      * SyncStep1 handshake instead of being re-sent.
      */
     applyRemoteUpdate(update: Uint8Array): void;