@vireocodedev/sqlite 0.2.0 → 0.2.1

package/dist/concurrency/createSqliteOperationCoordinator.d.ts

@@ -0,0 +1,24 @@
+declare const sqliteOperationLockOwnerBrand: unique symbol;
+export type SqliteOperationLockOwner = {
+    readonly [sqliteOperationLockOwnerBrand]: true;
+};
+export type ExclusiveLockManager = {
+    request: <T>(name: string, options: {
+        mode: "exclusive";
+    }, callback: () => Promise<T>) => Promise<T>;
+};
+export type CreateSqliteOperationCoordinatorConfig = {
+    lockName: string;
+    getLockManager?: () => ExclusiveLockManager | null;
+    createAbortReason?: (reason: string) => unknown;
+};
+export type SqliteOperationCoordinator = {
+    runDatabaseExclusive: <T>(operation: (lockOwner: SqliteOperationLockOwner) => Promise<T>, lockOwner?: SqliteOperationLockOwner) => Promise<T>;
+    runEntityExclusive: <T>(entityKey: string, operation: (lockOwner: SqliteOperationLockOwner) => Promise<T>, lockOwner?: SqliteOperationLockOwner) => Promise<T>;
+    runHydrationExclusive: (operation: (signal: AbortSignal, lockOwner: SqliteOperationLockOwner) => Promise<void>) => Promise<void>;
+    abortHydration: (reason?: string) => void;
+    awaitHydrationIdle: () => Promise<void>;
+};
+/** Creates isolated local queues with optional cross-context serialization through Web Locks. */
+export declare function createSqliteOperationCoordinator(config: CreateSqliteOperationCoordinatorConfig): SqliteOperationCoordinator;
+export {};

package/dist/core/sqliteCrud.d.ts

@@ -0,0 +1,4 @@
+import { SqliteDatabase } from './sqliteTypes';
+export declare function runSqliteTransaction(db: SqliteDatabase, action: () => void): void;
+export declare function listSqliteRows<T>(db: SqliteDatabase, sql: string, mapRow: (row: unknown[]) => T): T[];
+export declare function deleteSqliteRowsByKey(db: SqliteDatabase, table: string, keyColumn: string, values: Array<number | string>): void;

package/dist/core/sqliteEntityFactory.d.ts

