@sqlite-sync/core 0.6.0 → 0.7.1

package/dist/index.js

@@ -1,5 +1,6 @@
 import {
   CRDT_EVENT_NO_OP_PAYLOAD,
+  CrdtEventValidationError,
   HLCCounter,
   RESET_REQUEST_TTL_MS,
   SQLiteDbWrapper,
@@ -21,6 +22,7 @@ import {
   createSystemDbConfig,
   deserializeHLC,
   dummyKysely,
+  formatSchemaVerificationIssues,
   introspectDb,
   isNoOpCrdtEventPayload,
   isWorkerErrorResponseMessage,
@@ -31,8 +33,10 @@ import {
   serializeHLC,
   startPerformanceLogger,
   syncDbClientLockName,
+  validateNewCrdtEvent,
+  verifySyncSchema,
   xxhash
-} from "./chunk-3L4QG3BZ.js";
+} from "./chunk-LBYL5L4O.js";
 import {
   TypedBroadcastChannel,
   TypedEvent,
@@ -46,6 +50,63 @@ import {
   tryCatchAsync
 } from "./chunk-NHT3ELMN.js";
 
+// src/export-import.ts
+function createExportImport({
+  reactiveDb,
+  crdtStorage,
+  tablesConfig,
+  schemaVersion
+}) {
+  const crdtTableNames = tablesConfig.map((config) => config.crdtTableName);
+  const resolveTables = (requested) => {
+    if (!requested) {
+      return crdtTableNames;
+    }
+    for (const name of requested) {
+      if (!crdtTableNames.includes(name)) {
+        throw new Error(`Unknown table "${name}". Known synced tables: ${crdtTableNames.join(", ")}`);
+      }
+    }
+    return requested;
+  };
+  const exportData = (opts) => {
+    const tables = {};
+    for (const crdtTableName of resolveTables(opts?.tables)) {
+      const { rows } = reactiveDb.db.execute(`select * from ${quoteId(crdtTableName)}`, {
+        loggerLevel: "system"
+      });
+      tables[crdtTableName] = rows.map(({ tombstone: _tombstone, ...rest }) => rest);
+    }
+    return {
+      schemaVersion,
+      exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      tables
+    };
+  };
+  const importData = (data, opts) => {
+    const validate = opts?.validate ?? true;
+    if (validate && data.schemaVersion !== schemaVersion) {
+      throw new Error(
+        `Cannot import data from schema version ${data.schemaVersion} into a database at schema version ${schemaVersion}.`
+      );
+    }
+    const events = [];
+    for (const [crdtTableName, rows] of Object.entries(data.tables)) {
+      for (const row of rows) {
+        events.push({
+          type: "item-created",
+          dataset: crdtTableName,
+          item_id: row.id,
+          payload: JSON.stringify(row)
+        });
+      }
+    }
+    crdtStorage.applyOwnEvents(events);
+    return { imported: events.length };
+  };
+  return { exportData, importData };
+}
+
 // src/memory-db/sqlite-reactive-db.ts
 import sqlite3InitModule from "@sqlite.org/sqlite-wasm";
 
@@ -458,45 +519,202 @@ function parametersAreEqual(a, b) {
   return true;
 }
 
-// src/sqlite-crdt/crdt-schema.ts
-function createSyncDbSchema({ migrations }) {
-  return new CrdtSchemaBuilder({ tables: [], migrations });
+// src/schema/define-sync-schema.ts
+function defineSyncSchema({
+  tables,
+  migrations
+}) {
+  const tablesConfig = Object.entries(tables).map(([crdtTableName, table]) => ({
+    crdtTableName,
+    baseTableName: table.baseName ?? `_${crdtTableName}`
+  }));
+  const seenNames = /* @__PURE__ */ new Set();
+  for (const { crdtTableName, baseTableName } of tablesConfig) {
+    for (const name of [crdtTableName, baseTableName]) {
+      if (seenNames.has(name)) {
+        throw new Error(`Duplicate table name "${name}" in sync schema`);
+      }
+      seenNames.add(name);
+    }
+  }
+  return {
+    tables,
+    get tablesConfig() {
+      return tablesConfig;
+    },
+    get migrations() {
+      return migrations;
+    },
+    get "~clientSchema"() {
+      throw new Error("~clientSchema is type-only and cannot be accessed at runtime");
+    },
+    get "~serverSchema"() {
+      throw new Error("~serverSchema is type-only and cannot be accessed at runtime");
+    },
+    get "~mutationsSchema"() {
+      throw new Error("~mutationsSchema is type-only and cannot be accessed at runtime");
+    }
+  };
 }
-var CrdtSchemaBuilder = class _CrdtSchemaBuilder {
-  constructor(config) {
-    this.config = config;
+
+// src/schema/table-builder.ts
+var ColumnBuilder = class _ColumnBuilder {
+  constructor(meta) {
+    this.meta = meta;
   }
-  get tablesConfig() {
-    return this.config.tables;
+  /** Allow SQL NULL; widens the value type with `null`. */
+  nullable() {
+    return new _ColumnBuilder({ ...this.meta, nullable: true });
   }
-  get migrations() {
-    return this.config.migrations;
+  /** Declare a column default. The value is used both in DDL and when migrating older events. */
+  default(value) {
+    return new _ColumnBuilder({ ...this.meta, hasDefault: true, defaultValue: value });
   }
-  get "~clientSchema"() {
-    console.warn("~clientSchema should not be accessed on the client");
-    return null;
+  /** Narrow the TypeScript value type without changing storage, e.g. `t.text().$type<"movie" | "tv">()`. */
+  $type() {
+    return this;
   }
-  get "~serverSchema"() {
-    console.warn("~serverSchema should not be accessed on the server");
-    return null;
+  /** Human/AI-readable description, surfaced in generated schema docs. */
+  describe(description) {
+    return new _ColumnBuilder({ ...this.meta, description });
+  }
+};
+var RESERVED_COLUMNS = ["id", "tombstone"];
+var idColumnMeta = {
+  kind: "text",
+  sqlType: "text",
+  nullable: false,
+  hasDefault: false,
+  description: "Unique immutable item id"
+};
+var tombstoneColumnMeta = {
+  kind: "boolean",
+  sqlType: "integer",
+  nullable: false,
+  hasDefault: true,
+  defaultValue: false,
+  description: "Soft-delete marker"
+};
+var TableBuilder = class _TableBuilder {
+  constructor(userColumns, options) {
+    this.userColumns = userColumns;
+    for (const reserved of RESERVED_COLUMNS) {
+      if (reserved in userColumns) {
+        throw new Error(`Column "${reserved}" is added automatically to every synced table and cannot be declared`);
+      }
+    }
+    this.columns = {
+      id: idColumnMeta,
+      ...Object.fromEntries(Object.entries(userColumns).map(([name, column2]) => [name, column2.meta])),
+      tombstone: tombstoneColumnMeta
+    };
+    this.baseName = options?.baseName;
+    this.description = options?.description;
+  }
+  /** All columns in DDL order, including the auto-injected `id` and `tombstone`. */
+  columns;
+  baseName;
+  description;
+  describe(description) {
+    return new _TableBuilder(this.userColumns, { baseName: this.baseName, description });
   }
-  get "~mutationsSchema"() {
-    console.warn("~mutationsSchema should not be accessed on the client");
+  /** Type-only: the row shape returned by queries. Do not access at runtime. */
+  get $row() {
     return null;
   }
-  addTable() {
-    const withConfig = ({
-      baseTableName,
-      crdtTableName
-    }) => {
-      this.config.tables.push({ baseTableName, crdtTableName });
-      return new _CrdtSchemaBuilder(this.config);
-    };
-    return { withConfig };
+  /**
+   * Validate a CRDT event payload against the declared columns.
+   * `item-created` payloads must contain every column without a default (nullable columns may be omitted);
+   * `item-updated` payloads are partial and must not touch `id` or set `tombstone` to a deleted value.
+   */
+  validatePayload(payload, options) {
+    const event = options?.event ?? "item-created";
+    const errors = [];
+    for (const key of Object.keys(payload)) {
+      if (!(key in this.columns)) {
+        errors.push(`Unknown column "${key}"`);
+      }
+    }
+    if (event === "item-updated") {
+      if ("id" in payload) {
+        errors.push(`Column "id" is immutable and cannot appear in an update payload`);
+      }
+      if (payload.tombstone === true || payload.tombstone === 1) {
+        errors.push(`Column "tombstone" cannot be set to true/1 in an update payload; use an item-deleted event`);
+      }
+    }
+    if (event === "item-created") {
+      for (const [name, meta] of Object.entries(this.columns)) {
+        if (name in payload || name === "tombstone" || meta.nullable || meta.hasDefault) {
+          continue;
+        }
+        errors.push(`Missing required column "${name}"`);
+      }
+    }
+    for (const [name, value] of Object.entries(payload)) {
+      const meta = this.columns[name];
+      if (!meta || event === "item-updated" && name === "id") {
+        continue;
+      }
+      const error = validateValue(name, value, meta);
+      if (error) {
+        errors.push(error);
+      }
+    }
+    return errors.length === 0 ? { success: true } : { success: false, errors };
   }
-  build() {
-    return this;
+};
+function describeValue(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+function validateValue(name, value, meta) {
+  if (value === null) {
+    return meta.nullable ? null : `Column "${name}" is not nullable, got null`;
+  }
+  switch (meta.kind) {
+    case "text":
+      return typeof value === "string" ? null : `Column "${name}" expects text, got ${describeValue(value)}`;
+    case "integer":
+      return typeof value === "number" && Number.isInteger(value) ? null : `Column "${name}" expects an integer, got ${describeValue(value)}`;
+    case "real":
+      return typeof value === "number" && Number.isFinite(value) ? null : `Column "${name}" expects a number, got ${describeValue(value)}`;
+    case "boolean":
+      return typeof value === "boolean" || value === 0 || value === 1 ? null : `Column "${name}" expects a boolean (true/false or 0/1), got ${describeValue(value)}`;
+    case "enum": {
+      if (typeof value !== "string") {
+        return `Column "${name}" expects one of ${formatEnumValues(meta)}, got ${describeValue(value)}`;
+      }
+      return meta.enumValues?.includes(value) ? null : `Column "${name}" expects one of ${formatEnumValues(meta)}, got "${value}"`;
+    }
   }
+}
+function formatEnumValues(meta) {
+  return (meta.enumValues ?? []).map((value) => `"${value}"`).join(" | ");
+}
+function column(kind, sqlType) {
+  return new ColumnBuilder({ kind, sqlType, nullable: false, hasDefault: false });
+}
+var t = {
+  text: () => column("text", "text"),
+  integer: () => column("integer", "integer"),
+  real: () => column("real", "real"),
+  /** Stored as INTEGER 0/1; always bind booleans as 0/1 when writing raw SQL. */
+  boolean: () => column("boolean", "integer"),
+  /**
+   * Union of string literals stored as TEXT, e.g. `t.enum(["movie", "tv"])`. Unlike `$type`, the
+   * allowed values are kept as runtime metadata, so payloads are validated against them.
+   * For an open-ended set, use `t.text().$type<"idle" | (string & {})>()` instead.
+   */
+  enum: (values) => new ColumnBuilder({
+    kind: "enum",
+    sqlType: "text",
+    nullable: false,
+    hasDefault: false,
+    enumValues: values
+  }),
+  table: (columns, options) => new TableBuilder(columns, options)
 };
 
 // src/sqlite-crdt/crdt-storage-mutator.ts
@@ -583,7 +801,7 @@ select * from ${quoteId(baseTableName)}
 where tombstone = 0;`,
     { loggerLevel: "system" }
   );
-  const allColumnNames = tableSchema.columns.map((column) => column.name);
+  const allColumnNames = tableSchema.columns.map((column2) => column2.name);
   const jsonPayload = (from) => `'{'||${allColumnNames.map((col) => `'"${col}":'||json_quote(${from}.${quoteId(col)})`).join("||','||")}||'}'`;
   db.execute(
     `
@@ -636,17 +854,12 @@ function registerCrdtFunctions({
     innocuous: false,
     callback: (dataset, payloadRaw) => {
       const payload = JSON.parse(payloadRaw);
-      storage.applyOwnEvent(
-        {
-          type: "item-created",
-          dataset,
-          item_id: payload.id,
-          payload: payloadRaw
-        },
-        {
-          wrapInTransaction: false
-        }
-      );
+      storage.internal.applyOwnEventFromTransaction(reactiveDb.db, {
+        type: "item-created",
+        dataset,
+        item_id: payload.id,
+        payload: payloadRaw
+      });
       eventApplied = true;
       return void 0;
     }
@@ -668,34 +881,29 @@ function registerCrdtFunctions({
       const newPayload = JSON.parse(newPayloadRaw);
       let hasDiff = false;
       const updatePayload = {};
-      for (const column of tableSchema.columns) {
-        const oldValue = oldPayload[column.name];
-        const newValue = newPayload[column.name];
+      for (const column2 of tableSchema.columns) {
+        const oldValue = oldPayload[column2.name];
+        const newValue = newPayload[column2.name];
         if (oldValue === newValue) {
           continue;
         }
-        if (column.name === "id") {
+        if (column2.name === "id") {
           throw new Error(
             `Cannot update the "id" column of an item. It is used to identify the item and must be immutable.`
           );
         }
         hasDiff = true;
-        updatePayload[column.name] = newValue;
+        updatePayload[column2.name] = newValue;
       }
       if (!hasDiff) {
         return;
       }
-      storage.applyOwnEvent(
-        {
-          type: "item-updated",
-          dataset,
-          item_id: oldPayload.id,
-          payload: JSON.stringify(updatePayload)
-        },
-        {
-          wrapInTransaction: false
-        }
-      );
+      storage.internal.applyOwnEventFromTransaction(reactiveDb.db, {
+        type: "item-updated",
+        dataset,
+        item_id: oldPayload.id,
+        payload: JSON.stringify(updatePayload)
+      });
       eventApplied = true;
       return void 0;
     }
@@ -706,17 +914,12 @@ function registerCrdtFunctions({
     directOnly: false,
     innocuous: false,
     callback: (dataset, itemId) => {
-      storage.applyOwnEvent(
-        {
-          type: "item-deleted",
-          dataset,
-          item_id: itemId,
-          payload: "{}"
-        },
-        {
-          wrapInTransaction: false
-        }
-      );
+      storage.internal.applyOwnEventFromTransaction(reactiveDb.db, {
+        type: "item-deleted",
+        dataset,
+        item_id: itemId,
+        payload: "{}"
+      });
       eventApplied = true;
       return void 0;
     }
@@ -724,7 +927,7 @@ function registerCrdtFunctions({
   reactiveDb.addEventListener("transaction-committed", () => {
     if (eventApplied) {
       eventApplied = false;
-      storage.dispatchEventsApplied();
+      void storage.internal.processEnqueuedEvents();
     }
   });
   reactiveDb.addEventListener("transaction-rolled-back", () => {
@@ -799,7 +1002,8 @@ async function createMemoryDb({
   crdtTables,
   initializeSchema = true,
   initialSyncId,
-  eventHlcAccumulator
+  eventHlcAccumulator,
+  syncDbSchema
 }) {
   await xxhash.ensureLoaded();
   const reactiveDb = _reactiveDb;
@@ -821,7 +1025,8 @@ async function createMemoryDb({
     migrator,
     db,
     dbConfig: memoryDbConfig,
-    eventHlcAccumulator
+    eventHlcAccumulator,
+    schema: syncDbSchema
   });
   registerCrdtFunctions({
     reactiveDb,
@@ -1004,7 +1209,8 @@ async function createSyncedDb(options) {
     migrator: memoryDbMigrator,
     reactiveDb,
     hlcCounter,
-    crdtTables: options.syncDbSchema.tablesConfig
+    crdtTables: options.syncDbSchema.tablesConfig,
+    syncDbSchema: options.syncDbSchema
   });
   const pullSyncId = createStoredValue({
     initialValue: workerClientSnapshot.syncId
@@ -1037,6 +1243,12 @@ async function createSyncedDb(options) {
     globalThis.location?.reload();
   });
   perf.logEnd("createSyncedDb", "initialized", "info");
+  const { exportData, importData } = createExportImport({
+    reactiveDb,
+    crdtStorage,
+    tablesConfig: options.syncDbSchema.tablesConfig,
+    schemaVersion: workerClientSnapshot.schemaVersion
+  });
   let isDisposed = false;
   let unregisterDevtools;
   const dispose = async () => {
@@ -1084,6 +1296,8 @@ async function createSyncedDb(options) {
       setTimeout(() => globalThis.location?.reload(), 250);
     },
     subscribe: workerClient.subscribe,
+    exportData,
+    importData,
     dispose,
     _internal: {
       executeAsync: workerClient.execute.bind(workerClient),
@@ -1105,10 +1319,13 @@ async function createSyncedDb(options) {
 }
 export {
   CRDT_EVENT_NO_OP_PAYLOAD,
+  ColumnBuilder,
+  CrdtEventValidationError,
   HLCCounter,
   RESET_REQUEST_TTL_MS,
   SQLiteDbWrapper,
   SQLiteReactiveDb,
+  TableBuilder,
   TypedBroadcastChannel,
   TypedEvent,
   applyMemoryDbSchema,
@@ -1121,18 +1338,20 @@ export {
   createCrdtSyncProducer,
   createCrdtSyncRemoteSource,
   createDeferredPromise,
+  createExportImport,
   createKvStoreTableQuery,
   createMigrations,
   createMigrator,
   createSQLiteCrdtApplyFunction,
   createSQLiteKvStore,
   createStoredValue,
-  createSyncDbSchema,
   createSyncedDb,
   createSystemDbConfig,
   createTypedEventTarget,
+  defineSyncSchema,
   deserializeHLC,
   dummyKysely,
+  formatSchemaVerificationIssues,
   generateId,
   introspectDb,
   isNoOpCrdtEventPayload,
@@ -1143,8 +1362,11 @@ export {
   runSystemMigrations,
   serializeHLC,
   startPerformanceLogger,
+  t,
   tryCatch,
   tryCatchAsync,
+  validateNewCrdtEvent,
+  verifySyncSchema,
   xxhash
 };
 //# sourceMappingURL=index.js.map