@monlite/core 0.7.0 → 0.9.0

package/dist/index.js

@@ -17,6 +17,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) {
@@ -602,6 +687,7 @@ var Collection = class {
         this.columns.add(field);
         if (normalized.type === "JSON") this.jsonColumns.add(field);
       }
+      this.ensureTable();
     }
   }
   mon;
@@ -646,23 +732,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(
@@ -673,6 +751,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 ?? "{}");
@@ -795,6 +906,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 ?? {});
@@ -804,6 +916,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 = {};
@@ -834,6 +947,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) {
@@ -845,26 +965,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,
@@ -882,9 +1005,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;
@@ -901,15 +1044,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();
@@ -966,25 +1133,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;
@@ -994,7 +1163,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, {
@@ -1024,6 +1193,8 @@ var Collection = class {
         return ins.returned;
       })
     );
+    this.afterWrite([result._id]);
+    return result;
   }
   /* ----------------------------- delete ----------------------------- */
   runDelete(where, single) {
@@ -1049,6 +1220,7 @@ var Collection = class {
         }
       })
     );
+    this.afterWrite(rows.map((r) => r._id));
     return rows.map((r) => this.rowToDoc(r));
   }
   async delete(args) {
@@ -1710,9 +1882,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, {
@@ -1730,6 +1905,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() {
@@ -1755,6 +1939,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);
@@ -1844,6 +2035,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) {