@gonvex/client 0.5.2-staging.13 → 0.5.2-staging.15

package/dist/index.d.ts

@@ -1,10 +1,10 @@
-import type { BrowserTelemetryInfo, ExecutionScope, JsonValue, MessageTrace, ServerCapabilities, ServerMessage } from "@gonvex/protocol";
+import type { BrowserTelemetryInfo, ExecutionScope, JsonValue, MessageTrace, ServerCapabilities, ServerMessage, ReducerErrorClass } from "@gonvex/protocol";
 import type { LocalRuntimeBinding } from "@gonvex/local-runtime/worker-client";
 import { type ErrorReporterOptions } from "./error-reporter.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";
+import { type OutboxErrorClass, type ReducerOutboxScopeSummary, type ReducerOutboxState, type OutboxStore } from "./outbox.js";
 import { type LocalReplicaStorage, type LocalReplicaView, type ReplicaRow, type LiveQueryResult, type ReplicaCollectionState, type ReplicaCollectionSubscriptionState, type ReplicaCollectionPlan } from "./local-replica.js";
 import { type LiveQueryPlan, type OfflineLiveQueryResult } from "./query-expression.js";
 export * from "./error-reporter.js";
@@ -14,6 +14,8 @@ export * from "./kv-stores.js";
 export * from "./client-upgrades.js";
 export * from "./browser-upgrades.js";
 export * from "./signals.js";
+export * from "./paged-read-view.js";
+export { mergeReplicaRecord, type ReplicaRecordVersion, type VersionedReplicaRecord } from './replica-record.js';
 export * from "./external-auth.js";
 export { MemoryLocalReplicaStorage, type LocalReplicaStorage, type LocalReplicaSession, type LocalReplicaView, type ReplicaChange, type ReplicaFreshness, type ReplicaRow, type ReplicaScope, type ReplicaSnapshot, type ReplicaTransaction, type ReplicaWindow, type LiveQueryResult, type ReplicaCollectionState, type ReplicaCollectionSubscriptionState, type ReplicaCollectionPlan, } from "./local-replica.js";
 export * from "./query-expression.js";
@@ -93,12 +95,86 @@ export declare class GonvexClientError extends Error {
     readonly code: GonvexClientErrorCode;
     readonly path?: string;
     readonly operation?: "query" | "reducer" | "action";
+    /**
+     * For `server` Reducer errors: the runtime's classification, or a legacy
+     * inference when an older runtime sent none. Undefined means a legacy
+     * runtime's unclassified error, which is handled as a rejection.
+     */
+    readonly errorClass?: ReducerErrorClass;
+    /** True when the same call (same idempotency key) may succeed later. */
+    readonly retryable?: boolean;
     constructor(message: string, options: {
         code: GonvexClientErrorCode;
         path?: string;
         operation?: "query" | "reducer" | "action";
+        errorClass?: ReducerErrorClass;
+        retryable?: boolean;
     });
 }
