@gonvex/client 0.1.18 → 0.1.20

package/README.md

@@ -66,6 +66,42 @@ await client.clearQueryCache({ allScopes: true });
 Dexie is loaded asynchronously only after a cache-capable session is confirmed,
 so IndexedDB setup does not delay the WebSocket query path.
 
+## Durable Sync Collections
+
+Sync functions materialize bounded, authorized single-table collections in a
+normalized IndexedDB store and resume them from a durable Postgres cursor:
+
+```ts
+const watch = client.watchSync<Task>(
+  { kind: "sync", path: "tasks.recent" },
+  { workspaceId: "workspace-a" },
+);
+
+const stop = watch.onUpdate(() => {
+  render(watch.localSyncResult() ?? []);
+  console.log(watch.status()); // { isLoading, isUpToDate }
+});
+```
+
+Configure or disable the sync store when constructing the client:
+
+```ts
+const client = new GonvexClient(url, {
+  sync: {
+    databaseName: "my-product-sync",
+    maxBytes: 150 * 1024 * 1024,
+  },
+});
+
+const memoryOnly = new GonvexClient(url, { sync: false });
+```
+
+The default global IndexedDB budget is 100 MiB. Server-declared per-collection
+row/byte budgets still apply, and least-recently-used collections are evicted
+first. Storage is isolated by runtime, project, tenant, authenticated identity,
+and permissions. Sync is not an offline write queue; mutations and actions
+retain the fail-closed policy below.
+
 ## Lightweight Error Tracking
 
 Capture global browser failures and failed Gonvex operations with the same
@@ -145,6 +181,7 @@ The package exports:
 - `ConvexReactClient` compatibility alias
 - `GonvexClientError`, `ConnectionState`, timeout defaults
 - transparent persistent query caching and lower-level experimental cache helpers
+- `subscribeSync`, `watchSync`, and normalized persistent sync storage
 - browser capability and telemetry helpers
 - `GonvexErrorReporter` and automatic operation error reporting
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { BrowserTelemetryInfo, JsonValue, MessageTrace, ServerMessage } from "@gonvex/protocol";
+import type { BrowserTelemetryInfo, JsonValue, MessageTrace, ServerCapabilities, 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";
@@ -84,6 +84,11 @@ export type GonvexClientOptions = GonvexClientAuth & {
      * Defaults to 250ms; set a longer bounded window for local-first apps.
      */
     querySubscriptionRetentionMs?: number;
+    /**
+     * Keep listenerless durable syncs open briefly across React remounts.
+     * Defaults to 250ms, preventing close/open/snapshot churn in StrictMode.
+     */
+    syncSubscriptionRetentionMs?: number;
     sync?: false | SyncStoreOptions;
     errorReporting?: false | Omit<ErrorReporterOptions, "endpoint" | "project" | "tenant">;
     timeouts?: GonvexTimeoutOptions;
@@ -111,18 +116,24 @@ export declare class GonvexClient {
     private readonly telemetryHandlers;
     private readonly pendingMessages;
     private readonly pendingSyncOpens;
+    private readonly pendingQuerySubscribes;
+    private readonly syncPersistence;
     private syncOpenFlushTimer;
+    private querySubscribeFlushTimer;
     private serverCapabilities;
     private auth;
     private authInFlight;
+    private authWatchdogTimer;
     private telemetryEnabled;
     private readonly queryCache;
     private readonly queryCacheWaitForScope;
     private readonly queryCacheReadTimeoutMs;
     private readonly querySubscriptionRetentionMs;
+    private readonly syncSubscriptionRetentionMs;
     private readonly syncStore;
     private queryCacheDirective;
     private queryCacheGeneration;
+    private syncScopeGeneration;
     private queryCacheNegotiatedSocketGeneration;
     private syncIdentityGeneration;
     private readonly sessionScopeHandlers;
@@ -139,6 +150,8 @@ export declare class GonvexClient {
     private readonly timeouts;
     constructor(url: string, options?: GonvexClientOptions);
     connectionState(): ConnectionState;
+    /** Metadata advertised by the runtime in its latest session.ready frame. */
+    serverInfo(): Readonly<ServerCapabilities>;
     subscribeToConnectionState(handler: ConnectionStateHandler): () => void;
     private notifyConnectionState;
     setAuth(auth: GonvexClientAuth): void;
@@ -168,7 +181,9 @@ export declare class GonvexClient {
         onUpdate(handler: WatchUpdateHandler): () => void;
     };
     private handleSyncMessage;
+    private acceptSyncReady;
     private emitSyncMessage;
+    private markSyncSubscriptionsOutOfDate;
     private startSync;
     private sendSyncOpen;
     private syncOpenRequest;
@@ -185,9 +200,28 @@ export declare class GonvexClient {
      * nothing is subscribed to this query.
      */
     retryQuery(ref: FunctionReference, args?: JsonValue): void;
+    /**
+     * Flush a queue of mutations in one `mutation.callMany` frame (queue order,
+     * one websocket round trip). Each entry settles independently — a failed
+     * call does not reject the batch — so offline queues can apply per-row
+     * outcomes. Falls back to sequential `mutation` calls on runtimes that do
+     * not advertise the `mutationBatch` capability.
+     */
+    mutationMany<T = JsonValue>(calls: Array<{
+        ref: FunctionReference;
+        args?: JsonValue;
+    }>, options?: CallOptions): Promise<Array<{
+        status: "ok";
+        result: T;
+    } | {
+        status: "error";
+        error: GonvexClientError;
+    }>>;
     private call;
+    private registerCall;
     private unsubscribeQueryListener;
     private sendSubscription;
+    private flushQuerySubscribes;
     private resumeQuerySubscriptions;
     private enqueueSyncPersistence;
     private scheduleSyncRetry;
@@ -199,6 +233,8 @@ export declare class GonvexClient {
     private installQueryCacheDirective;
     private recoverWarmSyncDirective;
     private resetQueryCacheScope;
+    private resetQueryResultCacheState;
+    private resetSyncCacheState;
     private startQueryCacheRead;
     private persistQueryResult;
     private deleteCachedQuery;
@@ -207,6 +243,7 @@ export declare class GonvexClient {
     private emitTelemetry;
     private reportTelemetry;
     private sendAuth;
+    private armAuthWatchdog;
     private send;
     private sendNow;
     private flushPendingMessages;