@monlite/core 1.1.0 → 1.3.0

package/README.md

@@ -389,8 +389,21 @@ definition supports `index`, `unique`, `notNull`, `default`, and `references`.
 
 **Migrations are automatic for additive changes.** Re-opening a collection with a
 new declared column adds it (`ALTER TABLE ADD COLUMN`) on declaration — give
-`NOT NULL` columns a `default` so existing rows can be backfilled. Destructive
-changes (rename/drop/type-change) still need a manual migration.
+`NOT NULL` columns a `default` so existing rows can be backfilled.
+
+For **destructive changes** — dropping, renaming, or changing a column's
+type/constraints — call `$migrate()`. It safely rebuilds the table (in a
+transaction, preserving data and indexes) to match the new declared schema:
+
+```ts
+// v2 schema: `fullname` → `name`, `age` is now INTEGER, `legacy` removed.
+const users = db.collection("users", { schema: { name: "TEXT", age: "INTEGER" } });
+await users.$migrate({ rename: { fullname: "name" }, drop: ["legacy"] });
+```
+
+A column that exists on disk but isn't in the new schema (and isn't listed in
+`drop`) throws — so you never lose data by accident. Run migrations at startup,
+before using the collection.
 
 ### Do I have to care: JSON vs native columns?
 
@@ -446,9 +459,10 @@ await engine.start();
 ```
 
 Pull / push / two-way replication, last-write-wins (or custom) conflict
-resolution, and pluggable adapters (`MongoAdapter`, `MonliteAdapter` for
-monlite-to-monlite, `MemoryAdapter` for tests). monlite's ObjectId-compatible
-`_id`s map 1:1 to Mongo `_id`s. See the
+resolution, and pluggable adapters (`MongoAdapter`, `PostgresAdapter`,
+`MySqlAdapter`, `MonliteAdapter` for monlite-to-monlite, `MemoryAdapter` for
+tests) — keep local monlite as the embedded runtime and a server DB as the cloud
+of record. See the
 [`@monlite/sync` README](https://www.npmjs.com/package/@monlite/sync) for details.
 
 ---
@@ -587,13 +601,14 @@ Redis/Mongo/Qdrant replacement. For scale, keep the real services and
 
 ## Drivers & zero dependencies
 
-monlite talks to SQLite through a tiny driver adapter, so it runs on two
+monlite talks to SQLite through a tiny driver adapter, so it runs on
 interchangeable backends:
 
 | Backend | When it's used | Notes |
 |---|---|---|
 | **`node:sqlite`** | Built into Node **22.5+** | **Zero dependencies.** Still flagged experimental by Node, so it prints a one-time `ExperimentalWarning`. |
 | **`better-sqlite3`** | When the package is installed | Battle-tested native driver. Works on Node 18/20/22, no warning. Install it yourself: `npm i better-sqlite3`. |
+| **WASM (browser)** | Via [`@monlite/wasm`](https://www.npmjs.com/package/@monlite/wasm) | Runs monlite **in the browser** on SQLite-WASM (sql.js); pass `driver: wasmDriver(SQL)`. Snapshot persistence to IndexedDB/OPFS. |
 
 By default (`driver: "auto"`) monlite uses `better-sqlite3` if it's installed,
 otherwise falls back to the built-in `node:sqlite`. Force one explicitly:

package/dist/index.cjs

@@ -793,6 +793,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 ?? "{}");
@@ -1497,7 +1615,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") {