@tanstack/db-sqlite-persistence-core 0.1.2

package/dist/esm/persisted.d.ts

@@ -0,0 +1,293 @@
+import { StandardSchemaV1 } from '@standard-schema/spec';
+import { CollectionConfig, LoadSubsetOptions, PendingMutation, SyncConfig, UtilsRecord } from '@tanstack/db';
+export type PersistedMutationEnvelope = {
+    mutationId: string;
+    type: `insert`;
+    key: string | number;
+    value: Record<string, unknown>;
+} | {
+    mutationId: string;
+    type: `update`;
+    key: string | number;
+    value: Record<string, unknown>;
+} | {
+    mutationId: string;
+    type: `delete`;
+    key: string | number;
+    value: Record<string, unknown>;
+};
+export type ProtocolEnvelope<TPayload> = {
+    v: 1;
+    dbName: string;
+    collectionId: string;
+    senderId: string;
+    ts: number;
+    payload: TPayload;
+};
+export type LeaderHeartbeat = {
+    type: `leader:heartbeat`;
+    term: number;
+    leaderId: string;
+    latestSeq: number;
+    latestRowVersion: number;
+};
+export type TxCommitted = {
+    type: `tx:committed`;
+    term: number;
+    seq: number;
+    txId: string;
+    latestRowVersion: number;
+} & ({
+    requiresFullReload: true;
+} | {
+    requiresFullReload: false;
+    changedRows: Array<{
+        key: string | number;
+        value: Record<string, unknown>;
+    }>;
+    deletedKeys: Array<string | number>;
+    rowMetadataMutations?: Array<PersistedRowMetadataMutation<string | number>>;
+    collectionMetadataMutations?: Array<PersistedCollectionMetadataMutation>;
+});
+export type EnsureRemoteSubsetRequest = {
+    type: `rpc:ensureRemoteSubset:req`;
+    rpcId: string;
+    options: LoadSubsetOptions;
+};
+export type EnsureRemoteSubsetResponse = {
+    type: `rpc:ensureRemoteSubset:res`;
+    rpcId: string;
+    ok: true;
+} | {
+    type: `rpc:ensureRemoteSubset:res`;
+    rpcId: string;
+    ok: false;
+    error: string;
+};
+export type ApplyLocalMutationsRequest = {
+    type: `rpc:applyLocalMutations:req`;
+    rpcId: string;
+    envelopeId: string;
+    mutations: Array<PersistedMutationEnvelope>;
+};
+export type ApplyLocalMutationsResponse = {
+    type: `rpc:applyLocalMutations:res`;
+    rpcId: string;
+    ok: true;
+    term: number;
+    seq: number;
+    latestRowVersion: number;
+    acceptedMutationIds: Array<string>;
+} | {
+    type: `rpc:applyLocalMutations:res`;
+    rpcId: string;
+    ok: false;
+    code: `NOT_LEADER` | `VALIDATION_ERROR` | `CONFLICT` | `TIMEOUT`;
+    error: string;
+};
+export type PullSinceRequest = {
+    type: `rpc:pullSince:req`;
+    rpcId: string;
+    fromRowVersion: number;
+};
+export type PullSinceResponse = {
+    type: `rpc:pullSince:res`;
+    rpcId: string;
+    ok: true;
+    latestTerm: number;
+    latestSeq: number;
+    latestRowVersion: number;
+    requiresFullReload: true;
+} | {
+    type: `rpc:pullSince:res`;
+    rpcId: string;
+    ok: true;
+    latestTerm: number;
+    latestSeq: number;
+    latestRowVersion: number;
+    requiresFullReload: false;
+    changedKeys: Array<string | number>;
+    deletedKeys: Array<string | number>;
+    deltas?: Array<ReplayableTxDelta<Record<string, unknown>, string | number>>;
+} | {
+    type: `rpc:pullSince:res`;
+    rpcId: string;
+    ok: false;
+    error: string;
+};
+export type CollectionReset = {
+    type: `collection:reset`;
+    schemaVersion: number;
+    resetEpoch: number;
+};
+export interface PersistedIndexSpec {
+    readonly expressionSql: ReadonlyArray<string>;
+    readonly whereSql?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export type PersistedRowMetadataMutation<TKey extends string | number = string | number> = {
+    type: `set`;
+    key: TKey;
+    value: unknown;
+} | {
+    type: `delete`;
+    key: TKey;
+};
+export type PersistedCollectionMetadataMutation = {
+    type: `set`;
+    key: string;
+    value: unknown;
+} | {
+    type: `delete`;
+    key: string;
+};
+export type ReplayableTxDelta<T extends Record<string, unknown> = Record<string, unknown>, TKey extends string | number = string | number> = {
+    txId: string;
+    latestRowVersion: number;
+    changedRows: Array<{
+        key: TKey;
+        value: T;
+    }>;
+    deletedKeys: Array<TKey>;
+    rowMetadataMutations: Array<PersistedRowMetadataMutation<TKey>>;
+    collectionMetadataMutations: Array<PersistedCollectionMetadataMutation>;
+};
+export type PersistedScannedRow<T extends object, TKey extends string | number = string | number> = {
+    key: TKey;
+    value: T;
+    metadata?: unknown;
+};
+export type PersistedRowScanOptions = {
+    metadataOnly?: boolean;
+};
+export type PersistedTx<T extends object, TKey extends string | number = string | number> = {
+    txId: string;
+    term: number;
+    seq: number;
+    rowVersion: number;
+    truncate?: boolean;
+    mutations: Array<{
+        type: `insert`;
+        key: TKey;
+        value: T;
+        metadata?: unknown;
+        metadataChanged?: boolean;
+    } | {
+        type: `update`;
+        key: TKey;
+        value: T;
+        metadata?: unknown;
+        metadataChanged?: boolean;
+    } | {
+        type: `delete`;
+        key: TKey;
+        value: T;
+    }>;
+    rowMetadataMutations?: Array<PersistedRowMetadataMutation<TKey>>;
+    collectionMetadataMutations?: Array<PersistedCollectionMetadataMutation>;
+};
+export interface PersistenceAdapter<T extends object, TKey extends string | number = string | number> {
+    loadSubset: (collectionId: string, options: LoadSubsetOptions, ctx?: {
+        requiredIndexSignatures?: ReadonlyArray<string>;
+    }) => Promise<Array<{
+        key: TKey;
+        value: T;
+        metadata?: unknown;
+    }>>;
+    applyCommittedTx: (collectionId: string, tx: PersistedTx<T, TKey>) => Promise<void>;
+    loadCollectionMetadata?: (collectionId: string) => Promise<Array<{
+        key: string;
+        value: unknown;
+    }>>;
+    scanRows?: (collectionId: string, options?: PersistedRowScanOptions) => Promise<Array<PersistedScannedRow<T, TKey>>>;
+    ensureIndex: (collectionId: string, signature: string, spec: PersistedIndexSpec) => Promise<void>;
+    markIndexRemoved?: (collectionId: string, signature: string) => Promise<void>;
+    getStreamPosition?: (collectionId: string) => Promise<{
+        latestTerm: number;
+        latestSeq: number;
+        latestRowVersion: number;
+    }>;
+}
+export interface SQLiteDriver {
+    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>;
+}
+export interface PersistedCollectionCoordinator {
+    getNodeId: () => string;
+    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>;
+    requestApplyLocalMutations?: (collectionId: string, mutations: Array<PersistedMutationEnvelope>) => Promise<ApplyLocalMutationsResponse>;
+    pullSince?: (collectionId: string, fromRowVersion: number) => Promise<PullSinceResponse>;
+}
+export interface PersistedCollectionPersistence<T extends object, TKey extends string | number = string | number> {
+    adapter: PersistenceAdapter<T, TKey>;
+    coordinator?: PersistedCollectionCoordinator;
+    resolvePersistenceForCollection?: (options: {
+        collectionId: string;
+        mode: PersistedCollectionMode;
+        schemaVersion?: number;
+    }) => PersistedCollectionPersistence<T, TKey>;
+    resolvePersistenceForMode?: (mode: PersistedCollectionMode) => PersistedCollectionPersistence<T, TKey>;
+}
+type PersistedResolvedPersistence<T extends object, TKey extends string | number> = PersistedCollectionPersistence<T, TKey> & {
+    coordinator: PersistedCollectionCoordinator;
+};
+export type PersistedCollectionLeadershipState = {
+    nodeId: string;
+    isLeader: boolean;
+};
+export interface PersistedCollectionUtils extends UtilsRecord {
+    acceptMutations: (transaction: {
+        mutations: Array<PendingMutation<Record<string, unknown>>>;
+    }) => Promise<void> | void;
+    getLeadershipState?: () => PersistedCollectionLeadershipState;
+    forceReloadSubset?: (options: LoadSubsetOptions) => Promise<void> | void;
+}
+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<T, TKey>;
+    schemaVersion?: number;
+};
+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<T, TKey>;
+    schemaVersion?: number;
+};
+type PersistedSyncOptionsResult<T extends object, TKey extends string | number, TSchema extends StandardSchemaV1, TUtils extends UtilsRecord> = CollectionConfig<T, TKey, TSchema, TUtils> & {
+    persistence: PersistedResolvedPersistence<T, TKey>;
+};
+type PersistedLocalOnlyOptionsResult<T extends object, TKey extends string | number, TSchema extends StandardSchemaV1, TUtils extends UtilsRecord> = CollectionConfig<T, TKey, TSchema, TUtils & PersistedCollectionUtils> & {
+    id: string;
+    persistence: PersistedResolvedPersistence<T, TKey>;
+    utils: TUtils & PersistedCollectionUtils;
+};
+/**
+ * Phase-0 coordinator implementation for single-process runtimes.
+ * It satisfies the coordinator contract without cross-process transport.
+ */
+export declare class SingleProcessCoordinator implements PersistedCollectionCoordinator {
+    private readonly nodeId;
+    constructor(nodeId?: string);
+    getNodeId(): string;
+    subscribe(): () => void;
+    publish(): void;
+    isLeader(): boolean;
+    ensureLeadership(): Promise<void>;
+    requestEnsureRemoteSubset(): Promise<void>;
+    requestEnsurePersistedIndex(): Promise<void>;
+    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 encodePersistedStorageKey(key: string | number): string;
+export declare function decodePersistedStorageKey(encoded: string): string | number;
+export declare function createPersistedTableName(collectionId: string, prefix?: `c` | `t`): string;
+export {};