@monlite/core 1.1.0 → 1.3.0

package/dist/index.d.cts

@@ -27,6 +27,24 @@ declare class Collection<T = Doc> {
     private columnDdl;
     /** Auto-additive migration: add declared columns missing from an existing table. */
     private migrateColumns;
+    private foreignKeysOn;
+    private declaredIndexDdl;
+    /**
+     * Reconcile the physical table to the declared schema, performing the changes
+     * the auto-additive path can't: **dropping** columns, **renaming** them, and
+     * **changing a column's type/constraints** — via a safe, transactional table
+     * rebuild that preserves data. Structured collections only.
+     *
+     * Pass `rename` to map an existing physical column to a new declared name, and
+     * `drop` to acknowledge columns that the new schema removes (an unacknowledged
+     * column drop throws, so data is never lost by accident).
+     *
+     * ```ts
+     * const users = db.collection("users", { schema: { name: "TEXT", age: "INTEGER" } });
+     * await users.$migrate({ rename: { fullname: "name" }, drop: ["legacy"] });
+     * ```
+     */
+    $migrate(options?: MigrateOptions): Promise<void>;
     private rowToDoc;
     private encodeColumn;
     private insertColumns;
@@ -122,6 +140,48 @@ interface MonlitePlugin {
     collectionMethods?: Record<string, (collection: Collection<any>, ...args: any[]) => any>;
 }
 
+/**
+ * The minimal SQLite driver surface monlite needs. Implemented by both the
+ * better-sqlite3 and the built-in node:sqlite backends so the rest of the
+ * codebase is engine-agnostic.
+ */
+interface RunResult {
+    changes: number;
+    lastInsertRowid: number | bigint;
+}
+interface PreparedStatement {
+    run(...params: any[]): RunResult;
+    get(...params: any[]): any;
+    all(...params: any[]): any[];
+}
+interface Driver {
+    /** Backend identifier, e.g. "better-sqlite3" or "node:sqlite". */
+    readonly name: string;
+    exec(sql: string): void;
+    prepare(sql: string): PreparedStatement;
+    /** Run `fn` inside a transaction; rolls back and rethrows if it throws. */
+    transaction<T>(fn: () => T): T;
+    close(): void;
+    /** Rotate the encryption key (encrypted backends only). */
+    rekey?(key: string, cipher?: string): void;
+    /** The underlying native handle (better-sqlite3 Database / node:sqlite DatabaseSync). */
+    readonly raw: any;
+}
+interface DriverOpenOptions {
+    readonly?: boolean;
+    wal?: boolean;
+    /** Milliseconds to wait on a locked database before erroring. Default 5000. */
+    busyTimeout?: number;
+    /** Allow loading SQLite extensions (needed by `@monlite/vector`). Default false. */
+    allowExtensions?: boolean;
+    /** Encrypt the database at rest (better-sqlite3-multiple-ciphers only). */
+    encryption?: {
+        key: string;
+        cipher?: string;
+    };
+    verbose?: (sql: string) => void;
+}
+
 /**
  * Public type surface for monlite.
  *
@@ -167,6 +227,13 @@ interface CollectionOptions {
     schema?: CollectionSchema;
 }
 type CollectionMode = "document" | "structured";
+/** Options for {@link Collection.$migrate}. */
+interface MigrateOptions {
+    /** Rename existing physical columns: `{ oldName: newDeclaredName }`. */
+    rename?: Record<string, string>;
+    /** Acknowledge physical columns to drop (not present in the new schema). */
+    drop?: string[];
+}
 /** A column as reported by {@link Monlite.$schema}. */
 interface ColumnInfo {
     name: string;
@@ -371,8 +438,10 @@ interface MonliteOptions {
     /**
      * Which SQLite backend to use. `"auto"` (default) prefers `better-sqlite3`
      * when installed, otherwise the built-in `node:sqlite` (Node >= 22.5).
+     * You can also pass a custom {@link Driver} instance (e.g. `@monlite/wasm`
+     * for the browser).
      */
-    driver?: DriverName;
+    driver?: DriverName | Driver;
     /**
      * Encrypt the database at rest. Requires the `better-sqlite3-multiple-ciphers`
      * package (a drop-in for `better-sqlite3`); not supported on `node:sqlite`.
@@ -408,34 +477,6 @@ interface MonliteOptions {
     verbose?: (sql: string) => void;
 }
 
-/**
- * The minimal SQLite driver surface monlite needs. Implemented by both the
- * better-sqlite3 and the built-in node:sqlite backends so the rest of the
- * codebase is engine-agnostic.
- */
-interface RunResult {
-    changes: number;
-    lastInsertRowid: number | bigint;
-}
-interface PreparedStatement {
-    run(...params: any[]): RunResult;
-    get(...params: any[]): any;
-    all(...params: any[]): any[];
-}
-interface Driver {
-    /** Backend identifier, e.g. "better-sqlite3" or "node:sqlite". */
-    readonly name: string;
-    exec(sql: string): void;
-    prepare(sql: string): PreparedStatement;
-    /** Run `fn` inside a transaction; rolls back and rethrows if it throws. */
-    transaction<T>(fn: () => T): T;
-    close(): void;
-    /** Rotate the encryption key (encrypted backends only). */
-    rekey?(key: string, cipher?: string): void;
-    /** The underlying native handle (better-sqlite3 Database / node:sqlite DatabaseSync). */
-    readonly raw: any;
-}
-
 /**
  * Tracks which JSON paths are queried per collection and silently creates a
  * SQLite expression index once a path crosses the configured threshold.
@@ -747,4 +788,4 @@ declare function objectId(): string;
 /** True when a value looks like a monlite/ObjectId id (24 hex chars). */
 declare function isObjectId(value: unknown): value is string;
 
-export { type AggregateArgs, type AggregateResult, type ApplyResult, Collection, type CollectionMode, type CollectionOptions, type CollectionSchema, type ColumnDef, type ColumnInfo, type ColumnType, type ConflictResolver, type ConflictRow, type CountArgs, type CreateArgs, type CreateManyArgs, Monlite as Db, type DeleteArgs, type Doc, type Driver, type DriverName, type EncryptionOptions, type ExplainResult, type FieldFilter, type FieldSelection, type FilterInput, type FindFirstArgs, type FindManyArgs, type GroupByArgs, type GroupByResult, type HavingComparison, type HavingInput, type LiveEvent, type LocalChange, Monlite, MonliteConstraintError, MonliteEncryptionError, MonliteError, MonliteForeignKeyError, MonliteNotNullError, type MonliteOptions, type MonlitePlugin, MonliteQueryError, MonliteUniqueConstraintError, type OrderBy, type PluginChange, type PreparedStatement, type RemoteChange, type Select, type SortOrder, type SyncOp, type SyncStateRow, SyncStore, type SystemFields, type UpdateArgs, type UpdateData, type UpdateOperators, type UpsertArgs, type Version, type WatchHandle, type WhereInput as WhereClause, type WhereInput, type WithId, compareVersions, createDb, isObjectId, makeVersion, normalizeDriverError, objectId, versionTs };
+export { type AggregateArgs, type AggregateResult, type ApplyResult, Collection, type CollectionMode, type CollectionOptions, type CollectionSchema, type ColumnDef, type ColumnInfo, type ColumnType, type ConflictResolver, type ConflictRow, type CountArgs, type CreateArgs, type CreateManyArgs, Monlite as Db, type DeleteArgs, type Doc, type Driver, type DriverName, type DriverOpenOptions, type EncryptionOptions, type ExplainResult, type FieldFilter, type FieldSelection, type FilterInput, type FindFirstArgs, type FindManyArgs, type GroupByArgs, type GroupByResult, type HavingComparison, type HavingInput, type LiveEvent, type LocalChange, type MigrateOptions, Monlite, MonliteConstraintError, MonliteEncryptionError, MonliteError, MonliteForeignKeyError, MonliteNotNullError, type MonliteOptions, type MonlitePlugin, MonliteQueryError, MonliteUniqueConstraintError, type OrderBy, type PluginChange, type PreparedStatement, type RemoteChange, type RunResult, type Select, type SortOrder, type SyncOp, type SyncStateRow, SyncStore, type SystemFields, type UpdateArgs, type UpdateData, type UpdateOperators, type UpsertArgs, type Version, type WatchHandle, type WhereInput as WhereClause, type WhereInput, type WithId, compareVersions, createDb, isObjectId, makeVersion, normalizeDriverError, objectId, versionTs };

package/dist/index.d.ts

@@ -27,6 +27,24 @@ declare class Collection<T = Doc> {
     private columnDdl;
     /** Auto-additive migration: add declared columns missing from an existing table. */
     private migrateColumns;
+    private foreignKeysOn;
+    private declaredIndexDdl;
+    /**
+     * Reconcile the physical table to the declared schema, performing the changes
+     * the auto-additive path can't: **dropping** columns, **renaming** them, and
+     * **changing a column's type/constraints** — via a safe, transactional table
+     * rebuild that preserves data. Structured collections only.
+     *
+     * Pass `rename` to map an existing physical column to a new declared name, and
+     * `drop` to acknowledge columns that the new schema removes (an unacknowledged
+     * column drop throws, so data is never lost by accident).
+     *
+     * ```ts
+     * const users = db.collection("users", { schema: { name: "TEXT", age: "INTEGER" } });
+     * await users.$migrate({ rename: { fullname: "name" }, drop: ["legacy"] });
+     * ```
+     */
+    $migrate(options?: MigrateOptions): Promise<void>;
     private rowToDoc;
     private encodeColumn;
     private insertColumns;
@@ -122,6 +140,48 @@ interface MonlitePlugin {
     collectionMethods?: Record<string, (collection: Collection<any>, ...args: any[]) => any>;
 }
 
+/**
+ * The minimal SQLite driver surface monlite needs. Implemented by both the
+ * better-sqlite3 and the built-in node:sqlite backends so the rest of the
+ * codebase is engine-agnostic.
+ */
+interface RunResult {
+    changes: number;
+    lastInsertRowid: number | bigint;
+}
+interface PreparedStatement {
+    run(...params: any[]): RunResult;
+    get(...params: any[]): any;
+    all(...params: any[]): any[];
+}
+interface Driver {
+    /** Backend identifier, e.g. "better-sqlite3" or "node:sqlite". */
+    readonly name: string;
+    exec(sql: string): void;
+    prepare(sql: string): PreparedStatement;
+    /** Run `fn` inside a transaction; rolls back and rethrows if it throws. */
+    transaction<T>(fn: () => T): T;
+    close(): void;
+    /** Rotate the encryption key (encrypted backends only). */
+    rekey?(key: string, cipher?: string): void;
+    /** The underlying native handle (better-sqlite3 Database / node:sqlite DatabaseSync). */
+    readonly raw: any;
+}
+interface DriverOpenOptions {
+    readonly?: boolean;
+    wal?: boolean;
+    /** Milliseconds to wait on a locked database before erroring. Default 5000. */
+    busyTimeout?: number;
+    /** Allow loading SQLite extensions (needed by `@monlite/vector`). Default false. */
+    allowExtensions?: boolean;
+    /** Encrypt the database at rest (better-sqlite3-multiple-ciphers only). */
+    encryption?: {
+        key: string;
+        cipher?: string;
+    };
+    verbose?: (sql: string) => void;
+}
+
 /**
  * Public type surface for monlite.
  *
@@ -167,6 +227,13 @@ interface CollectionOptions {
     schema?: CollectionSchema;
 }
 type CollectionMode = "document" | "structured";
+/** Options for {@link Collection.$migrate}. */
+interface MigrateOptions {
+    /** Rename existing physical columns: `{ oldName: newDeclaredName }`. */
+    rename?: Record<string, string>;
+    /** Acknowledge physical columns to drop (not present in the new schema). */
+    drop?: string[];
+}
 /** A column as reported by {@link Monlite.$schema}. */
 interface ColumnInfo {
     name: string;
@@ -371,8 +438,10 @@ interface MonliteOptions {
     /**
      * Which SQLite backend to use. `"auto"` (default) prefers `better-sqlite3`
      * when installed, otherwise the built-in `node:sqlite` (Node >= 22.5).
+     * You can also pass a custom {@link Driver} instance (e.g. `@monlite/wasm`
+     * for the browser).
      */
-    driver?: DriverName;
+    driver?: DriverName | Driver;
     /**
      * Encrypt the database at rest. Requires the `better-sqlite3-multiple-ciphers`
      * package (a drop-in for `better-sqlite3`); not supported on `node:sqlite`.
@@ -408,34 +477,6 @@ interface MonliteOptions {
     verbose?: (sql: string) => void;
 }
 
-/**
- * The minimal SQLite driver surface monlite needs. Implemented by both the
- * better-sqlite3 and the built-in node:sqlite backends so the rest of the
- * codebase is engine-agnostic.
- */
-interface RunResult {
-    changes: number;
-    lastInsertRowid: number | bigint;
-}
-interface PreparedStatement {
-    run(...params: any[]): RunResult;
-    get(...params: any[]): any;
-    all(...params: any[]): any[];
-}
-interface Driver {
-    /** Backend identifier, e.g. "better-sqlite3" or "node:sqlite". */
-    readonly name: string;
-    exec(sql: string): void;
-    prepare(sql: string): PreparedStatement;
-    /** Run `fn` inside a transaction; rolls back and rethrows if it throws. */
-    transaction<T>(fn: () => T): T;
-    close(): void;
-    /** Rotate the encryption key (encrypted backends only). */
-    rekey?(key: string, cipher?: string): void;
-    /** The underlying native handle (better-sqlite3 Database / node:sqlite DatabaseSync). */
-    readonly raw: any;
-}
-
 /**
  * Tracks which JSON paths are queried per collection and silently creates a
  * SQLite expression index once a path crosses the configured threshold.
@@ -747,4 +788,4 @@ declare function objectId(): string;
 /** True when a value looks like a monlite/ObjectId id (24 hex chars). */
 declare function isObjectId(value: unknown): value is string;
 
-export { type AggregateArgs, type AggregateResult, type ApplyResult, Collection, type CollectionMode, type CollectionOptions, type CollectionSchema, type ColumnDef, type ColumnInfo, type ColumnType, type ConflictResolver, type ConflictRow, type CountArgs, type CreateArgs, type CreateManyArgs, Monlite as Db, type DeleteArgs, type Doc, type Driver, type DriverName, type EncryptionOptions, type ExplainResult, type FieldFilter, type FieldSelection, type FilterInput, type FindFirstArgs, type FindManyArgs, type GroupByArgs, type GroupByResult, type HavingComparison, type HavingInput, type LiveEvent, type LocalChange, Monlite, MonliteConstraintError, MonliteEncryptionError, MonliteError, MonliteForeignKeyError, MonliteNotNullError, type MonliteOptions, type MonlitePlugin, MonliteQueryError, MonliteUniqueConstraintError, type OrderBy, type PluginChange, type PreparedStatement, type RemoteChange, type Select, type SortOrder, type SyncOp, type SyncStateRow, SyncStore, type SystemFields, type UpdateArgs, type UpdateData, type UpdateOperators, type UpsertArgs, type Version, type WatchHandle, type WhereInput as WhereClause, type WhereInput, type WithId, compareVersions, createDb, isObjectId, makeVersion, normalizeDriverError, objectId, versionTs };
+export { type AggregateArgs, type AggregateResult, type ApplyResult, Collection, type CollectionMode, type CollectionOptions, type CollectionSchema, type ColumnDef, type ColumnInfo, type ColumnType, type ConflictResolver, type ConflictRow, type CountArgs, type CreateArgs, type CreateManyArgs, Monlite as Db, type DeleteArgs, type Doc, type Driver, type DriverName, type DriverOpenOptions, type EncryptionOptions, type ExplainResult, type FieldFilter, type FieldSelection, type FilterInput, type FindFirstArgs, type FindManyArgs, type GroupByArgs, type GroupByResult, type HavingComparison, type HavingInput, type LiveEvent, type LocalChange, type MigrateOptions, Monlite, MonliteConstraintError, MonliteEncryptionError, MonliteError, MonliteForeignKeyError, MonliteNotNullError, type MonliteOptions, type MonlitePlugin, MonliteQueryError, MonliteUniqueConstraintError, type OrderBy, type PluginChange, type PreparedStatement, type RemoteChange, type RunResult, type Select, type SortOrder, type SyncOp, type SyncStateRow, SyncStore, type SystemFields, type UpdateArgs, type UpdateData, type UpdateOperators, type UpsertArgs, type Version, type WatchHandle, type WhereInput as WhereClause, type WhereInput, type WithId, compareVersions, createDb, isObjectId, makeVersion, normalizeDriverError, objectId, versionTs };

package/dist/index.js

@@ -790,6 +790,124 @@ var Collection = class {
       }
     }
   }
+  foreignKeysOn() {
+    try {
+      const row = this.db.prepare(`PRAGMA foreign_keys`).get();
+      return !!row?.foreign_keys;
+    } catch {
+      return true;
+    }
+  }
+  declaredIndexDdl() {
+    const out = [];
+    for (const field of this.columnOrder) {
+      if (this.columnDefs[field].index) {
+        out.push(
+          `CREATE INDEX IF NOT EXISTS "idx_${this.name}_${field}" ON "${this.name}"("${field}")`
+        );
+      }
+    }
+    return out;
+  }
+  /**
+   * Reconcile the physical table to the declared schema, performing the changes
+   * the auto-additive path can't: **dropping** columns, **renaming** them, and
+   * **changing a column's type/constraints** — via a safe, transactional table
+   * rebuild that preserves data. Structured collections only.
+   *
+   * Pass `rename` to map an existing physical column to a new declared name, and
+   * `drop` to acknowledge columns that the new schema removes (an unacknowledged
+   * column drop throws, so data is never lost by accident).
+   *
+   * ```ts
+   * const users = db.collection("users", { schema: { name: "TEXT", age: "INTEGER" } });
+   * await users.$migrate({ rename: { fullname: "name" }, drop: ["legacy"] });
+   * ```
+   */
+  async $migrate(options = {}) {
+    if (this.mode !== "structured") {
+      throw new MonliteError(
+        `$migrate() is only available on structured collections (declare a schema).`
+      );
+    }
+    this.ensureTable();
+    const rename = options.rename ?? {};
+    const drop = new Set(options.drop ?? []);
+    const SYSTEM = /* @__PURE__ */ new Set(["_id", "created_at", "updated_at", "data"]);
+    const physical = this.db.prepare(`PRAGMA table_info("${this.name}")`).all().map((r) => r.name).filter((n) => !SYSTEM.has(n));
+    const physicalSet = new Set(physical);
+    const targetSet = new Set(this.columnOrder);
+    const renamedFrom = {};
+    for (const [from, to] of Object.entries(rename)) {
+      if (!physicalSet.has(from)) {
+        throw new MonliteError(
+          `Cannot rename "${from}": no such column in "${this.name}".`
+        );
+      }
+      if (!targetSet.has(to)) {
+        throw new MonliteError(
+          `Cannot rename "${from}" to "${to}": "${to}" is not in the schema.`
+        );
+      }
+      renamedFrom[to] = from;
+    }
+    const renameSources = new Set(Object.keys(rename));
+    for (const col of physical) {
+      if (targetSet.has(col) || renameSources.has(col) || drop.has(col))
+        continue;
+      throw new MonliteError(
+        `Column "${col}" exists in "${this.name}" but isn't in the schema. Add it to the schema, or list it in \`drop\` to remove it.`
+      );
+    }
+    const tmp = `__mon_migrate_${this.name}`;
+    const newCols = [
+      `_id        TEXT    PRIMARY KEY`,
+      `created_at INTEGER NOT NULL`,
+      `updated_at INTEGER NOT NULL`,
+      `data       TEXT    NOT NULL DEFAULT '{}'`,
+      ...this.columnOrder.map((f) => this.columnDdl(f, false))
+    ];
+    const destCols = [
+      "_id",
+      "created_at",
+      "updated_at",
+      "data",
+      ...this.columnOrder.map((f) => `"${f}"`)
+    ].join(", ");
+    const srcCols = [
+      "_id",
+      "created_at",
+      "updated_at",
+      "data",
+      ...this.columnOrder.map((t) => {
+        const src = renamedFrom[t] ?? (physicalSet.has(t) ? t : null);
+        return src ? `"${src}"` : "NULL";
+      })
+    ].join(", ");
+    const fkOn = this.foreignKeysOn();
+    if (fkOn) this.db.exec(`PRAGMA foreign_keys = OFF`);
+    try {
+      this.guard(
+        () => this.db.transaction(() => {
+          this.db.exec(`DROP TABLE IF EXISTS "${tmp}"`);
+          this.db.exec(
+            `CREATE TABLE "${tmp}" (
+  ${newCols.join(",\n  ")}
+)`
+          );
+          this.db.exec(
+            `INSERT INTO "${tmp}" (${destCols}) SELECT ${srcCols} FROM "${this.name}"`
+          );
+          this.db.exec(`DROP TABLE "${this.name}"`);
+          this.db.exec(`ALTER TABLE "${tmp}" RENAME TO "${this.name}"`);
+          for (const ddl of this.declaredIndexDdl()) this.db.exec(ddl);
+        })
+      );
+    } finally {
+      if (fkOn) this.db.exec(`PRAGMA foreign_keys = ON`);
+    }
+    this.insertSqlCache = void 0;
+  }
   /* --------------------------- row <-> doc -------------------------- */
   rowToDoc(row) {
     const doc = this.mode === "document" ? JSON.parse(row.data) : JSON.parse(row.data ?? "{}");
@@ -1494,7 +1612,11 @@ function loadNodeSqlite() {
     return null;
   }
 }
+function isDriverInstance(d) {
+  return typeof d === "object" && d !== null && typeof d.prepare === "function" && typeof d.exec === "function";
+}
 function createDriver(filename, options = {}) {
+  if (isDriverInstance(options.driver)) return options.driver;
   const choice = options.driver ?? "auto";
   if (options.encryption) {
     if (choice === "node:sqlite") {