+/** One durable reducer intent, as exposed to application UI. */
+export type OutboxIntent = {
+    /** The reducer id / idempotency key. Stable across retries, reloads and tabs. */
+    id: string;
+    /** Local queue sequence number. Lower numbers were issued first. */
+    entryId: number;
+    reducer: string;
+    state: ReducerOutboxState;
+    /** Failed deliveries counted toward the retry budget. */
+    attempts: number;
+    lastError?: string;
+    errorClass?: OutboxErrorClass;
+    createdAt: number;
+    nextAttemptAt: number;
+    /** When the intent became `failed` or `rejected`. */
+    settledAt?: number;
+    args: unknown;
+    /** Short, display-safe JSON preview of the arguments. */
+    argsSummary: string;
+    /** Rows this intent's optimistic prediction touched (best effort). */
+    entities: Array<{
+        entity: string;
+        id: string;
+    }>;
+};
+/** Per-row delivery status derived from the outbox. */
+export type EntityIntentStatus = "syncing" | "failed" | "rejected";
+export type ReducerRejectionEvent = {
+    reducerId: string;
+    path: string;
+    error: string;
+    errorClass?: OutboxErrorClass;
+};
+export type OutboxScope = ReducerOutboxScopeSummary & {
+    /** True for the identity this client is currently signed in as. */
+    current: boolean;
+};
+export type OutboxRetryOptions = {
+    /**
+     * Counted delivery failures (transient server errors and timeouts) before an
+     * intent is parked as `failed`. Default 10. `Infinity` retries forever.
+     */
+    maxAttempts?: number;
+    /** Cap for the exponential backoff between attempts. Default 60s. */
+    maxBackoffMs?: number;
+};
+export type ResetLocalReplicaOptions = {
+    /**
+     * Keep the durable outbox (default true). Pending, failed and rejected
+     * intents survive the reset and their predictions are re-applied on top of
+     * the rehydrated data. `false` also deletes every intent of the active
+     * identity that is not already inflight or committed; use it only for an
+     * explicit "discard unsynced changes" action.
+     */
+    keepOutbox?: boolean;
+};
+export type ResetLocalReplicaResult = {
+    /** Intents deleted because `keepOutbox: false` was requested. */
+    discardedIntents: number;
+    /** Replica Collections and Live Queries re-requested from the server. */
+    resubscribed: number;
+};
+export declare const DEFAULT_OUTBOX_MAX_ATTEMPTS = 10;
+export declare const DEFAULT_OUTBOX_RETRY_MAX_BACKOFF_MS = 60000;
 export type ConnectionState = {
     isWebSocketConnected: boolean;
     hasEverConnected: boolean;
@@ -189,10 +265,13 @@ export type GonvexClientOptions = GonvexClientAuth & {
         databaseName?: string;
         enabled?: boolean;
         store?: OutboxStore;
+        retry?: OutboxRetryOptions;
     };
     /** Transactional normalized store used by Replica Collections and Live Queries. */
     localReplica?: {
         storage?: LocalReplicaStorage;
+        maxResidentRows?: number;
+        maxResidentBytes?: number;
     };
     errorReporting?: false | Omit<ErrorReporterOptions, "transport" | "project" | "tenant">;
     timeouts?: GonvexTimeoutOptions;
@@ -212,20 +291,32 @@ export type GonvexTelemetryEvent = {
 };
 export declare class GonvexClient {
     private readonly url;
+    private readonly localTableBindings;
     private readonly localBinding?;
     private readonly localExecutor?;
     private readonly localStorage?;
     private localIdentity?;
     private localLane;
+    private preparationLane;
     private localReplayScheduled;
+    private waitingLocalEdits;
     private replacingLocal;
     private readonly unsubscribeLocal?;
     private readonly localCollectionClosers;
+    private readonly localCollectionKeys;
+    private readonly localExecutionTables;
     private readonly reducerRejectionHandlers;
+    private readonly outboxRetry;
+    private unauthenticatedRetries;
+    private intentsSnapshotValue;
+    private readonly intentListeners;
+    private intentsRefreshRunning;
+    private intentsRefreshDirty;
     private socket;
     private readonly handlers;
     private readonly querySubscriptions;
     private readonly replicaSubscriptions;
+    private readonly replicaMetadataListeners;
     private readonly oneShotQueries;
     private readonly telemetryHandlers;
     private readonly pendingMessages;
@@ -266,8 +357,15 @@ export declare class GonvexClient {
     private processedReplicaWatermarkRevision;
     private readonly pendingReplicaTransactions;
     private readonly unsubscribeOutbox;
+    private readonly sharedOutboxStore?;
+    private readonly unsubscribePeerOutbox?;
+    private readonly unsubscribePeerReplica?;
+    private peerRefreshScheduled;
+    private peerRefreshDirty;
     private readonly unsubscribeBrowserOnline;
     private drainingOutbox;
+    /** A wake-up (timer, enqueue, reconnect) that arrived while a drain was running. */
+    private outboxDrainRequested;
     private outboxDrainTimer;
     private readonly sessionScopeHandlers;
     private readonly errorReporter;
@@ -289,20 +387,86 @@ export declare class GonvexClient {
     private updateRequired;
     private lastOnlineAtMs;
     constructor(url: string, options?: GonvexClientOptions);
-    /** Authoritative sync failures arrive after an offline call returned locally. */
-    onReducerRejection(listener: (event: {
-        reducerId: string;
-        path: string;
-        error: string;
-    }) => void): () => void;
+    /**
+     * Authoritative sync failures arrive after an offline call returned locally.
+     * The intent also stays in the outbox as `rejected` until it is discarded
+     * or retried, so a UI that mounts later can still show it.
+     */
+    onReducerRejection(listener: (event: ReducerRejectionEvent) => void): () => void;
+    /** Every durable intent of the current identity, oldest first. */
+    listIntents(): Promise<OutboxIntent[]>;
+    /**
+     * Synchronous snapshot for external stores (React `useSyncExternalStore`).
+     * Kept current while at least one {@link subscribeIntents} listener exists.
+     */
+    intentsSnapshot(): readonly OutboxIntent[];
+    /** Observe intent changes; call {@link intentsSnapshot} for the new value. */
+    subscribeIntents(listener: () => void): () => void;
+    /**
+     * Delivery status for one row from the current snapshot: `failed` or
+     * `rejected` when an intent touching it needs attention, `syncing` while one
+     * is still queued, otherwise undefined.
+     */
+    entityIntentStatus(entity: string, id: string): EntityIntentStatus | undefined;
+    /**
+     * Re-arm a `failed` or `rejected` intent with a fresh retry budget. The
+     * original idempotency key is reused, so an attempt that had actually
+     * committed is replayed by the server rather than applied twice.
+     */
+    retryIntent(id: string): Promise<boolean>;
+    /**
+     * Drop a `pending`, `failed` or `rejected` intent: it will never be sent,
+     * its optimistic prediction is removed and later local intents are rebased.
+     * Inflight and committed intents cannot be discarded. Discarding an intent
+     * whose earlier attempt timed out does not undo a commit that the server
+     * may already have applied; the replica then shows the server's truth.
+     */
+    discardIntent(id: string): Promise<boolean>;
+    /**
+     * Discard the persisted Local Replica of the active identity (IndexedDB,
+     * Expo SQLite or any configured storage) and rehydrate it from the server.
+     *
+     * Online only: without an authenticated connection the call rejects with a
+     * `GonvexClientError` (`code: "disconnected"`) and changes nothing, so the
+     * user is never left with an empty cache that cannot be refilled. The saved
+     * offline session (identity and replica directive) is kept.
+     *
+     * By default the outbox is untouched: pending, failed and rejected intents
+     * stay durable, and the predictions of every live intent are re-applied
+     * immediately and recomputed as server data arrives. Active Replica
+     * Collections and Live Queries are re-requested without their old cursors,
+     * so the server sends full snapshots.
+     */
+    resetLocalReplica(options?: ResetLocalReplicaOptions): Promise<ResetLocalReplicaResult>;
+    /** Outbox owners with durable entries, including identities that never returned. */
+    listOutboxScopes(): Promise<OutboxScope[]>;
+    /**
+     * Permanently delete another identity's durable intents. The active scope
+     * cannot be purged this way; use {@link discardIntent} for its entries.
+     */
+    purgeOutboxScope(scope: string): Promise<number>;
+    /** Purge every outbox scope except the current identity's. Never runs automatically. */
+    purgeForeignOutboxScopes(): Promise<number>;
+    private refreshIntents;
+    private publishIntents;
     private restoreLocalSession;
     private ensureLocalCollections;
+    private hydrateMissingLocalTable;
     private localSnapshot;
+    private localReadCoverage;
+    private isUncoveredLocalRead;
+    private executeLocal;
     private inLocalLane;
+    private replaceLocalPredictions;
+    private coordinateOutbox;
+    private refreshPeerOutbox;
     private scheduleLocalReplay;
     private reportLocalRejection;
     private rebaseLocalEntries;
+    private rebaseLocalEntriesLocked;
     private runLocalReducer;
+    /** Preload code for a mounted control without reading data or executing an intent. */
+    prepareReducer(ref: FunctionReference): Promise<void>;
     /** The single normalized authoritative + optimistic application data store. */
     get localReplica(): LocalReplicaView;
     replicaSignature(ref: FunctionReference, args?: JsonValue): string;
@@ -310,11 +474,16 @@ export declare class GonvexClient {
     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>;
+    /** Retain only the data an active view observes; cold rows remain on disk. */
+    retainReplicaEntities(entity: string, ids: readonly string[]): () => void;
+    retainReplicaWindow(signature: string): () => void;
     /** 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. */
+    offlineLiveQuery<T extends ReplicaRow = ReplicaRow>(ref: FunctionReference, args?: JsonValue, options?: {
+        window?: boolean;
+    }): OfflineLiveQueryResult<T>;
+    /** Number of reducers still queued for delivery (excludes failed and rejected intents). */
     outboxCount(): Promise<number>;
     connectionState(): ConnectionState;
     /** Metadata advertised by the runtime in its latest session.ready frame. */
@@ -362,7 +531,9 @@ export declare class GonvexClient {
     /** 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): {
+    watchReplica<T extends JsonValue = JsonValue, Args extends JsonValue = JsonValue>(ref: FunctionReference<Args, T>, args?: Args, options?: {
+        deferStart?: boolean;
+    }): {
         localReplicaResult: () => T[] | undefined;
         localReplicaState: () => ReplicaCollectionSubscriptionState | undefined;
         status: () => {
@@ -376,7 +547,9 @@ export declare class GonvexClient {
      * 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): {
+    watchLiveQuery<T extends JsonValue = JsonValue, Args extends JsonValue = JsonValue>(ref: FunctionReference<Args, T>, args?: Args, options?: {
+        deferStart?: boolean;
+    }): {
         localLiveQueryResult: () => T | undefined;
         onUpdate(handler: WatchUpdateHandler): () => void;
     };
@@ -409,6 +582,25 @@ export declare class GonvexClient {
     private rejectOptimisticReducer;
     private ackOptimisticReducer;
     private drainOutbox;
+    /**
+     * Record a non-rejection delivery failure and arm the next attempt.
+     * - update_required: keep the intent pending and stop for an app update.
+     * - unauthenticated: keep the intent, re-authenticate, retry with backoff
+     *   that never spends the retry budget.
+     * - network: connectivity loss; retried on reconnect without spending budget.
+     * - transient (and timeouts): exponential backoff, parked as `failed` once
+     *   the retry budget is spent.
+     */
+    private recordDeliveryFailure;
+    /**
+     * Arm a timer for the earliest backed-off entry. Timer clocks and
+     * `Date.now()` can disagree by a millisecond, so a wake-up may find its
+     * entry not quite due; without this the queue would wait for an unrelated
+     * event to resume.
+     */
+    private scheduleNextOutboxAttempt;
+    /** Re-send auth on the open socket so a lost tenant session is restored. */
+    private requestReauthentication;
     private scheduleOutboxDrain;
     reducer<T extends JsonValue = JsonValue, Args extends JsonValue = JsonValue>(ref: FunctionReference<Args, T>, args: Args, options: CallOptions & {
         offline: "queue";
@@ -487,3 +679,5 @@ export declare class GonvexClient {
     private sendNow;
     private flushPendingMessages;
 }
+/** Row status from a list of intents: failed > rejected > syncing. */
+export declare function entityStatusFromIntents(intents: readonly OutboxIntent[], entity: string, id: string): EntityIntentStatus | undefined;