@@ -0,0 +1,134 @@
+import { SqliteRequestHandlers } from './sqliteRequestHandlers';
+import { SqliteDatabase } from './sqliteTypes';
+type SqliteEntityField<TValue> = {
+    column: string;
+    id?: boolean;
+    toDb?: (value: TValue) => unknown;
+    fromDb: (value: unknown) => TValue;
+};
+type SqliteEntityFields = Record<string, SqliteEntityField<any>>;
+type SqliteEntityFieldValue<TField> = TField extends SqliteEntityField<infer TValue> ? TValue : never;
+type SqliteEntityRecordFromFields<TFields extends SqliteEntityFields> = {
+    [TProperty in keyof TFields as undefined extends SqliteEntityFieldValue<TFields[TProperty]> ? never : TProperty]: SqliteEntityFieldValue<TFields[TProperty]>;
+} & {
+    [TProperty in keyof TFields as undefined extends SqliteEntityFieldValue<TFields[TProperty]> ? TProperty : never]?: Exclude<SqliteEntityFieldValue<TFields[TProperty]>, undefined>;
+};
+type SqliteEntityIdPropertyName<TFields extends SqliteEntityFields> = {
+    [TProperty in keyof TFields]: TFields[TProperty] extends {
+        id: true;
+    } ? TProperty : never;
+}[keyof TFields] & string;
+type SqliteEntityDeletePayloadFromFields<TFields extends SqliteEntityFields> = Pick<SqliteEntityRecordFromFields<TFields>, Extract<SqliteEntityIdPropertyName<TFields>, keyof SqliteEntityRecordFromFields<TFields>>>;
+type SqliteEntityOperationNames<TSingular extends string, TPlural extends string> = {
+    replace: `replace${TPlural}`;
+    upsert: `upsert${TSingular}`;
+    list: `list${TPlural}`;
+    delete: `delete${TPlural}`;
+};
+export type SqliteEntitySseConfig<TFields extends SqliteEntityFields, TSseEntity extends string, TSseContext extends object> = {
+    entity: TSseEntity;
+    hydrationEntityKey?: string;
+    mapCreate?: (payload: SqliteEntityRecordFromFields<TFields>, context: TSseContext) => SqliteEntityRecordFromFields<TFields> | null;
+    mapUpdate?: (payload: SqliteEntityRecordFromFields<TFields>, context: TSseContext) => SqliteEntityRecordFromFields<TFields> | null;
+    mapDeleteKeys?: (payload: SqliteEntityDeletePayloadFromFields<TFields>, context: TSseContext) => Array<number | string>;
+};
+export type SqliteEntitySpec<TFields extends SqliteEntityFields = SqliteEntityFields, TSingular extends string = string, TPlural extends string = string, TRequestKeys extends {
+    replace: string;
+    upsert: string;
+    delete: string;
+} = {
+    replace: string;
+    upsert: string;
+    delete: string;
+}, TSseEntity extends string = string, TSseContext extends object = object> = {
+    entityNameSingular: TSingular;
+    entityNamePlural: TPlural;
+    tableName: string;
+    fields: TFields;
+    keywordFields?: Array<keyof TFields & string>;
+    softDelete?: {
+        enabled: boolean;
+        columnName?: string;
+    };
+    orderBy?: string;
+    requestKeys: TRequestKeys;
+    sse?: SqliteEntitySseConfig<TFields, TSseEntity, TSseContext>;
+    hydration?: {
+        key: string;
+        hydrate: () => Promise<{
+            rowCount: number;
+        }>;
+    };
+};
+export type SqliteEntityBundle<TFields extends SqliteEntityFields, TOperationNames extends {
+    replace: string;
+    upsert: string;
+    list: string;
+    delete: string;
+}, TRequestKeys extends {
+    replace: string;
+    upsert: string;
+    delete: string;
+}, TSseEntity extends string, TSseContext extends object> = {
+    __sqliteEntityBundle: true;
+    fields: TFields;
+    operationNames: TOperationNames;
+    requestKeys: TRequestKeys;
+    tableName: string;
+    entityNameSingular: string;
+    entityNamePlural: string;
+    hydration?: {
+        key: string;
+        hydrate: () => Promise<{
+            rowCount: number;
+        }>;
+    };
+    replaceRows: (db: SqliteDatabase, rows: SqliteEntityRecordFromFields<TFields>[]) => void;
+    upsertRow: (db: SqliteDatabase, row: SqliteEntityRecordFromFields<TFields>) => void;
+    listRows: (db: SqliteDatabase) => SqliteEntityRecordFromFields<TFields>[];
+    deleteRows: (db: SqliteDatabase, keys: Array<number | string>) => void;
+    sse?: SqliteEntitySseConfig<TFields, TSseEntity, TSseContext>;
+    requestHandlers: SqliteRequestHandlers;
+    operationMap: {
+        [TReplace in TOperationNames["replace"]]: {
+            request: {
+                [TReplaceKey in TRequestKeys["replace"]]: SqliteEntityRecordFromFields<TFields>[];
+            };
+            response: null;
+        };
+    } & {
+        [TUpsert in TOperationNames["upsert"]]: {
+            request: {
+                [TUpsertKey in TRequestKeys["upsert"]]: SqliteEntityRecordFromFields<TFields>;
+            };
+            response: null;
+        };
+    } & {
+        [TList in TOperationNames["list"]]: {
+            request: {};
+            response: SqliteEntityRecordFromFields<TFields>[];
+        };
+    } & {
+        [TDelete in TOperationNames["delete"]]: {
+            request: {
+                [TDeleteKey in TRequestKeys["delete"]]: Array<number | string>;
+            };
+            response: null;
+        };
+    };
+};
+export type SqliteEntityOperationMapFromBundle<TBundle extends {
+    operationMap: Record<string, {
+        request: unknown;
+        response: unknown;
+    }>;
+}> = TBundle["operationMap"];
+export type SqliteEntityRecordFromBundle<TBundle> = TBundle extends {
+    upsertRow: (...args: infer TArgs) => void;
+} ? TArgs extends [SqliteDatabase, infer TRow] ? TRow : never : never;
+export declare function createSqliteEntityBundle<const TFields extends SqliteEntityFields, const TSingular extends string, const TPlural extends string, const TRequestKeys extends {
+    replace: string;
+    upsert: string;
+    delete: string;
+}, const TSseEntity extends string = string, const TSseContext extends object = object>(spec: SqliteEntitySpec<TFields, TSingular, TPlural, TRequestKeys, TSseEntity, TSseContext>): SqliteEntityBundle<TFields, SqliteEntityOperationNames<TSingular, TPlural>, TRequestKeys, TSseEntity, TSseContext>;
+export {};

