@gonvex/client 0.1.24 → 0.1.26

package/dist/index.js

@@ -1,6 +1,8 @@
 import { createQueryCacheStore, defaultQueryCacheReadTimeoutMs, } from "./query-cache.js";
 import { createSyncStore, syncHashesDigest, syncRowsHashes, } from "./sync-store.js";
 import { GonvexErrorReporter } from "./error-reporter.js";
+import { OptimisticOverlay } from "./optimistic.js";
+import { createMutationOutbox, } from "./outbox.js";
 export * from "./cache.js";
 export * from "./cache-coordinator.js";
 export * from "./browser-cache.js";
@@ -11,6 +13,9 @@ export * from "./persistent-cache.js";
 export * from "./query-cache.js";
 export * from "./sync-store.js";
 export * from "./error-reporter.js";
+export * from "./optimistic.js";
+export * from "./outbox.js";
+export * from "./signals.js";
 /**
  * Typed error for every rejected Gonvex operation. `code` distinguishes
  * server-side failures from transport-level ones so apps can decide whether
@@ -20,7 +25,7 @@ export * from "./error-reporter.js";
  * - `timeout`: no response arrived within the operation timeout. For
  *   mutations/actions the write may or may not have been applied.
  * - `disconnected`: the socket dropped while the operation was pending.
- *   Mutations/actions fail closed and are never replayed automatically.
+ *   Mutations/actions fail closed unless a mutation opted into the outbox.
  * - `closed`: the client was explicitly closed.
  * - `auth`: authentication was rejected.
  */
