@tanstack/db-sqlite-persistence-core 0.2.23 → 0.4.0

package/dist/esm/persisted.d.ts

@@ -1,15 +1,25 @@
+import { TransportedLoadSubsetOptions } from './remote-subset-wire.js';
+import { RemoteSubsetOwner } from './remote-subset-owner.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
-import { CollectionConfig, LoadSubsetOptions, PendingMutation, SyncConfig, UtilsRecord } from '@tanstack/db';
+import { CollectionConfig, InferSchemaOutput, LoadSubsetOptions, PendingMutation, SyncConfig, SyncPersistenceKeySetEvidence, SyncPersistenceScanOptions, UtilsRecord } from '@tanstack/db';
 export type PersistedMutationEnvelope = {
     mutationId: string;
     type: `insert`;
     key: string | number;
     value: Record<string, unknown>;
+    /** Persisted row metadata, not optimistic-transaction metadata. */
+    metadata?: unknown;
+    /** Whether this envelope replaces or deletes the persisted row metadata. */
+    metadataChanged?: boolean;
 } | {
     mutationId: string;
     type: `update`;
     key: string | number;
     value: Record<string, unknown>;
+    /** Persisted row metadata, not optimistic-transaction metadata. */
+    metadata?: unknown;
+    /** Whether this envelope replaces or deletes the persisted row metadata. */
+    metadataChanged?: boolean;
 } | {
     mutationId: string;
     type: `delete`;
@@ -52,17 +62,35 @@ export type TxCommitted = {
 export type EnsureRemoteSubsetRequest = {
     type: `rpc:ensureRemoteSubset:req`;
     rpcId: string;
-    options: LoadSubsetOptions;
+    acquisitionId: string;
+    options: TransportedLoadSubsetOptions;
 };
 export type EnsureRemoteSubsetResponse = {
     type: `rpc:ensureRemoteSubset:res`;
     rpcId: string;
     ok: true;
+    leaderId: string;
 } | {
     type: `rpc:ensureRemoteSubset:res`;
     rpcId: string;
     ok: false;
     error: string;
+    retryable?: true;
+};
+export type ReleaseRemoteSubsetRequest = {
+    type: `rpc:releaseRemoteSubset:req`;
+    rpcId: string;
+    acquisitionId: string;
+};
+export type ReleaseRemoteSubsetResponse = {
+    type: `rpc:releaseRemoteSubset:res`;
+    rpcId: string;
+    ok: true;
+} | {
+    type: `rpc:releaseRemoteSubset:res`;
+    rpcId: string;
+    ok: false;
+    error: string;
 };
 export type ApplyLocalMutationsRequest = {
     type: `rpc:applyLocalMutations:req`;
@@ -84,6 +112,42 @@ export type ApplyLocalMutationsResponse = {
     ok: false;
     code: `NOT_LEADER` | `VALIDATION_ERROR` | `CONFLICT` | `TIMEOUT`;
     error: string;
+} | {
+    type: `rpc:applyLocalMutations:res`;
+    rpcId: string;
+    ok: false;
+    code: `PERSISTENCE_ERROR`;
+    error: string;
+    sourceCode?: string | number;
+    path?: string | ReadonlyArray<string | number>;
+};
+export type ApplyCommittedTxRequest = {
+    type: `rpc:applyCommittedTx:req`;
+    rpcId: string;
+    envelopeId: string;
+    tx: PersistedTx;
+};
+export type ApplyCommittedTxResponse = {
+    type: `rpc:applyCommittedTx:res`;
+    rpcId: string;
+    ok: true;
+    term: number;
+    seq: number;
+    latestRowVersion: number;
+} | {
+    type: `rpc:applyCommittedTx:res`;
+    rpcId: string;
+    ok: false;
+    code: `NOT_LEADER` | `CONFLICT` | `TIMEOUT`;
+    error: string;
+} | {
+    type: `rpc:applyCommittedTx:res`;
+    rpcId: string;
+    ok: false;
+    code: `PERSISTENCE_ERROR`;
+    error: string;
+    sourceCode?: string | number;
+    path?: string | ReadonlyArray<string | number>;
 };
 export type PullSinceRequest = {
     type: `rpc:pullSince:req`;
@@ -157,8 +221,17 @@ export type PersistedScannedRow<T extends object = Record<string, unknown>, TKey
     value: T;
     metadata?: unknown;
 };
-export type PersistedRowScanOptions = {
-    metadataOnly?: boolean;
+export type PersistedRowScanOptions = SyncPersistenceScanOptions;
+export type PersistedKeySetEvidence = SyncPersistenceKeySetEvidence;
+export type PersistencePullSinceResult = {
+    latestRowVersion: number;
+    requiresFullReload: true;
+} | {
+    latestRowVersion: number;
+    requiresFullReload: false;
+    changedKeys: Array<string | number>;
+    deletedKeys: Array<string | number>;
+    deltas?: Array<ReplayableTxDelta<Record<string, unknown>, string | number>>;
 };
 export type PersistedTx<T extends object = Record<string, unknown>, TKey extends string | number = string | number> = {
     txId: string;
@@ -186,6 +259,18 @@ export type PersistedTx<T extends object = Record<string, unknown>, TKey extends
     rowMetadataMutations?: Array<PersistedRowMetadataMutation<TKey>>;
     collectionMetadataMutations?: Array<PersistedCollectionMetadataMutation>;
 };
+/**
+ * Opaque identity shared by every adapter over the same physical SQLite driver.
+ * The core adapter uses it to serialize non-preemptible logical operations
+ * while alternating one regular operation between queued hydrations.
+ *
+ * Delegating drivers must forward this property before they are passed to a
+ * SQLite persistence adapter. A driver may also brand each returned Promise
+ * with the same key for late capability discovery, but a wrapper must return
+ * that exact Promise: discovering the key after a call cannot retroactively
+ * schedule the wrapper's first logical operation.
+ */
+export declare const SQLITE_DRIVER_SHARED_LOGICAL_SCHEDULING_KEY: unique symbol;
 export interface PersistenceAdapter {
     loadSubset: (collectionId: string, options: LoadSubsetOptions, ctx?: {
         requiredIndexSignatures?: ReadonlyArray<string>;
@@ -194,6 +279,25 @@ export interface PersistenceAdapter {
         value: Record<string, unknown>;
         metadata?: unknown;
     }>>;
+    loadResumeSnapshot: (collectionId: string, ctx?: {
+        requiredIndexSignatures?: ReadonlyArray<string>;
+        includeRows?: boolean;
+    }) => Promise<{
+        rows: Array<{
+            key: string | number;
+            value: Record<string, unknown>;
+            metadata?: unknown;
+        }>;
+        keySet?: PersistedKeySetEvidence;
+        collectionMetadata: Array<{
+            key: string;
+            value: unknown;
+        }>;
+        latestTerm: number;
+        latestSeq: number;
+        latestRowVersion: number;
+        resetEpoch: number;
+    }>;
     applyCommittedTx: (collectionId: string, tx: PersistedTx) => Promise<void>;
     loadCollectionMetadata?: (collectionId: string) => Promise<Array<{
         key: string;
@@ -207,24 +311,56 @@ export interface PersistenceAdapter {
         latestSeq: number;
         latestRowVersion: number;
     }>;
+    /**
+     * Runs one complete logical hydrate as a non-preemptible scheduler unit.
+     * The callback must use the supplied unscheduled adapter for all nested
+     * persistence work and must not retain it after the callback settles.
+     */
+    runInHydrationScope?: <T>(task: (adapter: HydrationPersistenceAdapter) => Promise<T>) => Promise<T>;
+    /** Schedule one regular operation before it acquires external writer locks. */
+    runInRegularScope?: <T>(task: (adapter: HydrationPersistenceAdapter) => Promise<T>) => Promise<T>;
+    /** Whether hydration scopes currently enter a shared driver scheduler. */
+    isHydrationScopeScheduled?: () => boolean;
 }
+export type HydrationPersistenceAdapter = PersistenceAdapter & {
+    pullSince?: (collectionId: string, fromRowVersion: number) => Promise<PersistencePullSinceResult>;
+};
+export type { RemoteSubsetOwner } from './remote-subset-owner.js';
 export interface SQLiteDriver {
+    readonly [SQLITE_DRIVER_SHARED_LOGICAL_SCHEDULING_KEY]?: object;
+    /** Host-specific limit on bound parameters in one query, when lower than SQLite's. */
+    readonly maxBoundParameters?: number;
     exec: (sql: string) => Promise<void>;
     query: <T>(sql: string, params?: ReadonlyArray<unknown>) => Promise<ReadonlyArray<T>>;
     run: (sql: string, params?: ReadonlyArray<unknown>) => Promise<void>;
     transaction: <T>(fn: (transactionDriver: SQLiteDriver) => Promise<T>) => Promise<T>;
     transactionWithDriver?: <T>(fn: (transactionDriver: SQLiteDriver) => Promise<T>) => Promise<T>;
 }
+/**
+ * Forwards a driver's shared logical scheduling identity to a transparent
+ * delegating driver before the wrapper is used by a persistence adapter.
+ */
+export declare function forwardSQLiteDriverSharedLogicalScheduling<TDriver extends SQLiteDriver>(source: SQLiteDriver, wrapper: TDriver): TDriver;
 export interface PersistedCollectionCoordinator {
     getNodeId: () => string;
+    setAdapterForCollection?: (collectionId: string, adapter: PersistenceAdapter) => void;
     subscribe: (collectionId: string, onMessage: (message: ProtocolEnvelope<unknown>) => void) => () => void;
     publish: (collectionId: string, message: ProtocolEnvelope<unknown>) => void;
     isLeader: (collectionId: string) => boolean;
     ensureLeadership: (collectionId: string) => Promise<void>;
-    requestEnsureRemoteSubset?: (collectionId: string, options: LoadSubsetOptions) => Promise<void>;
-    requestEnsurePersistedIndex: (collectionId: string, signature: string, spec: PersistedIndexSpec) => Promise<void>;
+    requestEnsureRemoteSubset: (collectionId: string, options: LoadSubsetOptions) => Promise<void>;
+    requestReleaseRemoteSubset: (collectionId: string, options: LoadSubsetOptions) => Promise<void>;
+    registerRemoteSubsetOwner: (collectionId: string, owner: RemoteSubsetOwner) => () => void;
+    /**
+     * Requests leader-side index creation. The scoped adapter is leader-local
+     * and is never serialized to a follower. `localEnsureCompleted` lets the
+     * built-in leader avoid repeating successful local work.
+     */
+    requestEnsurePersistedIndex: (collectionId: string, signature: string, spec: PersistedIndexSpec, scopedAdapter?: HydrationPersistenceAdapter, localEnsureCompleted?: boolean) => Promise<void>;
     requestApplyLocalMutations?: (collectionId: string, mutations: Array<PersistedMutationEnvelope>) => Promise<ApplyLocalMutationsResponse>;
-    pullSince?: (collectionId: string, fromRowVersion: number) => Promise<PullSinceResponse>;
+    requestApplyCommittedTx: (collectionId: string, tx: PersistedTx, scopedAdapter?: HydrationPersistenceAdapter) => Promise<ApplyCommittedTxResponse>;
+    /** The scoped adapter is leader-local and is never serialized to a follower. */
+    pullSince?: (collectionId: string, fromRowVersion: number, scopedAdapter?: HydrationPersistenceAdapter) => Promise<PullSinceResponse>;
 }
 export interface PersistedCollectionPersistence {
     adapter: PersistenceAdapter;
@@ -251,14 +387,23 @@ export interface PersistedCollectionUtils extends UtilsRecord {
     /** Hydrate once without acquiring a new ongoing subset lease. */
     forceReloadSubset?: (options: LoadSubsetOptions) => Promise<void> | void;
 }
+export type PersistedInitialRenderOptions = {
+    strategy: `network-first`;
+    /** Time to prefer network before restored rows may render; defaults to 3s. */
+    networkTimeoutMs?: number;
+};
 export type PersistedSyncWrappedOptions<T extends object, TKey extends string | number, TSchema extends StandardSchemaV1 = never, TUtils extends UtilsRecord = UtilsRecord> = CollectionConfig<T, TKey, TSchema, TUtils> & {
     sync: SyncConfig<T, TKey>;
     persistence: PersistedCollectionPersistence;
     schemaVersion?: number;
+    /** Opt into network-first rendering with a persisted fallback. */
+    initialRender?: PersistedInitialRenderOptions;
 };
 export type PersistedLocalOnlyOptions<T extends object, TKey extends string | number, TSchema extends StandardSchemaV1 = never, TUtils extends UtilsRecord = UtilsRecord> = Omit<CollectionConfig<T, TKey, TSchema, TUtils>, `sync`> & {
     persistence: PersistedCollectionPersistence;
     schemaVersion?: number;
+    /** Opt into network-first rendering with a persisted fallback. */
+    initialRender?: PersistedInitialRenderOptions;
 };
 type PersistedSyncOptionsResult<T extends object, TKey extends string | number, TSchema extends StandardSchemaV1, TUtils extends UtilsRecord> = CollectionConfig<T, TKey, TSchema, TUtils> & {
     persistence: PersistedResolvedPersistence;
@@ -274,21 +419,41 @@ type PersistedLocalOnlyOptionsResult<T extends object, TKey extends string | num
  */
 export declare class SingleProcessCoordinator implements PersistedCollectionCoordinator {
     private readonly nodeId;
+    private readonly collectionAdapters;
+    private readonly remoteSubsetOwners;
+    private readonly remoteSubsetAcquisitions;
     constructor(nodeId?: string);
     getNodeId(): string;
     subscribe(): () => void;
     publish(): void;
     isLeader(): boolean;
     ensureLeadership(): Promise<void>;
-    requestEnsureRemoteSubset(): Promise<void>;
+    requestEnsureRemoteSubset(collectionId: string, options: LoadSubsetOptions): Promise<void>;
+    requestReleaseRemoteSubset(collectionId: string, options: LoadSubsetOptions): Promise<void>;
+    registerRemoteSubsetOwner(collectionId: string, owner: RemoteSubsetOwner): () => void;
     requestEnsurePersistedIndex(): Promise<void>;
+    setAdapterForCollection(collectionId: string, adapter: PersistenceAdapter): void;
+    requestApplyCommittedTx(collectionId: string, tx: PersistedTx): Promise<ApplyCommittedTxResponse>;
     pullSince(): Promise<PullSinceResponse>;
 }
 export declare function validatePersistedCollectionCoordinator(coordinator: PersistedCollectionCoordinator): void;
 export type PersistedCollectionMode = `sync-present` | `sync-absent`;
-export declare function persistedCollectionOptions<T extends object, TKey extends string | number, TSchema extends StandardSchemaV1 = never, TUtils extends UtilsRecord = UtilsRecord>(options: PersistedSyncWrappedOptions<T, TKey, TSchema, TUtils>): PersistedSyncOptionsResult<T, TKey, TSchema, TUtils>;
-export declare function persistedCollectionOptions<T extends object, TKey extends string | number, TSchema extends StandardSchemaV1 = never, TUtils extends UtilsRecord = UtilsRecord>(options: PersistedLocalOnlyOptions<T, TKey, TSchema, TUtils>): PersistedLocalOnlyOptionsResult<T, TKey, TSchema, TUtils>;
+export declare function persistedCollectionOptions<TSchema extends StandardSchemaV1, TKey extends string | number, TUtils extends UtilsRecord = UtilsRecord>(options: PersistedSyncWrappedOptions<InferSchemaOutput<TSchema>, TKey, TSchema, TUtils> & {
+    schema: TSchema;
+}): PersistedSyncOptionsResult<InferSchemaOutput<TSchema>, TKey, TSchema, TUtils> & {
+    schema: TSchema;
+};
+export declare function persistedCollectionOptions<TSchema extends StandardSchemaV1, TKey extends string | number, TUtils extends UtilsRecord = UtilsRecord>(options: PersistedLocalOnlyOptions<InferSchemaOutput<TSchema>, TKey, TSchema, TUtils> & {
+    schema: TSchema;
+}): PersistedLocalOnlyOptionsResult<InferSchemaOutput<TSchema>, TKey, TSchema, TUtils> & {
+    schema: TSchema;
+};
+export declare function persistedCollectionOptions<T extends object, TKey extends string | number, TSchema extends StandardSchemaV1 = never, TUtils extends UtilsRecord = UtilsRecord>(options: PersistedSyncWrappedOptions<T, TKey, TSchema, TUtils> & {
+    schema?: never;
+}): PersistedSyncOptionsResult<T, TKey, TSchema, TUtils>;
+export declare function persistedCollectionOptions<T extends object, TKey extends string | number, TSchema extends StandardSchemaV1 = never, TUtils extends UtilsRecord = UtilsRecord>(options: PersistedLocalOnlyOptions<T, TKey, TSchema, TUtils> & {
+    schema?: never;
+}): PersistedLocalOnlyOptionsResult<T, TKey, TSchema, TUtils>;
 export declare function encodePersistedStorageKey(key: string | number): string;
 export declare function decodePersistedStorageKey(encoded: string): string | number;
 export declare function createPersistedTableName(collectionId: string, prefix?: `c` | `t`): string;
-export {};