powersync-bridge 0.0.1-alpha.0

package/dist/index.d.cts

@@ -0,0 +1,496 @@
+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.cjs';
+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.cjs';
+
+/**
+ * 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;
+}
+
+type Clock = () => number;
+interface CheckpointCompletion {
+    /** Lower-bound stamp of the checkpoint's data position (download start), ms. */
+    readonly stamp: number;
+    readonly completedAt: number;
+    /** Stream this completion was observed on; null for the global status. */
+    readonly stream: string | null;
+}
+/**
+ * Session-scoped, monotonic, transition-independent freshness (§5.2, R3/R5).
+ *
+ * stamp(checkpoint_n) = max(observed download start ≤ its completion,
+ *                           completion time of checkpoint n−1,
+ *                           sessionConnectAt when no other bound exists)
+ * localFreshAt = max(previous, stamp) — a null observation never lowers it.
+ */
+declare class FreshnessTracker {
+    private readonly driver;
+    private readonly clock;
+    private sessionConnectAt;
+    private localFreshAt;
+    private prevCompletionAt;
+    private lastDownloadStart;
+    private lastSeenSyncedAt;
+    private lastDownloading;
+    private lastConnected;
+    private lastHasSynced;
+    private readonly streamFreshAt;
+    private readonly streamSeenSyncedAt;
+    private readonly completions;
+    private readonly completionListeners;
+    private readonly clearListeners;
+    private unsubscribe;
+    constructor(driver: BridgeDriver, clock: Clock);
+    /** Call once at engine init and again after every identity swap. */
+    start(epochStartedAt: number): void;
+    stop(): void;
+    private reset;
+    get sessionConnectAtMs(): number | null;
+    get localFreshAtMs(): number;
+    streamFreshAtMs(desc: StreamDescription): number;
+    /** Freshness for a list: the owning stream's stamp when declared, else the global stamp. */
+    freshAtFor(stream: StreamDescription | undefined): number;
+    /** "Answered" = in-session freshness evidence (R5). */
+    isFresh(stream: StreamDescription | undefined): boolean;
+    onCompletion(l: (c: CheckpointCompletion) => void): () => void;
+    onClear(l: () => void): () => void;
+    private onStatus;
+    private stampFor;
+    private recordCompletion;
+}
+
+/** `id` is always the implicit tiebreaker (§8.3): a scalar key K is treated as [K, 'id']. */
+declare function keyColumns<T>(orderKey: OrderKey<T>): [KeyOf<T>, KeyOf<T>];
+/** Comparator over rows for the declared order key + direction. Byte order for strings (SQLite BINARY). */
+declare function rowComparator<T>(orderKey: OrderKey<T>, direction?: SortDirection): (a: T, b: T) => number;
+/** The cursor a row yields, in the definition's cursor shape. */
+declare function cursorOfRow<T, K extends OrderKey<T>>(row: T, orderKey: K): CursorOf<T, K>;
+declare function encodeCursor(cursor: unknown): OpaqueCursor;
+declare function decodeCursor<C>(opaque: OpaqueCursor): C;
+
+/**
+ * Snapshot-lifetime pending window (§5.2): SEEDED with the live set at requestedAt, then every
+ * added AND completed ref observed until the snapshot retires. Never closed at consume.
+ */
+declare class PendingWindow {
+    private readonly refs;
+    private open;
+    constructor(seed: Iterable<PendingOpRef>);
+    observe(delta: CrudDelta): void;
+    get(table: string, id: string): PendingOpRef | undefined;
+    close(): void;
+}
+/**
+ * Identity-scoped engine state (F6-001): the crud-delta mirror (livePending), the open snapshot
+ * windows, and `recentlyAcked`. Created at engine init — before any list mounts — and replaced
+ * wholesale on identity swap.
+ */
+declare class CrudMirror {
+    private readonly driver;
+    private readonly freshness;
+    private readonly clock;
+    private readonly live;
+    private readonly recentlyAcked;
+    private readonly windows;
+    private readonly listeners;
+    private unsubCrud;
+    private unsubCompletion;
+    private seeded;
+    constructor(driver: BridgeDriver, freshness: FreshnessTracker, clock: Clock);
+    start(): void;
+    stop(): void;
+    /** Resolves once the initial live set has been read. */
+    ready(): Promise<void>;
+    /** Re-read the queue and apply the difference as a delta (fallback trigger: every local diff emission). */
+    resync(): Promise<void>;
+    apply(delta: CrudDelta): void;
+    /** A ref retires only when a checkpoint whose STAMP ≥ ackTime completes (F5-001). */
+    private retireAcked;
+    openWindow(): PendingWindow;
+    closeWindow(w: PendingWindow): void;
+    /** The three-set union (R1). */
+    pendingOp(table: string, id: string, window?: PendingWindow): PendingOpRef | undefined;
+    isLivePending(table: string, id: string): boolean;
+    onChange(l: () => void): () => void;
+}
+
+/** Minimal TanStack QueryClient surface the bridge relies on (R11: fetchQuery + keying only). */
+interface MinimalQueryClient {
+    fetchQuery<T>(opts: {
+        queryKey: readonly unknown[];
+        queryFn: (ctx: {
+            signal: AbortSignal;
+        }) => Promise<T>;
+        staleTime?: number;
+    }): Promise<T>;
+}
+interface SnapshotRecord<TApi> {
+    readonly rows: readonly TApi[];
+    readonly asOf: string | undefined;
+    readonly requestedAt: number;
+    readonly fetchedAt: number;
+}
+/**
+ * One fetch per (identity epoch, queryKey, staleTime window) — mount-triggered only, never a
+ * timer (R9). When a TanStack client is supplied it owns dedup + staleness; otherwise an
+ * internal cache with identical semantics is used, so core keeps zero required dependencies.
+ */
+declare class SnapshotCache {
+    private readonly clock;
+    private readonly queryClient;
+    private readonly entries;
+    constructor(clock: BridgeClock, queryClient: MinimalQueryClient | undefined);
+    fetch<TApi>(key: readonly unknown[], staleTime: number, fetcher: (signal: AbortSignal) => Promise<{
+        rows: readonly TApi[];
+        asOf?: string;
+    }>): Promise<SnapshotRecord<TApi>>;
+    /** Cancel every in-flight fetch under a key prefix (identity swap). */
+    abortAll(prefix: readonly unknown[]): void;
+    clear(): void;
+}
+
+interface RacedDeps {
+    readonly driver: BridgeDriver;
+    readonly adapter: QueryAdapter;
+    readonly crud: CrudMirror;
+    readonly freshness: FreshnessTracker;
+    readonly snapshots: SnapshotCache;
+    readonly clock: BridgeClock;
+    readonly epoch: number;
+    readonly identityKey: string | null;
+    readonly apiLegEnabled: boolean;
+    readonly measure: MeasureSink | undefined;
+}
+declare function emptyRacedResult<T>(): RacedListResult<T>;
+/**
+ * The raced list engine (§5.2). One instance per (epoch, definition, scope); ref-counted by hooks.
+ */
+declare class RacedListStore<TItem, TScope, TApi, K extends OrderKey<TItem>> {
+    private readonly deps;
+    private readonly def;
+    private readonly scope;
+    private readonly scopeKey;
+    readonly store: SnapshotStore<RacedListResult<TItem>>;
+    private readonly compare;
+    private readonly table;
+    private readonly abort;
+    private readonly startedAt;
+    private snap;
+    private snapPending;
+    private snapError;
+    private snapWindow;
+    private local;
+    private localError;
+    private emissionSeen;
+    private readonly inSession;
+    private unsubDiffs;
+    private unsubCrud;
+    private unsubFresh;
+    private prepared;
+    private owned;
+    private overlay;
+    private readonly tombstones;
+    private disposed;
+    private refs;
+    private measured;
+    private localMs;
+    private apiMs;
+    constructor(deps: RacedDeps, def: RacedListDefinition<TItem, TScope, TApi, K>, scope: TScope, scopeKey: string);
+    retain(): void;
+    release(): void;
+    get isDisposed(): boolean;
+    /** Synchronous part of an identity swap: the snapshot becomes empty 'pending' at once (R15). */
+    swapRoot(): void;
+    dispose(): void;
+    private start;
+    private startApiLeg;
+    /**
+     * A checkpoint completed. Status events and diff emissions are separate SDK events with no
+     * ordering guarantee; taking ownership on the stale local map would render the pre-checkpoint
+     * value for one frame (fresh→old→fresh). Pre-ownership we re-query once, then reconcile.
+     */
+    private onCompletion;
+    private onDiff;
+    private applyRemovals;
+    private reconcile;
+    private freshAt;
+    private localFresh;
+    private tryTakeOwnership;
+    private renderOwned;
+    private renderRace;
+    private finalize;
+    private build;
+    private report;
+    /** The cursor of the last rendered row — used by raced × infinite composition (R13). */
+    lastCursor(): ReturnType<typeof cursorOfRow<TItem, K>> | undefined;
+}
+
+type Platform = 'web' | 'native';
+type RacePolicy = 'race' | 'local-first';
+interface PlatformGates {
+    readonly native?: RacePolicy;
+    readonly web?: RacePolicy;
+}
+interface BridgeOptions {
+    readonly driver: BridgeDriver;
+    readonly adapter: QueryAdapter;
+    /** TanStack QueryClient — used for fetchQuery + keying only (R11). Optional. */
+    readonly queryClient?: MinimalQueryClient;
+    readonly platform?: Platform;
+    /** Native defaults to local-first (R8); web to race. */
+    readonly platformGates?: PlatformGates;
+    readonly measure?: {
+        readonly sink: MeasureSink;
+    };
+    readonly identity?: IdentityKeyOptions;
+    readonly clock?: BridgeClock;
+    readonly onEvicted?: (listId: string, ids: readonly string[]) => void;
+}
+/** The shape of a PowerSync backend connector, structurally (no SDK import in core). */
+interface ConnectorLike {
+    fetchCredentials(): Promise<{
+        token: string;
+        endpoint?: string;
+        expiresAt?: Date;
+    } | null>;
+    uploadData(database: unknown): Promise<void>;
+}
+/**
+ * The bridge: one per app, created once in a plain module before login (§5.1 root object).
+ * Owns the identity-scoped engine state (crud-delta mirror, recentlyAcked, freshness) from
+ * creation — before any list mounts (F6-001).
+ */
+declare class Bridge {
+    readonly driver: BridgeDriver;
+    readonly adapter: QueryAdapter;
+    readonly platform: Platform;
+    readonly clock: BridgeClock;
+    /** Increments on every identity swap; hooks subscribe to re-acquire their stores. */
+    readonly epochStore: Store<number>;
+    private readonly identity;
+    private readonly freshness;
+    private readonly crud;
+    private readonly snapshots;
+    private readonly epochSnapshot;
+    private readonly stores;
+    private readonly gates;
+    private readonly measure;
+    private readonly identityOpts;
+    private readonly onEvicted;
+    private disposed;
+    constructor(opts: BridgeOptions);
+    get epoch(): number;
+    get identityKey(): string | null;
+    /** 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. */
+    wrapConnector<C extends ConnectorLike>(connector: C): C;
+    /** Escape hatch for scope that is not in the token. */
+    setIdentity(scope: Record<string, unknown> | null): void;
+    /**
+     * Identity swap (R15): bump the epoch AND swap every store's root to empty 'pending' in ONE
+     * synchronous operation, then tear the rest down asynchronously.
+     */
+    private swapEpoch;
+    private acquire;
+    private apiLegEnabled;
+    raced<TItem, TScope, TApi, K extends OrderKey<TItem>>(def: RacedListDefinition<TItem, TScope, TApi, K>, scope: TScope): RacedListStore<TItem, TScope, TApi, K>;
+    infinite<TItem, TScope, K extends OrderKey<TItem>, TCursor, TPartition>(def: InfiniteListDefinition<TItem, TScope, K, TCursor, TPartition>, scope: TScope): InfiniteListStore<TItem, TScope, K, TCursor, TPartition>;
+    onDemand(name: string, params: Params | null, opts?: OnDemandOptions): OnDemandStreamStore;
+    autoSync(config: FlaggerConfig, ids: readonly string[]): AutoSyncFlagStore;
+    dispose(): void;
+}
+declare function createBridge(opts: BridgeOptions): Bridge;
+
+type RacedInput<TItem, TScope, TApi, K extends OrderKey<TItem>> = Omit<RacedListDefinition<TItem, TScope, TApi, K>, 'kind'>;
+type InfiniteInput<TItem, TScope, K extends OrderKey<TItem>, TCursor, TPartition> = Omit<InfiniteListDefinition<TItem, TScope, K, TCursor, TPartition>, 'kind'>;
+/**
+ * `TItem` is inferred from the query's awaited result (§8.1); `TApi` from `fetchSnapshot`.
+ * Definitions close over the app's ORM instance; annotate the scope (and the page argument
+ * for infinite lists) so the callback is not context-sensitive.
+ */
+declare function defineRacedList<TItem, TScope, TApi, K extends OrderKey<TItem>>(input: RacedInput<TItem, TScope, TApi, K>): RacedListDefinition<TItem, TScope, TApi, K>;
+declare function defineInfiniteList<TItem, TScope, K extends OrderKey<TItem>, TCursor, TPartition = string>(input: InfiniteInput<TItem, TScope, K, TCursor, TPartition>): InfiniteListDefinition<TItem, TScope, K, TCursor, TPartition>;
+
+/**
+ * Four-way removal taxonomy (§6.4):
+ *   filtered  — row still exists locally, no longer matches the list query → drop, no tombstone
+ *   delete    — absent, and its producing stream is still tracked before expiry → drop + tombstone
+ *   eviction  — absent, and its stream is gone or past expiry → retain, presentLocally:false
+ *   retain    — classification impossible (predicate threw) → retain
+ */
+type RemovalClass = 'filtered' | 'delete' | 'eviction' | 'retain';
+interface RemovalContext<T> {
+    readonly driver: BridgeDriver;
+    readonly clock: BridgeClock;
+    readonly table: string;
+    /** Producing stream for a row, when known (partition escalation). */
+    readonly provenance: (row: T) => StreamDescription | undefined;
+    readonly isInWindow?: ((row: T) => boolean) | undefined;
+}
+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 };