@gonvex/client 0.5.2-staging.10 → 0.5.2-staging.12

package/dist/browser-upgrades.d.ts

@@ -0,0 +1,19 @@
+import { type ClientContract, type ClientMigration } from "./client-upgrades.js";
+import type { LocalReplicaStorage } from "./local-replica.js";
+import type { OutboxStore } from "./outbox.js";
+export type BrowserUpgradeOptions = {
+    replicaName: string;
+    outboxName: string;
+    contract: ClientContract;
+    /** Version assigned to data written before this mechanism was introduced. */
+    initialVersion: number;
+    migrations: readonly ClientMigration[];
+    onRequired?: (error: Error) => void;
+};
+/** All app access goes through version-fenced SDK stores, including old tabs. */
+export declare function browserUpgradeStorage(options: BrowserUpgradeOptions): {
+    storage: LocalReplicaStorage;
+    store: OutboxStore;
+    ready: Promise<void>;
+    close(): void;
+};

package/dist/browser-upgrades.js

@@ -0,0 +1,111 @@
+import { Dexie } from "dexie";
+import { IndexedDBLocalReplicaStorage } from "./indexeddb-replica.js";
+import { migrateClientData, migrationChain } from "./client-upgrades.js";
+/** All app access goes through version-fenced SDK stores, including old tabs. */
+export function browserUpgradeStorage(options) {
+    const replica = new IndexedDBLocalReplicaStorage(options.replicaName);
+    const queue = new Dexie(options.outboxName);
+    queue.version(1).stores({ entries: "++id, state, nextAttemptAt" });
+    queue.version(2).stores({ entries: "++id, scope, state, nextAttemptAt, [scope+state], [scope+nextAttemptAt]" });
+    const meta = new Dexie(`${options.replicaName}-upgrades`);
+    meta.version(1).stores({ state: "&key" });
+    const lockName = `gonvex-upgrade:${options.replicaName}:${options.outboxName}`;
+    const locks = globalThis.navigator?.locks;
+    const channel = typeof BroadcastChannel === "function" ? new BroadcastChannel(lockName) : undefined;
+    let closed = false;
+    const requireUpgrade = (error) => { options.onRequired?.(error); return error; };
+    if (channel)
+        channel.onmessage = event => {
+            if (event.data?.version !== options.contract.version)
+                requireUpgrade(new Error("Another tab upgraded the application. Reload to continue."));
+        };
+    const ready = (async () => {
+        if (!locks)
+            throw new Error("Safe offline upgrades require browser Web Locks support");
+        await locks.request(lockName, { mode: "exclusive" }, async () => {
+            await Promise.all([meta.open(), queue.open()]);
+            const saved = await meta.state.get("contract");
+            const hasOldData = saved ? true : (await replica.listScopes()).length > 0 || await queue.entries.count() > 0;
+            let record = saved ?? { key: "contract", version: hasOldData ? options.initialVersion : options.contract.version };
+            // A interrupted upgrade must finish its exact staged payload before another upgrade starts.
+            const finish = async () => {
+                if (!record.journal)
+                    return;
+                for (const [scope, snapshot] of Object.entries(record.journal.snapshots))
+                    await replica.replaceSnapshot(snapshot, scope);
+                await queue.transaction("rw", queue.entries, async () => {
+                    await queue.entries.clear();
+                    await queue.entries.bulkPut(record.journal.entries);
+                });
+                record = { key: "contract", version: record.version };
+                await meta.state.put(record);
+            };
+            // An older tab must never finish a newer migration and then hydrate it.
+            if (record.version > options.contract.version)
+                throw new Error("Stored data requires a newer application build");
+            await finish();
+            const chain = migrationChain(record.version, options.contract.version, options.migrations);
+            if (chain.length) {
+                const snapshots = {};
+                for (const scope of await replica.listScopes()) {
+                    const snapshot = await replica.load(scope);
+                    if (snapshot)
+                        snapshots[scope] = snapshot;
+                }
+                const entries = await queue.entries.toArray();
+                if (entries.some(entry => !entry.scope))
+                    throw new Error("Unowned offline work needs recovery before upgrading");
+                // No writes until every transform succeeds. The journal is temporary upgrade data,
+                // never a second source of application state. Applying it is repeatable after a crash.
+                const journal = migrateClientData(snapshots, entries, chain);
+                record = { key: "contract", version: options.contract.version, journal };
+                await meta.state.put(record);
+                await finish();
+                channel?.postMessage({ version: record.version });
+            }
+            else
+                await meta.state.put(record);
+        });
+    })().catch(error => { throw requireUpgrade(error instanceof Error ? error : new Error(String(error))); });
+    // The SDK may initialize storage before React subscribes; retain the rejected ready promise.
+    void ready.catch(() => undefined);
+    const guarded = async (run) => {
+        await ready;
+        if (closed)
+            throw new Error("Application storage is closed");
+        return locks.request(lockName, { mode: "shared" }, async () => {
+            const record = await meta.state.get("contract");
+            if (record?.version !== options.contract.version || record.journal) {
+                throw requireUpgrade(new Error("Application storage changed. Reload before continuing."));
+            }
+            return run();
+        });
+    };
+    const storage = new Proxy(replica, {
+        get(target, property) {
+            const value = Reflect.get(target, property);
+            return typeof value === "function" ? (...args) => guarded(() => value.apply(target, args)) : value;
+        },
+    });
+    return {
+        storage, ready,
+        store: {
+            strictPersistence: true,
+            allocateId: () => guarded(async () => {
+                const last = await queue.entries.orderBy('id').last();
+                return meta.transaction('rw', meta.state, async () => {
+                    const counter = await meta.state.get('sequence');
+                    const version = Math.max(counter?.version ?? 0, last?.id ?? 0) + 1;
+                    await meta.state.put({ key: 'sequence', version });
+                    return version;
+                });
+            }),
+            load: () => guarded(() => queue.entries.toArray()),
+            put: entry => guarded(async () => { await queue.entries.put(entry); }),
+            delete: id => guarded(() => queue.entries.delete(id)),
+            clear: scope => guarded(() => scope ? queue.entries.where("scope").equals(scope).delete().then(() => undefined) : queue.entries.clear()),
+        },
+        close() { closed = true; channel?.close(); replica.close(); queue.close(); meta.close(); },
+    };
+}
+//# sourceMappingURL=browser-upgrades.js.map

