@gonvex/client 0.1.13 → 0.1.15

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import type { BrowserTelemetryInfo, JsonValue, MessageTrace, ServerMessage } from "@gonvex/protocol";
 import { type QueryCacheOptions, type QueryCacheStatus } from "./query-cache.js";
+import { type SyncStoreOptions } from "./sync-store.js";
 import { type ErrorReporterOptions } from "./error-reporter.js";
 export * from "./cache.js";
 export * from "./cache-coordinator.js";
@@ -9,6 +10,7 @@ export * from "./browser-cache-shared-worker.js";
 export * from "./browser-capabilities.js";
 export * from "./persistent-cache.js";
 export * from "./query-cache.js";
+export * from "./sync-store.js";
 export * from "./error-reporter.js";
 export type { QueryCacheDirective } from "@gonvex/protocol";
 type SubscriptionHandler = (message: ServerMessage) => void;
@@ -76,6 +78,7 @@ export type GonvexClientAuth = {
 };
 export type GonvexClientOptions = GonvexClientAuth & {
     queryCache?: false | QueryCacheOptions;
+    sync?: false | SyncStoreOptions;
     errorReporting?: false | Omit<ErrorReporterOptions, "endpoint" | "project" | "tenant">;
     timeouts?: GonvexTimeoutOptions;
 };
