@gonvex/client 0.1.32 → 0.3.0

package/dist/index.d.ts

@@ -1,44 +1,61 @@
-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 { BrowserTelemetryInfo, ExecutionScope, JsonValue, MessageTrace, ServerCapabilities, ServerMessage } from "@gonvex/protocol";
 import { type ErrorReporterOptions } from "./error-reporter.js";
-import { OptimisticOverlay, type OptimisticMutationDefinition, type OptimisticPatch, type OptimisticProjection } from "./optimistic.js";
+export { GonvexErrorReporter } from "./error-reporter.js";
+export type { ErrorReporterOptions, ErrorEventPayload, ErrorContext, ErrorAccount } from "./error-reporter.js";
+import { type OptimisticPatch, type OptimisticTransactionDefinition } from "./optimistic.js";
 import { type OutboxStore } from "./outbox.js";
-export * from "./cache.js";
-export * from "./cache-coordinator.js";
-export * from "./browser-cache.js";
-export * from "./browser-cache-client.js";
-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";
+import { type LocalReplicaStorage, type LocalReplicaView, type ReplicaRow, type LiveQueryResult, type ReplicaCollectionState } from "./local-replica.js";
+import { type LiveQueryPlan, type OfflineLiveQueryResult } from "./query-expression.js";
 export * from "./error-reporter.js";
 export * from "./optimistic.js";
 export * from "./outbox.js";
 export * from "./kv-stores.js";
 export * from "./signals.js";
-export type { QueryCacheDirective } from "@gonvex/protocol";
+export { MemoryLocalReplicaStorage, type LocalReplicaStorage, type LocalReplicaView, type ReplicaChange, type ReplicaFreshness, type ReplicaRow, type ReplicaScope, type ReplicaSnapshot, type ReplicaTransaction, type ReplicaWindow, type LiveQueryResult, type ReplicaCollectionState, } from "./local-replica.js";
+export * from "./query-expression.js";
+export * from "./indexeddb-replica.js";
+export * from "./control.js";
 type SubscriptionHandler = (message: ServerMessage) => void;