package/dist/browser-upgrades.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-upgrades.js","sourceRoot":"","sources":["../src/browser-upgrades.ts"],"names":[],"mappings":"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"}

package/dist/client-upgrades.d.ts

@@ -0,0 +1,26 @@
+import type { JsonValue } from "@gonvex/protocol";
+import type { ReplicaSnapshot } from "./local-replica.js";
+import type { ReducerOutboxEntry } from "./outbox.js";
+export type ClientContract = {
+    version: number;
+    offlineMaxAgeMs: number;
+};
+export type ClientMigration = {
+    from: number;
+    to: number;
+    /** Pure synchronous transformation of confirmed rows. Never optimistic patches. */
+    replica?: (snapshot: ReplicaSnapshot) => ReplicaSnapshot;
+    /** Throw if the user's meaning cannot be preserved. The original queue survives. */
+    intent?: (intent: {
+        path: string;
+        args: JsonValue;
+    }) => {
+        path: string;
+        args: JsonValue;
+    };
+};
+export declare function migrationChain(from: number, to: number, migrations: readonly ClientMigration[]): ClientMigration[];
+export declare function migrateClientData(snapshots: Record<string, ReplicaSnapshot>, entries: readonly ReducerOutboxEntry[], chain: readonly ClientMigration[]): {
+    snapshots: Record<string, ReplicaSnapshot>;
+    entries: ReducerOutboxEntry[];
+};

package/dist/client-upgrades.js

@@ -0,0 +1,40 @@
+export function migrationChain(from, to, migrations) {
+    if (!Number.isSafeInteger(from) || from < 1 || !Number.isSafeInteger(to) || to < from) {
+        throw new Error(`Unsupported client contract transition ${from} -> ${to}`);
+    }
+    const chain = [];
+    for (let version = from; version < to; version++) {
+        const candidates = migrations.filter(m => m.from === version);
+        if (candidates.length !== 1 || candidates[0].to !== version + 1) {
+            throw new Error(`Missing or ambiguous client migration ${version} -> ${version + 1}`);
+        }
+        chain.push(candidates[0]);
+    }
+    return chain;
+}
+export function migrateClientData(snapshots, entries, chain) {
+    let nextSnapshots = structuredClone(snapshots);
+    let nextEntries = structuredClone([...entries]);
+    for (const migration of chain) {
+        nextSnapshots = Object.fromEntries(Object.entries(nextSnapshots).map(([scope, snapshot]) => {
+            const next = migration.replica ? migration.replica(snapshot) : snapshot;
+            // Shape migration does not establish server freshness or preserve query membership contracts.
+            delete next.cursor;
+            next.liveQueries = {};
+            return [scope, next];
+        }));
+        nextEntries = nextEntries.map(entry => {
+            const originalPath = entry.receiptPath ?? entry.path;
+            const intent = migration.intent?.({ path: entry.path, args: structuredClone(entry.args) })
+                ?? { path: entry.path, args: entry.args };
+            if (!intent.path || intent.args === undefined)
+                throw new Error("Client migration returned an invalid intent");
+            return { ...entry, path: intent.path, args: intent.args,
+                receiptPath: originalPath, patches: [],
+                // Committed responses awaiting a watermark must be reconciled by their original receipt too.
+                state: "pending", nextAttemptAt: 0 };
+        });
+    }
+    return { snapshots: nextSnapshots, entries: nextEntries };
+}
+//# sourceMappingURL=client-upgrades.js.map

package/dist/client-upgrades.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-upgrades.js","sourceRoot":"","sources":["../src/client-upgrades.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import type { BrowserTelemetryInfo, ExecutionScope, JsonValue, MessageTrace, ServerCapabilities, ServerMessage } from "@gonvex/protocol";
+import type { LocalRuntimeBinding } from "@gonvex/local-runtime/worker-client";
 import { type ErrorReporterOptions } from "./error-reporter.js";
 export { GonvexErrorReporter } from "./error-reporter.js";
 export type { ErrorReporterOptions, ErrorEventPayload, ErrorContext, ErrorAccount } from "./error-reporter.js";
