@gonvex/client 0.1.32 → 0.3.0

package/dist/local-replica.d.ts

@@ -0,0 +1,240 @@
+import type { JsonValue, ReplicaCursor, SubscriptionRevision } from "@gonvex/protocol";
+import type { OptimisticPatch } from "./optimistic.js";
+export type ReplicaRow = Record<string, JsonValue>;
+export type ReplicaChange = {
+    entity: string;
+    id: string;
+    operation: "insert" | "update" | "delete";
+    oldValue?: ReplicaRow;
+    newValue?: ReplicaRow;
+    changedColumns?: string[];
+};
+export type ReplicaWindow = {
+    signature: string;
+    kind: "live" | "replica";
+    entity: string;
+    key: string;
+    ids: string[];
+    cursor?: ReplicaCursor;
+    completeness: "complete" | "partial";
+    source: "server" | "cache";
+    resultSkeleton?: JsonValue;
+    resultPath?: string[];
+    scalar?: JsonValue;
+    windowRevision?: string;
+    subscriptionRevision?: SubscriptionRevision;
+    mode?: "eager" | "progressive";
+    truncated?: boolean;
+    orderBy?: string;
+    orderDirection?: "asc" | "desc";
+    maxRows?: number;
+    maxBytes?: number;
+    hashes?: Record<string, string>;
+};
+export type ReplicaTransaction = {
+    cursor: ReplicaCursor;
+    originCommandId?: string;
+    changes: ReplicaChange[];
+    memberships?: ReplicaWindow[];
+};
+export type ReplicaSnapshot = {
+    cursor?: ReplicaCursor;
+    entities: Record<string, Record<string, ReplicaRow>>;
+    liveQueries: Record<string, ReplicaWindow>;
+};
+/** Opaque persistence namespace for one deployment/project/tenant identity. */
+export type ReplicaScope = string;
+/**
+ * Storage implementations must persist the complete transaction atomically.
+ * The SQLite adapter maps this call to BEGIN/apply/cursor/COMMIT; IndexedDB
+ * implementations use one readwrite transaction over the same stores.
+ */
+export interface LocalReplicaStorage {
+    load(scope?: ReplicaScope): Promise<ReplicaSnapshot | undefined>;
+    applyTransaction(transaction: ReplicaTransaction, snapshot: ReplicaSnapshot, scope?: ReplicaScope): Promise<void>;
+    /** Persist a normalized Query/Collection materialization atomically. */
+    replaceSnapshot?(snapshot: ReplicaSnapshot, scope?: ReplicaScope): Promise<void>;
+    replaceWindow?(window: ReplicaWindow, snapshot: ReplicaSnapshot, scope?: ReplicaScope): Promise<void>;
+    applyWindowDelta?(window: ReplicaWindow, delta: {
+        upserts: ReplicaRow[];
+        deleted: string[];
+    }, snapshot: ReplicaSnapshot, scope?: ReplicaScope): Promise<void>;
+    removeWindow?(signature: string, snapshot: ReplicaSnapshot, scope?: ReplicaScope): Promise<void>;
+    clear?(scope?: ReplicaScope): Promise<void>;
+}
+export type ReplicaFreshness = "current" | "verifying" | "offline";
+export type LiveQueryResult<T extends ReplicaRow = ReplicaRow> = {
+    rows: T[];
+    /** Ordered normalized entity IDs owned by the retained query window. */
+    ids: string[];
+    total?: number;
+    offset?: number;
+    limit?: number;
+    source: "server" | "cache";
+    completeness: "complete" | "partial";
+    freshness: ReplicaFreshness;
+    supported?: boolean;
+    unsupportedOperator?: string;
+};
+export type ReplicaCollectionState<T extends ReplicaRow = ReplicaRow> = LiveQueryResult<T> & {
+    truncated: boolean;
+    computedRevision: number;
+};
+/**
+ * Read-only view of the normalized Local Replica exposed to application code.
+ *
+ * Mutations are deliberately absent from this interface. The Gonvex client
+ * applies committed transactions, optimistic reducer effects, scope changes,
+ * and cache/window updates internally so application code cannot create a
+ * second state-management path or advance the local replica by hand.
+ */
+export interface LocalReplicaView {
+    cursor(): ReplicaCursor | undefined;
+    freshness(): ReplicaFreshness;
+    version(): number;
+    subscribe(listener: () => void): () => void;
+    hasPendingCommand(commandId: string): boolean;
+    getWindow(signature: string): ReplicaWindow | undefined;
+    listWindows(): ReplicaWindow[];
+    windowRows<T extends ReplicaRow = ReplicaRow>(signature: string): T[];
+    entity<T extends ReplicaRow = ReplicaRow>(entity: string, id: string): T | undefined;
+    entityBatch<T extends ReplicaRow = ReplicaRow>(entity: string, ids: readonly string[]): Array<T | undefined>;
+    entityRows<T extends ReplicaRow = ReplicaRow>(entity: string): T[];
+    entityCompleteness(entity: string): "complete" | "partial";
+    liveQuery<T extends ReplicaRow = ReplicaRow>(signature: string): LiveQueryResult<T>;
+    collectionState<T extends ReplicaRow = ReplicaRow>(signature: string): ReplicaCollectionState<T>;
+    hasLiveQuery(signature: string): boolean;
+    snapshot(): ReplicaSnapshot;
+}
+export declare class LocalReplica implements LocalReplicaView {
+    private readonly storage?;
+    private cursorValue?;
+    private entities;
+    private liveQueries;
+    /** Rows introduced by a materialized window may be reclaimed conservatively. */
+    private readonly windowOwned;
+    private pendingCommands;
+    private listeners;
+    private persistence;
+    private application;
+    private hydration?;
+    private freshnessValue;
+    private versionValue;
+    private scopeValue;
+    private scopeLoaded;
+    private scopeActivation?;
+    private scopeActivationName?;
+    private scopeActivationGeneration;
+    constructor(storage?: LocalReplicaStorage | undefined);
+    hydrate(): Promise<void>;
+    /**
+     * Atomically switch the authoritative store to an opaque persistence scope.
+     * A newer request supersedes an older one even if the older storage read is
+     * slow (or resolves after auth has already changed again).
+     */
+    activateScope(scope?: ReplicaScope, forceReload?: boolean): Promise<void>;
+    cursor(): {
+        epoch: string;
+        revision: number;
+    } | undefined;
+    freshness(): ReplicaFreshness;
+    version(): number;
+    setFreshness(freshness: ReplicaFreshness): void;
+    subscribe(listener: () => void): () => boolean;
+    applyOptimistic(commandId: string, patches: OptimisticPatch[]): void;
+    acknowledgeCommand(commandId: string, committedRevision?: number): void;
+    rejectCommand(commandId: string): void;
+    /** True while an optimistic command still contributes visible patches. */
+    hasPendingCommand(commandId: string): boolean;
+    applyTransaction(transaction: ReplicaTransaction, scope?: ReplicaScope): Promise<void>;
+    materializeWindow(input: {
+        signature: string;
+        kind?: "live" | "replica";
+        entity: string;
+        key: string;
+        rows: ReplicaRow[];
+        completeness: "complete" | "partial";
+        source: "server" | "cache";
+        cursor?: ReplicaCursor;
+        resultSkeleton?: JsonValue;
+        resultPath?: string[];
+        scalar?: JsonValue;
+        windowRevision?: string;
+        subscriptionRevision?: SubscriptionRevision;
+        mode?: "eager" | "progressive";
+        truncated?: boolean;
+        orderBy?: string;
+        orderDirection?: "asc" | "desc";
+        maxRows?: number;
+        maxBytes?: number;
+        hashes?: Record<string, string>;
+        removedIDs?: string[];
+        scope?: ReplicaScope;
+    }): Promise<void>;
+    /** Replace one server/cache window while retaining shared normalized entities. */
+    replaceWindow(input: Parameters<LocalReplica["materializeWindow"]>[0]): Promise<void>;
+    /** Apply a bounded window delta and persist it in the same transaction. */
+    applyWindowDelta(input: {
+        signature: string;
+        kind?: "live" | "replica";
+        entity: string;
+        key: string;
+        upserts: ReplicaRow[];
+        deleted: string[];
+        completeness?: "complete" | "partial";
+        source?: "server" | "cache";
+        cursor?: ReplicaCursor;
+        resultSkeleton?: JsonValue;
+        resultPath?: string[];
+        scalar?: JsonValue;
+        windowRevision?: string;
+        subscriptionRevision?: SubscriptionRevision;
+        mode?: "eager" | "progressive";
+        truncated?: boolean;
+        orderBy?: string;
+        orderDirection?: "asc" | "desc";
+        maxRows?: number;
+        maxBytes?: number;
+        hashes?: Record<string, string>;
+        removedIDs?: string[];
+        scope?: ReplicaScope;
+    }): Promise<void>;
+    getWindow(signature: string): ReplicaWindow | undefined;
+    listWindows(): ReplicaWindow[];
+    windowRows<T extends ReplicaRow = ReplicaRow>(signature: string): T[];
+    removeWindow(signature: string, scope?: ReplicaScope): Promise<void>;
+    clear(scope?: ReplicaScope): Promise<void>;
+    private materializeWindowNow;
+    private applyTransactionNow;
+    entity<T extends ReplicaRow = ReplicaRow>(entity: string, id: string): T | undefined;
+    /** Resolve several IDs from one atomic Local Replica version. */
+    entityBatch<T extends ReplicaRow = ReplicaRow>(entity: string, ids: readonly string[]): Array<T | undefined>;
+    /** All cached rows for one normalized entity, including optimistic overlays. */
+    entityRows<T extends ReplicaRow = ReplicaRow>(entity: string): T[];
+    /** Exact only when an authoritative, non-truncated Replica Collection covers the entity. */
+    entityCompleteness(entity: string): "complete" | "partial";
+    liveQuery<T extends ReplicaRow = ReplicaRow>(signature: string): LiveQueryResult<T>;
+    /** Rows and protocol-owned completeness for one Replica Collection window. */
+    collectionState<T extends ReplicaRow = ReplicaRow>(signature: string): ReplicaCollectionState<T>;
+    hasLiveQuery(signature: string): boolean;
+    snapshot(): ReplicaSnapshot;
+    private reconcileCommands;
+    private persist;
+    private notify;
+    private trackWindowOwnership;
+    private pruneOwnedEntities;
+    private pruneOwnedEntitiesAfterRemoval;
+}
+export declare class MemoryLocalReplicaStorage implements LocalReplicaStorage {
+    private readonly values;
+    load(scope?: ReplicaScope): Promise<ReplicaSnapshot | undefined>;
+    applyTransaction(_transaction: ReplicaTransaction, snapshot: ReplicaSnapshot, scope?: ReplicaScope): Promise<void>;
+    replaceSnapshot(snapshot: ReplicaSnapshot, scope?: ReplicaScope): Promise<void>;
+    replaceWindow(_window: ReplicaWindow, snapshot: ReplicaSnapshot, scope?: ReplicaScope): Promise<void>;
+    applyWindowDelta(_window: ReplicaWindow, _delta: {
+        upserts: ReplicaRow[];
+        deleted: string[];
+    }, snapshot: ReplicaSnapshot, scope?: ReplicaScope): Promise<void>;
+    removeWindow(_signature: string, snapshot: ReplicaSnapshot, scope?: ReplicaScope): Promise<void>;
+    clear(scope?: ReplicaScope): Promise<void>;
+}