package/dist/core/sqliteRequestHandlers.d.ts

@@ -0,0 +1,7 @@
+import { SqliteDatabase } from './sqliteTypes';
+import { WorkerRequest, WorkerResponseResult } from './sqliteWorkerProtocol';
+export type SqliteRequestHandler = (db: SqliteDatabase, request: WorkerRequest) => WorkerResponseResult | Promise<WorkerResponseResult>;
+export type SqliteRequestHandlers = Partial<Record<string, SqliteRequestHandler>>;
+export declare function createSqliteRequestHandlers<THandlers extends SqliteRequestHandlers>(handlers: THandlers): THandlers;
+export declare function mergeSqliteRequestHandlers(...handlersList: SqliteRequestHandlers[]): SqliteRequestHandlers;
+export declare function dispatchSqliteRequest(db: SqliteDatabase, request: WorkerRequest, handlers: SqliteRequestHandlers): Promise<WorkerResponseResult | undefined>;

package/dist/core/sqliteRuntime.d.ts

@@ -0,0 +1,7 @@
+import { SqliteDatabase, SqliteMigration } from './sqliteTypes';
+export declare function mapSqliteRuntimeError(error: unknown): string;
+export declare function querySingleNumber(db: SqliteDatabase, sql: string): number;
+export declare function getSchemaVersion(db: SqliteDatabase): number;
+export declare function setSchemaVersion(db: SqliteDatabase, version: number): void;
+export declare function applySqliteMigrations(db: SqliteDatabase, migrations: SqliteMigration[]): void;
+export declare function initializeSqliteDatabase(dbFile: string, migrations: SqliteMigration[]): Promise<SqliteDatabase>;

package/dist/core/sqliteTypes.d.ts

@@ -0,0 +1,12 @@
+export type SqliteStatement = {
+    bind: (value: readonly unknown[]) => SqliteStatement;
+    step: () => boolean;
+    get: (target: unknown[]) => unknown[];
+    getColumnNames?: (target?: string[]) => string[];
+    finalize: () => number | undefined;
+};
+export type SqliteDatabase = {
+    exec: (sql: string) => unknown;
+    prepare: (sql: string) => SqliteStatement;
+};
+export type SqliteMigration = (db: SqliteDatabase) => void;

package/dist/core/sqliteWorkerProtocol.d.ts

@@ -0,0 +1,18 @@
+export type WorkerRequest = {
+    id: number;
+    type: string;
+    [key: string]: unknown;
+};
+export type WorkerRequestInput = Omit<WorkerRequest, "id">;
+export type WorkerResponse = {
+    id: number;
+    ok: false;
+    error: string;
+} | {
+    id: number;
+    ok: true;
+    result: unknown;
+};
+export type WorkerResponseResult = Extract<WorkerResponse, {
+    ok: true;
+}>["result"];

package/dist/core/sqliteWorkerRuntime.d.ts

@@ -0,0 +1,19 @@
+import { SqliteRequestHandlers } from './sqliteRequestHandlers';
+import { SqliteMigration } from './sqliteTypes';
+import { WorkerRequest } from './sqliteWorkerProtocol';
+type WorkerLike = {
+    addEventListener: (type: "message", listener: (event: MessageEvent<unknown>) => void | Promise<void>) => void;
+    postMessage: (message: unknown) => void;
+};
+export type SqliteWorkerRuntimeConfig = {
+    dbFile: string;
+    migrations: SqliteMigration[];
+    requestHandlers: SqliteRequestHandlers;
+    debug?: boolean;
+    bootLogPrefix?: string;
+};
+export declare function createSqliteWorkerRuntime(config: SqliteWorkerRuntimeConfig): {
+    attach: (worker: WorkerLike) => void;
+    handleRequest: (worker: WorkerLike, request: WorkerRequest) => Promise<void>;
+};
+export {};

