@pylonsync/sync 0.22.25 → 0.22.27

package/dist/index.d.ts

@@ -346,18 +346,6 @@ export declare class SyncEngine {
      * is the dedup key.
      */
     private binaryHandlers;
-    /**
-     * Latest server CRDT SNAPSHOT frame per `entity|rowId`, kept so a
-     * follower tab that registers interest in an ALREADY-subscribed row
-     * gets state immediately. The server sends its catch-up snapshot only
-     * when a fresh `crdt-subscribe` goes over the WS — when the leader
-     * (or another follower) already holds the subscription, no wire
-     * traffic happens and, pre-cache, the new tab's LoroDoc stayed empty
-     * until the next live edit. Server broadcasts are always FULL merged
-     * snapshots (CRDT_FRAME_SNAPSHOT), so one frame per row is complete
-     * state. Bounded FIFO — see LAST_CRDT_FRAMES_MAX.
-     */
-    private lastCrdtFrames;
     /**
      * Server-side ephemeral subscriptions (CRDT row subs, reactive query
      * subs, future kinds). Owns the WS replay bookkeeping — each kind
@@ -930,18 +918,18 @@ export declare class SyncEngine {
      *  policy as `request()` — keeps the auth flows on the same
      *  authentication footing as data sync. */
     private authMutate;
-    /** Push pending mutations to the server. Coalesces concurrent callers
-     *  via the op queue's keyed dedupe — a slow push can't be restarted
-     *  by the poll timer or a user mutation, which would resend the same
-     *  batch (the mutation `op_id` keeps that safe at the protocol level,
-     *  but shipping the same batch twice is still wasted bandwidth). Also
-     *  serializes against pull / reconcile / resetReplica so a push can't
-     *  observe a half-reset cursor or a mid-reconcile replica. */
+    private inFlightPush;
+    private newPushIds;
+    private pushReplayRequested;
+    private pushRetryTimer;
+    /** Explicit recovery retries all pending writes. Concurrent callers share
+     *  the complete drain, including writes added during the request. */
     push(): Promise<void>;
-    /** Op ids of pending mutations that some push already sent (or
-     *  forwarded to the leader). */
-    private attemptedOps;
+    private pushNew;
+    private drainPush;
     private pushInner;
+    private cancelPushRetry;
+    private schedulePushRetry;
     /** Run `fn` after `ms` unless the engine stops first. A retry from a
      *  stopped engine would otherwise still reach the network. */
     private later;
@@ -1153,9 +1141,6 @@ export declare class SyncEngine {
      *  follower tab forwarded a CRDT sub, mirror over the multi-tab
      *  channel so followers see Loro updates too. */
     private dispatchBinaryFrame;
-    /** Drop the cached snapshot for a revoked row so it can't be
-     *  replayed to a late-joining tab after policy said no. */
-    private evictCrdtFrame;
     private request;
 }
 /** Data shape for hydrating the client from server-rendered content. */
@@ -1174,16 +1159,7 @@ export interface HydrationData {
 export declare function getServerData(baseUrl: string, entities: string[], options?: {
     token?: string;
 }): Promise<HydrationData>;
-/**
- * Stable equality check for reconciler diffs. Keys are sorted so
- * `{a:1,b:2}` and `{b:2,a:1}` compare equal — without that, every
- * reconcile pass would think every row had changed (insertion order
- * varies by mutation path on the server). Recursive on objects only;
- * arrays and primitives use their natural shape.
- */
-/** Cap on cached per-row CRDT snapshots (see lastCrdtFrames). 64 rows of
- *  collaborative state is far beyond what one browser session edits at
- *  once; FIFO eviction keeps a long-lived leader tab bounded. */
+/** @deprecated The engine no longer caches binary frames. */
 export declare const LAST_CRDT_FRAMES_MAX = 64;
 /**
  * Header-only peek at a binary CRDT frame: returns `"entity|rowId"` for
@@ -1199,7 +1175,7 @@ export declare const LAST_CRDT_FRAMES_MAX = 64;
  * this parser and the Swift one change with it.
  *
  * The engine still treats the PAYLOAD as opaque — this reads only the
- * routing header so the follower-catch-up cache can be keyed per row.
+ * routing header. A snapshot type does not prove the payload is complete.
  */
 export declare function crdtFrameKey(bytes: Uint8Array): string | null;
 /**

package/dist/local-store.d.ts

@@ -25,8 +25,19 @@ export declare class LocalStore {
      */
     private optimisticTombstones;
     private listeners;
+    private versions;
+    private rowVersions;
+    private revision;
+    private resetVersion;
+    /** Changes only when this entity changes or the replica is cleared. */
+    version(entity: string): number;
+    /** Changes only when this row changes or the replica is cleared. */
+    rowVersion(entity: string, id: string): number;
+    private touch;
     /** Get all rows for an entity. */
     list(entity: string): Row[];
+    /** Iterate current rows without copying the table. Consume synchronously. */
+    rows(entity: string): IterableIterator<Row>;
     /** Get a row by ID. */
     get(entity: string, id: string): Row | null;
     /** Snapshot of every entity name with at least one local row. Used
@@ -113,9 +124,11 @@ export declare class LocalStore {
      *  Void-returning callbacks are accepted for backwards compatibility
      *  (treated as durable / fire-and-forget). */
     _persistFn: ((change: ChangeEvent) => void | Promise<boolean>) | null;
-    /** Subscribe to store changes. Returns unsubscribe function. */
-    subscribe(listener: () => void): () => void;
-    notify(): void;
+    /** Subscribe globally or to one entity. Global status/reset signals reach both. */
+    subscribe(listener: (entity?: string) => void, entity?: string): () => void;
+    /** No entity means a global status or reset signal. */
+    notify(entity?: string): void;
+    private notifyEntities;
     /** Apply an optimistic insert. Returns a temporary id. */
     optimisticInsert(entity: string, data: Row): string;
     /**
@@ -186,6 +199,8 @@ export declare class LocalStore {
      * the engine's cursor stays pinned to the change-log position the
      * reconcile started from.
      */
+    applyReconcileInMemory(entity: string, upserts: Row[], removalIds: string[], tombstoneSeq: number): ChangeEvent[];
+    /** Apply and persist with the single-row fallback for standalone stores. */
     applyReconcileBatch(entity: string, upserts: Row[], removalIds: string[], tombstoneSeq: number): Promise<void>;
     /**
      * Drop every table + tombstone in-place, then notify. Used by the

package/dist/mutation-queue.d.ts

@@ -46,12 +46,14 @@ export interface PendingMutation {
 }
 /**
  * Optional persistence backend. The default IndexedDB persistence
- * layer provides `savePending`/`loadPending`. Callers can supply a
- * custom backend for tests or alternative storage.
+ * layer supports incremental writes with `saveChanges`. Custom backends
+ * can keep the full-snapshot `saveAll` contract.
  */
 export interface MutationQueuePersistence {
     saveAll(mutations: PendingMutation[]): Promise<void>;
     loadAll(): Promise<PendingMutation[]>;
+    /** Optional ordered, atomic delta write. Unchanged entries stay on disk. */
+    saveChanges?(upserts: PendingMutation[], removedIds: string[]): Promise<void>;
 }
 export declare class MutationQueue {
     private queue;
@@ -109,6 +111,8 @@ export declare class MutationQueue {
      *  and is retried; a later rejection shows up as `status: "failed"`. */
     settleQueued(id: string): void;
     markApplied(id: string): void;
+    /** Persist one response batch once, then settle each caller. */
+    markAppliedMany(ids: string[]): void;
     markFailed(id: string, error: string, errorCode?: string): void;
     private resolveWaiters;
     /**

package/dist/persistence.d.ts

@@ -143,10 +143,8 @@ export declare function persistChange(persistence: ReplicaPersistence, change: C
  * `MutationQueue` into the same database as the entity mirror so everything
  * the app needs to resume a session lives in one place.
  *
- * `saveAll` writes the entire queue on every change. That's O(n) per write,
- * but `n` is bounded by "how many mutations the user queued while offline",
- * which is tiny in practice. If that ever becomes a bottleneck, switch to
- * per-id `put`/`delete` — the schema (`keyPath: "id"`) already supports it.
+ * Incremental writes update only changed IDs. Full snapshots support initial
+ * hydration and identity reset, and remain available to custom backends.
  */
 export declare class IndexedDBMutationPersistence implements MutationQueuePersistence {
     private readonly parent;
@@ -154,5 +152,6 @@ export declare class IndexedDBMutationPersistence implements MutationQueuePersis
     constructor(parent: IndexedDBPersistence);
     private handle;
     saveAll(mutations: PendingMutation[]): Promise<void>;
+    saveChanges(upserts: PendingMutation[], removedIds: string[]): Promise<void>;
     loadAll(): Promise<PendingMutation[]>;
 }

package/dist/server-subscriptions.d.ts

@@ -18,6 +18,8 @@ export declare class ServerSubscriptions {
     unregister(key: string, unsubscribeMessage: unknown): void;
     /** Whether `key` is currently registered. */
     has(key: string): boolean;
+    /** Request fresh state for an existing subscription. */
+    refresh(key: string): void;
     /** Re-send every registered subscribe message. Called from
      *  `ws.onopen` after the socket reconnects — the server purges
      *  per-client subscription state on disconnect, so without this

package/dist/subscription-coordinator.d.ts

@@ -5,13 +5,6 @@ import type { ReactiveMessage } from "./types";
 export interface SubscriptionCoordinatorContext {
     isLeader(): boolean;
     broadcastToTabs(payload: unknown): void;
-    /** Leader-side replay of the cached CRDT snapshot for a row (see
-     *  SyncEngine.lastCrdtFrames). Called when a follower registers
-     *  interest in a row whose WS subscription is ALREADY alive — the
-     *  server only ships its catch-up snapshot on a fresh
-     *  `crdt-subscribe`, so without the replay the new tab's doc stays
-     *  empty until the next live edit. */
-    replayCrdtFrame?(entity: string, rowId: string): void;
 }
 export declare class SubscriptionCoordinator {
     private readonly serverSubs;
@@ -99,6 +92,7 @@ export declare class SubscriptionCoordinator {
      *  The engine gates its binary-broadcast on this so we don't fan
      *  binary frames to every tab when no follower cares about CRDT. */
     hasCrdtForwarders(): boolean;
+    hasCrdtForwardersFor(entity: string, rowId: string): boolean;
 }
 /** Internal CRDT key format: `${entity}\x00${rowId}`. Centralized so
  *  the engine's binary-frame parser (and any future routing logic)

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.22.25",
+  "version": "0.22.27",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",

package/src/bootstrap-speedup.test.ts

@@ -367,36 +367,22 @@ describe("Fix C: race election || auth/me", () => {
   });
 
   test("two tabs racing election: only the leader applies its bootstrap session", async () => {
-    // Multi-tab integration: two engines share a BroadcastChannel (Bun
-    // provides one in its test runtime). Both kick off
-    // fetchSessionBootstrap in parallel. Both fetches land — the
-    // network fetch isn't leader-gated; that's the whole speedup —
-    // but only the engine that won the election routes the result
-    // into the resolver via applySessionTransition. The follower's
-    // result is discarded by start().
-    //
-    // This test pins the invariant: a follower MUST NOT commit a
-    // session it fetched during the parallel bootstrap. If a future
-    // refactor "simplifies" the bootstrap back to gating the fetch on
-    // isMultiTabLeader, no behavior changes here (the test still
-    // passes); if the refactor instead drops the leader check at the
-    // APPLY point, follower starts double-committing — and this test
-    // fails because the follower would call applySessionTransition
-    // which broadcasts back to the leader.
-
+    // The follower's later response must not replace the leader's session.
     const appName = "boot-race-" + Math.random().toString(36).slice(2);
     let authMeHits = 0;
+    let releaseFollower!: () => void;
+    const followerResponse = new Promise<void>((resolve) => { releaseFollower = resolve; });
     const original = globalThis.fetch;
     globalThis.fetch = (async (input: RequestInfo | URL) => {
       const url = typeof input === "string" ? input : input.toString();
       if (url.endsWith("/api/auth/me")) {
-        authMeHits += 1;
-        await new Promise((r) => setTimeout(r, 10));
+        const request = ++authMeHits;
+        if (request === 2) await followerResponse;
         return {
           ok: true,
           status: 200,
           json: async () => ({
-            user_id: "u1",
+            user_id: request === 1 ? "leader-user" : "stale-follower-user",
             tenant_id: null,
             is_admin: false,
             roles: [],
@@ -452,6 +438,7 @@ describe("Fix C: race election || auth/me", () => {
     const startB = b.start();
 
     await Promise.all([startA, startB]);
+    releaseFollower();
     // Let any trailing broadcasts / poll ticks settle.
     await new Promise((r) => setTimeout(r, 100));
 
@@ -469,42 +456,54 @@ describe("Fix C: race election || auth/me", () => {
     const aSession = a.session.signature();
     const bSession = b.session.signature();
     expect(bSession).toBe(aSession);
-    // Both saw auth/me at most once each (no retry storm).
-    expect(authMeHits).toBeGreaterThanOrEqual(1);
-    expect(authMeHits).toBeLessThanOrEqual(2);
+    expect(a.session.resolved().userId).toBe("leader-user");
+    expect(authMeHits).toBe(2);
 
     a.stop();
     b.stop();
   });
 });
 
-// ---------------------------------------------------------------------------
-// Fix D — Fire-and-forget saveCursor on bootstrap
-//
-// The behavioral change is purely "didn't block start()". Hard to assert
-// directly without timing flakiness; instead pin the invariant that
-// start() completes even when saveCursor is artificially slow.
-// ---------------------------------------------------------------------------
-
-describe("Fix D: fire-and-forget bootstrap saveCursor", () => {
-  // This is the lightest-weight assertion that pins the fix: the
-  // bootstrap call site uses `void this.persistence.saveCursor(...)`,
-  // not `await`. We can't easily install a slow persistence layer into
-  // an engine that explicitly opted out of persistence, so the
-  // regression coverage here is the AST shape — verified by reading
-  // the file and asserting the call is not awaited.
-  test("source uses void (not await) for the bootstrap saveCursor", async () => {
-    const path = new URL("./index.ts", import.meta.url).pathname;
-    const src = await Bun.file(path).text();
-    // Find the bootstrap save block.
-    const marker = "// Save cursor after pull.";
-    const idx = src.indexOf(marker);
-    expect(idx).toBeGreaterThan(0);
-    const window = src.slice(idx, idx + 800);
-    // The fixed form uses `void this.persistence.saveCursor`; the
-    // pre-fix form was `await this.persistence.saveCursor`. Pin both
-    // sides of that change so a revert fails clearly.
-    expect(window).toContain("void this.persistence.saveCursor(this.cursor)");
-    expect(window).not.toContain("await this.persistence.saveCursor");
+describe("bootstrap cursor persistence", () => {
+  test("startup completes while the final cursor save is pending", async () => {
+    let release!: (saved: boolean) => void;
+    const pendingSave = new Promise<boolean>((resolve) => { release = resolve; });
+    let saves = 0;
+    const restoreFetch = installFetch(async (url) => ({
+      status: 200,
+      body: url.includes("/api/auth/me")
+        ? { user_id: null }
+        : { changes: [], cursor: { last_seq: 0 }, has_more: false },
+    }));
+    const engine = new SyncEngine({
+      baseUrl: "http://stub.invalid",
+      multiTab: false,
+      transport: "poll",
+      pollInterval: 1e9,
+      persistence: {
+        open: async () => {},
+        loadSnapshot: async () => ({ entities: {}, cursor: null, hadCache: false }),
+        loadIdentity: async () => null,
+        saveIdentity: async () => true,
+        saveCursor: () => { saves += 1; return pendingSave; },
+        saveRow: async () => true,
+        deleteRow: async () => true,
+        clear: async () => true,
+      },
+    });
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    try {
+      const result = await Promise.race([
+        engine.start().then(() => "started"),
+        new Promise<string>((resolve) => { timeout = setTimeout(() => resolve("blocked"), 1000); }),
+      ]);
+      expect(result).toBe("started");
+      expect(saves).toBeGreaterThan(0);
+    } finally {
+      clearTimeout(timeout);
+      release(true);
+      engine.stop();
+      restoreFetch();
+    }
   });
 });