@gonvex/client 0.1.29 → 0.1.31

package/README.md

@@ -99,8 +99,54 @@ 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.
+and permissions.
+
+## Entity-level optimistic mutations
+
+Declare how a mutation maps its arguments to an entity row and how each live
+read projects that entity:
+
+```go
+app.Mutation(
+  "tasks.update",
+  updateTask,
+  gonvex.OptimisticMutation("tasks").RowIDArg("taskId").FieldsArg("updates"),
+)
+
+app.Query(
+  "tasks.byWorkspace",
+  tasksByWorkspace,
+  gonvex.OptimisticProjection("tasks").Key("_id").ResultPath("page"),
+)
+```
+
+Generated references carry this metadata, so a normal mutation call is enough:
+
+```ts
+await client.mutation(api.tasks.update, {
+  taskId,
+  updates: { priority_id: priorityId },
+});
+```
+
+The client persists the pending mutation before exposing it, layers it over
+every matching sync and query subscription, and notifies watchers immediately.
+An RPC result marks the write accepted but does not remove it; the overlay is
+retired only when every source that displayed it reports the mutation id (or a
+restored committed snapshot already matches). Deterministic server errors
+remove the overlay and repaint the authoritative rows. This keeps stale query
+or sync frames from briefly reverting the UI.
+
+The authoritative sync/query cache stays immutable. Durable pending state lives
+in the mutation outbox and is re-applied to cached rows after reload. Outbox
+rows are isolated by project, tenant, and authenticated identity; an account
+switch removes the previous identity's overlay and can never replay its writes
+under the new session. Unscoped rows from the pre-isolation schema are removed
+during migration because their owner cannot be proven. If an opaque credential
+does not expose a stable identity (and no `identity` hint is supplied), its
+outbox is deliberately session-only rather than risking cross-user replay. For
+a complex projection that cannot be derived from one nested fields argument,
+callers can still provide explicit `optimistic` entity patches.
 
 ## Lightweight Error Tracking
 
@@ -162,12 +208,19 @@ Rejected operations throw `GonvexClientError` with `code`:
 - `closed` — client was explicitly closed
 - `auth` — authentication rejected
 
-### Mutation / action fail-closed policy
+### Mutation / action disconnect policy
+
+Actions and mutations without `{ offline: "queue" }` fail closed after a
+disconnect. They reject with `code: "disconnected"` (or `timeout` / `closed`).
+Optimistic mutations are persisted before transport even in fail-closed mode,
+so a process reload cannot expose an older cached row while an accepted write
+is still waiting for its authoritative subscription update.
 
-Pending mutations and actions are **never** auto-replayed after disconnect.
-They reject with `code: "disconnected"` (or `timeout` / `closed`). Silent
-re-fire of non-idempotent writes is unsafe; offline queues belong in the app
-(or mobile offline layer), not this client.
+Pass `{ offline: "queue" }` to a mutation to durably accept a transport failure
+and replay the same idempotency key after reconnect, whether or not that
+mutation also declares optimistic UI metadata. Actions are never queued.
+Deterministic server errors are never queued and always roll an optimistic
+entity overlay back when one exists.
 
 Live queries keep last-good data at the React layer (`useQueryResult`) and
 resubscribe after reconnect. Call `client.retryQuery(ref, args)` to force a
@@ -181,6 +234,8 @@ The package exports:
 - `ConvexReactClient` compatibility alias
 - `GonvexClientError`, `ConnectionState`, timeout defaults
 - transparent persistent query caching and lower-level experimental cache helpers
+- durable entity-level optimistic overlays for query and sync projections
+- opt-in mutation outbox replay with stable idempotency keys
 - `subscribeSync`, `watchSync`, and normalized persistent sync storage
 - browser capability and telemetry helpers
 - `GonvexErrorReporter` and automatic operation error reporting

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import type { BrowserTelemetryInfo, JsonValue, MessageTrace, ServerCapabilities,
 import { type QueryCacheOptions, type QueryCacheStatus } from "./query-cache.js";
 import { type SyncStoreOptions } from "./sync-store.js";
 import { type ErrorReporterOptions } from "./error-reporter.js";
-import { OptimisticOverlay, type OptimisticPatch } from "./optimistic.js";
+import { OptimisticOverlay, type OptimisticMutationDefinition, type OptimisticPatch, type OptimisticProjection } from "./optimistic.js";
 export * from "./cache.js";
 export * from "./cache-coordinator.js";
 export * from "./browser-cache.js";
@@ -34,6 +34,10 @@ type ConnectionStateHandler = (state: ConnectionState) => void;
 export type FunctionReference = {
     kind: string;
     path: string;
+    optimistic?: {
+        projection?: OptimisticProjection;
+        mutation?: OptimisticMutationDefinition;
+    };
 };
 export type GonvexClientErrorCode = "server" | "timeout" | "disconnected" | "closed" | "auth";
 /**
@@ -197,7 +201,11 @@ export declare class GonvexClient {
     private readonly mutationOutbox;
     private readonly overlay;
     private readonly optimisticMutationIds;
-    private readonly outboxReady;
+    private readonly optimisticOutboxEntryIds;
+    private outboxReady;
+    private outboxScope;
+    private outboxScopeGeneration;
+    private readonly outboxEphemeralScope;
     private readonly unsubscribeOutbox;
     private readonly unsubscribeOverlay;
     private drainingOutbox;
@@ -269,7 +277,10 @@ export declare class GonvexClient {
     private scheduleSyncWatermarkPersistence;
     private emitSyncMessage;
     private materializeSyncMessage;
-    private emitOptimisticCollection;
+    private materializeQueryMessage;
+    private emitOptimisticEntity;
+    private acknowledgeOptimisticSource;
+    private acknowledgeOptimisticQuerySnapshot;
     private markSyncSubscriptionsOutOfDate;
     private startSync;
     private sendSyncOpen;
@@ -278,16 +289,19 @@ export declare class GonvexClient {
     private unsubscribeSyncListener;
     private persistSyncSnapshot;
     private persistSyncDelta;
+    private activateOutboxScope;
     private restoreOutbox;
     private addOptimisticMutation;
     private settleOptimisticMutation;
     private rejectOptimisticMutation;
+    private ackOptimisticMutation;
     private drainOutbox;
     private scheduleOutboxDrain;
     mutation<T = JsonValue>(ref: FunctionReference, args: JsonValue, options: CallOptions & {
         offline: "queue";
     }): Promise<T | QueuedMutationOutcome>;
     mutation<T = JsonValue>(ref: FunctionReference, args?: JsonValue, options?: CallOptions): Promise<T>;
+    private runOptimisticMutation;
     action<T = JsonValue>(ref: FunctionReference, args?: JsonValue, options?: CallOptions): Promise<T>;
     query<T = JsonValue>(ref: FunctionReference, args?: JsonValue, options?: CallOptions): Promise<T>;
     /**
@@ -300,8 +314,9 @@ export declare class GonvexClient {
      * 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.
+     * outcomes. Falls back to the standard per-mutation path when the runtime
+     * lacks batching or when a call needs generated/explicit optimism or durable
+     * offline queuing, so there is never a second mutation-state implementation.
      */
     mutationMany<T = JsonValue>(calls: Array<{
         ref: FunctionReference;