@@ -10,9 +11,11 @@ export * from "./error-reporter.js";
 export * from "./optimistic.js";
 export * from "./outbox.js";
 export * from "./kv-stores.js";
+export * from "./client-upgrades.js";
+export * from "./browser-upgrades.js";
 export * from "./signals.js";
 export * from "./external-auth.js";
-export { MemoryLocalReplicaStorage, type LocalReplicaStorage, type LocalReplicaView, type ReplicaChange, type ReplicaFreshness, type ReplicaRow, type ReplicaScope, type ReplicaSnapshot, type ReplicaTransaction, type ReplicaWindow, type LiveQueryResult, type ReplicaCollectionState, type ReplicaCollectionSubscriptionState, type ReplicaCollectionPlan, } from "./local-replica.js";
+export { MemoryLocalReplicaStorage, type LocalReplicaStorage, type LocalReplicaSession, type LocalReplicaView, type ReplicaChange, type ReplicaFreshness, type ReplicaRow, type ReplicaScope, type ReplicaSnapshot, type ReplicaTransaction, type ReplicaWindow, type LiveQueryResult, type ReplicaCollectionState, type ReplicaCollectionSubscriptionState, type ReplicaCollectionPlan, } from "./local-replica.js";
 export * from "./query-expression.js";
 export * from "./indexeddb-replica.js";
 export * from "./control.js";
@@ -49,6 +52,11 @@ export type FunctionReference<Args extends JsonValue = JsonValue, Result extends
         conflict?: "reject" | "expectedVersion" | "merge";
         reason?: string;
     };
+    localExecution?: 1;
+    /** SDK-owned version check for replay; never an application argument. */
+    receiptPath?: string;
+    artifactHash?: string;
+    intentEntropy?: string;
     live?: {
         entity: string;
         key: string;
@@ -153,6 +161,13 @@ export type GonvexClientAuth = {
     };
 };
 export type GonvexClientOptions = GonvexClientAuth & {
+    clientContract?: import("./client-upgrades.js").ClientContract;
+    onUpdateRequired?: (reason: string) => void;
+    /** Supplied by generated client bindings, once for the entire application. */
+    localRuntime?: LocalRuntimeBinding & {
+        clientContract?: import("./client-upgrades.js").ClientContract;
+        collections?: readonly FunctionReference[];
+    };
     /**
      * Keep listenerless live queries subscribed for this long so route
      * backtracking can reuse their current result without WebSocket churn.
@@ -197,6 +212,16 @@ export type GonvexTelemetryEvent = {
 };
 export declare class GonvexClient {
     private readonly url;
+    private readonly localBinding?;
+    private readonly localExecutor?;
+    private readonly localStorage?;
+    private localIdentity?;
+    private localLane;
+    private localReplayScheduled;
+    private replacingLocal;
+    private readonly unsubscribeLocal?;
+    private readonly localCollectionClosers;
+    private readonly reducerRejectionHandlers;
     private socket;
     private readonly handlers;
     private readonly querySubscriptions;
@@ -259,7 +284,25 @@ export declare class GonvexClient {
     private hasEverConnected;
     private connectionCount;
     private readonly timeouts;
+    private readonly clientContract?;
+    private readonly updateRequiredHandler?;
+    private updateRequired;
+    private lastOnlineAtMs;
     constructor(url: string, options?: GonvexClientOptions);
+    /** Authoritative sync failures arrive after an offline call returned locally. */
+    onReducerRejection(listener: (event: {
+        reducerId: string;
+        path: string;
+        error: string;
+    }) => void): () => void;
+    private restoreLocalSession;
+    private ensureLocalCollections;
+    private localSnapshot;
+    private inLocalLane;
+    private scheduleLocalReplay;
+    private reportLocalRejection;
+    private rebaseLocalEntries;
+    private runLocalReducer;
     /** The single normalized authoritative + optimistic application data store. */
     get localReplica(): LocalReplicaView;
     replicaSignature(ref: FunctionReference, args?: JsonValue): string;
@@ -372,6 +415,7 @@ export declare class GonvexClient {
     }): Promise<T | QueuedReducerOutcome>;
     reducer<T extends JsonValue = JsonValue, Args extends JsonValue = JsonValue>(ref: FunctionReference<Args, T>, args?: Args, options?: CallOptions): Promise<T>;
     private runOptimisticReducer;
+    private requireClientUpdate;
     private canSendReducerNow;
     action<T extends JsonValue = JsonValue, Args extends JsonValue = JsonValue>(ref: FunctionReference<Args, T>, args?: Args, options?: CallOptions): Promise<T>;
     query<T extends JsonValue = JsonValue, Args extends JsonValue = JsonValue>(ref: FunctionReference<Args, T>, args?: Args, options?: CallOptions): Promise<T>;