powersync-bridge 0.0.1-alpha.0 → 0.0.1-alpha.1

package/dist/index.d.ts

@@ -1,173 +1,5 @@
-import { S as Store, B as BridgeDriver, a as BridgeClock, O as OrderKey, I as InfiniteListResult, Q as QueryAdapter, b as InfiniteListDefinition, c as OnDemandResult, P as Params, d as StreamDescription, C as CursorOf, e as OpaqueCursor, K as KeyOf, f as SortDirection, g as CrudDelta, h as PendingOpRef, R as RacedListResult, M as MeasureSink, i as RacedListDefinition } from './clock-BAt_Za0Q.js';
-export { A as ApiOffsetPolicy, j as ApiPolicy, k as Boundary, l as BoundaryReason, m as CompilableQuery, n as Cursor, D as DifferentialStream, E as EscalationPolicy, L as ListErrors, o as ListState, p as OnDemandStatus, q as PageArgs, r as PagedRow, s as PartitionPolicy, t as PendingOp, u as PreparedQuery, v as PriorityStatus, w as RaceMeasurement, x as RowDiff, y as RowOrigin, z as RowsBuilder, F as Snapshot, G as StreamHandle, H as StreamStatus, J as SyncStatusView, N as realClock } from './clock-BAt_Za0Q.js';
-
-/**
- * External store with a stable snapshot for useSyncExternalStore (R10/R11).
- * `replace()` swaps the snapshot and notifies once; `swapRoot()` is what an identity change
- * calls — it is synchronous, so no committed frame can observe the outgoing state (R15).
- */
-declare class SnapshotStore<S> implements Store<S> {
-    private snapshot;
-    private readonly listeners;
-    constructor(initial: S);
-    getSnapshot(): S;
-    subscribe(listener: () => void): () => void;
-    replace(next: S): void;
-    get listenerCount(): number;
-}
-
-type FlagState = 'idle' | 'flagging' | 'syncing' | 'synced' | 'timeout' | 'error';
-interface FlaggerConfig {
-    /** App-supplied backend call, e.g. POST /sync/flag. */
-    readonly requestFlag: (ids: readonly string[]) => Promise<void>;
-    /** Stream whose JOIN reads the per-user sync_requests table. */
-    readonly stream: string;
-    /** Table the flagged rows land in (for presence detection). */
-    readonly table: string;
-    readonly timeoutMs?: number;
-}
-interface FlagResult {
-    readonly state: FlagState;
-    readonly error?: Error;
-}
-/**
- * OPTIONAL primitive (§7): client-triggered, per-user server-side flagging. Use only for bucket
- * economy or server-decided membership; `useOnDemandStream` is the default single-row path.
- * `synced` is detected by watching the SPECIFIC requested ids, never by waitForFirstSync.
- */
-declare class AutoSyncFlagStore {
-    private readonly driver;
-    private readonly clock;
-    private readonly config;
-    private readonly ids;
-    readonly store: SnapshotStore<FlagResult>;
-    private handle;
-    private unsubStatus;
-    private cancelTimeout;
-    private disposed;
-    private refs;
-    constructor(driver: BridgeDriver, clock: BridgeClock, config: FlaggerConfig, ids: readonly string[]);
-    retain(): void;
-    release(): void;
-    get isDisposed(): boolean;
-    swapRoot(): void;
-    dispose(): void;
-    private start;
-}
-
-/**
- * Identity is DERIVED from the JWT the connector returns, never supplied by the app (R15, [DX]).
- * The key is the canonical JSON of the stable claims — a cache key, not a hash.
- */
-declare const DEFAULT_VOLATILE_CLAIMS: readonly string[];
-declare function decodeJwtPayload(token: string): Record<string, unknown>;
-interface IdentityKeyOptions {
-    readonly denyList?: readonly string[];
-    /** Connection parameters opted in BY KEY (rotating values must be excluded explicitly). */
-    readonly connectionParams?: Record<string, unknown>;
-}
-declare function identityKeyFromClaims(claims: Record<string, unknown>, opts?: IdentityKeyOptions): string;
-declare function identityKeyFromToken(token: string, opts?: IdentityKeyOptions): string;
-
-interface InfiniteDeps {
-    readonly driver: BridgeDriver;
-    readonly adapter: QueryAdapter;
-    readonly clock: BridgeClock;
-    readonly onEvicted?: ((ids: readonly string[]) => void) | undefined;
-}
-declare function emptyInfiniteResult<T>(): InfiniteListResult<T>;
-/**
- * The infinite list engine (§6.2): one global id set, a loaded-range local watch, and bounded
- * escalation through equality partitions or API pages.
- */
-declare class InfiniteListStore<TItem, TScope, K extends OrderKey<TItem>, TCursor, TPartition> {
-    private readonly deps;
-    private readonly def;
-    private readonly scope;
-    readonly store: SnapshotStore<InfiniteListResult<TItem>>;
-    private readonly compare;
-    private readonly table;
-    private readonly abort;
-    private pages;
-    private local;
-    private lookahead;
-    private emissionSeen;
-    private localError;
-    private unsubDiffs;
-    private readonly apiRows;
-    private readonly retained;
-    private readonly tombstones;
-    private readonly subs;
-    private readonly lru;
-    private probeCursor;
-    private serverFloor;
-    private floorRevalidated;
-    private boundary;
-    private reason;
-    private awaitingSync;
-    private loading;
-    private errors;
-    private warnings;
-    private errorCount;
-    private nextRetryAt;
-    private disposed;
-    private refs;
-    constructor(deps: InfiniteDeps, def: InfiniteListDefinition<TItem, TScope, K, TCursor, TPartition>, scope: TScope);
-    retain(): void;
-    release(): void;
-    get isDisposed(): boolean;
-    swapRoot(): void;
-    dispose(): void;
-    private subscribeLocal;
-    private onDiff;
-    private provenance;
-    private applyRemovals;
-    private lastCursor;
-    /** Explicit user retry clears the backoff (R16). */
-    retry(): Promise<void>;
-    loadMore(): Promise<void>;
-    private setUnknown;
-    private escalatePartition;
-    private finishEnd;
-    private track;
-    private untrack;
-    private apiGate;
-    private apiFailure;
-    private escalateApi;
-    private escalateOffset;
-    private absorbApi;
-    private mergedEntries;
-    private render;
-}
-
-interface OnDemandOptions {
-    readonly ttl?: number;
-    readonly priority?: 0 | 1 | 2 | 3;
-    readonly timeoutMs?: number;
-}
-/**
- * The default "pull one row" primitive (§7, [DX]): a plain on-demand equality-parameter stream.
- * Held while retained; the TTL keeps rows warm after release.
- */
-declare class OnDemandStreamStore {
-    private readonly driver;
-    private readonly clock;
-    private readonly name;
-    private readonly params;
-    private readonly opts;
-    readonly store: SnapshotStore<OnDemandResult>;
-    private handle;
-    private readonly abort;
-    private refs;
-    private disposed;
-    constructor(driver: BridgeDriver, clock: BridgeClock, name: string, params: Params | null, opts: OnDemandOptions);
-    retain(): void;
-    release(): void;
-    get isDisposed(): boolean;
-    swapRoot(): void;
-    dispose(): void;
-    private start;
-}
+import { B as BridgeDriver, S as StreamDescription, O as OrderKey, C as CursorOf, a as OpaqueCursor, K as KeyOf, b as SortDirection, c as CrudDelta, P as PendingOpRef, d as BridgeClock, e as Store, Q as QueryAdapter, M as MeasureSink, R as RacedListResult, f as RacedListDefinition, g as RowsBuilder, h as PagedRow, L as ListErrors, I as InfiniteListResult, i as InfiniteListDefinition, j as OnDemandResult, k as Params } from './clock-DANrBsZH.js';
+export { A as ApiOffsetPolicy, l as ApiPolicy, m as Boundary, n as BoundaryReason, o as CompilableQuery, p as Cursor, D as DifferentialStream, E as EscalationPolicy, q as ListState, r as OnDemandStatus, s as PageArgs, t as PartitionPolicy, u as PendingOp, v as PreparedQuery, w as PriorityStatus, x as RaceMeasurement, y as RowDiff, z as RowOrigin, F as Snapshot, G as StreamHandle, H as StreamStatus, J as SyncStatusView, N as realClock } from './clock-DANrBsZH.js';
 
 type Clock = () => number;
 interface CheckpointCompletion {
@@ -307,10 +139,27 @@ declare class SnapshotCache {
         asOf?: string;
     }>): Promise<SnapshotRecord<TApi>>;
     /** Cancel every in-flight fetch under a key prefix (identity swap). */