-export type SyncReadyMessage = Extract<ServerMessage, {
-    type: "sync.ready";
+export type ReplicaReadyMessage = Extract<ServerMessage, {
+    type: "replica.ready";
 }> & {
     /** True when the server cut this collection at its row or byte budget. */
     truncated?: boolean;
 };
-export type SyncMessage = Extract<ServerMessage, {
-    type: "sync.snapshot" | "sync.delta" | "sync.needHashes" | "sync.syncing" | "sync.reset" | "sync.error";
-}> | SyncReadyMessage;
-export type SyncSubscriptionHandler = (message: SyncMessage) => void;
+export type ReplicaMessage = Extract<ServerMessage, {
+    type: "replica.snapshot" | "replica.delta" | "replica.needHashes" | "replica.syncing" | "replica.reset" | "replica.error";
+}> | ReplicaReadyMessage;
+export type ReplicaSubscriptionHandler = (message: ReplicaMessage) => void;
 type WatchUpdateHandler = () => void;
 type TelemetryHandler = (event: GonvexTelemetryEvent) => void;
 type ConnectionStateHandler = (state: ConnectionState) => void;
-export type FunctionReference = {
+export type SupportCommand = {
+    id: string;
+    kind: string;
+    payload: JsonValue;
+};
+export type FunctionReference<Args extends JsonValue = JsonValue, Result extends JsonValue = JsonValue> = {
     kind: string;
     path: string;
+    /** Core Control Plane functions share the same persistent connection. */
+    scope?: ExecutionScope;
+    authorization?: "public" | "account" | "tenantAdmin" | "developer" | "projectAdmin" | "internal";
+    argsSchema?: JsonValue;
+    resultSchema?: JsonValue;
+    delivery?: "oneShot" | "live" | "replica";
+    offline?: {
+        mode: "forbidden" | "allowed" | "onlineOnly";
+        conflict?: "reject" | "expectedVersion" | "merge";
+        reason?: string;
+    };
+    live?: {
+        entity: string;
+        key: string;
+        resultPath?: readonly string[];
+        plan: LiveQueryPlan;
+    };
     optimistic?: {
-        projection?: OptimisticProjection;
-        mutation?: OptimisticMutationDefinition;
+        transaction?: OptimisticTransactionDefinition;
     };
 };
 export type GonvexClientErrorCode = "server" | "timeout" | "disconnected" | "closed" | "auth";
@@ -49,20 +66,20 @@ export type GonvexClientErrorCode = "server" | "timeout" | "disconnected" | "clo
  *
  * - `server`: the runtime executed the function and returned an error.
  * - `timeout`: no response arrived within the operation timeout. For
- *   mutations/actions the write may or may not have been applied.
+ *   reducers/actions the write may or may not have been applied.
  * - `disconnected`: the socket dropped while the operation was pending.
- *   Mutations/actions fail closed unless a mutation opted into the outbox.
+ *   Reducers/actions fail closed unless a reducer opted into the outbox.
  * - `closed`: the client was explicitly closed.
  * - `auth`: authentication was rejected.
  */
 export declare class GonvexClientError extends Error {
     readonly code: GonvexClientErrorCode;
     readonly path?: string;
-    readonly operation?: "query" | "mutation" | "action";
+    readonly operation?: "query" | "reducer" | "action";
     constructor(message: string, options: {
         code: GonvexClientErrorCode;
         path?: string;
-        operation?: "query" | "mutation" | "action";
+        operation?: "query" | "reducer" | "action";
     });
 }
 export type ConnectionState = {
@@ -71,33 +88,33 @@ export type ConnectionState = {
     connectionCount: number;
     connectionRetries: number;
     hasInflightRequests: boolean;
-    inflightMutations: number;
+    inflightReducers: number;
     inflightActions: number;
     inflightOneShotQueries: number;
 };
 export type GonvexTimeoutOptions = {
     /** One-shot `client.query()` timeout. Default 20s. `0` disables. */
     queryTimeoutMs?: number;
-    /** `client.mutation()` timeout. Default 20s. `0` disables. */
-    mutationTimeoutMs?: number;
+    /** `client.reducer()` timeout. Default 20s. `0` disables. */
+    reducerTimeoutMs?: number;
     /** `client.action()` timeout. Default 60s. `0` disables. */
     actionTimeoutMs?: number;
 };
 export declare const DEFAULT_QUERY_TIMEOUT_MS = 20000;
-export declare const DEFAULT_MUTATION_TIMEOUT_MS = 20000;
+export declare const DEFAULT_REDUCER_TIMEOUT_MS = 20000;
 export declare const DEFAULT_ACTION_TIMEOUT_MS = 60000;
 export type CallOptions = {
     /** Per-call override of the operation timeout. `0` disables. */
     timeoutMs?: number;
-    /** Ordered row changes to expose until the mutation settles. */
+    /** Ordered row changes to expose until the reducer settles. */
     optimistic?: OptimisticPatch[];
     /** Queue transport failures durably instead of rejecting. Default `reject`. */
     offline?: "queue" | "reject";
 };
-/** Returned when an offline mutation has been accepted by the local outbox. */
-export type QueuedMutationOutcome = {
+/** Returned when an offline reducer has been accepted by the local outbox. */
+export type QueuedReducerOutcome = {
     status: "queued";
-    mutationId: string;
+    reducerId: string;
 };
 export type GonvexAuthTokenFetcher = (args: {
     /** True when the server just rejected the current token — bypass any cache. */
@@ -109,33 +126,24 @@ export type GonvexClientAuth = {
     tenant?: string;
     telemetry?: boolean;
     /**
-     * Async source of the auth token, mirroring Convex's `fetchToken` contract.
+     * Async source of the auth token.
      * When installed, the client re-fetches before every auth send — on first
      * connect, on every reconnect, and once more with `forceRefreshToken: true`
      * when the server rejects the current token — so a socket that outlives a
-     * short-lived JWT (e.g. an ~1h Firebase ID token) reauthenticates with a
+     * short-lived Gonvex app session reauthenticates with a
      * live credential instead of replaying the expired one. A `token` passed in
      * the same `setAuth` call is trusted and sent as-is; resolving `null` signs
      * the session out; a rejected fetch keeps the currently installed token so
      * an offline start is not signed out.
      */
     fetchToken?: GonvexAuthTokenFetcher;
-    /**
-     * Non-secret identity hint ({@link https://datatracker.ietf.org/doc/html/rfc7519 JWT}
-     * `sub` and `iss` claims) that stands in for a token when deriving the local
-     * cache identity. Lets a cold start with no usable token — e.g. an offline
-     * tab whose identity provider cannot refresh — recover the warm query-cache
-     * directive and serve cached reads. Never sent to the server; a parseable
-     * token always takes precedence, and both must derive the same key for the
-     * same user (persist the claims of the last token you installed).
-     */
+    /** Non-secret identity hint used to isolate local-replica persistence. */
     identity?: {
         sub: string;
         iss?: string;
     };
 };
 export type GonvexClientOptions = GonvexClientAuth & {
-    queryCache?: false | QueryCacheOptions;
     /**
      * Keep listenerless live queries subscribed for this long so route
      * backtracking can reuse their current result without WebSocket churn.
@@ -143,15 +151,14 @@ export type GonvexClientOptions = GonvexClientAuth & {
      */
     querySubscriptionRetentionMs?: number;
     /**
-     * Keep listenerless durable syncs open briefly across React remounts.
+     * Keep listenerless Replica Collections open briefly across React remounts.
      * Defaults to 250ms, preventing close/open/snapshot churn in StrictMode.
      */
-    syncSubscriptionRetentionMs?: number;
-    sync?: false | SyncStoreOptions;
+    replicaSubscriptionRetentionMs?: number;
     /**
-     * Durable mutation queue settings. Every replay keeps its original
+     * Durable reducer queue settings. Every replay keeps its original
      * idempotency key, making an accidental cross-tab double-send server-safe.
-     * Runtimes without IndexedDB inject `store` to keep queued mutations
+     * Runtimes without IndexedDB inject `store` to keep queued reducers
      * durable; queue semantics always stay in the SDK.
      */
     outbox?: {
@@ -159,14 +166,18 @@ export type GonvexClientOptions = GonvexClientAuth & {
         enabled?: boolean;
         store?: OutboxStore;
     };
-    errorReporting?: false | Omit<ErrorReporterOptions, "endpoint" | "project" | "tenant">;
+    /** Transactional normalized store used by Replica Collections and Live Queries. */
+    localReplica?: {
+        storage?: LocalReplicaStorage;
+    };
+    errorReporting?: false | Omit<ErrorReporterOptions, "transport" | "project" | "tenant">;
     timeouts?: GonvexTimeoutOptions;
 };
 export type GonvexTelemetryEvent = {
-    type: "mutation" | "action" | "query";
+    type: "reducer" | "action" | "query";
     id: string;
     path: string;
-    reason?: "initial" | "invalidate" | "recover";
+    reason?: "initial" | "change" | "recover";
     outcome: "ok" | "error";
     error?: string;
     clientSentAtMs?: number;
@@ -180,14 +191,13 @@ export declare class GonvexClient {
     private socket;
     private readonly handlers;
     private readonly querySubscriptions;
-    private readonly syncSubscriptions;
+    private readonly replicaSubscriptions;
     private readonly oneShotQueries;
     private readonly telemetryHandlers;
     private readonly pendingMessages;
-    private readonly pendingSyncOpens;
+    private readonly pendingReplicaOpens;
     private readonly pendingQuerySubscribes;
-    private readonly syncPersistence;
-    private syncOpenFlushTimer;
+    private replicaOpenFlushTimer;
     private querySubscribeFlushTimer;
     private serverCapabilities;
     private auth;
@@ -197,29 +207,23 @@ export declare class GonvexClient {
     private authRetriedAfterError;
     private readonly authErrorHandlers;
     private telemetryEnabled;
-    private readonly queryCache;
-    private readonly queryCacheWaitForScope;
-    private readonly queryCacheReadTimeoutMs;
     private readonly querySubscriptionRetentionMs;
-    private readonly syncSubscriptionRetentionMs;
-    private readonly syncStore;
-    private readonly mutationOutbox;
-    private readonly overlay;
-    private readonly optimisticMutationIds;
+    private readonly replicaSubscriptionRetentionMs;
+    private readonly reducerOutbox;
+    private readonly replica;
+    private readonly replicaView;
+    private readonly optimisticReducerIds;
     private readonly optimisticOutboxEntryIds;
     private outboxReady;
     private outboxScope;
     private outboxScopeGeneration;
     private readonly outboxEphemeralScope;
+    private replicaScope;
+    private hasAuthoritativeReplicaScope;
+    private replicaReady;
     private readonly unsubscribeOutbox;
-    private readonly unsubscribeOverlay;
     private drainingOutbox;
     private outboxDrainTimer;
-    private queryCacheDirective;
-    private queryCacheGeneration;
-    private syncScopeGeneration;
-    private queryCacheNegotiatedSocketGeneration;
-    private syncIdentityGeneration;
     private readonly sessionScopeHandlers;
     private readonly errorReporter;
     private reconnectTimer;
@@ -228,14 +232,24 @@ export declare class GonvexClient {
     private manuallyClosed;
     private readonly pendingCalls;
     private readonly connectionStateHandlers;
+    private readonly supportCommandHandlers;
     private isWebSocketConnected;
     private hasEverConnected;
     private connectionCount;
     private readonly timeouts;
     constructor(url: string, options?: GonvexClientOptions);
-    /** The client's materialized optimistic state for pending-row indicators. */
-    get optimisticOverlay(): OptimisticOverlay;
-    /** Number of mutations waiting for a definitive server result. */
+    /** The single normalized authoritative + optimistic application data store. */
+    get localReplica(): LocalReplicaView;
+    replicaSignature(ref: FunctionReference, args?: JsonValue): string;
+    /** Read one persisted Live Query membership without starting another transport subscription. */
+    retainedLiveQuery<T extends ReplicaRow = ReplicaRow>(signature: string): LiveQueryResult<T>;
+    /** Resolve an ordered ID batch from one normalized entity store. */
+    replicaEntities<T extends ReplicaRow = ReplicaRow>(entity: string, ids: readonly string[]): Array<T | undefined>;
+    /** Read rows and server-owned completeness for a persisted Replica Collection. */
+    replicaCollectionState<T extends ReplicaRow = ReplicaRow>(ref: FunctionReference, args?: JsonValue): ReplicaCollectionState<T>;
+    /** Run the generated Live Query plan over the bounded normalized cache. */
+    offlineLiveQuery<T extends ReplicaRow = ReplicaRow>(ref: FunctionReference, args?: JsonValue): OfflineLiveQueryResult<T>;
+    /** Number of reducers waiting for a definitive server result. */
     outboxCount(): Promise<number>;
     connectionState(): ConnectionState;
     /** Metadata advertised by the runtime in its latest session.ready frame. */
@@ -256,79 +270,96 @@ export declare class GonvexClient {
     private rejectPendingCalls;
     onTelemetry(handler: TelemetryHandler): () => boolean;
     onSessionScopeChange(handler: () => void): () => boolean;
-    clearQueryCache(options?: {
-        allScopes?: boolean;
-    }): Promise<void>;
-    getQueryCacheStatus(): QueryCacheStatus;
-    subscribeQuery(ref: FunctionReference, args: JsonValue | undefined, onMessage: SubscriptionHandler): () => void;
+    onSupportCommand(handler: (command: SupportCommand) => void): () => boolean;
+    subscribeLiveQuery<Args extends JsonValue = JsonValue, Result extends JsonValue = JsonValue>(ref: FunctionReference<Args, Result>, args: Args | undefined, onMessage: SubscriptionHandler): () => void;
+    /** Watch an authorized host-owned Control Plane Query on the persistent connection. */
+    watchControlQuery<T extends JsonValue = JsonValue, Args extends JsonValue = JsonValue>(ref: FunctionReference<Args, T>, args?: Args): {
+        getSnapshot(): Readonly<{
+            result: T | undefined;
+            version: number;
+        }>;
+        onUpdate(listener: WatchUpdateHandler): () => void;
+    };
+    private handleQueryMessage;
+    private materializeLiveQuery;
     private normalizeSubscriptionMessage;
     private acceptRevision;
-    watchQuery<T = JsonValue>(ref: FunctionReference, args?: JsonValue): {
-        localQueryResult(): T | undefined;
-        onUpdate(handler: WatchUpdateHandler): () => void;
-    };
-    subscribeSync(ref: FunctionReference, args: JsonValue | undefined, onMessage: SyncSubscriptionHandler): () => void;
-    watchSync<T extends JsonValue = JsonValue>(ref: FunctionReference, args?: JsonValue): {
-        localSyncResult(): T[] | undefined;
-        status(): {
+    private subscribeReplicaTransport;
+    /** Subscribe to a bounded Replica Collection. */
+    subscribeReplica<Args extends JsonValue = JsonValue, Result extends JsonValue = JsonValue>(ref: FunctionReference<Args, Result>, args: Args | undefined, onMessage: ReplicaSubscriptionHandler): () => void;
+    /** Watch a bounded Replica Collection through the normalized Local Replica. */
+    watchReplica<T extends JsonValue = JsonValue, Args extends JsonValue = JsonValue>(ref: FunctionReference<Args, T>, args?: Args): {
+        localReplicaResult: () => T[] | undefined;
+        localReplicaState: () => ReplicaCollectionState | undefined;
+        status: () => {
             isLoading: boolean;
             isUpToDate: boolean;
         };
         onUpdate(handler: WatchUpdateHandler): () => void;
     };
-    private handleSyncMessage;
-    private acceptSyncReady;
-    private handleSyncWatermark;
-    private scheduleSyncWatermarkPersistence;
-    private emitSyncMessage;
-    private materializeSyncMessage;
+    /**
+     * Watch a structured Live Query through normalized LocalReplica rows. The
+     * latest query result is retained only as the transport-shaped skeleton;
+     * its row window is always rebuilt from LocalReplica membership/entities.
+     */
+    watchLiveQuery<T extends JsonValue = JsonValue, Args extends JsonValue = JsonValue>(ref: FunctionReference<Args, T>, args?: Args): {
+        localLiveQueryResult: () => T | undefined;
+        onUpdate(handler: WatchUpdateHandler): () => void;
+    };
+    private handleReplicaMessage;
+    private acceptReplicaReady;
+    private handleReplicaWatermark;
+    private emitReplicaMessage;
+    private materializeReplicaMessage;
     private materializeQueryMessage;
     private emitOptimisticEntity;
     private acknowledgeOptimisticSource;
     private acknowledgeOptimisticQuerySnapshot;
-    private markSyncSubscriptionsOutOfDate;
-    private startSync;
-    private sendSyncOpen;
-    private syncOpenRequest;
-    private flushSyncOpens;
-    private unsubscribeSyncListener;
-    private persistSyncSnapshot;
-    private persistSyncDelta;
+    private markReplicaSubscriptionsOutOfDate;
+    private startReplica;
+    private sendReplicaOpen;
+    private replicaOpenRequest;
+    private flushReplicaOpens;
+    private unsubscribeReplicaListener;
     private activateOutboxScope;
+    private activateReplicaDirective;
+    private quarantineReplicaScope;
+    private rejectMissingReplicaDirective;
+    private rejectReplicaDirective;
     private restoreOutbox;
-    private addOptimisticMutation;
-    private settleOptimisticMutation;
-    private rejectOptimisticMutation;
-    private ackOptimisticMutation;
+    private addOptimisticReducer;
+    private settleOptimisticReducer;
+    private rejectOptimisticReducer;
+    private ackOptimisticReducer;
     private drainOutbox;
     private scheduleOutboxDrain;
-    mutation<T = JsonValue>(ref: FunctionReference, args: JsonValue, options: CallOptions & {
+    reducer<T extends JsonValue = JsonValue, Args extends JsonValue = JsonValue>(ref: FunctionReference<Args, T>, args: Args, 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>;
+    }): Promise<T | QueuedReducerOutcome>;
+    reducer<T extends JsonValue = JsonValue, Args extends JsonValue = JsonValue>(ref: FunctionReference<Args, T>, args?: Args, options?: CallOptions): Promise<T>;
+    private runOptimisticReducer;
+    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>;
     /**
      * Force a live query subscription to re-request its result from the server,
      * e.g. after a `query.error` or when a subscriber gave up waiting. No-op if
      * nothing is subscribed to this query.
      */
-    retryQuery(ref: FunctionReference, args?: JsonValue): void;
+    retryLiveQuery(ref: FunctionReference, args?: JsonValue): void;
     /**
-     * Flush a queue of mutations in one `mutation.callMany` frame (queue order,
+     * Flush a queue of reducers in one `reducer.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 the standard per-mutation path when the runtime
+     * outcomes. Falls back to the standard per-reducer 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.
+     * offline queuing, so there is never a second reducer-state implementation.
      */
-    mutationMany<T = JsonValue>(calls: Array<{
+    reducerMany<T extends JsonValue = JsonValue>(calls: Array<{
         ref: FunctionReference;
         args?: JsonValue;
     }>, options?: CallOptions): Promise<Array<{
         status: "ok";
-        result: T;
+        result: T | QueuedReducerOutcome;
     } | {
         status: "error";
         error: GonvexClientError;
@@ -339,25 +370,30 @@ export declare class GonvexClient {
     private sendSubscription;
     private flushQuerySubscribes;
     private resumeQuerySubscriptions;
-    private enqueueSyncPersistence;
-    private scheduleSyncRetry;
-    private clearSyncRetry;
+    private resumeReplicaSubscriptions;
+    private scheduleReplicaRetry;
+    private clearReplicaRetry;
     private requestSubscriptionSnapshot;
     private sendOneShotQuery;
     private resubscribeQueries;
+    private sendPendingControlCall;
+    private sendInvocation;
+    private hasControlPlaneWork;
     private scheduleReconnect;
-    private installQueryCacheDirective;
-    private recoverWarmSyncDirective;
-    private resetQueryCacheScope;
-    private resetQueryResultCacheState;
-    private resetSyncCacheState;
-    private startQueryCacheRead;
-    private persistQueryResult;
-    private deleteCachedQuery;
+    private resetReplicaScopeState;
+    /**
+     * A subscription id is also the server's response routing key. Rotate it on
+     * auth scope changes so a delayed frame from the previous tenant cannot be
+     * delivered to a handler that now materializes into the new scope.
+     */
+    private rotateSubscriptionScopes;
     private emitTelemetryFromCall;
     private recordTelemetry;
     private emitTelemetry;
     private reportTelemetry;
+    /** Send a bounded native error-telemetry frame using authenticated connection attribution. */
+    reportError(type: "register" | "envelope" | "heartbeat", payload: unknown): Promise<void>;
+    private sendNativeError;
     private sendAuth;
     private sendAuthFrame;
     private fetchAndSendAuth;
@@ -368,6 +404,3 @@ export declare class GonvexClient {
     private sendNow;
     private flushPendingMessages;
 }
-export declare class ConvexReactClient extends GonvexClient {
-    constructor(url: string, options?: GonvexClientOptions);
-}