@syncular/client 0.15.47 → 0.16.1

package/dist/outbox.js

@@ -26,17 +26,40 @@ export function appendOutboxCommit(db, clientCommitId, operations, nowMs, before
         ]);
     }
 }
-/** Pending commits in FIFO creation order (§7.1). */
+/** Pending commits in FIFO creation order (§7.1). Full reads serve replay and the public listing. */
 export function listOutbox(db) {
     return db
         .query(`SELECT seq, client_commit_id, created_at_ms, operations
        FROM _syncular_outbox ORDER BY seq ASC`)
-        .map((row) => ({
+        .map(decodeOutboxRow);
+}
+function decodeOutboxRow(row) {
+    return {
         seq: row.seq,
         clientCommitId: row.client_commit_id,
         createdAtMs: row.created_at_ms,
         operations: JSON.parse(row.operations),
-    }));
+    };
+}
+/** Keyset pages bound staging; laziness decodes only commits consumed by the encoder. */
+export function* iterateOutbox(db, throughSeq) {
+    let afterSeq = 0;
+    while (afterSeq < throughSeq) {
+        const rows = db.query(`SELECT seq, client_commit_id, created_at_ms, operations FROM _syncular_outbox
+       WHERE seq > ? AND seq <= ? ORDER BY seq ASC LIMIT 32`, [afterSeq, throughSeq]);
+        if (rows.length === 0)
+            return;
+        for (const row of rows) {
+            const commit = decodeOutboxRow(row);
+            afterSeq = commit.seq;
+            yield commit;
+        }
+    }
+}
+/** Routine status reads never load operation bodies. */
+export function countOutbox(db) {
+    return db.query('SELECT COUNT(*) AS count FROM _syncular_outbox')[0]
+        .count;
 }
 export function deleteOutboxCommit(db, clientCommitId) {
     db.exec('DELETE FROM _syncular_outbox_before_images WHERE client_commit_id = ?', [clientCommitId]);

package/dist/reactive-store.d.ts

@@ -1,5 +1,5 @@
 import { type SyncAvailability } from './availability.js';
-import type { CommitOutcome, QueryReadSpec, QuerySnapshot, WindowCoverage, WindowState } from './client.js';
+import type { CommitOutcome, ClientSnapshotReader, QueryReadSpec, QuerySnapshot, WindowCoverage, WindowState } from './client.js';
 import type { SqlValue } from './database.js';
 import type { ClientChangeListener, SyncStatusSnapshot } from './invalidation.js';
 import type { LeadershipState } from './multi-tab.js';
@@ -27,16 +27,14 @@ export interface LiveQueryResult<Row> {
     readonly isRefreshing: boolean;
     readonly availability: SyncAvailability;
 }
-export interface ReactiveQueryClient {
+export interface ReactiveQueryClient extends Pick<ClientSnapshotReader, 'statusSnapshot' | 'commitOutcomes'> {
     readonly currentSchemaVersion?: number;
     onChange(listener: ClientChangeListener): () => void;
     querySnapshot<Row = Record<string, SqlValue>>(spec: QueryReadSpec): QuerySnapshot<Row> | Promise<QuerySnapshot<Row>>;
-    statusSnapshot(): SyncStatusSnapshot | Promise<SyncStatusSnapshot>;
     leadershipSnapshot?(): LeadershipState | undefined;
     onLeadershipChange?(listener: (state: LeadershipState) => void): () => void;
-    readonly conflicts: readonly unknown[] | (() => readonly unknown[] | Promise<readonly unknown[]>);
-    readonly rejections: readonly unknown[] | (() => readonly unknown[] | Promise<readonly unknown[]>);
-    commitOutcomes(): readonly CommitOutcome[] | Promise<readonly CommitOutcome[]>;
+    conflicts(): readonly unknown[] | Promise<readonly unknown[]>;
+    rejections(): readonly unknown[] | Promise<readonly unknown[]>;
     setWindow(base: WindowBase, units: readonly string[]): void | Promise<void>;
     windowState(base: WindowBase): WindowState | Promise<WindowState>;
 }
@@ -85,6 +83,14 @@ export declare class ReactiveClientStore {
     window(base: WindowBase): ExternalStoreEntry<WindowState>;
     setWindowClaim(owner: symbol, base: WindowBase, units: readonly string[]): Promise<void>;
     releaseWindowClaims(owner: symbol): void;
+    /** Retained observation counts for diagnostics and resource benchmarks. */
+    cacheStats(): {
+        queries: number;
+        activeQueries: number;
+        windows: number;
+        activeWindows: number;
+        windowClaims: number;
+    };
     start(): void;
     dispose(): void;
 }

package/dist/reactive-store.js

@@ -1,11 +1,9 @@
 import { classifySyncAvailability, } from './availability.js';
+import { ClientSyncError } from './errors.js';
 import { windowBaseKey } from './window.js';
 function errorOf(value) {
     return value instanceof Error ? value : new Error(String(value));
 }
-function readCollection(value) {
-    return typeof value === 'function' ? value() : value;
-}
 function unsupportedCanonicalValue(value) {
     const description = Object.prototype.toString.call(value);
     throw new TypeError(`unsupported reactive cache-key value ${description}; use null, string, finite number, bigint, boolean, bytes, arrays, or plain objects`);
@@ -178,9 +176,58 @@ function reconcileRows(previous, fresh, rowKey) {
         ? previous
         : next;
 }
+/** Shared ownership for query and window observations, including abandoned renders. */
+class ObservationCache {
+    #entries = new Map();
+    #active = new Set();
+    get size() {
+        return this.#entries.size;
+    }
+    get activeSize() {
+        return this.#active.size;
+    }
+    get(key) {
+        return this.#entries.get(key);
+    }
+    add(key, entry) {
+        this.#entries.set(key, entry);
+        this.#cleanup(key, entry);
+    }
+    activate(key, candidate) {
+        const entry = this.#entries.get(key) ?? candidate;
+        this.#entries.set(key, entry);
+        this.#active.add(entry);
+        return entry;
+    }
+    deactivate(key, entry) {
+        this.#active.delete(entry);
+        this.#cleanup(key, entry);
+    }
+    #cleanup(key, entry) {
+        scheduleMicrotask(() => {
+            if (this.#active.has(entry))
+                return;
+            if (this.#entries.get(key) === entry)
+                this.#entries.delete(key);
+            entry.reset();
+        });
+    }
+    onChange(batch) {
+        for (const entry of this.#active)
+            entry.onChange(batch);
+    }
+    clear() {
+        for (const entry of this.#entries.values())
+            entry.dispose();
+        this.#entries.clear();
+        this.#active.clear();
+    }
+}
 class QueryEntry {
     store;
     spec;
+    key;
+    cache;
     #owner = Symbol('query-window-claim');
     #listeners = new Set();
     #state = {
@@ -191,22 +238,31 @@ class QueryEntry {
         isRefreshing: false,
         availability: { state: 'ready' },
     };
-    #subscribers = 0;
+    #delegate;
+    #generation = 0;
     #scheduled = false;
     #running = false;
     #requested = false;
     #desiredRevision = 0n;
     #claimReady = Promise.resolve();
     #offStatus;
-    constructor(store, spec) {
+    constructor(store, spec, key, cache) {
         this.store = store;
         this.spec = spec;
+        this.key = key;
+        this.cache = cache;
     }
-    getSnapshot = () => this.#state;
+    getSnapshot = () => this.#delegate?.getSnapshot() ?? this.#state;
     subscribe = (listener) => {
-        this.#listeners.add(listener);
-        this.#subscribers += 1;
-        if (this.#subscribers === 1) {
+        const current = this.cache.activate(this.key, this);
+        if (current !== this) {
+            this.#delegate = current;
+            return this.#delegate.subscribe(listener);
+        }
+        this.#delegate = undefined;
+        const notify = () => listener();
+        this.#listeners.add(notify);
+        if (this.#listeners.size === 1) {
             this.#offStatus = this.store.status.subscribe(() => this.#onAvailabilityChange());
             this.#onAvailabilityChange();
             if (this.spec.claimCoverage !== false) {
@@ -215,28 +271,59 @@ class QueryEntry {
                     claims.push(this.store.setWindowClaim(this.#owner, coverage.base, coverage.units));
                 }
                 this.#claimReady = Promise.all(claims).then(() => undefined);
+                // A render can lose its last subscriber before the read loop starts.
+                // The loop still observes the original rejection while it owns the claim.
+                void this.#claimReady.catch(() => undefined);
             }
             this.#requestRead();
         }
         return () => {
-            if (!this.#listeners.delete(listener))
+            if (!this.#listeners.delete(notify))
                 return;
-            this.#subscribers -= 1;
-            if (this.#subscribers === 0) {
+            if (this.#listeners.size === 0) {
+                this.cache.deactivate(this.key, this);
                 this.#offStatus?.();
                 this.#offStatus = undefined;
                 this.store.releaseWindowClaims(this.#owner);
             }
         };
     };
-    refresh = () => this.#requestRead(true);
+    refresh = () => {
+        if (this.#delegate !== undefined)
+            this.#delegate.refresh();
+        else
+            this.#requestRead(true);
+    };
+    reset() {
+        this.#generation += 1;
+        this.#scheduled = false;
+        this.#running = false;
+        this.#requested = false;
+        this.#desiredRevision = 0n;
+        this.#claimReady = Promise.resolve();
+        this.#state = {
+            rows: [],
+            phase: 'loading',
+            revision: undefined,
+            error: undefined,
+            isRefreshing: false,
+            availability: { state: 'ready' },
+        };
+    }
+    dispose() {
+        this.#listeners.clear();
+        this.#offStatus?.();
+        this.#offStatus = undefined;
+        this.store.releaseWindowClaims(this.#owner);
+        this.reset();
+    }
     onChange(batch) {
         if (!batchMatches(batch, this.spec))
             return;
         if (batch.revision > this.#desiredRevision) {
             this.#desiredRevision = batch.revision;
         }
-        if (this.#subscribers > 0)
+        if (this.#listeners.size > 0)
             this.#requestRead();
     }
     #publish(next) {
@@ -253,6 +340,8 @@ class QueryEntry {
             listener();
     }
     #requestRead(refreshing = false) {
+        if (this.#listeners.size === 0)
+            return;
         this.#requested = true;
         if (refreshing &&
             this.#state.revision !== undefined &&
@@ -262,7 +351,10 @@ class QueryEntry {
         if (this.#scheduled || this.#running)
             return;
         this.#scheduled = true;
+        const generation = this.#generation;
         scheduleMicrotask(() => {
+            if (generation !== this.#generation)
+                return;
             this.#scheduled = false;
             void this.#readLoop();
         });
@@ -292,8 +384,9 @@ class QueryEntry {
             this.#requestRead();
     }
     async #readLoop() {
-        if (this.#running || this.#subscribers === 0)
+        if (this.#running || this.#listeners.size === 0)
             return;
+        const generation = this.#generation;
         this.#running = true;
         try {
             do {
@@ -301,6 +394,8 @@ class QueryEntry {
                 if (this.store.availabilitySnapshot().state === 'blocked')
                     break;
                 await this.#claimReady;
+                if (generation !== this.#generation || this.#listeners.size === 0)
+                    return;
                 const snapshot = await this.store.client.querySnapshot({
                     sql: this.spec.sql,
                     ...(this.spec.params !== undefined
@@ -310,6 +405,8 @@ class QueryEntry {
                         ? { coverage: this.spec.coverage }
                         : {}),
                 });
+                if (generation !== this.#generation || this.#listeners.size === 0)
+                    return;
                 const availability = this.store.availabilitySnapshot();
                 if (availability.state === 'blocked') {
                     this.#publish({
@@ -341,9 +438,11 @@ class QueryEntry {
                     isRefreshing: false,
                     availability,
                 });
-            } while (this.#requested && this.#subscribers > 0);
+            } while (this.#requested && this.#listeners.size > 0);
         }
         catch (error) {
+            if (generation !== this.#generation || this.#listeners.size === 0)
+                return;
             const wrapped = errorOf(error);
             this.#publish({
                 ...this.#state,
@@ -354,15 +453,18 @@ class QueryEntry {
             });
         }
         finally {
-            this.#running = false;
-            if (this.#requested && this.#subscribers > 0)
-                this.#requestRead();
+            if (generation === this.#generation) {
+                this.#running = false;
+                if (this.#requested && this.#listeners.size > 0)
+                    this.#requestRead();
+            }
         }
     }
 }
 class ValueEntry {
     value;
     read;
+    #generation = 0;
     #listeners = new Set();
     constructor(value, read) {
         this.value = value;
@@ -374,9 +476,17 @@ class ValueEntry {
         return () => this.#listeners.delete(listener);
     };
     refresh = () => {
-        void this.read().then((next) => this.set(next));
+        const generation = ++this.#generation;
+        void this.read().then((next) => {
+            if (generation === this.#generation)
+                this.set(next);
+        });
     };
+    invalidate() {
+        this.#generation += 1;
+    }
     set(next) {
+        this.invalidate();
         if (next === this.value)
             return;
         this.value = next;
@@ -388,28 +498,59 @@ class WindowEntry {
     store;
     base;
     baseKey;
+    cache;
     #listeners = new Set();
     #state = { units: [], pending: [] };
+    #generation = 0;
+    #delegate;
     #running = false;
     #requested = false;
-    constructor(store, base, baseKey) {
+    constructor(store, base, baseKey, cache) {
         this.store = store;
         this.base = base;
         this.baseKey = baseKey;
+        this.cache = cache;
     }
-    getSnapshot = () => this.#state;
+    getSnapshot = () => this.#delegate?.getSnapshot() ?? this.#state;
     subscribe = (listener) => {
-        this.#listeners.add(listener);
+        const current = this.cache.activate(this.baseKey, this);
+        if (current !== this) {
+            this.#delegate = current;
+            return this.#delegate.subscribe(listener);
+        }
+        this.#delegate = undefined;
+        const notify = () => listener();
+        this.#listeners.add(notify);
         if (this.#listeners.size === 1)
             this.refresh();
-        return () => this.#listeners.delete(listener);
+        return () => {
+            if (this.#listeners.delete(notify) && this.#listeners.size === 0) {
+                this.cache.deactivate(this.baseKey, this);
+            }
+        };
     };
     refresh = () => {
+        if (this.#delegate !== undefined) {
+            this.#delegate.refresh();
+            return;
+        }
+        if (this.#listeners.size === 0)
+            return;
         this.#requested = true;
         if (this.#running)
             return;
         void this.#readLoop();
     };
+    reset() {
+        this.#generation += 1;
+        this.#running = false;
+        this.#requested = false;
+        this.#state = { units: [], pending: [] };
+    }
+    dispose() {
+        this.#listeners.clear();
+        this.reset();
+    }
     onChange(batch) {
         if (batch.windows.some((change) => change.baseKey === this.baseKey) &&
             this.#listeners.size > 0) {
@@ -417,34 +558,39 @@ class WindowEntry {
         }
     }
     async #readLoop() {
+        const generation = this.#generation;
         this.#running = true;
         try {
             do {
                 this.#requested = false;
                 const next = await this.store.client.windowState(this.base);
+                if (generation !== this.#generation || this.#listeners.size === 0)
+                    return;
                 if (canonicalValue(next.units) !== canonicalValue(this.#state.units) ||
                     canonicalValue(next.pending) !== canonicalValue(this.#state.pending)) {
                     this.#state = next;
                     for (const listener of this.#listeners)
                         listener();
                 }
-            } while (this.#requested);
+            } while (this.#requested && this.#listeners.size > 0);
         }
         catch {
             // WindowState predates the error-bearing query result. Keep the last
             // coherent snapshot; a later exact window event or refresh retries.
         }
         finally {
-            this.#running = false;
-            if (this.#requested)
-                this.refresh();
+            if (generation === this.#generation) {
+                this.#running = false;
+                if (this.#requested)
+                    this.refresh();
+            }
         }
     }
 }
 export class ReactiveClientStore {
     client;
-    #queries = new Map();
-    #windows = new Map();
+    #queries = new ObservationCache();
+    #windows = new ObservationCache();
     #windowClaims = new Map();
     #offChange;
     #offLeadership;
@@ -479,8 +625,8 @@ export class ReactiveClientStore {
         const conflicts = new ValueEntry({ conflicts: [], rejections: [], error: undefined, isLoading: true }, async () => {
             try {
                 const [found, rejected] = await Promise.all([
-                    readCollection(client.conflicts),
-                    readCollection(client.rejections),
+                    client.conflicts(),
+                    client.rejections(),
                 ]);
                 return {
                     conflicts: found,
@@ -513,9 +659,6 @@ export class ReactiveClientStore {
         this.status = status;
         this.conflicts = conflicts;
         this.outcomes = outcomes;
-        status.refresh();
-        conflicts.refresh();
-        outcomes.refresh();
         this.start();
     }
     query(spec) {
@@ -541,8 +684,8 @@ export class ReactiveClientStore {
         });
         let entry = this.#queries.get(key);
         if (entry === undefined) {
-            entry = new QueryEntry(this, spec);
-            this.#queries.set(key, entry);
+            entry = new QueryEntry(this, spec, key, this.#queries);
+            this.#queries.add(key, entry);
         }
         return entry;
     }
@@ -580,8 +723,8 @@ export class ReactiveClientStore {
         const key = windowBaseKey(base);
         let entry = this.#windows.get(key);
         if (entry === undefined) {
-            entry = new WindowEntry(this, base, key);
-            this.#windows.set(key, entry);
+            entry = new WindowEntry(this, base, key, this.#windows);
+            this.#windows.add(key, entry);
         }
         return entry;
     }
@@ -624,7 +767,8 @@ export class ReactiveClientStore {
         });
     }
     async #flushWindow(group) {
-        if (group.running)
+        const baseKey = windowBaseKey(group.base);
+        if (group.running || this.#windowClaims.get(baseKey) !== group)
             return;
         group.running = true;
         try {
@@ -636,6 +780,8 @@ export class ReactiveClientStore {
                 const key = canonicalValue(units);
                 if (key !== group.appliedKey) {
                     await this.client.setWindow(group.base, units);
+                    if (this.#windowClaims.get(baseKey) !== group)
+                        return;
                     group.appliedKey = key;
                 }
             }
@@ -648,18 +794,33 @@ export class ReactiveClientStore {
         }
         finally {
             group.running = false;
-            if (group.requested)
+            if (group.requested && this.#windowClaims.get(baseKey) === group)
                 this.#scheduleWindow(group);
+            else if (group.claims.size === 0 &&
+                group.waiters.length === 0 &&
+                group.appliedKey === canonicalValue([])) {
+                const key = windowBaseKey(group.base);
+                if (this.#windowClaims.get(key) === group)
+                    this.#windowClaims.delete(key);
+            }
         }
     }
+    /** Retained observation counts for diagnostics and resource benchmarks. */
+    cacheStats() {
+        return {
+            queries: this.#queries.size,
+            activeQueries: this.#queries.activeSize,
+            windows: this.#windows.size,
+            activeWindows: this.#windows.activeSize,
+            windowClaims: this.#windowClaims.size,
+        };
+    }
     start() {
         if (this.#offChange !== undefined)
             return;
         this.#offChange = this.client.onChange((batch) => {
-            for (const entry of this.#queries.values())
-                entry.onChange(batch);
-            for (const entry of this.#windows.values())
-                entry.onChange(batch);
+            this.#queries.onChange(batch);
+            this.#windows.onChange(batch);
             if (batch.status !== undefined) {
                 this.status.set({
                     status: batch.status,
@@ -680,14 +841,27 @@ export class ReactiveClientStore {
                 ...previous,
                 leadership,
             });
+            if (previous.isLoading)
+                this.status.refresh();
         });
+        this.status.refresh();
+        this.conflicts.refresh();
+        this.outcomes.refresh();
     }
     dispose() {
+        this.#queries.clear();
+        this.#windows.clear();
+        for (const entry of [this.status, this.conflicts, this.outcomes]) {
+            entry.invalidate();
+        }
         this.#offChange?.();
         this.#offChange = undefined;
         this.#offLeadership?.();
         this.#offLeadership = undefined;
         for (const group of this.#windowClaims.values()) {
+            for (const waiter of group.waiters.splice(0)) {
+                waiter.reject(new ClientSyncError('client.reactive_store_disposed', 'reactive store disposed'));
+            }
             // Releasing a window is best-effort teardown. A resource owner may have
             // already closed the underlying worker/native handle before React effect
             // cleanup runs (notably during schema-changing HMR). Do not let that

package/dist/realtime-supervisor.d.ts

@@ -1,6 +1,5 @@
 import type { SecurityLifecycle } from './client.js';
 import type { ClientDiagnosticsConnectivity, ClientDiagnosticsListener, ClientDiagnosticsSnapshot } from './diagnostics.js';
-export { linkRealtimeSupervisorObservation } from './realtime-supervisor-observation.js';
 type CancelTimer = () => void;
 export interface RealtimeSupervisorClient {
     connectRealtime(): Promise<void>;
@@ -91,3 +90,4 @@ export declare class RealtimeSupervisor {
 export declare function installRealtimeSupervisor<T extends RealtimeSupervisorClient>(client: T, options?: RealtimeSupervisorOptions): T;
 export declare function realtimeSupervisorSnapshot(client: object): RealtimeSupervisorSnapshot;
 export declare function subscribeRealtimeSupervisor(client: object, listener: () => void): () => void;
+export {};

package/dist/realtime-supervisor.js

@@ -1,5 +1,3 @@
-import { realtimeSupervisorObservationSource } from './realtime-supervisor-observation.js';
-export { linkRealtimeSupervisorObservation } from './realtime-supervisor-observation.js';
 const REALTIME_SUPERVISOR_KEY = Symbol.for('syncular.realtime-supervisor.v1');
 const DEFAULT_INITIAL_DELAY_MS = 1_000;
 const DEFAULT_MAXIMUM_DELAY_MS = 30_000;
@@ -8,16 +6,12 @@ const UNSUPPORTED_SNAPSHOT = Object.freeze({
     phase: 'unsupported',
     attempt: 0,
 });
-function attachment(client, visited = new Set()) {
-    if (visited.has(client))
-        return undefined;
-    visited.add(client);
+function attachment(client) {
     const candidate = Reflect.get(client, REALTIME_SUPERVISOR_KEY);
     if (candidate?.version === 1 && candidate.supervisor) {
         return candidate;
     }
-    const source = realtimeSupervisorObservationSource(client);
-    return source === undefined ? undefined : attachment(source, visited);
+    return undefined;
 }
 function scheduleTimer(callback, delayMs) {
     const timer = globalThis.setTimeout(callback, delayMs);

package/dist/remote.d.ts

@@ -18,6 +18,8 @@ export interface SyncRemoteClientConfig {
     readonly operations?: RemoteOperationTransport;
     readonly operationRealtime?: RemoteOperationRealtimeConnector;
     readonly encryption?: EncryptionConfig;
+    /** Acquired partition log epoch for restore-safe ordinary commits (§2.1). */
+    readonly logEpoch?: string;
 }
 export interface RemoteCommitInput {
     /** Stable caller-owned idempotency identity for this logical commit. */