+    invalidate(key: readonly unknown[]): void;
+    /** Cancel every in-flight fetch under a key prefix (identity swap). */
     abortAll(prefix: readonly unknown[]): void;
     clear(): void;
 }
 
+/**
+ * External store with a stable snapshot for useSyncExternalStore (R10/R11).
+ * `replace()` swaps the snapshot and notifies once; `swapRoot()` is what an identity change
+ * calls — it is synchronous, so no committed frame can observe the outgoing state (R15).
+ */
+declare class SnapshotStore<S> implements Store<S> {
+    private snapshot;
+    private readonly listeners;
+    constructor(initial: S);
+    readonly getSnapshot: () => S;
+    readonly subscribe: (listener: () => void) => (() => void);
+    replace(next: S): void;
+    get listenerCount(): number;
+}
+
 interface RacedDeps {
     readonly driver: BridgeDriver;
     readonly adapter: QueryAdapter;
@@ -387,6 +236,280 @@ declare class RacedListStore<TItem, TScope, TApi, K extends OrderKey<TItem>> {
     lastCursor(): ReturnType<typeof cursorOfRow<TItem, K>> | undefined;
 }
 
+interface QueryPage<T> {
+    readonly cursor: T | undefined;
+    readonly limit: number;
+}
+/** Query keys include every predicate, identity and permission that can change the result. */
+interface InfiniteQueryOptions<T extends {
+    id: string;
+}> {
+    readonly queryKey: readonly unknown[];
+    readonly query: (page: QueryPage<T>) => RowsBuilder<T>;
+    /** Return rows in the same order as SQLite. Honor limit, including its lookahead row. */
+    readonly fetchPage: (page: QueryPage<T> & {
+        readonly signal: AbortSignal;
+    }) => Promise<readonly T[]>;
+    readonly orderBy: OrderKey<T>;
+    readonly direction?: 'asc' | 'desc';
+    readonly pageSize?: number;
+    readonly maxRows?: number;
+    readonly staleTime?: number;
+    readonly enabled?: boolean;
+    readonly table?: string;
+    /** Heterogeneous feeds identify each underlying business row for pending-write protection. */
+    readonly getRowIdentity?: (row: T) => {
+        table: string;
+        id: string;
+    };
+    readonly isInWindow?: (row: T) => boolean;
+}
+/** Shared by core and React so changing page configuration cannot reuse an incompatible store. */
+declare const infiniteQueryKey: <T extends {
+    id: string;
+}>(options: InfiniteQueryOptions<T>) => string;
+interface InfiniteQueryResult<T> {
+    readonly data: T[];
+    readonly items: readonly PagedRow<T>[];
+    readonly isLoading: boolean;
+    readonly isFetching: boolean;
+    readonly isFetchingNextPage: boolean;
+    readonly hasNextPage: boolean;
+    readonly needsOlderWindow: boolean;
+    readonly error: Error | undefined;
+    readonly errors: ListErrors;
+    readonly isError: boolean;
+    readonly windowRevision: number;
+}
+declare class OfflineError extends Error {
+    readonly name = "OfflineError";
+    constructor();
+}
+interface QueryDeps extends RacedDeps {
+    readonly connectivity: Store<boolean | undefined>;
+}
+/** One loaded-range watch and one ordered API cursor chain. Every requested page races both. */
+declare class InfiniteQueryStore<T extends {
+    id: string;
+}> {
+    private readonly deps;
+    private readonly options;
+    readonly store: SnapshotStore<InfiniteQueryResult<T>>;
+    private readonly pageSize;
+    private readonly maxRows;
+    private readonly compare;
+    private table;
+    private target;
+    private anchor;
+    private revision;
+    private local;
+    private readonly retained;
+    private readonly tombstones;
+    private readonly filtered;
+    private readonly inSession;
+    private pages;
+    private localPending;
+    private localStamp;
+    private localError;
+    private apiError;
+    private apiPending;
+    private apiFailed;
+    private offline;
+    private generation;
+    private watchGeneration;
+    private lastLocalWatch;
+    private refs;
+    private ready;
+    private disposed;
+    private unwatch;
+    private stops;
+    private request;
+    private requestKey;
+    constructor(deps: QueryDeps, options: InfiniteQueryOptions<T>);
+    get isDisposed(): boolean;
+    retain(): void;
+    release(): void;
+    swapRoot(): void;
+    dispose(): void;
+    private readOffline;
+    private cancelRequest;
+    private networkChanged;
+    private identity;
+    private pending;
+    private localBuilder;
+    private watch;
+    private acceptLocal;
+    private checkpoint;
+    private clearPages;
+    private apiEnd;
+    private apiCount;
+    private apiCursor;
+    private cursorKey;
+    private pump;
+    private entries;
+    private result;
+    private render;
+    readonly fetchNextPage: () => void;
+    readonly retry: () => void;
+    readonly refresh: () => void;
+    readonly continueOlder: () => void;
+    private reset;
+}
+
+type FlagState = 'idle' | 'flagging' | 'syncing' | 'synced' | 'timeout' | 'error';
+interface FlaggerConfig {
+    /** App-supplied backend call, e.g. POST /sync/flag. */
+    readonly requestFlag: (ids: readonly string[]) => Promise<void>;
+    /** Stream whose JOIN reads the per-user sync_requests table. */
+    readonly stream: string;
+    /** Table the flagged rows land in (for presence detection). */
+    readonly table: string;
+    readonly timeoutMs?: number;
+}
+interface FlagResult {
+    readonly state: FlagState;
+    readonly error?: Error;
+}
+/**
+ * OPTIONAL primitive (§7): client-triggered, per-user server-side flagging. Use only for bucket
+ * economy or server-decided membership; `useOnDemandStream` is the default single-row path.
+ * `synced` is detected by watching the SPECIFIC requested ids, never by waitForFirstSync.
+ */
+declare class AutoSyncFlagStore {
+    private readonly driver;
+    private readonly clock;
+    private readonly config;
+    private readonly ids;
+    readonly store: SnapshotStore<FlagResult>;
+    private handle;
+    private unsubStatus;
+    private cancelTimeout;
+    private disposed;
+    private refs;
+    constructor(driver: BridgeDriver, clock: BridgeClock, config: FlaggerConfig, ids: readonly string[]);
+    retain(): void;
+    release(): void;
+    get isDisposed(): boolean;
+    swapRoot(): void;
+    dispose(): void;
+    private start;
+}
+
+/**
+ * Identity is DERIVED from the JWT the connector returns, never supplied by the app (R15, [DX]).
+ * The key is the canonical JSON of the stable claims — a cache key, not a hash.
+ */
+declare const DEFAULT_VOLATILE_CLAIMS: readonly string[];
+declare function decodeJwtPayload(token: string): Record<string, unknown>;
+interface IdentityKeyOptions {
+    readonly denyList?: readonly string[];
+    /** Connection parameters opted in BY KEY (rotating values must be excluded explicitly). */
+    readonly connectionParams?: Record<string, unknown>;
+}
+declare function identityKeyFromClaims(claims: Record<string, unknown>, opts?: IdentityKeyOptions): string;
+declare function identityKeyFromToken(token: string, opts?: IdentityKeyOptions): string;
+
+interface InfiniteDeps {
+    readonly driver: BridgeDriver;
+    readonly adapter: QueryAdapter;
+    readonly clock: BridgeClock;
+    readonly onEvicted?: ((ids: readonly string[]) => void) | undefined;
+}
+declare function emptyInfiniteResult<T>(): InfiniteListResult<T>;
+/**
+ * The infinite list engine (§6.2): one global id set, a loaded-range local watch, and bounded
+ * escalation through equality partitions or API pages.
+ */
+declare class InfiniteListStore<TItem, TScope, K extends OrderKey<TItem>, TCursor, TPartition> {
+    private readonly deps;
+    private readonly def;
+    private readonly scope;
+    readonly store: SnapshotStore<InfiniteListResult<TItem>>;
+    private readonly compare;
+    private readonly table;
+    private readonly abort;
+    private pages;
+    private local;
+    private lookahead;
+    private emissionSeen;
+    private localError;
+    private unsubDiffs;
+    private readonly apiRows;
+    private readonly retained;
+    private readonly tombstones;
+    private readonly subs;
+    private readonly lru;
+    private probeCursor;
+    private serverFloor;
+    private floorRevalidated;
+    private boundary;
+    private reason;
+    private awaitingSync;
+    private loading;
+    private localPagePending;
+    private errors;
+    private warnings;
+    private errorCount;
+    private nextRetryAt;
+    private disposed;
+    private refs;
+    constructor(deps: InfiniteDeps, def: InfiniteListDefinition<TItem, TScope, K, TCursor, TPartition>, scope: TScope);
+    retain(): void;
+    release(): void;
+    get isDisposed(): boolean;
+    swapRoot(): void;
+    dispose(): void;
+    private subscribeLocal;
+    private onDiff;
+    private provenance;
+    private applyRemovals;
+    private lastCursor;
+    /** Explicit user retry clears the backoff (R16). */
+    retry(): Promise<void>;
+    loadMore(): Promise<void>;
+    private setUnknown;
+    private escalatePartition;
+    private finishEnd;
+    private track;
+    private untrack;
+    private apiGate;
+    private apiFailure;
+    private escalateApi;
+    private escalateOffset;
+    private absorbApi;
+    private mergedEntries;
+    private render;
+}
+
+interface OnDemandOptions {
+    readonly ttl?: number;
+    readonly priority?: 0 | 1 | 2 | 3;
+    readonly timeoutMs?: number;
+}
+/**
+ * The default "pull one row" primitive (§7, [DX]): a plain on-demand equality-parameter stream.
+ * Held while retained; the TTL keeps rows warm after release.
+ */
+declare class OnDemandStreamStore {
+    private readonly driver;
+    private readonly clock;
+    private readonly name;
+    private readonly params;
+    private readonly opts;
+    readonly store: SnapshotStore<OnDemandResult>;
+    private handle;
+    private readonly abort;
+    private refs;
+    private disposed;
+    constructor(driver: BridgeDriver, clock: BridgeClock, name: string, params: Params | null, opts: OnDemandOptions);
+    retain(): void;
+    release(): void;
+    get isDisposed(): boolean;
+    swapRoot(): void;
+    dispose(): void;
+    private start;
+}
+
 type Platform = 'web' | 'native';
 type RacePolicy = 'race' | 'local-first';
 interface PlatformGates {
@@ -429,6 +552,7 @@ declare class Bridge {
     readonly clock: BridgeClock;
     /** Increments on every identity swap; hooks subscribe to re-acquire their stores. */
     readonly epochStore: Store<number>;
+    readonly connectivity: SnapshotStore<boolean | undefined>;
     private readonly identity;
     private readonly freshness;
     private readonly crud;
@@ -440,9 +564,14 @@ declare class Bridge {
     private readonly identityOpts;
     private readonly onEvicted;
     private disposed;
+    private readonly onNetwork;
     constructor(opts: BridgeOptions);
     get epoch(): number;
     get identityKey(): string | null;
+    setOnline(online: boolean | undefined): void;
+    query<T extends {
+        id: string;
+    }>(options: InfiniteQueryOptions<T>): InfiniteQueryStore<T>;
     /** Resolves once the initial upload-queue read has landed (tests). */
     ready(): Promise<void>;
     /** Connect THROUGH the bridge so identity is derived from every token the connector produces. */
@@ -493,4 +622,4 @@ interface RemovalContext<T> {
 declare function probePresence(driver: BridgeDriver, table: string, ids: readonly string[]): Promise<Set<string>>;
 declare function classifyRemovals<T>(ctx: RemovalContext<T>, removed: ReadonlyMap<string, T>): Promise<Map<string, RemovalClass>>;
 
-export { AutoSyncFlagStore, Bridge, BridgeClock, BridgeDriver, type BridgeOptions, type ConnectorLike, CrudDelta, CursorOf, DEFAULT_VOLATILE_CLAIMS, type FlagResult, type FlagState, type FlaggerConfig, type IdentityKeyOptions, InfiniteListDefinition, InfiniteListResult, InfiniteListStore, KeyOf, MeasureSink, type MinimalQueryClient, type OnDemandOptions, OnDemandResult, OnDemandStreamStore, OpaqueCursor, OrderKey, Params, PendingOpRef, type Platform, type PlatformGates, QueryAdapter, type RacePolicy, RacedListDefinition, RacedListResult, RacedListStore, type RemovalClass, SnapshotStore, SortDirection, Store, StreamDescription, classifyRemovals, createBridge, cursorOfRow, decodeCursor, decodeJwtPayload, defineInfiniteList, defineRacedList, emptyInfiniteResult, emptyRacedResult, encodeCursor, identityKeyFromClaims, identityKeyFromToken, keyColumns, probePresence, rowComparator };
+export { AutoSyncFlagStore, Bridge, BridgeClock, BridgeDriver, type BridgeOptions, type ConnectorLike, CrudDelta, CursorOf, DEFAULT_VOLATILE_CLAIMS, type FlagResult, type FlagState, type FlaggerConfig, type IdentityKeyOptions, InfiniteListDefinition, InfiniteListResult, InfiniteListStore, type InfiniteQueryOptions, type InfiniteQueryResult, InfiniteQueryStore, KeyOf, ListErrors, MeasureSink, type MinimalQueryClient, OfflineError, type OnDemandOptions, OnDemandResult, OnDemandStreamStore, OpaqueCursor, OrderKey, PagedRow, Params, PendingOpRef, type Platform, type PlatformGates, QueryAdapter, type QueryPage, type RacePolicy, RacedListDefinition, RacedListResult, RacedListStore, type RemovalClass, RowsBuilder, SnapshotStore, SortDirection, Store, StreamDescription, classifyRemovals, createBridge, cursorOfRow, decodeCursor, decodeJwtPayload, defineInfiniteList, defineRacedList, emptyInfiniteResult, emptyRacedResult, encodeCursor, identityKeyFromClaims, identityKeyFromToken, infiniteQueryKey, keyColumns, probePresence, rowComparator };