@@ -72,6 +77,14 @@ export class GonvexClient {
     auth = {};
     authInFlight = false;
     authWatchdogTimer;
+    // Monotonic guard for async token fetches: a resolve whose generation is no
+    // longer current was superseded (newer setAuth, watchdog re-issue, or a
+    // reconnect's own fetch) and must be discarded.
+    authFetchGeneration = 0;
+    // At most one forced refresh per rejection cycle; cleared when auth settles
+    // or a fresh send cycle starts, so a bad token can't refresh-loop forever.
+    authRetriedAfterError = false;
+    authErrorHandlers = new Set();
     telemetryEnabled = false;
     queryCache;
     queryCacheWaitForScope;
@@ -79,6 +92,14 @@ export class GonvexClient {
     querySubscriptionRetentionMs;
     syncSubscriptionRetentionMs;
     syncStore;
+    mutationOutbox;
+    overlay = new OptimisticOverlay();
+    optimisticMutationIds = new Set();
+    outboxReady;
+    unsubscribeOutbox;
+    unsubscribeOverlay;
+    drainingOutbox = false;
+    outboxDrainTimer;
     queryCacheDirective;
     queryCacheGeneration = 0;
     // Sync collections live under a visibility-only scope that survives query
@@ -108,6 +129,14 @@ export class GonvexClient {
         this.querySubscriptionRetentionMs = normalizeQuerySubscriptionRetentionMs(options.querySubscriptionRetentionMs);
         this.syncSubscriptionRetentionMs = normalizeQuerySubscriptionRetentionMs(options.syncSubscriptionRetentionMs);
         this.syncStore = createSyncStore(options.sync);
+        this.mutationOutbox = createMutationOutbox(options.outbox);
+        this.unsubscribeOutbox = this.mutationOutbox.subscribe(() => {
+            void this.drainOutbox();
+        });
+        this.unsubscribeOverlay = this.overlay.subscribe((collection) => {
+            this.emitOptimisticCollection(collection);
+        });
+        this.outboxReady = this.restoreOutbox();
         this.timeouts = {
             queryTimeoutMs: options.timeouts?.queryTimeoutMs ?? DEFAULT_QUERY_TIMEOUT_MS,
             mutationTimeoutMs: options.timeouts?.mutationTimeoutMs ?? DEFAULT_MUTATION_TIMEOUT_MS,
@@ -118,6 +147,15 @@ export class GonvexClient {
         }
         this.recoverWarmSyncDirective();
     }
+    /** The client's materialized optimistic state for pending-row indicators. */
+    get optimisticOverlay() {
+        return this.overlay;
+    }
+    /** Number of mutations waiting for a definitive server result. */
+    async outboxCount() {
+        await this.outboxReady;
+        return this.mutationOutbox.count();
+    }
     connectionState() {
         const inflightMutations = countPendingCalls(this.pendingCalls, "mutation");
         const inflightActions = countPendingCalls(this.pendingCalls, "action");
@@ -152,13 +190,40 @@ export class GonvexClient {
         }
     }
     setAuth(auth) {
+        this.applyAuth(auth);
+        // The caller owns auth now: a token fetch still in flight from the
+        // previous installation must not clobber this one when it resolves.
+        this.authFetchGeneration += 1;
+        if (this.socket?.readyState === WebSocket.OPEN) {
+            // A token supplied in this very call was just minted by the caller —
+            // send it as-is instead of paying another fetch round trip.
+            this.sendAuth(true, { useFetcher: !hasOwn(auth, "token") });
+        }
+    }
+    /**
+     * Subscribe to unrecoverable auth rejections: the server refused the
+     * credentials and, when a token fetcher is installed, a force-refreshed
+     * token did not fix it. Lets apps route to sign-in instead of silently
+     * degrading to an unauthenticated session.
+     */
+    onAuthError(handler) {
+        this.authErrorHandlers.add(handler);
+        return () => {
+            this.authErrorHandlers.delete(handler);
+        };
+    }
+    applyAuth(auth) {
         const nextAuth = { ...this.auth, ...auth };
         const tokenScopeChanged = hasOwn(auth, "token")
             && auth.token !== this.auth.token
             && !sameAuthTokenIdentity(this.auth, nextAuth);
         const scopeMayChange = tokenScopeChanged
             || (hasOwn(auth, "tenant") && auth.tenant !== this.auth.tenant)
-            || (hasOwn(auth, "project") && auth.project !== this.auth.project);
+            || (hasOwn(auth, "project") && auth.project !== this.auth.project)
+            // An identity hint that changes the derived key must recover (or drop)
+            // the warm directive just like a token change would. Same-key updates —
+            // e.g. installing the hint after its token is already live — are inert.
+            || (hasOwn(auth, "identity") && !sameAuthTokenIdentity(this.auth, nextAuth));
         if (scopeMayChange) {
             this.resetQueryCacheScope();
         }
@@ -172,9 +237,6 @@ export class GonvexClient {
         if (auth.telemetry !== undefined) {
             this.telemetryEnabled = auth.telemetry === true;
         }
-        if (this.socket?.readyState === WebSocket.OPEN) {
-            this.sendAuth(true);
-        }
     }
     connect() {
         if (this.socket && this.socket.readyState <= WebSocket.OPEN)
@@ -198,6 +260,7 @@ export class GonvexClient {
             this.sendAuth(false);
             if (isReconnect)
                 this.resubscribeQueries(generation);
+            void this.drainOutbox();
             this.notifyConnectionState();
         });
         socket.addEventListener("close", () => {
@@ -254,18 +317,33 @@ export class GonvexClient {
                     this.authWatchdogTimer = undefined;
                 }
                 if (message.type === "auth.result") {
+                    this.authRetriedAfterError = false;
                     this.installQueryCacheDirective(queryCacheDirectiveFromAuthResult(message.result));
                     this.queryCacheNegotiatedSocketGeneration = this.socketGeneration;
                     this.resumeQuerySubscriptions();
                 }
                 else {
+                    const fetcher = this.auth.fetchToken;
+                    if (fetcher && !this.authRetriedAfterError) {
+                        // The installed token was rejected — typically expired while the
+                        // socket was down. Force-refresh through the fetcher and retry
+                        // once before treating the rejection as final.
+                        this.authRetriedAfterError = true;
+                        this.authInFlight = true;
+                        this.armAuthWatchdog();
+                        void this.refreshRejectedAuth(fetcher, this.auth.token, message.error);
+                        return;
+                    }
+                    this.authRetriedAfterError = false;
                     this.resetQueryCacheScope();
+                    this.notifyAuthError(message.error);
                 }
                 this.flushPendingMessages();
             }
             if (message.type === "sync.readyMany") {
                 for (const ready of message.ready) {
-                    this.handlers.get(ready.id)?.({ type: "sync.ready", ...ready });
+                    const readyMessage = { type: "sync.ready", ...ready };
+                    this.handlers.get(ready.id)?.(readyMessage);
                 }
                 return;
             }
@@ -301,6 +379,12 @@ export class GonvexClient {
             this.querySubscribeFlushTimer = undefined;
         }
         this.pendingQuerySubscribes.clear();
+        if (this.outboxDrainTimer) {
+            clearTimeout(this.outboxDrainTimer);
+            this.outboxDrainTimer = undefined;
+        }
+        this.unsubscribeOutbox();
+        this.unsubscribeOverlay();
         for (const subscription of this.querySubscriptions.values()) {
             if (subscription.cacheReadFallbackTimer)
                 clearTimeout(subscription.cacheReadFallbackTimer);
@@ -309,6 +393,10 @@ export class GonvexClient {
         this.querySubscriptions.clear();
         this.syncSubscriptions.clear();
         this.sessionScopeHandlers.clear();
+        this.authErrorHandlers.clear();
+        // Invalidate any token fetch still in flight so its resolve can't touch
+        // the closed client's caches.
+        this.authFetchGeneration += 1;
         this.queryCacheGeneration += 1;
         this.queryCacheDirective = undefined;
         this.queryCache?.close();
@@ -575,8 +663,9 @@ export class GonvexClient {
             existing.listeners.add(onMessage);
             if (existing.lastMessage) {
                 queueMicrotask(() => {
-                    if (existing.listeners.has(onMessage) && existing.lastMessage)
-                        onMessage(existing.lastMessage);
+                    if (existing.listeners.has(onMessage) && existing.lastMessage) {
+                        onMessage(this.materializeSyncMessage(existing, existing.lastMessage));
+                    }
                 });
             }
             return () => this.unsubscribeSyncListener(key, onMessage);
@@ -677,6 +766,7 @@ export class GonvexClient {
             subscription.cursor = message.cursor;
             subscription.keyField = message.key;
             subscription.mode = message.mode;
+            subscription.truncated = undefined;
             subscription.orderBy = message.orderBy;
             subscription.orderDirection = message.orderDirection;
             subscription.maxRows = message.maxRows;
@@ -730,6 +820,7 @@ export class GonvexClient {
             subscription.verificationGeneration += 1;
             subscription.isUpToDate = false;
             subscription.cursor = undefined;
+            subscription.truncated = undefined;
             subscription.rows = [];
             subscription.persistedRows = undefined;
             subscription.hashes = {};
@@ -825,6 +916,7 @@ export class GonvexClient {
         subscription.opening = false;
         subscription.cursor = message.cursor;
         subscription.mode = message.mode ?? subscription.mode;
+        subscription.truncated = message.truncated;
         subscription.integrityDigest = verifiedDigest;
         subscription.integrityRows = subscription.rows;
         subscription.forceFullIntegrity = false;
@@ -835,8 +927,24 @@ export class GonvexClient {
         this.emitSyncMessage(subscription, message.digest === verifiedDigest ? message : { ...message, digest: verifiedDigest });
     }
     emitSyncMessage(subscription, message) {
+        const outgoing = this.materializeSyncMessage(subscription, message);
         for (const listener of Array.from(subscription.listeners))
-            listener(message);
+            listener(outgoing);
+    }
+    materializeSyncMessage(subscription, message) {
+        if (message.type !== "sync.snapshot")
+            return message;
+        return {
+            ...message,
+            result: this.overlay.apply(subscription.path, message.result, message.key),
+        };
+    }
+    emitOptimisticCollection(collection) {
+        for (const subscription of this.syncSubscriptions.values()) {
+            if (subscription.path !== collection || subscription.lastMessage?.type !== "sync.snapshot")
+                continue;
+            this.emitSyncMessage(subscription, subscription.lastMessage);
+        }
     }
     markSyncSubscriptionsOutOfDate() {
         for (const subscription of this.syncSubscriptions.values()) {
@@ -901,6 +1009,7 @@ export class GonvexClient {
                 subscription.cursor = cached.cursor;
                 subscription.keyField = cached.keyField;
                 subscription.mode = cached.mode;
+                subscription.truncated = cached.truncated;
                 subscription.orderBy = cached.orderBy;
                 subscription.orderDirection = cached.orderDirection;
                 subscription.maxRows = cached.maxRows;
@@ -1050,6 +1159,7 @@ export class GonvexClient {
             cursor: subscription.cursor,
             keyField: subscription.keyField,
             mode: subscription.mode,
+            truncated: subscription.truncated,
             orderBy: subscription.orderBy,
             orderDirection: subscription.orderDirection,
             maxRows: subscription.maxRows,
@@ -1070,6 +1180,7 @@ export class GonvexClient {
             cursor: subscription.cursor,
             keyField: subscription.keyField,
             mode: subscription.mode,
+            truncated: subscription.truncated,
             orderBy: subscription.orderBy,
             orderDirection: subscription.orderDirection,
             upserts,
@@ -1083,8 +1194,100 @@ export class GonvexClient {
         subscription.persistedRows = subscription.rows;
         this.enqueueSyncPersistence(subscription, scope, () => store.applyDelta(scope, subscription.path, subscription.args, value));
     }
+    async restoreOutbox() {
+        const entries = await this.mutationOutbox.loadAll();
+        if (this.manuallyClosed)
+            return;
+        for (const entry of entries) {
+            this.addOptimisticMutation(entry.idempotencyKey, entry.patches ?? []);
+        }
+        const nextAttemptAt = Math.min(...entries
+            .filter((entry) => entry.state === "pending")
+            .map((entry) => entry.nextAttemptAt));
+        if (Number.isFinite(nextAttemptAt) && nextAttemptAt > Date.now()) {
+            this.scheduleOutboxDrain(nextAttemptAt - Date.now());
+        }
+    }
+    addOptimisticMutation(mutationId, patches) {
+        if (patches.length === 0 || this.optimisticMutationIds.has(mutationId))
+            return;
+        this.optimisticMutationIds.add(mutationId);
+        this.overlay.add(mutationId, patches);
+    }
+    settleOptimisticMutation(mutationId) {
+        this.optimisticMutationIds.delete(mutationId);
+        this.overlay.settle(mutationId);
+    }
+    rejectOptimisticMutation(mutationId) {
+        this.optimisticMutationIds.delete(mutationId);
+        this.overlay.reject(mutationId);
+    }
+    async drainOutbox() {
+        await this.outboxReady;
+        if (this.drainingOutbox
+            || this.manuallyClosed
+            || !this.socket
+            || this.socket.readyState !== WebSocket.OPEN)
+            return;
+        this.drainingOutbox = true;
+        try {
+            while (!this.manuallyClosed && this.socket?.readyState === WebSocket.OPEN) {
+                const entry = await this.mutationOutbox.nextReady(Date.now());
+                if (!entry)
+                    return;
+                await this.mutationOutbox.markInflight(entry.id);
+                try {
+                    await this.call("mutation", { kind: "mutation", path: entry.path }, entry.args, this.timeouts.mutationTimeoutMs, entry.idempotencyKey);
+                    await this.mutationOutbox.ack(entry.id);
+                    this.settleOptimisticMutation(entry.idempotencyKey);
+                }
+                catch (error) {
+                    if (error instanceof GonvexClientError && error.code === "server") {
+                        await this.mutationOutbox.ack(entry.id);
+                        this.rejectOptimisticMutation(entry.idempotencyKey);
+                        continue;
+                    }
+                    await this.mutationOutbox.fail(entry.id, mutationErrorMessage(error));
+                    this.scheduleOutboxDrain(Math.min(30_000, 1_000 * (2 ** (entry.attempts + 1))));
+                    return;
+                }
+            }
+        }
+        finally {
+            this.drainingOutbox = false;
+        }
+    }
+    scheduleOutboxDrain(delay) {
+        if (this.manuallyClosed)
+            return;
+        if (this.outboxDrainTimer)
+            clearTimeout(this.outboxDrainTimer);
+        this.outboxDrainTimer = setTimeout(() => {
+            this.outboxDrainTimer = undefined;
+            void this.drainOutbox();
+        }, delay);
+    }
     mutation(ref, args = {}, options = {}) {
-        return this.call("mutation", ref, args, options.timeoutMs ?? this.timeouts.mutationTimeoutMs);
+        const mutationId = randomID();
+        const patches = options.optimistic ?? [];
+        this.addOptimisticMutation(mutationId, patches);
+        return this.call("mutation", ref, args, options.timeoutMs ?? this.timeouts.mutationTimeoutMs, mutationId).then((result) => {
+            this.settleOptimisticMutation(mutationId);
+            return result;
+        }).catch(async (error) => {
+            if (isQueueableMutationError(error) && options.offline === "queue") {
+                await this.mutationOutbox.enqueue({
+                    path: ref.path,
+                    args,
+                    idempotencyKey: mutationId,
+                    entityKeys: patches.map((patch) => patch.rowId),
+                    patches,
+                });
+                return { status: "queued", mutationId };
+            }
+            this.rejectOptimisticMutation(mutationId);
+            throw error;
+        });
     }
     action(ref, args = {}, options = {}) {
         return this.call("action", ref, args, options.timeoutMs ?? this.timeouts.actionTimeoutMs);
@@ -1202,9 +1405,9 @@ export class GonvexClient {
         this.notifyConnectionState();
         return Promise.all(registered.map((entry) => settle(entry.promise, entry.path)));
     }
-    call(kind, ref, args, timeoutMs) {
+    call(kind, ref, args, timeoutMs, id) {
         this.connect();
-        const entry = this.registerCall(kind, ref, args, timeoutMs);
+        const entry = this.registerCall(kind, ref, args, timeoutMs, id);
         if (kind === "mutation") {
             try {
                 const w = globalThis;
@@ -1220,8 +1423,8 @@ export class GonvexClient {
         this.notifyConnectionState();
         return entry.promise;
     }
-    registerCall(kind, ref, args, timeoutMs) {
-        const id = randomID();
+    registerCall(kind, ref, args, timeoutMs, callId = randomID()) {
+        const id = callId;
         const clientSentAtMs = nowMs();
         const promise = new Promise((resolve, reject) => {
             const pending = { id, kind, path: ref.path, reject };
@@ -1671,11 +1874,20 @@ export class GonvexClient {
             device: event.device ?? browserTelemetryInfo(),
         });
     }
-    sendAuth(force) {
-        if (!force && !this.auth.token && !this.auth.tenant && !this.auth.project)
+    sendAuth(force, options = {}) {
+        if (!force && !this.auth.token && !this.auth.tenant && !this.auth.project && !this.auth.fetchToken)
             return;
         this.authInFlight = true;
+        this.authRetriedAfterError = false;
         this.armAuthWatchdog();
+        const fetcher = this.auth.fetchToken;
+        if (fetcher && options.useFetcher !== false) {
+            void this.fetchAndSendAuth(fetcher);
+            return;
+        }
+        this.sendAuthFrame();
+    }
+    sendAuthFrame() {
         this.sendNow({
             type: "auth",
             id: randomID(),
@@ -1685,6 +1897,74 @@ export class GonvexClient {
             device: browserTelemetryInfo(),
         });
     }
+    // Tokens from a fetcher are typically short-lived while the socket (and any
+    // disconnect gap) can span hours: replaying the token that was current at
+    // setAuth time guarantees an auth.error after a long sleep. authInFlight is
+    // already true here, so everything else queues behind the fetch exactly as
+    // it queues behind the server's auth reply.
+    async fetchAndSendAuth(fetcher) {
+        const generation = ++this.authFetchGeneration;
+        const socket = this.socket;
+        let token;
+        try {
+            token = await fetcher({ forceRefreshToken: false });
+        }
+        catch {
+            // A fetcher that cannot reach its identity provider (offline start)
+            // must not sign the session out — fall back to the installed token.
+            token = undefined;
+        }
+        if (generation !== this.authFetchGeneration || this.auth.fetchToken !== fetcher)
+            return;
+        if (typeof token === "string" && token) {
+            this.applyAuth({ token });
+        }
+        else if (token === null) {
+            // The fetcher is authoritative about sign-out.
+            this.applyAuth({ token: undefined });
+        }
+        // A dead socket's close handler already reset authInFlight; the next
+        // reconnect runs its own sendAuth, so this resolve has nothing to send.
+        if (this.socket !== socket || socket?.readyState !== WebSocket.OPEN)
+            return;
+        this.sendAuthFrame();
+    }
+    async refreshRejectedAuth(fetcher, rejectedToken, error) {
+        const generation = ++this.authFetchGeneration;
+        const socket = this.socket;
+        let token;
+        try {
+            token = await fetcher({ forceRefreshToken: true });
+        }
+        catch {
+            token = undefined;
+        }
+        if (generation !== this.authFetchGeneration || this.auth.fetchToken !== fetcher)
+            return;
+        if (typeof token === "string" && token && token !== rejectedToken) {
+            this.applyAuth({ token });
+            if (this.socket === socket && socket?.readyState === WebSocket.OPEN) {
+                this.sendAuthFrame();
+            }
+            return;
+        }
+        // No fresher credential exists (fetch failed, signed out, or the refresh
+        // returned the very token the server just refused): surface the rejection
+        // and degrade to the unauthenticated flow exactly like the no-fetcher path.
+        this.authInFlight = false;
+        if (this.authWatchdogTimer) {
+            clearTimeout(this.authWatchdogTimer);
+            this.authWatchdogTimer = undefined;
+        }
+        this.resetQueryCacheScope();
+        this.notifyAuthError(error);
+        this.flushPendingMessages();
+    }
+    notifyAuthError(error) {
+        for (const handler of Array.from(this.authErrorHandlers)) {
+            handler(error);
+        }
+    }
     // A lost auth reply (e.g. the server swapped its app plugin and dropped
     // in-flight responses while the socket stayed up) used to leave
     // authInFlight stuck true forever: every later mutation/subscription
@@ -1757,6 +2037,13 @@ function countPendingCalls(calls, kind) {
     }
     return count;
 }
+function isQueueableMutationError(error) {
+    return error instanceof GonvexClientError
+        && (error.code === "disconnected" || error.code === "timeout");
+}
+function mutationErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 function stableStringify(value) {
     if (typeof value === "string") {
         return JSON.stringify(value)
@@ -1886,6 +2173,8 @@ function authFromOptions(options) {
         token: options.token,
         tenant: options.tenant,
         telemetry: options.telemetry,
+        identity: options.identity,
+        fetchToken: options.fetchToken,
     };
 }
 function normalizeQuerySubscriptionRetentionMs(value) {
@@ -1896,6 +2185,19 @@ function normalizeQuerySubscriptionRetentionMs(value) {
     return Math.max(0, Math.min(5 * 60_000, Math.floor(value)));
 }
 function authIdentityKey(auth) {
+    if (!auth.tenant)
+        return "";
+    if (auth.token)
+        return authIdentityKeyFromToken(auth);
+    // Token-free fallback: an explicit identity hint carries the same claims a
+    // token would supply, so both paths derive the same key for the same user.
+    const hint = auth.identity;
+    if (hint && typeof hint.sub === "string" && hint.sub.trim()) {
+        return [auth.project ?? "", auth.tenant, hint.iss ?? "", hint.sub].join("\u0000");
+    }
+    return "";
+}
+function authIdentityKeyFromToken(auth) {
     if (!auth.token || !auth.tenant)
         return "";
     const parts = auth.token.split(".");