package/dist/devtools/createSqlConsoleClient.d.ts

@@ -0,0 +1,20 @@
+import { SqliteTransport } from '../runtime/createSqliteTransport';
+import { SqlExecutionResult, SqlPagedQueryRequest, SqlPagedQueryResult } from '../runtime/contracts';
+export type SqlConsoleClient = {
+    executeScript: (script: string) => Promise<SqlExecutionResult>;
+    executePagedQuery: (request: SqlPagedQueryRequest) => Promise<SqlPagedQueryResult>;
+};
+export type CreateSqlConsoleClientConfig = {
+    runtime: {
+        shouldUseInMemoryFallback: () => boolean;
+    };
+    transport: Pick<SqliteTransport, "sendWorkerRequest">;
+    requestTypes?: {
+        executeScript: string;
+        executePagedQuery: string;
+    };
+    now?: () => number;
+    log?: (message: string, ...details: unknown[]) => void;
+    createUnavailableError?: (operation: "script" | "paged-query") => Error;
+};
+export declare function createSqlConsoleClient(config: CreateSqlConsoleClientConfig): SqlConsoleClient;

package/dist/hydration/createHydrationContributorRegistry.d.ts

@@ -0,0 +1,11 @@
+export type HydrationContributor = {
+    key: string;
+    hydrate: (signal: AbortSignal) => Promise<{
+        rowCount: number;
+    }>;
+};
+export type HydrationContributorRegistry = {
+    register: (contributors: HydrationContributor[]) => void;
+    list: () => HydrationContributor[];
+};
+export declare function createHydrationContributorRegistry(): HydrationContributorRegistry;

package/dist/hydration/createHydrationController.d.ts

@@ -0,0 +1,60 @@
+import { HydrationContributor } from './createHydrationContributorRegistry';
+import { HydrationRequestQueue } from './createHydrationRequestQueue';
+import { SqliteHydrationEntityStateRecord } from '../runtime/contracts';
+export type RemoteHydrationVersion = {
+    entity: string;
+    revision: number;
+};
+export type HydrationRunContext = {
+    heartbeatEnabled?: boolean;
+    heartbeatConnected?: boolean;
+};
+export type HydrationLogDetails = Record<string, unknown>;
+export type HydrationControllerEvents = {
+    registerEntities: (keys: string[]) => void;
+    markRunning: (running: boolean) => void;
+    markEntityRunning: (key: string) => void;
+    markEntitySuccess: (key: string, rowCount: number) => void;
+    markEntityError: (key: string, message: string) => void;
+    startGate: () => void;
+    resetGate: () => void;
+    finishGate: () => void;
+    markDataReady: () => void;
+    setErrorMessage: (message: string | null) => void;
+};
+export type CreateHydrationControllerConfig<TLockOwner = unknown> = {
+    getContributors: () => HydrationContributor[];
+    entityStateClient: {
+        list: () => Promise<SqliteHydrationEntityStateRecord[]>;
+        upsert: (state: SqliteHydrationEntityStateRecord) => Promise<void>;
+    };
+    requests: Pick<HydrationRequestQueue, "consume" | "hasPending" | "rejectPending" | "settle" | "reject">;
+    runHydrationExclusive: (operation: (signal: AbortSignal, lockOwner: TLockOwner) => Promise<void>) => Promise<void>;
+    runEntityExclusive: (entityKey: string, operation: () => Promise<void>, lockOwner: TLockOwner) => Promise<void>;
+    fetchRemoteVersions: (entityKeys: string[], signal: AbortSignal) => Promise<{
+        versions: RemoteHydrationVersion[];
+    }>;
+    events: HydrationControllerEvents;
+    remoteVersionsTimeoutMs: number;
+    entityTimeoutMs: (entityKey: string) => number;
+    retryBaseMs: number;
+    retryMaxMs: number;
+    retryExponentLimit?: number;
+    elapsedNow?: () => number;
+    timestampNow?: () => number;
+    schedule?: (callback: () => void, delayMs: number) => ReturnType<typeof setTimeout>;
+    cancelScheduled?: (handle: ReturnType<typeof setTimeout>) => void;
+    isCancellationError?: (error: unknown) => boolean;
+    debug?: (message: string, details?: HydrationLogDetails) => void;
+    warn?: (message: string, details?: HydrationLogDetails) => void;
+    error?: (message: string, details?: HydrationLogDetails) => void;
+};
+export type HydrationController = {
+    run: (context?: HydrationRunContext) => Promise<void>;
+    requestRetry: () => void;
+    reset: (pendingRequestReason: string) => void;
+    cancelScheduledRetry: () => void;
+    dispose: () => void;
+    isRunning: () => boolean;
+};
+export declare function createHydrationController<TLockOwner = unknown>(config: CreateHydrationControllerConfig<TLockOwner>): HydrationController;

