@monlite/core 0.7.0 → 0.9.0

package/README.md

@@ -319,6 +319,31 @@ await users.distinct("tags");                        // ["a", "b", "c"]
 
 ---
 
+## Live queries (reactivity)
+
+`collection.watch()` keeps a query result live. The callback fires once
+immediately (`type: "init"`) and again whenever a change **affects this query** —
+matching is **row-level**, so unrelated writes don't trigger a recompute. It also
+fires for changes applied by `@monlite/sync`, so the UI updates when cloud data
+arrives.
+
+```ts
+const handle = users.watch({ where: { role: "admin" } }, (event) => {
+  event.results; // full current result set
+  event.added;   // docs that just entered the set
+  event.removed; // docs that just left
+  event.changed; // docs still in the set whose contents changed
+});
+
+handle.results; // current results, kept up to date
+handle.stop();  // unsubscribe
+```
+
+Perfect for Electron/Tauri UIs: bind `handle.results` to your view and it stays
+in sync with every write (local or synced).
+
+---
+
 ## Structured collections (native SQL columns)
 
 By default a collection is **document mode** — schema-free, every field stored
@@ -362,6 +387,11 @@ await db.$queryRaw`
 Column types: `"TEXT" | "INTEGER" | "REAL" | "BLOB" | "JSON"`. A full column
 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.
+
 ### Do I have to care: JSON vs native columns?
 
 - **For correctness — no.** Both modes return identical results through the same API.
@@ -472,6 +502,13 @@ ON users(json_extract(data, '$.address.city'));
 
 You never think about indexes. Disable with `createDb("./app.db", { autoIndex: false })`.
 
+Want to see whether a query uses an index? Ask:
+
+```ts
+await users.explain({ where: { "address.city": "Riyadh" } });
+// { sql, usesIndex: true, plan: [{ id, parent, detail }, …] }
+```
+
 ---
 
 ## Database management
@@ -480,6 +517,7 @@ You never think about indexes. Disable with `createDb("./app.db", { autoIndex: f
 await db.$collections();   // string[] of collection names
 await db.$drop("users");   // drop a collection and its data
 await db.$dropAll();       // drop everything
+await db.backup("./snapshot.db"); // consistent on-disk snapshot
 await db.$disconnect();    // close the connection
 db.sqlite;                 // the underlying native driver handle
 db.driverName;             // "better-sqlite3" | "node:sqlite"
@@ -487,6 +525,31 @@ db.driverName;             // "better-sqlite3" | "node:sqlite"
 
 ---
 
+## Plugins
+
+`@monlite/core` stays lean; heavier or optional capabilities are opt-in plugins
+passed to `createDb`:
+
+```ts
+import { createDb } from "@monlite/core";
+import { fts } from "@monlite/fts";
+
+const db = createDb("./app.db", {
+  plugins: [fts({ posts: ["title", "body"] })],
+});
+
+await db.collection("posts").search("hello world"); // full-text search
+```
+
+| Plugin | Adds |
+|---|---|
+| [`@monlite/fts`](https://www.npmjs.com/package/@monlite/fts) | Full-text search (SQLite FTS5) via `collection.search()` |
+
+Write your own against the `MonlitePlugin` interface (`init` / `afterWrite` /
+`collectionMethods` hooks).
+
+---
+
 ## Drivers & zero dependencies
 
 monlite talks to SQLite through a tiny driver adapter, so it runs on two

package/dist/index.cjs

@@ -20,6 +20,91 @@ function isObjectId(value) {
   return typeof value === "string" && /^[0-9a-f]{24}$/i.test(value);
 }
 
+// src/reactive.ts
+var RELEVANCE_PROBE_LIMIT = 500;
+var LiveQuery = class {
+  constructor(source, args, cb) {
+    this.source = source;
+    this.args = args;
+    this.cb = cb;
+    this.recompute("init");
+  }
+  source;
+  args;
+  cb;
+  results = [];
+  stopped = false;
+  ids = /* @__PURE__ */ new Set();
+  /** Called by the Reactor with the ids that changed this tick. */
+  notify(changedIds) {
+    if (this.stopped) return;
+    if (!this.isRelevant(changedIds)) return;
+    this.recompute("change", changedIds);
+  }
+  isRelevant(changedIds) {
+    for (const id of changedIds) {
+      if (this.ids.has(id)) return true;
+    }
+    if (changedIds.size > RELEVANCE_PROBE_LIMIT) return true;
+    const idIn = {
+      _id: { in: [...changedIds] }
+    };
+    const where = this.args.where ? { AND: [this.args.where, idIn] } : idIn;
+    return this.source.existsCore(where);
+  }
+  recompute(type, changedIds) {
+    const next = this.source.findManyCore(this.args);
+    const nextById = new Map(next.map((d) => [d._id, d]));
+    const added = next.filter((d) => !this.ids.has(d._id));
+    const removed = this.results.filter((d) => !nextById.has(d._id));
+    const changed = changedIds ? next.filter((d) => this.ids.has(d._id) && changedIds.has(d._id)) : [];
+    this.results = next;
+    this.ids = new Set(nextById.keys());
+    this.cb({ type, results: next, added, removed, changed });
+  }
+};
+var Reactor = class {
+  byCollection = /* @__PURE__ */ new Map();
+  pending = /* @__PURE__ */ new Map();
+  flushScheduled = false;
+  hasWatchers(collection) {
+    return this.byCollection.has(collection);
+  }
+  register(collection, lq) {
+    let set = this.byCollection.get(collection);
+    if (!set) this.byCollection.set(collection, set = /* @__PURE__ */ new Set());
+    set.add(lq);
+  }
+  unregister(collection, lq) {
+    const set = this.byCollection.get(collection);
+    if (!set) return;
+    set.delete(lq);
+    if (set.size === 0) this.byCollection.delete(collection);
+  }
+  /** Record that documents changed; schedule a notification flush. */
+  emit(collection, ids) {
+    const set = this.byCollection.get(collection);
+    if (!set || set.size === 0 || ids.length === 0) return;
+    let p = this.pending.get(collection);
+    if (!p) this.pending.set(collection, p = /* @__PURE__ */ new Set());
+    for (const id of ids) p.add(id);
+    if (!this.flushScheduled) {
+      this.flushScheduled = true;
+      queueMicrotask(() => this.flush());
+    }
+  }
+  flush() {
+    this.flushScheduled = false;
+    const work = [...this.pending];
+    this.pending.clear();
+    for (const [collection, ids] of work) {
+      const set = this.byCollection.get(collection);
+      if (!set) continue;
+      for (const lq of [...set]) lq.notify(ids);
+    }
+  }
+};
+
 // src/errors.ts
 var MonliteError = class extends Error {
   constructor(message, options) {
@@ -605,6 +690,7 @@ var Collection = class {
         this.columns.add(field);
         if (normalized.type === "JSON") this.jsonColumns.add(field);
       }
+      this.ensureTable();
     }
   }
   mon;
@@ -649,23 +735,15 @@ var Collection = class {
         `_id        TEXT    PRIMARY KEY`,
         `created_at INTEGER NOT NULL`,
         `updated_at INTEGER NOT NULL`,
-        `data       TEXT    NOT NULL DEFAULT '{}'`
+        `data       TEXT    NOT NULL DEFAULT '{}'`,
+        ...this.columnOrder.map((f) => this.columnDdl(f, false))
       ];
-      for (const field of this.columnOrder) {
-        const def = this.columnDefs[field];
-        let line = `"${field}" ${sqliteType(def.type)}`;
-        if (def.notNull) line += " NOT NULL";
-        if (def.unique) line += " UNIQUE";
-        if (def.default !== void 0)
-          line += ` DEFAULT ${formatDefault(def.default)}`;
-        if (def.references) line += ` REFERENCES ${def.references}`;
-        lines.push(line);
-      }
       this.db.exec(
         `CREATE TABLE IF NOT EXISTS "${this.name}" (
   ${lines.join(",\n  ")}
 )`
       );
+      this.migrateColumns();
       for (const field of this.columnOrder) {
         if (this.columnDefs[field].index) {
           this.db.exec(
@@ -676,6 +754,39 @@ var Collection = class {
     }
     this.initialized = true;
   }
+  columnDdl(field, forAlter) {
+    const def = this.columnDefs[field];
+    let line = `"${field}" ${sqliteType(def.type)}`;
+    if (def.notNull) line += " NOT NULL";
+    if (def.unique && !forAlter) line += " UNIQUE";
+    if (def.default !== void 0)
+      line += ` DEFAULT ${formatDefault(def.default)}`;
+    if (def.references) line += ` REFERENCES ${def.references}`;
+    return line;
+  }
+  /** Auto-additive migration: add declared columns missing from an existing table. */
+  migrateColumns() {
+    const existing = new Set(
+      this.db.prepare(`PRAGMA table_info("${this.name}")`).all().map((r) => r.name)
+    );
+    for (const field of this.columnOrder) {
+      if (existing.has(field)) continue;
+      try {
+        this.db.exec(
+          `ALTER TABLE "${this.name}" ADD COLUMN ${this.columnDdl(field, true)}`
+        );
+      } catch (err) {
+        throw new MonliteError(
+          `Failed to add column "${field}" to "${this.name}": ${err.message}. NOT NULL columns need a default when added to an existing table.`
+        );
+      }
+      if (this.columnDefs[field].unique) {
+        this.db.exec(
+          `CREATE UNIQUE INDEX IF NOT EXISTS "uq_${this.name}_${field}" ON "${this.name}"("${field}")`
+        );
+      }
+    }
+  }
   /* --------------------------- row <-> doc -------------------------- */
   rowToDoc(row) {
     const doc = this.mode === "document" ? JSON.parse(row.data) : JSON.parse(row.data ?? "{}");
@@ -798,6 +909,7 @@ var Collection = class {
     this.ensureTable();
     if (op === "delete") {
       this.db.prepare(`DELETE FROM "${this.name}" WHERE _id = ?`).run(id);
+      this.afterWrite([id]);
       return;
     }
     const clean = stripSystem(doc ?? {});
@@ -807,6 +919,7 @@ var Collection = class {
         `INSERT INTO "${this.name}" (_id, data, created_at, updated_at) VALUES (?, ?, ?, ?)
            ON CONFLICT(_id) DO UPDATE SET data = excluded.data, updated_at = excluded.updated_at`
       ).run(id, JSON.stringify(clean), createdAt, ts);
+      this.afterWrite([id]);
       return;
     }
     const overflow = {};
@@ -837,6 +950,13 @@ var Collection = class {
     this.db.prepare(
       `INSERT INTO "${this.name}" (${colList}) VALUES (${placeholders}) ON CONFLICT(_id) DO UPDATE SET ${updateSet}`
     ).run(...values);
+    this.afterWrite([id]);
+  }
+  /** @internal Notify reactivity watchers and plugins that documents changed. */
+  afterWrite(ids) {
+    if (ids.length === 0) return;
+    this.mon.reactor.emit(this.name, ids);
+    this.mon.firePluginAfterWrite(this.name, ids);
   }
   /* ----------------------------- create ----------------------------- */
   async create(args) {
@@ -848,26 +968,29 @@ var Collection = class {
       recorder?.recordLocal(this.name, row._id, "upsert", row.created_at);
     };
     this.guard(() => recorder ? this.db.transaction(write) : write());
+    this.afterWrite([row._id]);
     return row.returned;
   }
   async createMany(args) {
     this.ensureTable();
     const stmt = this.db.prepare(this.insertSql());
     const recorder = this.recorder;
+    const ids = [];
     this.guard(
       () => this.db.transaction(() => {
         for (const item of args.data) {
           const row = this.buildInsert(item);
           stmt.run(...row.values);
           recorder?.recordLocal(this.name, row._id, "upsert", row.created_at);
+          ids.push(row._id);
         }
       })
     );
+    this.afterWrite(ids);
     return { count: args.data.length };
   }
   /* ------------------------------ read ------------------------------ */
-  async findMany(args = {}) {
-    this.ensureTable();
+  buildFindSql(args) {
     const params = [];
     const where = buildWhere(args.where, {
       params,
@@ -885,9 +1008,29 @@ var Collection = class {
       sql += (args.take != null ? "" : " LIMIT -1") + " OFFSET ?";
       params.push(args.skip);
     }
+    return { sql, params };
+  }
+  /** @internal Synchronous core of findMany (used by reactivity). */
+  findManyCore(args = {}) {
+    this.ensureTable();
+    const { sql, params } = this.buildFindSql(args);
     const rows = this.db.prepare(sql).all(...params);
     return rows.map((r) => project(this.rowToDoc(r), args.select));
   }
+  /** @internal Synchronous core of exists (used by reactivity). */
+  existsCore(where) {
+    this.ensureTable();
+    const params = [];
+    const clause = buildWhere(where, {
+      params,
+      onPath: this.trackPath,
+      columns: this.columns
+    });
+    return this.db.prepare(`SELECT 1 FROM "${this.name}" WHERE ${clause} LIMIT 1`).get(...params) != null;
+  }
+  async findMany(args = {}) {
+    return this.findManyCore(args);
+  }
   async findFirst(args = {}) {
     const rows = await this.findMany({ ...args, take: 1 });
     return rows[0] ?? null;
@@ -904,15 +1047,39 @@ var Collection = class {
   }
   /** True if at least one document matches. */
   async exists(where) {
+    return this.existsCore(where);
+  }
+  /**
+   * Subscribe to a live query. The callback fires immediately with the current
+   * results (`type: "init"`) and again whenever a change affects the result set
+   * (row-level: only relevant changes trigger a recompute). Includes changes
+   * applied by `@monlite/sync`.
+   */
+  watch(args = {}, cb) {
     this.ensureTable();
-    const params = [];
-    const clause = buildWhere(where, {
-      params,
-      onPath: this.trackPath,
-      columns: this.columns
-    });
-    const row = this.db.prepare(`SELECT 1 FROM "${this.name}" WHERE ${clause} LIMIT 1`).get(...params);
-    return row != null;
+    const lq = new LiveQuery(this, args, cb);
+    const reactor = this.mon.reactor;
+    const name = this.name;
+    reactor.register(name, lq);
+    return {
+      get results() {
+        return lq.results;
+      },
+      stop() {
+        lq.stopped = true;
+        reactor.unregister(name, lq);
+      }
+    };
+  }
+  /** Show SQLite's query plan for a `findMany`, and whether it uses an index. */
+  async explain(args = {}) {
+    this.ensureTable();
+    const { sql, params } = this.buildFindSql(args);
+    const plan = this.db.prepare(`EXPLAIN QUERY PLAN ${sql}`).all(...params);
+    const usesIndex = plan.some(
+      (r) => /USING (COVERING )?INDEX/i.test(r.detail)
+    );
+    return { sql, usesIndex, plan };
   }
   async findById(id) {
     this.ensureTable();
@@ -969,25 +1136,27 @@ var Collection = class {
     if (!rows.length) return [];
     const now = Date.now();
     const recorder = this.recorder;
-    return this.guard(
+    const out = this.guard(
       () => this.db.transaction(() => {
-        const out = [];
+        const result = [];
         for (const row of rows) {
           const current = stripSystem(this.rowToDoc(row));
           const updated = stripSystem(applyUpdate(current, data));
           const { setSql, values } = this.buildUpdateSet(updated, now);
           this.db.prepare(`UPDATE "${this.name}" SET ${setSql} WHERE _id = ?`).run(...values, row._id);
           recorder?.recordLocal(this.name, row._id, "upsert", now);
-          out.push({
+          result.push({
             ...updated,
             _id: row._id,
             created_at: row.created_at,
             updated_at: now
           });
         }
-        return out;
+        return result;
       })
     );
+    this.afterWrite(out.map((d) => d._id));
+    return out;
   }
   async update(args) {
     return this.runUpdate(args.where, args.data, true)[0] ?? null;
@@ -997,7 +1166,7 @@ var Collection = class {
   }
   async upsert(args) {
     this.ensureTable();
-    return this.guard(
+    const result = this.guard(
       () => this.db.transaction(() => {
         const params = [];
         const clause = buildWhere(args.where, {
@@ -1027,6 +1196,8 @@ var Collection = class {
         return ins.returned;
       })
     );
+    this.afterWrite([result._id]);
+    return result;
   }
   /* ----------------------------- delete ----------------------------- */
   runDelete(where, single) {
@@ -1052,6 +1223,7 @@ var Collection = class {
         }
       })
     );
+    this.afterWrite(rows.map((r) => r._id));
     return rows.map((r) => this.rowToDoc(r));
   }
   async delete(args) {
@@ -1713,9 +1885,12 @@ var Monlite = class {
   driver;
   /** @internal */
   autoIndexer;
+  /** @internal Reactivity hub for `collection.watch()`. */
+  reactor = new Reactor();
   /** @internal Sync metadata store; present only when `{ sync: true }`. */
   $sync;
   collections = /* @__PURE__ */ new Map();
+  plugins;
   closed = false;
   constructor(filename, options = {}) {
     this.driver = createDriver(filename, {
@@ -1733,6 +1908,15 @@ var Monlite = class {
     if (options.sync) {
       this.$sync = new SyncStore(this.driver, options.nodeId, this);
     }
+    this.plugins = options.plugins ?? [];
+    for (const plugin of this.plugins) plugin.init?.(this);
+  }
+  /** @internal Notify plugins that documents changed (post-commit). */
+  firePluginAfterWrite(collection, ids) {
+    if (this.plugins.length === 0 || ids.length === 0) return;
+    for (const plugin of this.plugins) {
+      plugin.afterWrite?.(this, { collection, ids });
+    }
   }
   /** Stable node id for LWW tie-breaking (only when sync is enabled). */
   get nodeId() {
@@ -1758,6 +1942,13 @@ var Monlite = class {
     if (!col) {
       col = new Collection(this, name, options);
       this.collections.set(name, col);
+      for (const plugin of this.plugins) {
+        for (const [method, impl] of Object.entries(
+          plugin.collectionMethods ?? {}
+        )) {
+          col[method] = (...args) => impl(col, ...args);
+        }
+      }
     } else if (options?.schema) {
       const requested = Object.keys(options.schema);
       const existing = new Set(col.columnNames);
@@ -1847,6 +2038,15 @@ var Monlite = class {
   async $dropAll() {
     for (const name of await this.$collections()) await this.$drop(name);
   }
+  /**
+   * Write a consistent on-disk snapshot of the database to `path` (via
+   * `VACUUM INTO`). The destination file must not already exist.
+   */
+  backup(path) {
+    this.assertOpen();
+    this.driver.exec(`VACUUM INTO '${path.replace(/'/g, "''")}'`);
+    return Promise.resolve();
+  }
   /** Close the underlying SQLite connection. */
   $disconnect() {
     if (!this.closed) {