@monlite/core 0.6.0 → 0.8.0

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) {
@@ -239,9 +324,7 @@ function cmp(expr, op, v, ctx) {
 }
 function inExpr(expr, arr, ctx, negate) {
   if (!Array.isArray(arr)) {
-    throw new MonliteQueryError(
-      `${negate ? "notIn" : "in"} expects an array`
-    );
+    throw new MonliteQueryError(`${negate ? "notIn" : "in"} expects an array`);
   }
   if (arr.length === 0) return negate ? "1" : "0";
   const placeholders = arr.map((v) => {
@@ -371,7 +454,8 @@ function applyUpdate(doc, data) {
   }
   const ops = data;
   if (ops.$set) {
-    for (const [path, value] of Object.entries(ops.$set)) setPath(next, path, value);
+    for (const [path, value] of Object.entries(ops.$set))
+      setPath(next, path, value);
   }
   if (ops.$inc) {
     for (const [path, by] of Object.entries(ops.$inc)) {
@@ -492,7 +576,11 @@ function buildHaving(having, params, columns) {
     if (!selection) continue;
     for (const field of Object.keys(selection)) {
       parts.push(
-        ...comparisonSql(`${fn}(${fieldExpr(field, columns)})`, selection[field], params)
+        ...comparisonSql(
+          `${fn}(${fieldExpr(field, columns)})`,
+          selection[field],
+          params
+        )
       );
     }
   }
@@ -520,7 +608,11 @@ function groupBy(ctx, args) {
     groupCols.push({ alias, field });
   });
   selects.push(`COUNT(*) AS agg_count`);
-  const { selects: accSelects, cols } = buildAccumulators(args, ctx.onPath, ctx.columns);
+  const { selects: accSelects, cols } = buildAccumulators(
+    args,
+    ctx.onPath,
+    ctx.columns
+  );
   selects.push(...accSelects);
   let sql = `SELECT ${selects.join(", ")} FROM "${ctx.table}" WHERE ${where} GROUP BY ${groupExprs.join(", ")}`;
   if (args.having) {
@@ -598,6 +690,7 @@ var Collection = class {
         this.columns.add(field);
         if (normalized.type === "JSON") this.jsonColumns.add(field);
       }
+      this.ensureTable();
     }
   }
   mon;
@@ -642,22 +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(
@@ -668,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 ?? "{}");
@@ -713,7 +832,12 @@ var Collection = class {
     const now = Date.now();
     const id = input._id != null ? String(input._id) : objectId();
     const doc = stripSystem(input);
-    const returned = { ...doc, _id: id, created_at: now, updated_at: now };
+    const returned = {
+      ...doc,
+      _id: id,
+      created_at: now,
+      updated_at: now
+    };
     if (this.mode === "document") {
       return {
         _id: id,
@@ -765,9 +889,72 @@ var Collection = class {
     ];
     return { setSql: setParts.join(", "), values };
   }
-  /** Sync store, but only for document collections (structured sync is future work). */
+  /** Sync store for recording local changes (both document and structured). */
   get recorder() {
-    return this.mode === "document" ? this.mon.$sync : void 0;
+    return this.mon.$sync;
+  }
+  /** @internal Read a full document by id (mode-aware), synchronously. */
+  getRaw(id) {
+    this.ensureTable();
+    const row = this.db.prepare(`SELECT * FROM "${this.name}" WHERE _id = ?`).get(id);
+    return row ? this.rowToDoc(row) : null;
+  }
+  /**
+   * @internal Apply a remote change to storage WITHOUT recording it to the
+   * change feed (the sync store records the `remote` feed row itself). Used by
+   * `@monlite/sync` so structured collections sync correctly through the same
+   * column/overflow split as local writes.
+   */
+  applyRemoteWrite(op, id, doc, ts) {
+    this.ensureTable();
+    if (op === "delete") {
+      this.db.prepare(`DELETE FROM "${this.name}" WHERE _id = ?`).run(id);
+      this.afterWrite([id]);
+      return;
+    }
+    const clean = stripSystem(doc ?? {});
+    const createdAt = typeof doc?.created_at === "number" ? doc.created_at : ts;
+    if (this.mode === "document") {
+      this.db.prepare(
+        `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 = {};
+    const colValues = {};
+    for (const [k, v] of Object.entries(clean)) {
+      if (this.columns.has(k)) colValues[k] = v;
+      else overflow[k] = v;
+    }
+    const cols = [
+      "_id",
+      "created_at",
+      "updated_at",
+      "data",
+      ...this.columnOrder
+    ];
+    const values = [
+      id,
+      createdAt,
+      ts,
+      JSON.stringify(overflow),
+      ...this.columnOrder.map(
+        (c) => c in colValues ? this.encodeColumn(c, colValues[c]) : null
+      )
+    ];
+    const colList = cols.map((c) => `"${c}"`).join(", ");
+    const placeholders = cols.map(() => "?").join(", ");
+    const updateSet = cols.filter((c) => c !== "_id" && c !== "created_at").map((c) => `"${c}" = excluded."${c}"`).join(", ");
+    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 that documents changed. */
+  afterWrite(ids) {
+    this.mon.reactor.emit(this.name, ids);
   }
   /* ----------------------------- create ----------------------------- */
   async create(args) {
@@ -779,26 +966,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,
@@ -816,9 +1006,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;
@@ -835,15 +1045,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();
@@ -900,25 +1134,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;
@@ -928,7 +1164,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, {
@@ -958,6 +1194,8 @@ var Collection = class {
         return ins.returned;
       })
     );
+    this.afterWrite([result._id]);
+    return result;
   }
   /* ----------------------------- delete ----------------------------- */
   runDelete(where, single) {
@@ -983,6 +1221,7 @@ var Collection = class {
         }
       })
     );
+    this.afterWrite(rows.map((r) => r._id));
     return rows.map((r) => this.rowToDoc(r));
   }
   async delete(args) {
@@ -996,7 +1235,12 @@ var Collection = class {
     this.ensureTable();
     return this.guard(
       () => aggregate(
-        { db: this.db, table: this.name, onPath: this.trackPath, columns: this.columns },
+        {
+          db: this.db,
+          table: this.name,
+          onPath: this.trackPath,
+          columns: this.columns
+        },
         args
       )
     );
@@ -1005,7 +1249,12 @@ var Collection = class {
     this.ensureTable();
     return this.guard(
       () => groupBy(
-        { db: this.db, table: this.name, onPath: this.trackPath, columns: this.columns },
+        {
+          db: this.db,
+          table: this.name,
+          onPath: this.trackPath,
+          columns: this.columns
+        },
         args
       )
     );
@@ -1253,12 +1502,14 @@ function stripSystem2(obj) {
   return rest;
 }
 var SyncStore = class {
-  constructor(db, nodeId) {
+  constructor(db, nodeId, mon) {
     this.db = db;
+    this.mon = mon;
     this.init();
     this.nodeId = this.resolveNodeId(nodeId);
   }
   db;
+  mon;
   nodeId;
   versionSeq = 0;
   init() {
@@ -1293,7 +1544,9 @@ var SyncStore = class {
   }
   resolveNodeId(explicit) {
     if (explicit) {
-      this.db.prepare(`INSERT OR REPLACE INTO _monlite_meta (key, value) VALUES ('nodeId', ?)`).run(explicit);
+      this.db.prepare(
+        `INSERT OR REPLACE INTO _monlite_meta (key, value) VALUES ('nodeId', ?)`
+      ).run(explicit);
       return explicit;
     }
     const row = this.db.prepare(`SELECT value FROM _monlite_meta WHERE key = 'nodeId'`).get();
@@ -1408,6 +1661,9 @@ var SyncStore = class {
         );
       }
       if (winner !== "remote") {
+        if (localVersion !== null) {
+          this.recordLocal(change.collection, change._id, "upsert", Date.now());
+        }
         return { applied: false, conflict: localVersion !== null, winner };
       }
       this.applyData(change);
@@ -1421,24 +1677,31 @@ var SyncStore = class {
         change.version,
         versionTs(change.version)
       );
-      return { applied: true, conflict: localVersion !== null, winner: "remote" };
+      return {
+        applied: true,
+        conflict: localVersion !== null,
+        winner: "remote"
+      };
     });
   }
   applyData(change) {
-    const { collection: coll, _id, op } = change;
+    const ts = versionTs(change.version);
+    if (this.mon) {
+      this.mon.collection(change.collection).applyRemoteWrite(change.op, change._id, change.doc, ts);
+      return;
+    }
+    const coll = change.collection;
     this.ensureCollTable(coll);
-    if (op === "delete") {
-      this.db.prepare(`DELETE FROM "${coll}" WHERE _id = ?`).run(_id);
+    if (change.op === "delete") {
+      this.db.prepare(`DELETE FROM "${coll}" WHERE _id = ?`).run(change._id);
       return;
     }
     const doc = change.doc ?? {};
-    const data = JSON.stringify(stripSystem2(doc));
-    const ts = versionTs(change.version);
     const createdAt = typeof doc.created_at === "number" ? doc.created_at : ts;
     this.db.prepare(
       `INSERT INTO "${coll}" (_id, data, created_at, updated_at) VALUES (?, ?, ?, ?)
          ON CONFLICT(_id) DO UPDATE SET data = excluded.data, updated_at = excluded.updated_at`
-    ).run(_id, data, createdAt, ts);
+    ).run(change._id, JSON.stringify(stripSystem2(doc)), createdAt, ts);
   }
   /**
    * Latest change per document with `seq` greater than the given watermark,
@@ -1495,6 +1758,7 @@ var SyncStore = class {
     this.db.transaction(() => {
       for (const coll of collections) {
         assertName(coll);
+        if (!this.tableExists(coll)) continue;
         const docs = this.db.prepare(`SELECT _id, updated_at FROM "${coll}"`).all();
         for (const d of docs) {
           if (this.currentVersion(coll, d._id) !== null) continue;
@@ -1540,7 +1804,14 @@ var SyncStore = class {
     this.db.prepare(
       `INSERT INTO _monlite_conflicts (coll, doc_id, local_version, remote_version, winner, ts)
          VALUES (?, ?, ?, ?, ?, ?)`
-    ).run(coll, id, localVersion, remoteVersion, winner, versionTs(remoteVersion));
+    ).run(
+      coll,
+      id,
+      localVersion,
+      remoteVersion,
+      winner,
+      versionTs(remoteVersion)
+    );
   }
   conflicts() {
     const rows = this.db.prepare(
@@ -1559,6 +1830,8 @@ var SyncStore = class {
   /* ------------------------------ helpers ------------------------------- */
   readDoc(coll, id) {
     assertName(coll);
+    if (this.mon) return this.mon.collection(coll).getRaw(id);
+    if (!this.tableExists(coll)) return null;
     const row = this.db.prepare(
       `SELECT _id, data, created_at, updated_at FROM "${coll}" WHERE _id = ?`
     ).get(id);
@@ -1569,6 +1842,9 @@ var SyncStore = class {
     doc.updated_at = row.updated_at;
     return doc;
   }
+  tableExists(name) {
+    return this.db.prepare(`SELECT 1 FROM sqlite_master WHERE type='table' AND name = ?`).get(name) != null;
+  }
   ensureCollTable(coll) {
     assertName(coll);
     this.db.exec(
@@ -1607,6 +1883,8 @@ 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();
@@ -1625,7 +1903,7 @@ var Monlite = class {
       options.autoIndexAfter ?? 10
     );
     if (options.sync) {
-      this.$sync = new SyncStore(this.driver, options.nodeId);
+      this.$sync = new SyncStore(this.driver, options.nodeId, this);
     }
   }
   /** Stable node id for LWW tie-breaking (only when sync is enabled). */
@@ -1741,6 +2019,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) {