@sqlite-sync/core 0.6.0 → 0.7.1

package/dist/index.d.ts

@@ -1,13 +1,63 @@
 import * as kysely from 'kysely';
 import { Kysely, SchemaModule } from 'kysely';
-import { S as SQLiteDbWrapper, L as Logger, T as TypedEvent, I as InternalSQLiteWrapper, a as StoredValue, C as CrdtStorage, E as ExecuteParams, b as ExecuteResult, Q as QueryBuilderOutput, K as KyselyQueryFactory, c as SQLiteTransactionWrapper, W as WorkerState, D as DeSyncDetectedReason } from './crdt-sync-remote-source-CJrVzW-B.js';
-export { R as CRDT_EVENT_NO_OP_PAYLOAD, U as CrdtEventOrigin, V as CrdtEventStatus, X as CrdtEventType, F as CrdtSyncRemoteSource, Y as CrdtUpdateLogItem, Z as CrdtUpdateLogPayload, g as DatabaseIntrospection, a5 as DeferredPromise, a6 as DistributiveOmit, J as EventsPullRequest, N as EventsPushRequest, O as EventsPushResponse, H as HLC, f as HLCCounter, a1 as KyselyStatementFactory, j as LogLevel, M as MigratableEvent, n as Migrations, o as MigrationsDb, P as PendingCrdtEvent, $ as PersistedCrdtEvent, a2 as PreparedStatement, p as SyncDbMigrator, w as SystemDbConfig, x as SystemMigration, y as SystemMigrationContext, h as TableMetadata, aa as TypedBroadcastChannel, ab as TypedEventTarget, ae as WorkerConfig, af as WorkerNotificationMessage, q as applyMemoryDbSchema, r as applyWorkerDbSchema, t as baseSystemMigrations, d as compareHLC, z as createCrdtApplyFunction, B as createCrdtStorage, G as createCrdtSyncRemoteSource, a3 as createDeferredPromise, l as createMigrations, m as createMigrator, A as createSQLiteCrdtApplyFunction, a0 as createStoredValue, u as createSystemDbConfig, a4 as createTypedEventTarget, e as deserializeHLC, a7 as generateId, i as introspectDb, _ as isNoOpCrdtEventPayload, a8 as jsonSafeParse, a9 as quoteId, v as runSystemMigrations, s as serializeHLC, k as startPerformanceLogger, ac as tryCatch, ad as tryCatchAsync } from './crdt-sync-remote-source-CJrVzW-B.js';
-import { S as SyncDbSchema, C as CrdtTableConfig } from './reset-state-Comk7IC0.js';
-export { a as CreateCrdtSchemaOptions, R as RESET_REQUEST_TTL_MS, b as ResetRequest, d as ResetStore, c as createSyncDbSchema } from './reset-state-Comk7IC0.js';
+import { I as InternalSQLiteWrapper, S as StoredValue, E as ExecuteResult, C as CrdtStorage, a as CrdtTableConfig, b as SQLiteDbWrapper, L as Logger, T as TypedEvent, c as SyncSchemaTables, d as SyncDbSchema, A as AnyTableBuilder, e as TableBuilder, f as TableColumns, g as InferRow, R as ReadonlyTable, M as Migrations, N as NewCrdtEvent, h as ExecuteParams, Q as QueryBuilderOutput, K as KyselyQueryFactory, i as SQLiteTransactionWrapper, W as WorkerState, D as DeSyncDetectedReason } from './crdt-sync-remote-source-yXp-iMEd.js';
+export { U as AnyColumnBuilder, ab as CRDT_EVENT_NO_OP_PAYLOAD, V as ColumnBuilder, X as ColumnKind, Y as ColumnMeta, m as ColumnMetadata, ac as CrdtEventOrigin, ad as CrdtEventStatus, ae as CrdtEventType, a6 as CrdtSyncRemoteSource, af as CrdtUpdateLogItem, ag as CrdtUpdateLogPayload, n as DatabaseIntrospection, ao as DeferredPromise, ap as DistributiveOmit, a8 as EventsPullRequest, a9 as EventsPushRequest, aa as EventsPushResponse, H as HLC, l as HLCCounter, ak as KyselyStatementFactory, q as LogLevel, v as MigratableEvent, w as MigrationsDb, a5 as OwnCrdtEvent, Z as PayloadValidationResult, a3 as PendingCrdtEvent, ai as PersistedCrdtEvent, al as PreparedStatement, _ as SqliteStorageType, x as SyncDbMigrator, J as SystemDbConfig, O as SystemMigration, P as SystemMigrationContext, p as TableMetadata, $ as TableOptions, at as TypedBroadcastChannel, au as TypedEventTarget, ax as WorkerConfig, ay as WorkerNotificationMessage, y as applyMemoryDbSchema, z as applyWorkerDbSchema, B as baseSystemMigrations, j as compareHLC, a1 as createCrdtApplyFunction, a4 as createCrdtStorage, a7 as createCrdtSyncRemoteSource, am as createDeferredPromise, t as createMigrations, u as createMigrator, a2 as createSQLiteCrdtApplyFunction, aj as createStoredValue, F as createSystemDbConfig, an as createTypedEventTarget, k as deserializeHLC, aq as generateId, o as introspectDb, ah as isNoOpCrdtEventPayload, ar as jsonSafeParse, as as quoteId, G as runSystemMigrations, s as serializeHLC, r as startPerformanceLogger, a0 as t, av as tryCatch, aw as tryCatchAsync } from './crdt-sync-remote-source-yXp-iMEd.js';
+export { R as RESET_REQUEST_TTL_MS, a as ResetRequest, b as ResetStore } from './reset-state-D6UslXaj.js';
 import '@sqlite.org/sqlite-wasm';
 
 declare const dummyKysely: Kysely<any>;
 
