@sqlite-sync/core 0.0.1 → 0.0.3

package/dist/crdt-sync-remote-source-idoIjMcs.d.ts

@@ -0,0 +1,479 @@
+import { CompiledQuery, Compilable, Kysely, CreateTableBuilder, CreateIndexBuilder, ColumnDataType, Expression, ColumnDefinitionBuilderCallback } from 'kysely';
+import { Sqlite3Static, Database, SqlValue, FunctionOptions } from '@sqlite.org/sqlite-wasm';
+
+interface HLC {
+    timestamp: number;
+    counter: number;
+    nodeId: string;
+}
+declare class HLCCounter {
+    private timestamp;
+    private counter;
+    private nodeId;
+    private readonly getTimestamp;
+    private readonly maxDrift;
+    constructor(nodeId: string, getTimestamp: () => number, maxDrift?: number);
+    getCurrentHLC(): HLC;
+    getNextHLC(): HLC;
+    mergeHLC(hlc: HLC): void;
+}
+declare function serializeHLC(hlc: HLC): string;
+declare function deserializeHLC(serialized: string): HLC;
+declare function compareHLC(one: HLC, two: HLC): number;
+
+type LogLevel = "info" | "warning" | "error" | "trace" | "system";
+type Logger = (type: string, message: string, level?: LogLevel) => void;
+declare const startPerformanceLogger: (logger: Logger) => {
+    restart: () => void;
+    logEnd: (type: string, message: string, level?: LogLevel) => void;
+};
+
+type ExecuteParams = {
+    sql: string;
+    parameters: readonly unknown[];
+};
+type ExecuteResult<T> = {
+    rows: T[];
+};
+type PreparedStatement<TParams extends SqlValue[], TResult> = {
+    execute: (parameters: TParams) => TResult[];
+    finalize: () => void;
+    isFinalized: boolean;
+};
+type ScalarFunctionOptions<TArgs extends readonly SqlValue[], TResult extends SqlValue | undefined> = {
+    name: string;
+    callback: (...args: TArgs) => TResult;
+} & Pick<FunctionOptions, "deterministic" | "directOnly" | "innocuous">;
+type SqliteWrapperOptions = {
+    logger?: Logger;
+    loggerPrefix?: string;
+    sqlite3: Sqlite3Static;
+    db: () => Database;
+};
+type SQLiteTransactionWrapper<TDatabase = unknown> = Pick<SQLiteDbWrapper<TDatabase>, "execute" | "sql" | "executeKysely" | "prepare" | "executePrepared" | "prepareKysely">;
+type QueryMetaOpts = {
+    loggerLevel?: "info" | "system";
+};
+declare class SQLiteDbWrapper<TDatabase = unknown> {
+    private db;
+    private sqlite3;
+    private logger?;
+    private loggerPrefix?;
+    private loadedDbSchema;
+    private readonly dataPointers;
+    private preparedStatements;
+    private preparedStatementsMap;
+    private preparedRawStatementsMap;
+    constructor(opts: SqliteWrapperOptions);
+    get ensureDb(): Database;
+    get dbSchema(): DatabaseIntrospection;
+    execute<T = unknown>(opts: ExecuteParams | string | CompiledQuery<T>, meta?: QueryMetaOpts): ExecuteResult<T>;
+    executeTransaction<T>(callback: (db: SQLiteTransactionWrapper<TDatabase>) => T): T;
+    isInTransaction(): boolean;
+    beginTransaction(): {
+        commit: () => void;
+        rollback: () => void;
+    };
+    prepare<TParams extends SqlValue[], TResult>(sql: string, opts?: QueryMetaOpts): PreparedStatement<TParams, TResult>;
+    prepareKysely<TParams extends Record<string, unknown>>(opts?: QueryMetaOpts): <TQuery extends Compilable<TResult>, TResult = QueryBuilderOutput<TQuery>>(factory: KyselyStatementFactory<TParams, TDatabase, TQuery, TResult>) => TypedStatement<TParams, TResult>;
+    executeKysely<TQuery extends Compilable<TResult>, TResult = QueryBuilderOutput<TQuery>>(factory: KyselyQueryFactory<TDatabase, TQuery, TResult>, meta?: QueryMetaOpts): ExecuteResult<TResult>;
+    executePrepared<TParams extends Record<string, unknown>, TQuery extends Compilable<TResult>, TResult = QueryBuilderOutput<TQuery>>(key: string, params: TParams, factory: KyselyStatementFactory<TParams, TDatabase, TQuery, TResult>, meta?: QueryMetaOpts): TResult[];
+    executePreparedRaw<TParams extends SqlValue[], TResult>({ key, sql, params, meta, }: {
+        key: string;
+        sql: string;
+        params?: TParams;
+        meta?: QueryMetaOpts;
+    }): TResult[];
+    sql<T = unknown>(templateOrString: TemplateStringsArray | string, ...parameters: unknown[]): ExecuteResult<T>;
+    createScalarFunction<TArgs extends SqlValue[], TResult extends SqlValue | undefined>({ name, callback, deterministic, directOnly, innocuous, }: ScalarFunctionOptions<TArgs, TResult>): Database;
+    useSnapshot(snapshot: Uint8Array<ArrayBufferLike>): void;
+    createSnapshot(): Uint8Array<ArrayBuffer>;
+    invalidateDbSchema(): void;
+    cleanup(): void;
+    close(): void;
+}
+type QueryBuilderOutput<QB> = QB extends Compilable<infer O> ? O : never;
+type ParamsGetter<TParams> = <TKey extends keyof TParams>(key: TKey) => TParams[TKey];
+type TypedStatement<TParams extends Record<string, unknown>, TResult> = {
+    execute: (parameters: TParams) => TResult[];
+};
+type KyselyStatementFactory<TParams extends Record<string, unknown>, TDatabase, TQuery extends Compilable<TResult>, TResult = QueryBuilderOutput<TQuery>> = (kysely: Kysely<TDatabase>, params: ParamsGetter<TParams>) => TQuery;
+type KyselyQueryFactory<TDatabase, TQuery extends Compilable<TResult>, TResult = QueryBuilderOutput<TQuery>> = (kysely: Kysely<TDatabase>) => TQuery;
+
+type TableMetadata = {
+    name: string;
+    isView: boolean;
+    columns: ColumnMetadata[];
+};
+type DatabaseIntrospection = Record<string, TableMetadata>;
+type ColumnMetadata = {
+    name: string;
+    dataType: string;
+    isNullable: boolean;
+    isAutoIncrementing: boolean;
+    hasDefaultValue: boolean;
+    comment: undefined;
+};
+declare function introspectDb<BaseDatabase>(_db: SQLiteDbWrapper<BaseDatabase>): DatabaseIntrospection;
+
+type DeferredPromise<T> = {
+    promise: Promise<T>;
+    resolve: (value: T) => void;
+    reject: (error: Error) => void;
+};
+declare function createDeferredPromise<T>(opts?: {
+    timeout?: number;
+    onTimeout?: () => void;
+}): DeferredPromise<T>;
+declare const generateId: () => `${string}-${string}-${string}-${string}-${string}`;
+type DistributiveOmit<T, K extends keyof T> = T extends any ? Omit<T, K> : never;
+declare class TypedBroadcastChannel<TMessage> {
+    private readonly channel;
+    constructor(name: string);
+    postMessage(message: TMessage): void;
+    set onmessage(callback: ((event: MessageEvent<TMessage>) => void) | null);
+    close(): void;
+}
+declare class TypedEvent<T = unknown> extends Event {
+    readonly payload: T;
+    constructor(type: string, payload: T);
+}
+type TypedEventTarget<T extends Record<string, unknown>> = {
+    addEventListener: <K extends keyof T & string>(type: K, listener: (event: TypedEvent<T[K]>) => void) => void;
+    removeEventListener: <K extends keyof T & string>(type: K, listener: (event: TypedEvent<T[K]>) => void) => void;
+    dispatchEvent: <K extends keyof T & string>(type: K, payload: T[K]) => void;
+};
+declare const createTypedEventTarget: <T extends Record<string, unknown>>() => TypedEventTarget<T>;
+type TryCatchResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: unknown;
+};
+declare function tryCatch<T>(fn: () => T): TryCatchResult<T>;
+declare function tryCatchAsync<T>(fn: () => Promise<T>): Promise<TryCatchResult<T>>;
+declare function jsonSafeParse<T>(json: string): TryCatchResult<T>;
+/** Quote a SQLite identifier (table/column name), handling dot-separated schema qualifiers. */
+declare function quoteId(name: string): string;
+
+type CrdtEventType = "item-created" | "item-updated";
+type CrdtEventStatus = "pending" | "applied" | "failed" | "skipped";
+type CrdtEventOrigin = "remote" | "own" | "local";
+type PersistedCrdtEvent = {
+    schema_version: number;
+    sync_id: number;
+    status: CrdtEventStatus;
+    type: CrdtEventType;
+    timestamp: string;
+    origin: CrdtEventOrigin;
+    source_node_id: string;
+    dataset: string;
+    item_id: string;
+    payload: string;
+};
+type CrdtUpdateLogItem = {
+    dataset: string;
+    item_id: string;
+    payload: string;
+};
+type CrdtUpdateLogPayload = Record<string, string>;
+
+type StoredValue<T> = {
+    get current(): T;
+    set current(newValue: T);
+};
+declare function createStoredValue<T>({ initialValue, saveToStorage, }: {
+    initialValue: T;
+    saveToStorage?: (value: T) => void;
+}): StoredValue<T>;
+
+type CrdtEvent = {
+    type: CrdtEventType;
+    dataset: string;
+    item_id: string;
+    payload: Record<string, unknown>;
+};
+type MigratableEvent = {
+    schema_version: number;
+    type: CrdtEventType;
+    dataset: string;
+    item_id: string;
+    payload: string;
+};
+type CrdtEventTransformer = (event: CrdtEvent) => CrdtEvent | null;
+type MigrationStepSql = {
+    sql: string;
+    parameters?: readonly unknown[];
+} | Compilable | ((db: Kysely<unknown>) => Compilable);
+type TableRename = {
+    oldTable: string;
+    newTable: string;
+};
+type MigrationStep = {
+    sql: MigrationStepSql | MigrationStepSql[];
+    eventTransformer?: MigrationEventTransformers;
+    tableRenames?: TableRename[];
+    tableDrops?: string[];
+};
+type RawMigrationStep = {
+    sql: MigrationSql[];
+    eventTransformer?: CompiledMigrationEventTransformer;
+    tableRenames?: TableRename[];
+    tableDrops?: string[];
+};
+type MigrationSql = {
+    sql: string;
+    parameters: readonly unknown[];
+};
+type DataTypeExpression = ColumnDataType | Expression<any>;
+declare const migrationSteps: {
+    createTable: (table: string, build: (table: CreateTableBuilder<string, never>) => Compilable) => MigrationStep;
+    dropTable: (table: string) => MigrationStep;
+    createIndex: (indexName: string, build: (index: CreateIndexBuilder) => Compilable) => MigrationStep;
+    dropIndex: (indexName: string) => MigrationStep;
+    renameTable: ({ oldTable, newTable }: {
+        oldTable: string;
+        newTable: string;
+    }) => MigrationStep;
+    renameColumn: ({ table, oldColumn, newColumn, }: {
+        table: string;
+        oldColumn: string;
+        newColumn: string;
+    }) => MigrationStep;
+    addColumn: ({ table, column, type, defaultValue, build, }: {
+        table: string;
+        column: string;
+        type: DataTypeExpression;
+        defaultValue: number | boolean | string | null;
+        build?: ColumnDefinitionBuilderCallback;
+    }) => MigrationStep;
+    dropColumn: ({ table, column }: {
+        table: string;
+        column: string;
+    }) => MigrationStep;
+};
+type MigrationEventTransformers = Record<string, CrdtEventTransformer>;
+type CompiledMigrationEventTransformer = (event: CrdtEvent) => CrdtEvent | null;
+declare function createMigrations(buildMigrations: (builder: typeof migrationSteps) => Record<number, MigrationStep[]>): Record<number, RawMigrationStep>;
+type Migrations = ReturnType<typeof createMigrations>;
+type MigrationsDb = {
+    startTransaction: (callback: (tx: MigrationsTransaction) => void) => void;
+};
+type MigrationsTransaction = {
+    execute: (sql: string, parameters: readonly unknown[]) => void;
+};
+declare function createMigrator({ migrations, schemaVersion, updateLogTableName, }: {
+    migrations: Migrations;
+    schemaVersion: StoredValue<number>;
+    updateLogTableName?: string;
+}): {
+    latestSchemaVersion: number;
+    readonly currentSchemaVersion: number;
+    migrateDbToLatest: (db: MigrationsDb) => void;
+    migrateEvent: <Event extends MigratableEvent>(event: Event, targetVersion?: number) => Event | null;
+    migrateEvents: <Event extends MigratableEvent>(events: Event[], targetVersion?: number) => Event[];
+};
+type SyncDbMigrator = ReturnType<typeof createMigrator>;
+
+type PendingCrdtEvent = {
+    type: CrdtEventType;
+    dataset: string;
+    item_id: string;
+    timestamp: string;
+    payload: string;
+};
+declare const createSQLiteCrdtApplyFunction: ({ db, updateLogTableName, }: {
+    db: SQLiteTransactionWrapper<any>;
+    updateLogTableName: string;
+}) => (event: PendingCrdtEvent) => void;
+type CreateCrdtApplyOpts = {
+    getCrdtUpdateLog: (opts: {
+        itemId: string;
+        dataset: string;
+    }) => CrdtUpdateLogPayload | null;
+    insertItem: (opts: {
+        dataset: string;
+        payload: Record<string, unknown>;
+    }) => void;
+    insertCrdtUpdateLog: (opts: {
+        dataset: string;
+        itemId: string;
+        payload: string;
+    }) => void;
+    updateItem: (opts: {
+        dataset: string;
+        itemId: string;
+        payload: Record<string, unknown>;
+    }) => void;
+    updateCrdtUpdateLog: (opts: {
+        dataset: string;
+        itemId: string;
+        payload: string;
+    }) => void;
+};
+declare function createCrdtApplyFunction({ getCrdtUpdateLog, insertItem, insertCrdtUpdateLog, updateItem, updateCrdtUpdateLog, }: CreateCrdtApplyOpts): (event: PendingCrdtEvent) => void;
+
+type LocalCrdtEvent = {
+    type: CrdtEventType;
+    dataset: string;
+    item_id: string;
+    payload: string;
+    timestamp: string;
+    schema_version: number;
+};
+type OwnCrdtEvent = {
+    type: CrdtEventType;
+    dataset: string;
+    item_id: string;
+    payload: string;
+    timestamp?: undefined;
+    schema_version?: undefined;
+};
+type RemoteCrdtEvent = {
+    type: CrdtEventType;
+    dataset: string;
+    item_id: string;
+    payload: string;
+    timestamp: string;
+    schema_version: number;
+};
+type GetEventsOptions = {
+    afterSyncId?: number;
+    status?: CrdtEventStatus;
+    excludeOrigin?: string;
+    excludeNodeId?: string;
+    limit?: number;
+};
+type GetEventsBatch = {
+    events: PersistedCrdtEvent[];
+    hasMore: boolean;
+    nextSyncId: number;
+};
+type EventUpdate = {
+    status: CrdtEventStatus;
+    schema_version: number;
+    type: CrdtEventType;
+    dataset: string;
+    item_id: string;
+    payload: string;
+};
+type StorageHLC = Pick<HLCCounter, "getNextHLC" | "mergeHLC">;
+type DbSyncerStorage = {
+    nodeId: string;
+    syncId: StoredValue<number>;
+    migrator: SyncDbMigrator;
+    persistEvent: (events: PersistedCrdtEvent) => void;
+    getEventsBatch: (options: GetEventsOptions) => PersistedCrdtEvent[];
+    updateEvent: (syncId: number, update: EventUpdate) => void;
+    handleCrdtEventApply: (event: PersistedCrdtEvent) => void;
+    hlc: StorageHLC;
+    transaction?: (callback: () => void) => void;
+};
+type CrdtStorage = ReturnType<typeof createCrdtStorage>;
+type EventsAppliedPayload = {
+    syncId: number;
+};
+declare function createCrdtStorage(storage: DbSyncerStorage): {
+    getEventsBatch: (options: GetEventsOptions) => GetEventsBatch;
+    enqueueLocalEvents: (events: LocalCrdtEvent[], sourceNodeId: string) => void;
+    enqueueOwnEvents: (events: OwnCrdtEvent[]) => void;
+    enqueueRemoteEvents: (events: RemoteCrdtEvent[]) => void;
+    applyOwnEvent: (event: OwnCrdtEvent, { wrapInTransaction }?: {
+        wrapInTransaction?: boolean;
+    }) => void;
+    dispatchEventsApplied: () => void;
+    addEventListener: <K extends "events-applied">(type: K, listener: (event: TypedEvent<{
+        "events-applied": EventsAppliedPayload;
+    }[K]>) => void) => void;
+    removeEventListener: <K extends "events-applied">(type: K, listener: (event: TypedEvent<{
+        "events-applied": EventsAppliedPayload;
+    }[K]>) => void) => void;
+};
+
+type WorkerState = {
+    remoteState: "online" | "offline" | "pending";
+};
+type EventsPullResponse = {
+    events: {
+        schema_version: number;
+        type: CrdtEventType;
+        timestamp: string;
+        dataset: string;
+        item_id: string;
+        payload: string;
+    }[];
+    hasMore: boolean;
+    nextSyncId: number;
+};
+type WorkerConfig<Props = any> = {
+    dbId: string;
+    clientId: string;
+    clearOnInit?: boolean;
+    props: Props;
+};
+
+type CrdtSyncRemoteSourceConfig = {
+    bufferSize: number;
+    storage: CrdtStorage;
+    migrator: SyncDbMigrator;
+    pullSyncId: StoredValue<number>;
+    pushSyncId: StoredValue<number>;
+    nodeId: string;
+    remoteFactory?: CreateRemoteSourceFactory;
+};
+type EventsPullRequest = {
+    afterSyncId: number;
+    excludeNodeId?: string;
+};
+type EventsPushRequest = {
+    nodeId: string;
+    events: (PendingCrdtEvent & {
+        schema_version: number;
+    })[];
+};
+type EventsPushResponse = {
+    ok: boolean;
+};
+type CrdtSyncRemoteSource = ReturnType<typeof createCrdtSyncRemoteSource>;
+type CreateRemoteSourceFactory = (opts: {
+    onEventsAvailable: (newSyncId: number) => void;
+}) => RemoteSource | Promise<RemoteSource>;
+type RemoteSource = {
+    pullEvents: (request: EventsPullRequest) => Promise<EventsPullResponse>;
+    pushEvents: (request: EventsPushRequest) => Promise<EventsPushResponse>;
+    disconnect?: () => void | Promise<void>;
+};
+type RemoteSourceState = {
+    type: "pending";
+} | {
+    type: "offline";
+    reason: OfflineReason;
+} | {
+    type: "online";
+    source: RemoteSource;
+};
+type OfflineReason = "NOT_INITIALIZED" | "INITIALIZATION_FAILED" | "REMOTE_PUSH_ERROR" | "REMOTE_PULL_ERROR" | "DISCONNECTED";
+declare const createCrdtSyncRemoteSource: ({ bufferSize, storage, migrator, pullSyncId, pushSyncId, nodeId, remoteFactory, }: CrdtSyncRemoteSourceConfig) => {
+    goOnline: () => Promise<void>;
+    goOffline: {
+        (reason: OfflineReason): Promise<void>;
+        promise(): Promise<void> | null;
+        isExecuting(): boolean;
+    };
+    syncWithRemote: {
+        (): Promise<void>;
+        promise(): Promise<void> | null;
+        isExecuting(): boolean;
+    };
+    getState: () => "pending" | "offline" | "online";
+    dispose: () => Promise<void>;
+    addEventListener: <K extends "state-changed">(type: K, listener: (event: TypedEvent<{
+        "state-changed": RemoteSourceState["type"];
+    }[K]>) => void) => void;
+    removeEventListener: <K extends "state-changed">(type: K, listener: (event: TypedEvent<{
+        "state-changed": RemoteSourceState["type"];
+    }[K]>) => void) => void;
+};
+
+export { type TypedEventTarget as $, type CrdtEventStatus as A, type CrdtEventType as B, type CrdtStorage as C, type DatabaseIntrospection as D, type ExecuteParams as E, type CrdtUpdateLogItem as F, type GetEventsOptions as G, type HLC as H, type CrdtUpdateLogPayload as I, createStoredValue as J, type KyselyQueryFactory as K, type Logger as L, type MigratableEvent as M, type PreparedStatement as N, createDeferredPromise as O, type PersistedCrdtEvent as P, type QueryBuilderOutput as Q, createTypedEventTarget as R, SQLiteDbWrapper as S, TypedEvent as T, type DeferredPromise as U, type DistributiveOmit as V, type WorkerState as W, generateId as X, jsonSafeParse as Y, quoteId as Z, TypedBroadcastChannel as _, type SQLiteTransactionWrapper as a, tryCatch as a0, tryCatchAsync as a1, type WorkerConfig as a2, type CreateRemoteSourceFactory as a3, type GetEventsBatch as a4, type EventsPullResponse as a5, type StoredValue as b, type ExecuteResult as c, compareHLC as d, deserializeHLC as e, HLCCounter as f, type TableMetadata as g, type LogLevel as h, introspectDb as i, startPerformanceLogger as j, createMigrations as k, createMigrator as l, type Migrations as m, type MigrationsDb as n, type SyncDbMigrator as o, createCrdtApplyFunction as p, createSQLiteCrdtApplyFunction as q, type PendingCrdtEvent as r, serializeHLC as s, createCrdtStorage as t, type CrdtSyncRemoteSource as u, createCrdtSyncRemoteSource as v, type EventsPullRequest as w, type EventsPushRequest as x, type EventsPushResponse as y, type CrdtEventOrigin as z };