@pylonsync/sync 0.22.25 → 0.22.27

package/src/local-store.ts

@@ -35,7 +35,36 @@ export class LocalStore {
    * `optimistic_delete_releases_id_when_server_confirms`.
    */
   private optimisticTombstones: Map<string, Set<string>> = new Map();
-  private listeners: Set<() => void> = new Set();
+  private listeners = new Map<(entity?: string) => void, string | undefined>();
+  private versions = new Map<string, number>();
+  private rowVersions = new Map<string, Map<string, number>>();
+  private revision = 0;
+  private resetVersion = 0;
+
+  /** Changes only when this entity changes or the replica is cleared. */
+  version(entity: string): number {
+    return this.versions.get(entity) ?? this.resetVersion;
+  }
+
+  /** Changes only when this row changes or the replica is cleared. */
+  rowVersion(entity: string, id: string): number {
+    return this.rowVersions.get(entity)?.get(id) ?? this.resetVersion;
+  }
+
+  private touch(entity: string, id: string): void {
+    const revision = ++this.revision;
+    this.versions.set(entity, revision);
+    if (this.tables.get(entity)?.has(id)) {
+      let versions = this.rowVersions.get(entity);
+      if (!versions) {
+        versions = new Map();
+        this.rowVersions.set(entity, versions);
+      }
+      versions.set(id, revision);
+    } else {
+      this.rowVersions.get(entity)?.delete(id);
+    }
+  }
 
   /** Get all rows for an entity. */
   list(entity: string): Row[] {
@@ -44,6 +73,11 @@ export class LocalStore {
     return Array.from(table.values());
   }
 
+  /** Iterate current rows without copying the table. Consume synchronously. */
+  rows(entity: string): IterableIterator<Row> {
+    return this.tables.get(entity)?.values() ?? [][Symbol.iterator]();
+  }
+
   /** Get a row by ID. */
   get(entity: string, id: string): Row | null {
     return this.tables.get(entity)?.get(id) ?? null;
@@ -84,6 +118,7 @@ export class LocalStore {
     const table = this.tables.get(entity);
     if (!table || !table.has(id)) return false;
     table.delete(id);
+    this.touch(entity, id);
     this.recordTombstone(entity, id, tombstoneSeq);
     return true;
   }
@@ -107,6 +142,7 @@ export class LocalStore {
    */
   revokeRow(entity: string, id: string, tombstoneSeq: number): boolean {
     const removed = this.tables.get(entity)?.delete(id) ?? false;
+    if (removed) this.touch(entity, id);
     this.recordTombstone(entity, id, tombstoneSeq);
     return removed;
   }
@@ -180,6 +216,7 @@ export class LocalStore {
         this.recordTombstone(change.entity, change.row_id, change.seq);
         break;
     }
+    this.touch(change.entity, change.row_id);
   }
 
   /** Apply multiple changes synchronously. Persistence runs fire-
@@ -190,7 +227,7 @@ export class LocalStore {
     for (const change of changes) {
       this.applyChange(change);
     }
-    this.notify();
+    this.notifyEntities(new Set(changes.map((change) => change.entity)));
 
     if (this._persistFn) {
       for (const change of changes) {
@@ -210,7 +247,7 @@ export class LocalStore {
     for (const change of changes) {
       this.applyChange(change);
     }
-    this.notify();
+    this.notifyEntities(new Set(changes.map((change) => change.entity)));
     return changes.map((c) => this.hydrateFromMemory(c));
   }
 
@@ -233,7 +270,7 @@ export class LocalStore {
     for (const change of changes) {
       this.applyChange(change);
     }
-    this.notify();
+    this.notifyEntities(new Set(changes.map((change) => change.entity)));
     let allDurable = true;
     if (this._persistFn) {
       // Sequential await — concurrent IDB writes can resolve out of
@@ -272,15 +309,25 @@ export class LocalStore {
    *  (treated as durable / fire-and-forget). */
   _persistFn: ((change: ChangeEvent) => void | Promise<boolean>) | null = null;
 
-  /** Subscribe to store changes. Returns unsubscribe function. */
-  subscribe(listener: () => void): () => void {
-    this.listeners.add(listener);
-    return () => this.listeners.delete(listener);
+  /** Subscribe globally or to one entity. Global status/reset signals reach both. */
+  subscribe(listener: (entity?: string) => void, entity?: string): () => void {
+    this.listeners.set(listener, entity);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /** No entity means a global status or reset signal. */
+  notify(entity?: string): void {
+    this.notifyEntities(entity === undefined ? undefined : new Set([entity]));
   }
 
-  notify(): void {
-    for (const listener of this.listeners) {
-      listener();
+  private notifyEntities(entities?: ReadonlySet<string>): void {
+    if (entities?.size === 0) return;
+    const changedEntity =
+      entities?.size === 1 ? entities.values().next().value : undefined;
+    for (const [listener, entity] of this.listeners) {
+      if (!entities || entity === undefined || entities.has(entity)) listener(changedEntity);
     }
   }
 
@@ -291,7 +338,8 @@ export class LocalStore {
       this.tables.set(entity, new Map());
     }
     this.tables.get(entity)!.set(tempId, { id: tempId, ...data });
-    this.notify();
+    this.touch(entity, tempId);
+    this.notify(entity);
     return tempId;
   }
 
@@ -312,7 +360,8 @@ export class LocalStore {
       this.tables.set(entity, new Map());
     }
     this.tables.get(entity)!.set(id, { ...data, id });
-    this.notify();
+    this.touch(entity, id);
+    this.notify(entity);
   }
 
   /**
@@ -327,7 +376,10 @@ export class LocalStore {
    */
   rollbackOptimisticInsert(entity: string, id: string): void {
     const removed = this.tables.get(entity)?.delete(id);
-    if (removed) this.notify();
+    if (removed) {
+      this.touch(entity, id);
+      this.notify(entity);
+    }
   }
 
   /** Apply an optimistic update. */
@@ -337,7 +389,8 @@ export class LocalStore {
     const existing = table.get(id);
     if (existing) {
       table.set(id, { ...existing, ...data });
-      this.notify();
+      this.touch(entity, id);
+      this.notify(entity);
     }
   }
 
@@ -369,7 +422,8 @@ export class LocalStore {
       // Server authoritatively removed this row mid-flight — its
       // deletion outranks our local rollback.
       this.tables.get(entity)?.delete(id);
-      this.notify();
+      this.touch(entity, id);
+      this.notify(entity);
       return;
     }
     if (prev) {
@@ -378,7 +432,8 @@ export class LocalStore {
     } else {
       this.tables.get(entity)?.delete(id);
     }
-    this.notify();
+    this.touch(entity, id);
+    this.notify(entity);
   }
 
   /** Apply an optimistic delete. Block any incoming insert/update
@@ -389,7 +444,8 @@ export class LocalStore {
       this.optimisticTombstones.set(entity, new Set());
     }
     this.optimisticTombstones.get(entity)!.add(id);
-    this.notify();
+    this.touch(entity, id);
+    this.notify(entity);
   }
 
   /**
@@ -409,12 +465,12 @@ export class LocalStore {
    * the engine's cursor stays pinned to the change-log position the
    * reconcile started from.
    */
-  async applyReconcileBatch(
+  applyReconcileInMemory(
     entity: string,
     upserts: Row[],
     removalIds: string[],
     tombstoneSeq: number,
-  ): Promise<void> {
+  ): ChangeEvent[] {
     if (!this.tables.has(entity)) this.tables.set(entity, new Map());
     const table = this.tables.get(entity)!;
     const applied: Array<{ id: string; row: Row }> = [];
@@ -427,6 +483,7 @@ export class LocalStore {
       if (this.isTombstoned(entity, id, tombstoneSeq + 1)) continue;
       const merged = { ...row, id };
       table.set(id, merged);
+      this.touch(entity, id);
       applied.push({ id, row: merged });
     }
     const removed: string[] = [];
@@ -435,43 +492,51 @@ export class LocalStore {
         removed.push(id);
       }
     }
-    if (applied.length > 0 || removed.length > 0) this.notify();
-    // Persist sequentially so disk order matches memory order — same
-    // discipline as applyChangesAsync.
+    if (applied.length > 0 || removed.length > 0) this.notify(entity);
+    return [
+      ...applied.map(({ id, row }): ChangeEvent => ({
+        seq: tombstoneSeq + 1,
+        entity,
+        row_id: id,
+        kind: "insert",
+        data: row,
+        timestamp: "",
+      })),
+      ...removed.map((id): ChangeEvent => ({
+        seq: tombstoneSeq,
+        entity,
+        row_id: id,
+        kind: "delete",
+        timestamp: "",
+      })),
+    ];
+  }
+
+  /** Apply and persist with the single-row fallback for standalone stores. */
+  async applyReconcileBatch(
+    entity: string,
+    upserts: Row[],
+    removalIds: string[],
+    tombstoneSeq: number,
+  ): Promise<void> {
+    const changes = this.applyReconcileInMemory(
+      entity, upserts, removalIds, tombstoneSeq,
+    );
     if (this._persistFn) {
-      for (const { id, row } of applied) {
-        const ev: ChangeEvent = {
-          seq: tombstoneSeq + 1,
-          entity,
-          row_id: id,
-          kind: "insert",
-          data: row,
-          timestamp: "",
-        };
-        const result = this._persistFn(ev);
-        if (result instanceof Promise) await result;
-      }
-      for (const id of removed) {
-        const ev: ChangeEvent = {
-          seq: tombstoneSeq,
-          entity,
-          row_id: id,
-          kind: "delete",
-          data: undefined as unknown as Row,
-          timestamp: "",
-        };
-        const result = this._persistFn(ev);
-        if (result instanceof Promise) await result;
-      }
+      for (const change of changes) await this._persistFn(change);
     }
   }
 
+
   /**
    * Drop every table + tombstone in-place, then notify. Used by the
    * sync engine's `resetReplica()` on identity flip (token or tenant
    * changed — the old replica reflects a different visible set).
    */
   clearAll(): void {
+    this.resetVersion = ++this.revision;
+    this.versions.clear();
+    this.rowVersions.clear();
     this.tables.clear();
     this.tombstones.clear();
     this.optimisticTombstones.clear();

package/src/mutation-owner-token.test.ts

@@ -92,9 +92,13 @@ describe("mutation owner and the bearer token", () => {
   }, 10_000);
 
   test("a session that expired across a reload keeps the user's queued writes", async () => {
+    let pushCalls = 0;
     globalThis.fetch = (async (input: RequestInfo | URL) => {
       const url = String(input);
-      if (url.includes("/api/sync/push")) throw new Error("must not push");
+      if (url.includes("/api/sync/push")) {
+        pushCalls += 1;
+        throw new Error("must not push");
+      }
       const body = url.includes("/api/auth/me")
         ? { user_id: null }
         : { changes: [], cursor: { last_seq: 0 }, has_more: false };
@@ -124,6 +128,7 @@ describe("mutation owner and the bearer token", () => {
     });
     await engine.start();
     await engine.push();
+    expect(pushCalls).toBe(0);
     expect(engine.pendingCount()).toBe(1);
     engine.stop();
     reopened.connection?.close();

package/src/mutation-owner.test.ts

@@ -112,9 +112,13 @@ describe("mutation owner", () => {
   }, 10_000);
 
   test("after a reload while signed out, the previous user's queued writes are not pushed", async () => {
+    let pushCalls = 0;
     globalThis.fetch = (async (input: RequestInfo | URL) => {
       const url = String(input);
-      if (url.includes("/api/sync/push")) throw new Error("must not push");
+      if (url.includes("/api/sync/push")) {
+        pushCalls += 1;
+        throw new Error("must not push");
+      }
       const body = url.includes("/api/sync/pull")
         ? { changes: [], cursor: { last_seq: 0 }, has_more: false }
         : url.includes("/api/auth/me")
@@ -150,6 +154,7 @@ describe("mutation owner", () => {
     });
     await engine.start();
     await engine.push();
+    expect(pushCalls).toBe(0);
     expect(engine.pendingCount()).toBe(1);
     expect(engine.mutations.pending()[0]!.owner).toBe("u1");
     engine.stop();

package/src/mutation-queue.ts

@@ -73,12 +73,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>;
 }
 
 interface OutcomeWaiter {
@@ -87,7 +89,7 @@ interface OutcomeWaiter {
 }
 
 export class MutationQueue {
-  private queue: PendingMutation[] = [];
+  private queue = new Map<string, PendingMutation>();
   private persistence?: MutationQueuePersistence;
   /** Callers waiting for a mutation's outcome, by op id. Memory-only:
    *  a promise cannot outlive the page that created it. */
@@ -116,11 +118,10 @@ export class MutationQueue {
       // hydrate was awaiting `loadAll()` will already have flushed a
       // snapshot that didn't include the loaded rows — re-flush
       // after merge so disk matches memory again.
-      const existingIds = new Set(this.queue.map((m) => m.id));
       let mergedAny = false;
       for (const m of loaded) {
-        if (!existingIds.has(m.id)) {
-          this.queue.push(m);
+        if (!this.queue.has(m.id)) {
+          this.queue.set(m.id, m);
           mergedAny = true;
         }
       }
@@ -150,25 +151,29 @@ export class MutationQueue {
       typeof change.op_id === "string" && change.op_id.length > 0
         ? change.op_id
         : `mut_${Date.now()}_${Math.random().toString(36).slice(2)}`;
-    if (this.queue.some((m) => m.id === id)) return id;
+    if (this.queue.has(id)) return id;
     const changeWithOp: ClientChange = { ...change, op_id: id };
     const entry: PendingMutation = { id, change: changeWithOp, status: "pending", prevRow };
     if (owner !== undefined) entry.owner = owner;
     if (ownerPending) entry.ownerPending = true;
-    this.queue.push(entry);
-    this.flush();
+    this.queue.set(id, entry);
+    this.flush([entry]);
     return id;
   }
 
   pending(): PendingMutation[] {
-    return this.queue.filter((m) => m.status === "pending");
+    const pending: PendingMutation[] = [];
+    for (const mutation of this.queue.values()) {
+      if (mutation.status === "pending") pending.push(mutation);
+    }
+    return pending;
   }
 
   /** Look up a queued mutation by op id (any status). Used by the
    *  follower's mutations-failed handler to reach the captured
    *  `prevRow` for rollback. */
   get(id: string): PendingMutation | undefined {
-    return this.queue.find((m) => m.id === id);
+    return this.queue.get(id);
   }
 
   /**
@@ -186,7 +191,7 @@ export class MutationQueue {
    */
   pendingRowKeys(): Set<string> {
     const out = new Set<string>();
-    for (const m of this.queue) {
+    for (const m of this.queue.values()) {
       if (m.status === "pending" || m.status === "failed") {
         out.add(`${m.change.entity}/${m.change.row_id}`);
       }
@@ -219,20 +224,31 @@ export class MutationQueue {
   }
 
   markApplied(id: string): void {
-    const m = this.queue.find((m) => m.id === id);
-    if (m) m.status = "applied";
-    this.flush();
-    this.resolveWaiters(id);
+    this.markAppliedMany([id]);
+  }
+
+  /** Persist one response batch once, then settle each caller. */
+  markAppliedMany(ids: string[]): void {
+    const changed: PendingMutation[] = [];
+    for (const id of new Set(ids)) {
+      const m = this.queue.get(id);
+      if (m) {
+        m.status = "applied";
+        changed.push(m);
+      }
+    }
+    if (changed.length > 0) this.flush(changed);
+    for (const id of ids) this.resolveWaiters(id);
   }
 
   markFailed(id: string, error: string, errorCode?: string): void {
-    const m = this.queue.find((m) => m.id === id);
+    const m = this.queue.get(id);
     if (m) {
       m.status = "failed";
       m.error = error;
       if (errorCode) m.errorCode = errorCode;
     }
-    this.flush();
+    if (m) this.flush([m]);
     const waiters = this.waiters.get(id);
     if (!waiters) return;
     this.waiters.delete(id);
@@ -260,24 +276,28 @@ export class MutationQueue {
    * surface them to the user and so retries are possible.
    */
   clear(): void {
-    this.queue = this.queue.filter(
-      (m) => m.status === "pending" || m.status === "failed",
-    );
-    this.flush();
+    const removedIds: string[] = [];
+    for (const [id, m] of this.queue) {
+      if (m.status === "applied") {
+        this.queue.delete(id);
+        removedIds.push(id);
+      }
+    }
+    if (removedIds.length > 0) this.flush([], removedIds);
   }
 
   /** Stamp every write whose owner was pending with the user the first
    *  resolved session names. */
   stampPendingOwner(owner: string | null): void {
-    let changed = false;
-    for (const m of this.queue) {
+    const changed: PendingMutation[] = [];
+    for (const m of this.queue.values()) {
       if (m.ownerPending) {
         m.owner = owner;
         delete m.ownerPending;
-        changed = true;
+        changed.push(m);
       }
     }
-    if (changed) this.flush();
+    if (changed.length > 0) this.flush(changed);
   }
 
   /** Drop one mutation that must never be pushed (it belongs to another
@@ -285,8 +305,8 @@ export class MutationQueue {
    *  touch the local store. */
   discard(id: string): void {
     const m = this.get(id);
-    this.queue = this.queue.filter((q) => q.id !== id);
-    this.flush();
+    this.queue.delete(id);
+    this.flush([], [id]);
     const waiters = this.waiters.get(id);
     if (!waiters) return;
     this.waiters.delete(id);
@@ -306,8 +326,8 @@ export class MutationQueue {
   /** Remove a specific mutation by id. Used by the UI after user
    *  ack of failures. */
   remove(id: string): void {
-    this.queue = this.queue.filter((m) => m.id !== id);
-    this.flush();
+    this.queue.delete(id);
+    this.flush([], [id]);
   }
 
   /**
@@ -323,11 +343,11 @@ export class MutationQueue {
    */
   clearAll(): void {
     const dropped = this.queue;
-    this.queue = [];
+    this.queue = new Map();
     this.flush();
     // Nobody will push these writes any more. Reject their waiters so a
     // caller awaiting the outcome does not hang.
-    for (const m of dropped) {
+    for (const m of dropped.values()) {
       const waiters = this.waiters.get(m.id);
       if (!waiters) continue;
       this.waiters.delete(m.id);
@@ -346,10 +366,13 @@ export class MutationQueue {
   }
 
   /** Fire-and-forget persistence write. */
-  private flush(): void {
+  private flush(upserts?: PendingMutation[], removedIds: string[] = []): void {
     if (!this.persistence) return;
-    const snapshot = this.queue.slice();
-    this.persistence.saveAll(snapshot).catch((err) => {
+    // Copy mutable status/owner fields before handing data to an async backend.
+    const write = upserts && this.persistence.saveChanges
+      ? this.persistence.saveChanges(upserts.map((m) => ({ ...m })), removedIds)
+      : this.persistence.saveAll(Array.from(this.queue.values(), (m) => ({ ...m })));
+    write.catch((err) => {
       console.warn("[sync] mutation-queue persist failed:", err);
     });
   }

package/src/persistence.ts

@@ -417,10 +417,8 @@ export async function persistChange(
  * `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 class IndexedDBMutationPersistence implements MutationQueuePersistence {
   private db: IDBDatabase | null = null;
@@ -449,6 +447,20 @@ export class IndexedDBMutationPersistence implements MutationQueuePersistence {
     });
   }
 
+  async saveChanges(upserts: PendingMutation[], removedIds: string[]): Promise<void> {
+    const db = this.handle();
+    if (!db) return;
+    const tx = db.transaction(MUTATIONS_STORE, "readwrite");
+    const store = tx.objectStore(MUTATIONS_STORE);
+    for (const mutation of upserts) store.put(mutation);
+    for (const id of removedIds) store.delete(id);
+    return new Promise((resolve, reject) => {
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error ?? new Error("mutation queue update failed"));
+      tx.onabort = () => reject(tx.error ?? new Error("mutation queue update aborted"));
+    });
+  }
+
   async loadAll(): Promise<PendingMutation[]> {
     const db = this.handle();
     if (!db) return [];