+type KvStoreItem = {
+    key: string;
+    value: string;
+};
+declare function createKvStoreTableQuery(schema: SchemaModule, tableName: string): kysely.CreateTableBuilder<string, "value" | "key">;
+declare function createSQLiteKvStore({ db, metaTableName }: {
+    db: InternalSQLiteWrapper<any>;
+    metaTableName: string;
+}): {
+    get: (key: string) => string | null;
+    set: (key: string, value: string) => void;
+    remove: (key: string) => void;
+    createStringStoredValue: (key: string, defaultValue: string) => StoredValue<string>;
+    createNumberStoredValue: (key: string, defaultValue: number) => StoredValue<number>;
+};
+
+/**
+ * A portable, schema-version-aware dump of every active entity in a synced DB.
+ * Unlike a raw SQLite snapshot, it carries no event history — just the current
+ * `tombstone = 0` rows, ready to be replayed as fresh create events on import.
+ */
+type SyncedDbExport = {
+    schemaVersion: number;
+    exportedAt: string;
+    /** crdt table name -> active rows (each includes `id`, excludes `tombstone`). */
+    tables: Record<string, Array<Record<string, unknown>>>;
+};
+type ExportImportReactiveDb = {
+    db: {
+        execute<T>(sql: string, meta: {
+            loggerLevel: "system";
+        }): ExecuteResult<T>;
+    };
+};
+type CreateExportImportOptions = {
+    reactiveDb: ExportImportReactiveDb;
+    crdtStorage: CrdtStorage;
+    tablesConfig: CrdtTableConfig[];
+    schemaVersion: number;
+};
+declare function createExportImport({ reactiveDb, crdtStorage, tablesConfig, schemaVersion, }: CreateExportImportOptions): {
+    exportData: (opts?: {
+        tables?: string[];
+    }) => SyncedDbExport;
+    importData: (data: SyncedDbExport, opts?: {
+        validate?: boolean;
+    }) => {
+        imported: number;
+    };
+};
+
 declare function ensureLoaded(): Promise<void>;
 declare function h64(input: string, seed?: bigint): bigint;
 declare const xxhash: {
@@ -90,21 +140,71 @@ declare class SQLiteReactiveDb<Database> {
 }
 declare function parametersAreEqual(a: readonly unknown[] | undefined, b: readonly unknown[] | undefined): boolean;
 
-type KvStoreItem = {
-    key: string;
-    value: string;
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type RowOf<Table extends AnyTableBuilder> = Table extends TableBuilder<infer Cols extends TableColumns, any> ? InferRow<Cols> : never;
+type BaseNameOf<CrdtName, Table extends AnyTableBuilder> = string extends Table["~baseName"] ? `_${CrdtName & string}` : [Table["~baseName"]] extends [string] ? Table["~baseName"] : `_${CrdtName & string}`;
+type ClientSchemaOf<Tables extends SyncSchemaTables> = Simplify<{
+    [K in keyof Tables]: RowOf<Tables[K]>;
+} & {
+    [K in keyof Tables as BaseNameOf<K, Tables[K]>]: ReadonlyTable<RowOf<Tables[K]>>;
+}>;
+type ServerSchemaOf<Tables extends SyncSchemaTables> = Simplify<{
+    [K in keyof Tables]: ReadonlyTable<RowOf<Tables[K]>>;
+} & {
+    [K in keyof Tables as BaseNameOf<K, Tables[K]>]: ReadonlyTable<RowOf<Tables[K]>>;
+}>;
+type MutationsSchemaOf<Tables extends SyncSchemaTables> = Simplify<{
+    [K in keyof Tables as BaseNameOf<K, Tables[K]>]: RowOf<Tables[K]>;
+}>;
+interface DefinedSyncSchema<Tables extends SyncSchemaTables> extends SyncDbSchema<ClientSchemaOf<Tables>, ServerSchemaOf<Tables>, MutationsSchemaOf<Tables>> {
+    /** The table builders, for type extraction (`typeof schema.tables.item.$row`) and runtime metadata. */
+    tables: Tables;
+}
+type DefineSyncSchemaConfig<Tables extends SyncSchemaTables> = {
+    tables: Tables;
+    /** Full migration history (including the initial createTable version), built with `createMigrations`. */
+    migrations: Migrations;
 };
-declare function createKvStoreTableQuery(schema: SchemaModule, tableName: string): kysely.CreateTableBuilder<string, "key" | "value">;
-declare function createSQLiteKvStore({ db, metaTableName }: {
-    db: InternalSQLiteWrapper<any>;
-    metaTableName: string;
-}): {
-    get: (key: string) => string | null;
-    set: (key: string, value: string) => void;
-    remove: (key: string) => void;
-    createStringStoredValue: (key: string, defaultValue: string) => StoredValue<string>;
-    createNumberStoredValue: (key: string, defaultValue: number) => StoredValue<number>;
+/**
+ * Define a sync database schema from `t.table()` builders.
+ *
+ * Record keys are the crdt (view) table names; base table names default to the key
+ * prefixed with "_", overridable per table via `t.table(cols, { baseName })`.
+ */
+declare function defineSyncSchema<Tables extends SyncSchemaTables>({ tables, migrations, }: DefineSyncSchemaConfig<Tables>): DefinedSyncSchema<Tables>;
+
+type NewCrdtEventValidationResult = {
+    success: true;
+    event: NewCrdtEvent;
+} | {
+    success: false;
+    errors: string[];
 };
+declare class CrdtEventValidationError extends Error {
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+declare function validateNewCrdtEvent(schema: Pick<SyncDbSchema, "tables" | "tablesConfig">, input: unknown): NewCrdtEventValidationResult;
+
+type SchemaVerificationIssue = {
+    table: string;
+    column?: string;
+    message: string;
+};
+/**
+ * Verify that replaying the full migration history on a fresh database produces
+ * exactly the declared table schema. Creates a throwaway in-memory SQLite db,
+ * applies all migrations, introspects the result, and diffs it against the
+ * `t.table()` declarations.
+ *
+ * Returns an empty array when migrations and schema agree. Intended for dev-time
+ * checks (`startDbWorker({ verifySchema: true })`) and tests:
+ * `expect(await verifySyncSchema(syncDbSchema)).toEqual([])`.
+ */
+declare function verifySyncSchema(schema: SyncDbSchema): Promise<SchemaVerificationIssue[]>;
+declare function formatSchemaVerificationIssues(issues: SchemaVerificationIssue[]): string;
 
 type CrdtStorageMutator<Database> = ReturnType<typeof createCrdtStorageMutator<Database>>;
 type CommitEventOptions<Database, Table extends keyof Database & string> = {
@@ -222,6 +322,14 @@ declare function createSyncedDb<Database, Props = undefined>(options: SyncedDbOp
     }[K]>) => void) => {
         unsubscribe: () => void;
     };
+    exportData: (opts?: {
+        tables?: string[];
+    }) => SyncedDbExport;
+    importData: (data: SyncedDbExport, opts?: {
+        validate?: boolean;
+    }) => {
+        imported: number;
+    };
     dispose: () => Promise<void>;
     _internal: {
         executeAsync: (query: ExecuteParams) => Promise<ExecuteResult<unknown>>;
@@ -238,4 +346,4 @@ declare function createSyncedDb<Database, Props = undefined>(options: SyncedDbOp
 }>;
 type SyncedDb<Database> = Awaited<ReturnType<typeof createSyncedDb<Database>>>;
 
-export { CrdtStorage, type CrdtStorageMutator, CrdtTableConfig, ExecuteParams, ExecuteResult, InternalSQLiteWrapper, type KvStoreItem, KyselyQueryFactory, Logger, QueryBuilderOutput, SQLiteDbWrapper, SQLiteReactiveDb, SQLiteTransactionWrapper, type SharedLiveQuery, type SharedLiveQuerySnapshot, StoredValue, SyncDbSchema, type SyncedDb, TypedEvent, WorkerState, createCrdtStorageMutator, createCrdtSyncProducer, createKvStoreTableQuery, createSQLiteKvStore, createSyncedDb, dummyKysely, makeCrdtTable, parametersAreEqual, xxhash };
+export { AnyTableBuilder, CrdtEventValidationError, CrdtStorage, type CrdtStorageMutator, CrdtTableConfig, type DefineSyncSchemaConfig, type DefinedSyncSchema, ExecuteParams, ExecuteResult, InferRow, InternalSQLiteWrapper, type KvStoreItem, KyselyQueryFactory, Logger, Migrations, type NewCrdtEventValidationResult, QueryBuilderOutput, ReadonlyTable, SQLiteDbWrapper, SQLiteReactiveDb, SQLiteTransactionWrapper, type SchemaVerificationIssue, type SharedLiveQuery, type SharedLiveQuerySnapshot, StoredValue, SyncDbSchema, SyncSchemaTables, type SyncedDb, type SyncedDbExport, TableBuilder, TableColumns, TypedEvent, WorkerState, createCrdtStorageMutator, createCrdtSyncProducer, createExportImport, createKvStoreTableQuery, createSQLiteKvStore, createSyncedDb, defineSyncSchema, dummyKysely, formatSchemaVerificationIssues, makeCrdtTable, parametersAreEqual, validateNewCrdtEvent, verifySyncSchema, xxhash };