package/dist/hydration/createHydrationEntityClient.d.ts

@@ -0,0 +1,16 @@
+import { InMemorySqliteStore } from '../runtime/createManagedSqliteRuntime';
+import { SqliteTransport } from '../runtime/createSqliteTransport';
+import { SqliteHydrationEntityStateRecord } from '../runtime/contracts';
+export type HydrationEntityClientRuntime = {
+    shouldUseInMemoryFallback: () => boolean;
+    registerInMemoryStore: (store: InMemorySqliteStore) => () => void;
+};
+export type HydrationEntityClient = {
+    list: () => Promise<SqliteHydrationEntityStateRecord[]>;
+    upsert: (state: SqliteHydrationEntityStateRecord) => Promise<void>;
+    dispose: () => void;
+};
+export declare function createHydrationEntityClient(config: {
+    runtime: HydrationEntityClientRuntime;
+    transport: Pick<SqliteTransport, "sendWorkerRequest">;
+}): HydrationEntityClient;

package/dist/hydration/createHydrationGate.d.ts

@@ -0,0 +1,22 @@
+export type HydrationGatePhase = "idle" | "running" | "finished";
+export type HydrationGateSnapshot = {
+    phase: HydrationGatePhase;
+    startedAt: number | null;
+    dataReady: boolean;
+    errorMessage: string | null;
+    retryRequestTick: number;
+};
+export type HydrationGate = {
+    getSnapshot: () => HydrationGateSnapshot;
+    subscribe: (listener: (snapshot: HydrationGateSnapshot) => void) => () => void;
+    setErrorMessage: (message: string | null) => void;
+    requestRetry: () => void;
+    reset: () => void;
+    start: () => void;
+    finish: () => void;
+    markDataReady: () => void;
+};
+export type CreateHydrationGateConfig = {
+    now?: () => number;
+};
+export declare function createHydrationGate(config?: CreateHydrationGateConfig): HydrationGate;

package/dist/hydration/createHydrationRequestQueue.d.ts

@@ -0,0 +1,22 @@
+export type HydrationRequest = {
+    keys: Set<string>;
+    resolve: () => void;
+    reject: (error: Error) => void;
+};
+export type HydrationRequestBatch = {
+    requests: HydrationRequest[];
+    forcedKeys: Set<string>;
+};
+export type HydrationRequestQueue = {
+    request: (keys: string[]) => Promise<void>;
+    consume: () => HydrationRequestBatch;
+    hasPending: () => boolean;
+    rejectPending: (reason: string) => void;
+    settle: (batch: HydrationRequestBatch, failedKeys: ReadonlySet<string>) => void;
+    reject: (batch: HydrationRequestBatch, error: unknown) => void;
+};
+export type CreateHydrationRequestQueueConfig = {
+    onRequestQueued?: () => void;
+    createUnexpectedError?: () => Error;
+};
+export declare function createHydrationRequestQueue(config?: CreateHydrationRequestQueueConfig): HydrationRequestQueue;

package/dist/hydration/createHydrationStatus.d.ts

