@monlite/core 0.1.0 → 0.3.0

package/README.md

@@ -26,11 +26,18 @@ That's it. No setup. No config. Your data is in `app.db`.
 
 ```bash
 npm install @monlite/core
-# or: pnpm add @monlite/core / yarn add @monlite/core
 ```
 
-monlite uses [`better-sqlite3`](https://github.com/WiseLibs/better-sqlite3) under
-the hood (its only runtime dependency). Node 18+ is required.
+**monlite has zero required dependencies.** On **Node 22.5+** it uses the
+built-in [`node:sqlite`](https://nodejs.org/api/sqlite.html) engine out of the
+box. To run on Node 18/20 — or to avoid `node:sqlite`'s experimental warning —
+also install the (optional) native driver:
+
+```bash
+npm install @monlite/core better-sqlite3
+```
+
+See [Drivers & zero dependencies](#drivers--zero-dependencies) below.
 
 ---
 
@@ -65,6 +72,7 @@ const mem = createDb(":memory:");      // in-memory database
 
 ```ts
 const db = createDb("./app.db", {
+  driver: "auto",       // "auto" | "better-sqlite3" | "node:sqlite" (default: "auto")
   autoIndex: true,      // auto-create indexes on hot JSON paths (default: true)
   autoIndexAfter: 10,   // create an index after a path is queried N times (default: 10)
   readonly: false,      // open read-only (default: false)
@@ -242,6 +250,29 @@ const grouped = await users.groupBy({
   orderBy: { _count: "desc" },
 });
 // [ { role: "admin", _count: 5, _sum: { age: 140 } }, … ]
+
+// groupBy + having (filter groups by an aggregate, like SQL HAVING)
+await users.groupBy({
+  by: ["role"],
+  _count: true,
+  _sum: { age: true },
+  having: {
+    _count: { gte: 2 },          // keep groups with COUNT(*) >= 2
+    _sum: { age: { gt: 50 } },   // and SUM(age) > 50
+  },
+});
+// having comparisons: equals, not, gt, gte, lt, lte — on _count and on
+// _sum/_avg/_min/_max of any field.
+```
+
+### distinct
+
+```ts
+await users.distinct("role");                       // ["admin", "editor"]
+await users.distinct("age", { role: "admin" });     // [28, 31]
+
+// Array fields are unwound — each element is a value (like MongoDB):
+await users.distinct("tags");                        // ["a", "b", "c"]
 ```
 
 ---
@@ -276,7 +307,9 @@ await db.$transaction((tx) => {
 });
 ```
 
-Need the raw driver? `db.sqlite` is the underlying `better-sqlite3` instance.
+Need the raw driver? `db.sqlite` is the underlying native handle (a
+`better-sqlite3` `Database` or a `node:sqlite` `DatabaseSync`, depending on the
+active backend), and `db.driverName` tells you which one is in use.
 
 ---
 
@@ -302,11 +335,39 @@ await db.$collections();   // string[] of collection names
 await db.$drop("users");   // drop a collection and its data
 await db.$dropAll();       // drop everything
 await db.$disconnect();    // close the connection
-db.sqlite;                 // the underlying better-sqlite3 instance
+db.sqlite;                 // the underlying native driver handle
+db.driverName;             // "better-sqlite3" | "node:sqlite"
 ```
 
 ---
 
+## Drivers & zero dependencies
+
+monlite talks to SQLite through a tiny driver adapter, so it runs on two
+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`. |
+
+By default (`driver: "auto"`) monlite uses `better-sqlite3` if it's installed,
+otherwise falls back to the built-in `node:sqlite`. Force one explicitly:
+
+```ts
+createDb("./app.db", { driver: "node:sqlite" });    // zero-dep (Node 22.5+)
+createDb("./app.db", { driver: "better-sqlite3" }); // native, no warning
+```
+
+Both backends pass the exact same test suite, so behavior is identical — pick
+based on your Node version and whether you want the extra dependency.
+
+> Want truly zero dependencies on Node 22.5+? Just `npm install @monlite/core`
+> and don't install `better-sqlite3`. To silence the experimental warning,
+> either install `better-sqlite3` or run Node with `--no-warnings`.
+
+---
+
 ## How it works
 
 Every collection is a single SQLite table:
@@ -325,8 +386,9 @@ and `updated_at` are real columns. SQLite's built-in `json_extract` /
 `json_each` power all document queries. No columns are added per field, so
 there is no schema and no migration — ever.
 
-All operations are synchronous under the hood (better-sqlite3 is sync) but are
-exposed as `async` (they return Promises) for API consistency and future-proofing.
+All operations are synchronous under the hood (both SQLite backends are sync)
+but are exposed as `async` (they return Promises) for API consistency and
+future-proofing.
 
 ### Notes & limitations
 

package/dist/index.cjs

@@ -1,13 +1,10 @@
 'use strict';
 
-var Database = require('better-sqlite3');
 var crypto = require('crypto');
+var module$1 = require('module');
 
-function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
-
-var Database__default = /*#__PURE__*/_interopDefault(Database);
-
-// src/db.ts
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+// src/id.ts
 var PROCESS_UNIQUE = crypto.randomBytes(5);
 var counter = crypto.randomBytes(3).readUIntBE(0, 3);
 function objectId() {
@@ -382,6 +379,44 @@ function aggregate(ctx, args) {
   }
   return result;
 }
+var HAVING_FNS = [
+  ["_sum", "SUM"],
+  ["_avg", "AVG"],
+  ["_min", "MIN"],
+  ["_max", "MAX"]
+];
+function comparisonSql(expr, cmp2, params) {
+  const out = [];
+  const ops = [
+    ["equals", "="],
+    ["not", "<>"],
+    ["gt", ">"],
+    ["gte", ">="],
+    ["lt", "<"],
+    ["lte", "<="]
+  ];
+  for (const [key, op] of ops) {
+    const v = cmp2[key];
+    if (v === void 0) continue;
+    params.push(v);
+    out.push(`${expr} ${op} ?`);
+  }
+  return out;
+}
+function buildHaving(having, params) {
+  const parts = [];
+  if (having._count) {
+    parts.push(...comparisonSql("COUNT(*)", having._count, params));
+  }
+  for (const [kind, fn] of HAVING_FNS) {
+    const selection = having[kind];
+    if (!selection) continue;
+    for (const field of Object.keys(selection)) {
+      parts.push(...comparisonSql(`${fn}(${fieldExpr(field)})`, selection[field], params));
+    }
+  }
+  return parts.join(" AND ");
+}
 function groupBy(ctx, args) {
   if (!Array.isArray(args.by) || args.by.length === 0) {
     throw new Error("groupBy requires a non-empty `by` array");
@@ -400,6 +435,10 @@ function groupBy(ctx, args) {
   const { selects: accSelects, cols } = buildAccumulators(args, ctx.onPath);
   selects.push(...accSelects);
   let sql = `SELECT ${selects.join(", ")} FROM "${ctx.table}" WHERE ${where} GROUP BY ${groupExprs.join(", ")}`;
+  if (args.having) {
+    const havingSql = buildHaving(args.having, params);
+    if (havingSql) sql += ` HAVING ${havingSql}`;
+  }
   if (args.orderBy) {
     const parts = [];
     for (const key of Object.keys(args.orderBy)) {
@@ -445,7 +484,7 @@ var Collection = class {
   initialized = false;
   trackPath = (path) => this.mon.autoIndexer.track(this.name, path);
   get db() {
-    return this.mon.sqlite;
+    return this.mon.driver;
   }
   ensureTable() {
     if (this.initialized) return;
@@ -491,13 +530,12 @@ var Collection = class {
     const stmt = this.db.prepare(
       `INSERT INTO "${this.name}" (_id, data, created_at, updated_at) VALUES (?, ?, ?, ?)`
     );
-    const insertAll = this.db.transaction((items) => {
-      for (const item of items) {
+    this.db.transaction(() => {
+      for (const item of args.data) {
         const row = this.prepareInsert(item);
         stmt.run(row._id, row.data, row.created_at, row.updated_at);
       }
     });
-    insertAll(args.data);
     return { count: args.data.length };
   }
   /* ------------------------------ read ------------------------------ */
@@ -537,6 +575,24 @@ var Collection = class {
     const row = this.db.prepare(`SELECT COUNT(*) AS n FROM "${this.name}" WHERE ${where}`).get(...params);
     return row.n;
   }
+  /**
+   * Return the distinct values of a field across the collection. Array fields
+   * are unwound (each element counts as a value), matching MongoDB's `distinct`.
+   */
+  async distinct(field, where) {
+    this.ensureTable();
+    const params = [];
+    const clause = buildWhere(where, { params, onPath: this.trackPath });
+    let sql;
+    if (isReserved(field)) {
+      sql = `SELECT DISTINCT ${fieldExpr(field)} AS v FROM "${this.name}" WHERE ${clause} ORDER BY v`;
+    } else {
+      this.trackPath(field);
+      sql = `SELECT DISTINCT je.value AS v FROM "${this.name}" CROSS JOIN json_each("${this.name}".data, ${pathLiteral(field)}) je WHERE ${clause} ORDER BY v`;
+    }
+    const rows = this.db.prepare(sql).all(...params);
+    return rows.map((r) => r.v);
+  }
   /* ----------------------------- update ----------------------------- */
   runUpdate(where, data, single) {
     this.ensureTable();
@@ -550,7 +606,7 @@ var Collection = class {
     const stmt = this.db.prepare(
       `UPDATE "${this.name}" SET data = ?, updated_at = ? WHERE _id = ?`
     );
-    const txn = this.db.transaction(() => {
+    return this.db.transaction(() => {
       const out = [];
       for (const row of rows) {
         const current = JSON.parse(row.data);
@@ -565,7 +621,6 @@ var Collection = class {
       }
       return out;
     });
-    return txn();
   }
   async update(args) {
     return this.runUpdate(args.where, args.data, true)[0] ?? null;
@@ -595,10 +650,9 @@ var Collection = class {
     const rows = this.db.prepare(selectSql).all(...params);
     if (!rows.length) return [];
     const stmt = this.db.prepare(`DELETE FROM "${this.name}" WHERE _id = ?`);
-    const txn = this.db.transaction(() => {
+    this.db.transaction(() => {
       for (const row of rows) stmt.run(row._id);
     });
-    txn();
     return rows.map((r) => this.rowToDoc(r));
   }
   async delete(args) {
@@ -676,6 +730,134 @@ var AutoIndexer = class {
   }
 };
 
+// src/driver/better-sqlite3.ts
+var BetterSqlite3Driver = class {
+  name = "better-sqlite3";
+  raw;
+  verbose;
+  constructor(BetterSqlite3, filename, options) {
+    this.verbose = options.verbose;
+    this.raw = new BetterSqlite3(filename, {
+      readonly: options.readonly ?? false
+    });
+    if (!options.readonly && (options.wal ?? true)) {
+      this.raw.pragma("journal_mode = WAL");
+    }
+  }
+  exec(sql) {
+    this.verbose?.(sql);
+    this.raw.exec(sql);
+  }
+  prepare(sql) {
+    this.verbose?.(sql);
+    return this.raw.prepare(sql);
+  }
+  transaction(fn) {
+    return this.raw.transaction(fn)();
+  }
+  close() {
+    this.raw.close();
+  }
+};
+
+// src/driver/node-sqlite.ts
+var NodeSqliteDriver = class {
+  name = "node:sqlite";
+  raw;
+  verbose;
+  depth = 0;
+  constructor(nodeSqlite, filename, options) {
+    this.verbose = options.verbose;
+    const { DatabaseSync } = nodeSqlite;
+    this.raw = new DatabaseSync(filename, {
+      readOnly: options.readonly ?? false
+    });
+    if (!options.readonly && (options.wal ?? true)) {
+      this.raw.exec("PRAGMA journal_mode = WAL");
+    }
+  }
+  exec(sql) {
+    this.verbose?.(sql);
+    this.raw.exec(sql);
+  }
+  prepare(sql) {
+    this.verbose?.(sql);
+    const stmt = this.raw.prepare(sql);
+    return {
+      run: (...p) => stmt.run(...p),
+      get: (...p) => stmt.get(...p),
+      all: (...p) => stmt.all(...p)
+    };
+  }
+  transaction(fn) {
+    const savepoint = `monlite_sp_${this.depth}`;
+    if (this.depth === 0) this.raw.exec("BEGIN");
+    else this.raw.exec(`SAVEPOINT ${savepoint}`);
+    this.depth++;
+    try {
+      const result = fn();
+      this.depth--;
+      if (this.depth === 0) this.raw.exec("COMMIT");
+      else this.raw.exec(`RELEASE ${savepoint}`);
+      return result;
+    } catch (err) {
+      this.depth--;
+      if (this.depth === 0) this.raw.exec("ROLLBACK");
+      else this.raw.exec(`ROLLBACK TO ${savepoint}; RELEASE ${savepoint}`);
+      throw err;
+    }
+  }
+  close() {
+    this.raw.close();
+  }
+};
+
+// src/driver/index.ts
+var req = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)));
+function loadBetterSqlite3() {
+  try {
+    const mod = req("better-sqlite3");
+    return mod?.default ?? mod;
+  } catch {
+    return null;
+  }
+}
+function loadNodeSqlite() {
+  try {
+    return req("node:sqlite");
+  } catch {
+    return null;
+  }
+}
+function createDriver(filename, options = {}) {
+  const choice = options.driver ?? "auto";
+  if (choice === "better-sqlite3") {
+    const mod = loadBetterSqlite3();
+    if (!mod) {
+      throw new MonliteError(
+        `driver "better-sqlite3" was requested but the package is not installed. Run \`npm install better-sqlite3\`.`
+      );
+    }
+    return new BetterSqlite3Driver(mod, filename, options);
+  }
+  if (choice === "node:sqlite") {
+    const mod = loadNodeSqlite();
+    if (!mod) {
+      throw new MonliteError(
+        `driver "node:sqlite" is unavailable. It requires Node >= 22.5.`
+      );
+    }
+    return new NodeSqliteDriver(mod, filename, options);
+  }
+  const better = loadBetterSqlite3();
+  if (better) return new BetterSqlite3Driver(better, filename, options);
+  const node = loadNodeSqlite();
+  if (node) return new NodeSqliteDriver(node, filename, options);
+  throw new MonliteError(
+    `No SQLite driver available. Either install better-sqlite3 (\`npm install better-sqlite3\`) or run on Node >= 22.5 for the built-in node:sqlite backend.`
+  );
+}
+
 // src/db.ts
 function validateName(name) {
   if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
@@ -697,27 +879,33 @@ function buildTagged(strings, values) {
   return { sql, params };
 }
 var Monlite = class {
-  /** The underlying better-sqlite3 connection (escape hatch). */
-  sqlite;
+  /** @internal The active SQLite driver. */
+  driver;
   /** @internal */
   autoIndexer;
   collections = /* @__PURE__ */ new Map();
   closed = false;
   constructor(filename, options = {}) {
-    const verbose = options.verbose;
-    this.sqlite = new Database__default.default(filename, {
-      readonly: options.readonly ?? false,
-      ...verbose ? { verbose: (msg) => verbose(String(msg)) } : {}
+    this.driver = createDriver(filename, {
+      driver: options.driver,
+      readonly: options.readonly,
+      wal: options.wal,
+      verbose: options.verbose
     });
-    if (!options.readonly && (options.wal ?? true)) {
-      this.sqlite.pragma("journal_mode = WAL");
-    }
     this.autoIndexer = new AutoIndexer(
-      this.sqlite,
+      this.driver,
       options.autoIndex ?? true,
       options.autoIndexAfter ?? 10
     );
   }
+  /** The underlying native database handle (escape hatch). */
+  get sqlite() {
+    return this.driver.raw;
+  }
+  /** Name of the active backend: `"better-sqlite3"` or `"node:sqlite"`. */
+  get driverName() {
+    return this.driver.name;
+  }
   /** Get (or lazily create) a typed collection handle. */
   collection(name) {
     this.assertOpen();
@@ -733,26 +921,26 @@ var Monlite = class {
   $queryRaw(strings, ...values) {
     this.assertOpen();
     const { sql, params } = buildTagged(strings, values);
-    return Promise.resolve(this.sqlite.prepare(sql).all(...params));
+    return Promise.resolve(this.driver.prepare(sql).all(...params));
   }
   /** Like {@link $queryRaw} but takes a raw SQL string and positional params. */
   $queryRawUnsafe(sql, ...params) {
     this.assertOpen();
     return Promise.resolve(
-      this.sqlite.prepare(sql).all(...params.map(bindable))
+      this.driver.prepare(sql).all(...params.map(bindable))
     );
   }
   /** Tagged-template SQL statement returning the number of affected rows. */
   $executeRaw(strings, ...values) {
     this.assertOpen();
     const { sql, params } = buildTagged(strings, values);
-    return Promise.resolve(this.sqlite.prepare(sql).run(...params).changes);
+    return Promise.resolve(this.driver.prepare(sql).run(...params).changes);
   }
   /** Like {@link $executeRaw} but takes a raw SQL string and positional params. */
   $executeRawUnsafe(sql, ...params) {
     this.assertOpen();
     return Promise.resolve(
-      this.sqlite.prepare(sql).run(...params.map(bindable)).changes
+      this.driver.prepare(sql).run(...params.map(bindable)).changes
     );
   }
   /**
@@ -761,13 +949,12 @@ var Monlite = class {
    */
   async $transaction(fn) {
     this.assertOpen();
-    const txn = this.sqlite.transaction(() => fn(this));
-    return txn();
+    return this.driver.transaction(() => fn(this));
   }
   /** List all collection (table) names. */
   $collections() {
     this.assertOpen();
-    const rows = this.sqlite.prepare(
+    const rows = this.driver.prepare(
       `SELECT name FROM sqlite_master
          WHERE type='table' AND name NOT LIKE 'sqlite_%'
          ORDER BY name`
@@ -778,7 +965,7 @@ var Monlite = class {
   $drop(name) {
     this.assertOpen();
     validateName(name);
-    this.sqlite.exec(`DROP TABLE IF EXISTS "${name}"`);
+    this.driver.exec(`DROP TABLE IF EXISTS "${name}"`);
     this.collections.delete(name);
     this.autoIndexer.reset(name);
     return Promise.resolve();
@@ -791,7 +978,7 @@ var Monlite = class {
   $disconnect() {
     if (!this.closed) {
       this.closed = true;
-      this.sqlite.close();
+      this.driver.close();
     }
     return Promise.resolve();
   }