@@ -97,6 +100,7 @@ export declare class GonvexClient {
     private socket;
     private readonly handlers;
     private readonly querySubscriptions;
+    private readonly syncSubscriptions;
     private readonly oneShotQueries;
     private readonly telemetryHandlers;
     private readonly pendingMessages;
@@ -104,8 +108,10 @@ export declare class GonvexClient {
     private authInFlight;
     private telemetryEnabled;
     private readonly queryCache;
+    private readonly syncStore;
     private queryCacheDirective;
     private queryCacheGeneration;
+    private syncIdentityGeneration;
     private readonly sessionScopeHandlers;
     private readonly errorReporter;
     private reconnectTimer;
@@ -139,6 +145,22 @@ export declare class GonvexClient {
         localQueryResult(): T | undefined;
         onUpdate(handler: WatchUpdateHandler): () => void;
     };
+    subscribeSync(ref: FunctionReference, args: JsonValue | undefined, onMessage: SubscriptionHandler): () => void;
+    watchSync<T extends JsonValue = JsonValue>(ref: FunctionReference, args?: JsonValue): {
+        localSyncResult(): T[] | undefined;
+        status(): {
+            isLoading: boolean;
+            isUpToDate: boolean;
+        };
+        onUpdate(handler: WatchUpdateHandler): () => void;
+    };
+    private handleSyncMessage;
+    private emitSyncMessage;
+    private startSync;
+    private sendSyncOpen;
+    private unsubscribeSyncListener;
+    private persistSyncSnapshot;
+    private persistSyncDelta;
     mutation<T = JsonValue>(ref: FunctionReference, args?: JsonValue, options?: CallOptions): Promise<T>;
     action<T = JsonValue>(ref: FunctionReference, args?: JsonValue, options?: CallOptions): Promise<T>;
     query<T = JsonValue>(ref: FunctionReference, args?: JsonValue, options?: CallOptions): Promise<T>;
@@ -151,11 +173,15 @@ export declare class GonvexClient {
     private call;
     private unsubscribeQueryListener;
     private sendSubscription;
+    private enqueueSyncPersistence;
+    private scheduleSyncRetry;
+    private clearSyncRetry;
     private requestSubscriptionSnapshot;
     private sendOneShotQuery;
     private resubscribeQueries;
     private scheduleReconnect;
     private installQueryCacheDirective;
+    private recoverWarmSyncDirective;
     private resetQueryCacheScope;
     private startQueryCacheRead;
     private persistQueryResult;

package/dist/index.js

@@ -1,4 +1,5 @@
 import { createQueryCacheStore } from "./query-cache.js";
+import { createSyncStore } from "./sync-store.js";
 import { GonvexErrorReporter } from "./error-reporter.js";
 export * from "./cache.js";
 export * from "./cache-coordinator.js";
@@ -8,6 +9,7 @@ export * from "./browser-cache-shared-worker.js";
 export * from "./browser-capabilities.js";
 export * from "./persistent-cache.js";
 export * from "./query-cache.js";
+export * from "./sync-store.js";
 export * from "./error-reporter.js";
 /**
  * Typed error for every rejected Gonvex operation. `code` distinguishes
@@ -42,6 +44,7 @@ export class GonvexClient {
     socket;
     handlers = new Map();
     querySubscriptions = new Map();
+    syncSubscriptions = new Map();
     oneShotQueries = new Map();
     telemetryHandlers = new Set();
     pendingMessages = [];
@@ -49,8 +52,10 @@ export class GonvexClient {
     authInFlight = false;
     telemetryEnabled = false;
     queryCache;
+    syncStore;
     queryCacheDirective;
     queryCacheGeneration = 0;
+    syncIdentityGeneration = 0;
     sessionScopeHandlers = new Set();
     errorReporter;
     reconnectTimer;
@@ -68,6 +73,7 @@ export class GonvexClient {
         this.auth = authFromOptions(options);
         this.telemetryEnabled = options.telemetry === true;
         this.queryCache = createQueryCacheStore(options.queryCache);
+        this.syncStore = createSyncStore(options.sync);
         this.timeouts = {
             queryTimeoutMs: options.timeouts?.queryTimeoutMs ?? DEFAULT_QUERY_TIMEOUT_MS,
             mutationTimeoutMs: options.timeouts?.mutationTimeoutMs ?? DEFAULT_MUTATION_TIMEOUT_MS,
@@ -76,6 +82,7 @@ export class GonvexClient {
         if (options.errorReporting && options.project) {
             this.errorReporter = new GonvexErrorReporter({ endpoint: url, project: options.project, tenant: options.tenant, ...options.errorReporting });
         }
+        this.recoverWarmSyncDirective();
     }
     connectionState() {
         const inflightMutations = countPendingCalls(this.pendingCalls, "mutation");
@@ -107,13 +114,19 @@ export class GonvexClient {
         }
     }
     setAuth(auth) {
-        const scopeMayChange = (hasOwn(auth, "token") && auth.token !== this.auth.token)
+        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);
         if (scopeMayChange) {
             this.resetQueryCacheScope();
         }
-        this.auth = { ...this.auth, ...auth };
+        this.auth = nextAuth;
+        if (scopeMayChange)
+            this.recoverWarmSyncDirective();
         if (auth.tenant !== undefined)
             this.errorReporter?.setTenant(auth.tenant);
         if (auth.project !== undefined)
@@ -213,12 +226,17 @@ export class GonvexClient {
         }
         this.oneShotQueries.clear();
         this.rejectPendingCalls((call) => new GonvexClientError(`Gonvex client was closed while waiting for ${call.kind} ${call.path}`, { code: "closed", path: call.path, operation: call.kind }));
+        for (const subscription of this.syncSubscriptions.values()) {
+            this.clearSyncRetry(subscription);
+        }
         this.handlers.clear();
         this.querySubscriptions.clear();
+        this.syncSubscriptions.clear();
         this.sessionScopeHandlers.clear();
         this.queryCacheGeneration += 1;
         this.queryCacheDirective = undefined;
         this.queryCache?.close();
+        this.syncStore?.close();
         this.errorReporter?.close();
         const socket = this.socket;
         this.socket = undefined;
@@ -461,6 +479,261 @@ export class GonvexClient {
             },
         };
     }
+    subscribeSync(ref, args = {}, onMessage) {
+        this.connect();
+        const key = querySubscriptionKey(ref, args);
+        const existing = this.syncSubscriptions.get(key);
+        if (existing) {
+            existing.listeners.add(onMessage);
+            if (existing.lastMessage) {
+                queueMicrotask(() => {
+                    if (existing.listeners.has(onMessage) && existing.lastMessage)
+                        onMessage(existing.lastMessage);
+                });
+            }
+            return () => this.unsubscribeSyncListener(key, onMessage);
+        }
+        const subscription = {
+            id: randomID(),
+            key,
+            path: ref.path,
+            args,
+            listeners: new Set([onMessage]),
+            rows: [],
+            keyField: "id",
+            opening: false,
+            persistence: Promise.resolve(),
+            retryAttempt: 0,
+        };
+        this.syncSubscriptions.set(key, subscription);
+        this.handlers.set(subscription.id, (message) => this.handleSyncMessage(subscription, message));
+        this.startSync(subscription);
+        return () => this.unsubscribeSyncListener(key, onMessage);
+    }
+    watchSync(ref, args = {}) {
+        let latest;
+        let latestError;
+        let isUpToDate = false;
+        const updateHandlers = new Set();
+        const notify = () => {
+            for (const handler of updateHandlers)
+                handler();
+        };
+        const unsubscribe = this.subscribeSync(ref, args, (message) => {
+            if (message.type === "sync.snapshot") {
+                latest = message.result;
+                latestError = undefined;
+                notify();
+            }
+            else if (message.type === "sync.ready") {
+                isUpToDate = true;
+                notify();
+            }
+            else if (message.type === "sync.error") {
+                latestError = new Error(message.error);
+                notify();
+            }
+        });
+        const unsubscribeScope = this.onSessionScopeChange(() => {
+            latest = undefined;
+            latestError = undefined;
+            isUpToDate = false;
+            notify();
+        });
+        return {
+            localSyncResult() {
+                if (latestError)
+                    throw latestError;
+                return latest;
+            },
+            status() {
+                return { isLoading: latest === undefined, isUpToDate };
+            },
+            onUpdate(handler) {
+                updateHandlers.add(handler);
+                return () => {
+                    updateHandlers.delete(handler);
+                    if (updateHandlers.size === 0) {
+                        unsubscribe();
+                        unsubscribeScope();
+                    }
+                };
+            },
+        };
+    }
+    handleSyncMessage(subscription, message) {
+        if (message.type === "sync.snapshot") {
+            this.clearSyncRetry(subscription, true);
+            subscription.opening = false;
+            subscription.cursor = message.cursor;
+            subscription.keyField = message.key;
+            subscription.orderBy = message.orderBy;
+            subscription.orderDirection = message.orderDirection;
+            subscription.maxRows = message.maxRows;
+            subscription.maxBytes = message.maxBytes;
+            subscription.rows = boundSyncRows(message.result, message.key, message.maxRows, message.maxBytes, message.orderBy, message.orderDirection);
+            const snapshot = { ...message, result: subscription.rows };
+            subscription.lastMessage = snapshot;
+            this.emitSyncMessage(subscription, snapshot);
+            this.persistSyncSnapshot(subscription);
+            return;
+        }
+        if (message.type === "sync.delta") {
+            if (subscription.cursor && (message.cursor.epoch !== subscription.cursor.epoch
+                || message.cursor.revision <= subscription.cursor.revision))
+                return;
+            this.clearSyncRetry(subscription, true);
+            subscription.cursor = message.cursor;
+            subscription.rows = applySyncDelta(subscription.rows, subscription.keyField, message.upserts ?? [], message.deleted ?? [], subscription.maxRows, subscription.maxBytes, subscription.orderBy, subscription.orderDirection);
+            const snapshot = {
+                type: "sync.snapshot",
+                id: subscription.id,
+                path: subscription.path,
+                result: subscription.rows,
+                cursor: message.cursor,
+                key: subscription.keyField,
+                orderBy: subscription.orderBy,
+                orderDirection: subscription.orderDirection,
+                maxRows: subscription.maxRows,
+                maxBytes: subscription.maxBytes,
+            };
+            subscription.lastMessage = snapshot;
+            this.emitSyncMessage(subscription, snapshot);
+            this.persistSyncDelta(subscription, message.upserts ?? [], message.deleted ?? []);
+            return;
+        }
+        if (message.type === "sync.reset") {
+            this.clearSyncRetry(subscription, true);
+            subscription.cursor = undefined;
+            subscription.rows = [];
+            subscription.lastMessage = undefined;
+            subscription.opening = false;
+            const directive = this.queryCacheDirective;
+            const store = this.syncStore;
+            if (directive && store) {
+                this.enqueueSyncPersistence(subscription, () => store.delete(directive.scope, subscription.path, subscription.args));
+            }
+            queueMicrotask(() => this.sendSyncOpen(subscription));
+            return;
+        }
+        if (message.type === "sync.ready") {
+            this.clearSyncRetry(subscription, true);
+            subscription.opening = false;
+            subscription.cursor = message.cursor;
+        }
+        if (message.type === "sync.error") {
+            subscription.opening = false;
+            this.scheduleSyncRetry(subscription);
+        }
+        this.emitSyncMessage(subscription, message);
+    }
+    emitSyncMessage(subscription, message) {
+        for (const listener of Array.from(subscription.listeners))
+            listener(message);
+    }
+    startSync(subscription) {
+        const directive = this.queryCacheDirective;
+        const store = this.syncStore;
+        if (!directive)
+            return;
+        if (!store) {
+            this.sendSyncOpen(subscription);
+            return;
+        }
+        const generation = this.queryCacheGeneration;
+        if (subscription.cacheReadGeneration === generation)
+            return;
+        subscription.cacheReadGeneration = generation;
+        void store.load(directive.scope, subscription.path, subscription.args).then((cached) => {
+            if (this.syncSubscriptions.get(subscription.key) !== subscription
+                || this.queryCacheGeneration !== generation
+                || this.queryCacheDirective?.scope !== directive.scope)
+                return;
+            if (cached) {
+                subscription.rows = cached.rows;
+                subscription.cursor = cached.cursor;
+                subscription.keyField = cached.keyField;
+                subscription.orderBy = cached.orderBy;
+                subscription.orderDirection = cached.orderDirection;
+                subscription.maxRows = cached.maxRows;
+                subscription.maxBytes = cached.maxBytes;
+                const message = {
+                    type: "sync.snapshot",
+                    id: subscription.id,
+                    path: subscription.path,
+                    result: cached.rows,
+                    cursor: cached.cursor,
+                    key: cached.keyField,
+                    orderBy: cached.orderBy,
+                    orderDirection: cached.orderDirection,
+                    maxRows: cached.maxRows,
+                    maxBytes: cached.maxBytes,
+                };
+                subscription.lastMessage = message;
+                this.emitSyncMessage(subscription, message);
+            }
+            this.sendSyncOpen(subscription);
+        }).catch(() => this.sendSyncOpen(subscription));
+    }
+    sendSyncOpen(subscription) {
+        if (subscription.listeners.size === 0 || subscription.opening)
+            return;
+        subscription.opening = true;
+        subscription.socketGeneration = this.socketGeneration;
+        this.send({
+            type: "sync.open",
+            id: subscription.id,
+            path: subscription.path,
+            args: subscription.args,
+            cursor: subscription.cursor,
+            keys: subscription.rows.map((row) => syncRowKey(row, subscription.keyField)).filter(Boolean),
+        });
+    }
+    unsubscribeSyncListener(key, listener) {
+        const subscription = this.syncSubscriptions.get(key);
+        if (!subscription)
+            return;
+        subscription.listeners.delete(listener);
+        if (subscription.listeners.size > 0)
+            return;
+        this.clearSyncRetry(subscription);
+        this.syncSubscriptions.delete(key);
+        this.handlers.delete(subscription.id);
+        this.send({ type: "sync.close", id: subscription.id });
+    }
+    persistSyncSnapshot(subscription) {
+        const directive = this.queryCacheDirective;
+        const store = this.syncStore;
+        if (!directive || !store || !subscription.cursor)
+            return;
+        const value = {
+            rows: subscription.rows,
+            cursor: subscription.cursor,
+            keyField: subscription.keyField,
+            orderBy: subscription.orderBy,
+            orderDirection: subscription.orderDirection,
+            maxRows: subscription.maxRows,
+            maxBytes: subscription.maxBytes,
+        };
+        this.enqueueSyncPersistence(subscription, () => store.replace(directive.scope, subscription.path, subscription.args, value));
+    }
+    persistSyncDelta(subscription, upserts, deleted) {
+        const directive = this.queryCacheDirective;
+        const store = this.syncStore;
+        if (!directive || !store || !subscription.cursor)
+            return;
+        const value = {
+            cursor: subscription.cursor,
+            keyField: subscription.keyField,
+            orderBy: subscription.orderBy,
+            orderDirection: subscription.orderDirection,
+            upserts,
+            deleted,
+            maxRows: subscription.maxRows,
+            maxBytes: subscription.maxBytes,
+        };
+        this.enqueueSyncPersistence(subscription, () => store.applyDelta(directive.scope, subscription.path, subscription.args, value));
+    }
     mutation(ref, args = {}, options = {}) {
         return this.call("mutation", ref, args, options.timeoutMs ?? this.timeouts.mutationTimeoutMs);
     }
@@ -617,6 +890,39 @@ export class GonvexClient {
             args: subscription.args,
         });
     }
+    enqueueSyncPersistence(subscription, operation) {
+        subscription.persistence = subscription.persistence
+            .catch(() => undefined)
+            .then(operation)
+            .catch(() => undefined);
+    }
+    scheduleSyncRetry(subscription) {
+        if (this.manuallyClosed
+            || subscription.retryTimer
+            || subscription.listeners.size === 0
+            || this.syncSubscriptions.get(subscription.key) !== subscription)
+            return;
+        const delay = Math.min(250 * (2 ** subscription.retryAttempt), 5_000);
+        subscription.retryAttempt += 1;
+        subscription.retryTimer = setTimeout(() => {
+            subscription.retryTimer = undefined;
+            if (this.manuallyClosed
+                || !this.isWebSocketConnected
+                || subscription.listeners.size === 0
+                || this.syncSubscriptions.get(subscription.key) !== subscription)
+                return;
+            subscription.opening = false;
+            this.sendSyncOpen(subscription);
+        }, delay);
+    }
+    clearSyncRetry(subscription, resetAttempt = false) {
+        if (subscription.retryTimer) {
+            clearTimeout(subscription.retryTimer);
+            subscription.retryTimer = undefined;
+        }
+        if (resetAttempt)
+            subscription.retryAttempt = 0;
+    }
     requestSubscriptionSnapshot(subscription) {
         subscription.socketGeneration = undefined;
         this.sendSubscription(subscription);
@@ -639,6 +945,14 @@ export class GonvexClient {
         for (const query of this.oneShotQueries.values()) {
             this.sendOneShotQuery(query);
         }
+        for (const subscription of this.syncSubscriptions.values()) {
+            if (subscription.listeners.size === 0)
+                continue;
+            this.clearSyncRetry(subscription, true);
+            subscription.opening = false;
+            subscription.socketGeneration = undefined;
+            this.sendSyncOpen(subscription);
+        }
     }
     scheduleReconnect() {
         if (this.manuallyClosed || this.reconnectTimer)
@@ -667,9 +981,30 @@ export class GonvexClient {
             this.resetQueryCacheScope();
         }
         this.queryCacheDirective = value;
+        const identity = authIdentityKey(this.auth);
+        if (identity)
+            void this.syncStore?.saveDirective(identity, value).catch(() => undefined);
         for (const subscription of this.querySubscriptions.values()) {
             this.startQueryCacheRead(subscription);
         }
+        for (const subscription of this.syncSubscriptions.values()) {
+            this.startSync(subscription);
+        }
+    }
+    recoverWarmSyncDirective() {
+        const store = this.syncStore;
+        const identity = authIdentityKey(this.auth);
+        const generation = ++this.syncIdentityGeneration;
+        if (!store || !identity)
+            return;
+        void store.loadDirective(identity).then((directive) => {
+            if (generation !== this.syncIdentityGeneration
+                || authIdentityKey(this.auth) !== identity
+                || this.queryCacheDirective
+                || !validQueryCacheDirective(directive))
+                return;
+            this.installQueryCacheDirective(directive);
+        }).catch(() => undefined);
     }
     resetQueryCacheScope() {
         const hadScope = this.queryCacheDirective !== undefined;
@@ -680,7 +1015,15 @@ export class GonvexClient {
             subscription.serverSettled = false;
             subscription.cacheReadGeneration = undefined;
         }
-        if (hadScope || this.querySubscriptions.size > 0) {
+        for (const subscription of this.syncSubscriptions.values()) {
+            this.clearSyncRetry(subscription, true);
+            subscription.rows = [];
+            subscription.cursor = undefined;
+            subscription.lastMessage = undefined;
+            subscription.cacheReadGeneration = undefined;
+            subscription.opening = false;
+        }
+        if (hadScope || this.querySubscriptions.size > 0 || this.syncSubscriptions.size > 0) {
             for (const handler of this.sessionScopeHandlers)
                 handler();
         }
@@ -857,6 +1200,65 @@ function stableStringify(value) {
 function sameRevision(left, right) {
     return !!right && left.epoch === right.epoch && left.sequence === right.sequence;
 }
+function boundSyncRows(rows, keyField, maxRows, maxBytes, orderBy, orderDirection) {
+    const kept = [];
+    const seen = new Set();
+    let bytes = 0;
+    for (const row of sortClientSyncRows(rows, orderBy, orderDirection)) {
+        const key = syncRowKey(row, keyField);
+        if (!key || seen.has(key))
+            continue;
+        const size = syncJSONSize(row);
+        if (maxRows && kept.length >= maxRows)
+            break;
+        if (maxBytes && bytes + size > maxBytes)
+            break;
+        kept.push(row);
+        seen.add(key);
+        bytes += size;
+    }
+    return kept;
+}
+function applySyncDelta(current, keyField, upserts, deleted, maxRows, maxBytes, orderBy, orderDirection) {
+    const deletedSet = new Set(deleted);
+    const upsertKeys = new Set(upserts.map((row) => syncRowKey(row, keyField)).filter(Boolean));
+    const remainder = current.filter((row) => {
+        const key = syncRowKey(row, keyField);
+        return key && !deletedSet.has(key) && !upsertKeys.has(key);
+    });
+    return boundSyncRows([...upserts, ...remainder], keyField, maxRows, maxBytes, orderBy, orderDirection);
+}
+function sortClientSyncRows(rows, orderBy, orderDirection) {
+    if (!orderBy)
+        return rows;
+    const direction = orderDirection === "asc" ? 1 : -1;
+    return [...rows].sort((left, right) => {
+        const leftValue = syncOrderValue(left, orderBy);
+        const rightValue = syncOrderValue(right, orderBy);
+        if (leftValue === rightValue)
+            return 0;
+        if (leftValue === null)
+            return 1;
+        if (rightValue === null)
+            return -1;
+        return leftValue < rightValue ? -direction : direction;
+    });
+}
+function syncOrderValue(value, orderBy) {
+    if (!value || Array.isArray(value) || typeof value !== "object")
+        return null;
+    const candidate = value[orderBy];
+    return typeof candidate === "string" || typeof candidate === "number" ? candidate : null;
+}
+function syncRowKey(value, keyField) {
+    if (!value || Array.isArray(value) || typeof value !== "object")
+        return "";
+    const key = value[keyField];
+    return key === null || key === undefined ? "" : String(key);
+}
+function syncJSONSize(value) {
+    return new TextEncoder().encode(JSON.stringify(value)).byteLength;
+}
 function applyKeyedPatch(previous, patch) {
     const rows = new Map();
     for (const row of previous) {
@@ -900,6 +1302,34 @@ function authFromOptions(options) {
         telemetry: options.telemetry,
     };
 }
+function authIdentityKey(auth) {
+    if (!auth.token || !auth.tenant)
+        return "";
+    const parts = auth.token.split(".");
+    if (parts.length < 2)
+        return "";
+    try {
+        const encoded = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+        const padded = encoded.padEnd(Math.ceil(encoded.length / 4) * 4, "=");
+        const payload = JSON.parse(globalThis.atob(padded));
+        if (typeof payload.sub !== "string" || !payload.sub.trim())
+            return "";
+        return [
+            auth.project ?? "",
+            auth.tenant,
+            typeof payload.iss === "string" ? payload.iss : "",
+            payload.sub,
+        ].join("\u0000");
+    }
+    catch {
+        return "";
+    }
+}
+function sameAuthTokenIdentity(left, right) {
+    const leftIdentity = authIdentityKey(left);
+    const rightIdentity = authIdentityKey(right);
+    return leftIdentity !== "" && leftIdentity === rightIdentity;
+}
 function queryCacheDirectiveFromAuthResult(result) {
     if (!isJsonRecord(result))
         return undefined;