@@ -0,0 +1,26 @@
+export type HydrationEntityStatus = {
+    key: string;
+    state: "idle" | "running" | "success" | "error";
+    lastAttemptAt: number | null;
+    lastSuccessAt: number | null;
+    rowCount: number | null;
+    errorMessage: string | null;
+};
+export type HydrationStatusSnapshot = {
+    entities: HydrationEntityStatus[];
+    running: boolean;
+};
+export type HydrationStatus = {
+    getSnapshot: () => HydrationStatusSnapshot;
+    subscribe: (listener: (snapshot: HydrationStatusSnapshot) => void) => () => void;
+    registerEntities: (keys: string[]) => void;
+    markRunning: (running: boolean) => void;
+    markEntityRunning: (key: string) => void;
+    markEntitySuccess: (key: string, rowCount: number) => void;
+    markEntityError: (key: string, errorMessage: string) => void;
+    reset: () => void;
+};
+export type CreateHydrationStatusConfig = {
+    now?: () => number;
+};
+export declare function createHydrationStatus(config?: CreateHydrationStatusConfig): HydrationStatus;

package/dist/hydration/createLocalReflectionQueue.d.ts

@@ -0,0 +1,11 @@
+export type LocalReflectionQueue = {
+    enqueue: (entityKey: string, operation: () => Promise<void>) => void;
+    awaitIdle: () => Promise<void>;
+    getPendingCount: () => number;
+};
+export type CreateLocalReflectionQueueConfig = {
+    runEntityExclusive: (entityKey: string, operation: () => Promise<void>) => Promise<void>;
+    onError?: (entityKey: string, error: unknown) => void;
+    onPendingCountChange?: (pendingCount: number) => void;
+};
+export declare function createLocalReflectionQueue(config: CreateLocalReflectionQueueConfig): LocalReflectionQueue;

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+export { deleteSqliteRowsByKey, listSqliteRows, runSqliteTransaction } from './core/sqliteCrud';
+export * from './core/sqliteEntityFactory';
+export { createSqliteRequestHandlers, dispatchSqliteRequest, mergeSqliteRequestHandlers, } from './core/sqliteRequestHandlers';
+export type { SqliteRequestHandler, SqliteRequestHandlers } from './core/sqliteRequestHandlers';
+export type { SqliteDatabase, SqliteMigration, SqliteStatement } from './core/sqliteTypes';
+export type { WorkerRequest, WorkerRequestInput, WorkerResponse, WorkerResponseResult, } from './core/sqliteWorkerProtocol';
+export * from './concurrency/createSqliteOperationCoordinator';
+export * from './devtools/createSqlConsoleClient';
+export * from './hydration/createHydrationContributorRegistry';
+export * from './hydration/createHydrationController';
+export * from './hydration/createHydrationEntityClient';
+export * from './hydration/createHydrationGate';
+export * from './hydration/createHydrationRequestQueue';
+export * from './hydration/createHydrationStatus';
+export * from './hydration/createLocalReflectionQueue';
+export * from './lifecycle/createDatabaseOwnerStore';
+export * from './lifecycle/createOfflineDataLifecycle';
+export * from './lifecycle/createOpfsDatabaseFiles';
+export * from './offline-queue/createOfflineQueueCapture';
+export * from './offline-queue/createOfflineQueueClient';
+export * from './offline-queue/createOfflineQueueStatus';
+export * from './offline-queue/offlineQueueStateSqlite';
+export * from './offline-queue/replayOfflineSyncBatch';
+export * from './runtime/createManagedSqliteRuntime';
+export * from './runtime/createSqliteEntityClient';
+export * from './runtime/createSqliteTransport';
+export { createSqliteWorkerRuntime, type SqliteWorkerRuntimeConfig } from './core/sqliteWorkerRuntime';
+export { createSqliteWorkerRuntimeConfig } from './sqliteWorkerConfig';
+export { HYDRATION_ENTITY_STATE_SQLITE_REQUEST_HANDLERS, listHydrationEntityStates, upsertHydrationEntityState, type HydrationEntityStateSqliteOperationMap, } from './runtime/hydrationEntityStateSqlite';
+export { executePagedQuery, executeSqlScript, SQL_CONSOLE_SQLITE_REQUEST_HANDLERS, type SqlConsoleSqliteOperationMap, } from './runtime/sqlConsoleSqlite';
+export type { CreateSqliteWorkerRuntimeConfigInput, OfflineSyncCommandRecord, SqlExecutionResult, SqlExecutionStatementResult, SqliteHydrationEntityStateRecord, SqliteWorkerEntityBundleConfig, SqlPagedQueryRequest, SqlPagedQueryResult, } from './runtime/contracts';