@ix-xs/node-comfort 2.1.0 → 2.2.0

package/src/SQLite.js

@@ -1,7 +1,7 @@
 "use strict";
 
 /**
- * SQLite made pleasant, on the engine built into Node.js (22.13+): CRUD with
+ * SQLite made pleasant, on the engine built into Node.js: CRUD with
  * rich filters, JSON and boolean columns, transactions, migrations and
  * backups. Methods are synchronous, like the engine, but `await` still
  * works. Errors are `SQLiteError`s. Values are always bound as parameters
@@ -19,6 +19,10 @@
  * });
  * db.insert("users", { email: "ada@example.com", settings: { theme: "dark" } });
  * db.getAll("users", { email: { like: "%@example.com" } }, { orderBy: "email", limit: 20 });
+ *
+ * // Values from a request can't turn into operators:
+ * const safe = new nc.SQLite("data/app.sqlite", { operators: "tagged" });
+ * safe.getAll("users", { age: nc.SQLite.op.gte(18), role: nc.SQLite.op.in(["admin", "editor"]) });
  */
 
 const nodePath = require("node:path");
@@ -48,14 +52,15 @@ const { toMs } = require("./internal/shared.js");
  * @property {unknown} [defaultValue] Objects work for JSON columns, booleans for BOOLEAN ones. `"CURRENT_TIMESTAMP"`, `"CURRENT_DATE"` and `"CURRENT_TIME"` mean the moment of the insert.
  * @property {string} [defaultExpression] A default computed by SQLite, like `"(unixepoch())"` or `"(lower(hex(randomblob(16))))"`. Written into the table as is: never build it from user input.
  * @property {unknown[]} [values] Allowed values.
- * @property {string} [check] A `CHECK` expression, like `"price >= 0"`.
+ * @property {string} [check] A `CHECK` expression, like `"price >= 0"`. Written into the table as is: never build it from user input.
  * @property {{ table: string, column: string }} [references] Foreign key target.
  * @property {ForeignKeyAction} [onDelete] When the referenced row is deleted.
  * @property {ForeignKeyAction} [onUpdate] When the referenced key changes.
  */
 
 /**
- * A constraint on several columns.
+ * A constraint on several columns. The `expression` of a `check` is written
+ * into the table as is: never build it from user input.
  * @typedef {{ type: "unique", columns: string[] } | { type: "primaryKey", columns: string[] } | { type: "check", expression: string } | { type: "foreignKey", columns: string[], references: { table: string, columns: string[] }, onDelete?: ForeignKeyAction, onUpdate?: ForeignKeyAction }} TableConstraint
  */
 
@@ -65,7 +70,7 @@ const { toMs } = require("./internal/shared.js");
  * @property {string[]} columns Several columns make a composite index.
  * @property {boolean} [unique]
  * @property {string} [name] Defaults to `idx_<table>_<columns>`.
- * @property {string} [where] Makes it a partial index, like `"deleted_at IS NULL"`.
+ * @property {string} [where] Makes it a partial index, like `"deleted_at IS NULL"`. Written into the index as is: never build it from user input.
  */
 
 /**
@@ -101,6 +106,13 @@ const { toMs } = require("./internal/shared.js");
  * `IS NULL`, an array means "one of", and an object uses operators. Keys
  * combine with AND; use `$or` and `$and` for the rest.
  *
+ * A value taken from a request must be checked first (parsed JSON like
+ * `{ "ne": "" }` would act as an operator), or the database opened with
+ * `operators: "tagged"`, where only `SQLite.op` makes operators.
+ *
+ * On a read, a missing value drops its condition: check required values
+ * first (writes, and reads with `operators: "tagged"`, throw instead).
+ *
  * A key with dots looks inside a JSON column: `"settings.theme"` is the
  * `theme` key of the `settings` column, `"tags.0"` the first item of `tags`.
  *
@@ -108,6 +120,7 @@ const { toMs } = require("./internal/shared.js");
  * { status: "active", age: { gte: 18, lt: 65 }, role: ["admin", "editor"], deleted_at: null }
  * { $or: [{ email: { like: "%@acme.com" } }, { vip: true }] }
  * { "settings.theme": "dark", "settings.beta": true }
+ * { age: nc.SQLite.op.gte(18), role: nc.SQLite.op.in(["admin", "editor"]) }
  *
  * @template [R=Record<string, any>] Row type; its keys are suggested as columns.
  * @typedef {{ [K in keyof R]?: WhereValue } & { [path: `${string}.${string}`]: WhereValue } & { $or?: Where<R>[], $and?: Where<R>[] }} Where
@@ -115,7 +128,33 @@ const { toMs } = require("./internal/shared.js");
 
 /**
  * The condition for one column: a value, `null`, an array, or operators.
- * @typedef {null | string | number | bigint | boolean | Date | Uint8Array | readonly unknown[] | WhereOperators} WhereValue
+ * @typedef {null | string | number | bigint | boolean | Date | Uint8Array | readonly unknown[] | WhereOperators | TaggedOperator} WhereValue
+ */
+
+/**
+ * An operator made by `SQLite.op`. It carries a mark that JSON can't
+ * produce, so it's an operator with `operators: "tagged"` too. Several can
+ * be spread into one object: `{ ...op.gte(18), ...op.lt(65) }`.
+ * @typedef {Readonly<WhereOperators>} TaggedOperator
+ */
+
+/**
+ * The helpers of `SQLite.op`, one per filter operator.
+ * @typedef {object} OperatorHelpers
+ * @property {(value: unknown) => TaggedOperator} eq Equal. `null` means `IS NULL`.
+ * @property {(value: unknown) => TaggedOperator} ne Not equal. Rows where the column is `NULL` match too.
+ * @property {(value: number | string | bigint | Date) => TaggedOperator} gt Greater than.
+ * @property {(value: number | string | bigint | Date) => TaggedOperator} gte Greater than or equal.
+ * @property {(value: number | string | bigint | Date) => TaggedOperator} lt Less than.
+ * @property {(value: number | string | bigint | Date) => TaggedOperator} lte Less than or equal.
+ * @property {(values: readonly unknown[]) => TaggedOperator} in One of these values.
+ * @property {(values: readonly unknown[]) => TaggedOperator} notIn None of these values.
+ * @property {(pattern: string) => TaggedOperator} like A `LIKE` pattern: `%` any text, `_` one character.
+ * @property {(pattern: string) => TaggedOperator} notLike
+ * @property {(pattern: string) => TaggedOperator} glob A case-sensitive pattern: `*` any text, `?` one character.
+ * @property {(min: unknown, max: unknown) => TaggedOperator} between From `min` to `max`, both included.
+ * @property {() => TaggedOperator} isNull `IS NULL`.
+ * @property {() => TaggedOperator} notNull `IS NOT NULL`.
  */
 
 /**
@@ -138,12 +177,13 @@ const { toMs } = require("./internal/shared.js");
  * @typedef {object} SQLiteOptions
  * @property {boolean} [json] Parse `JSON` columns. Defaults to `true`.
  * @property {boolean} [booleans] Return `BOOLEAN` columns as `true`/`false`. Defaults to `true`.
- * @property {boolean} [dates] Return `DATE`, `DATETIME` and `TIMESTAMP` columns as `Date`s.
+ * @property {boolean} [dates] Return `DATE`, `DATETIME` and `TIMESTAMP` columns as `Date`s. Defaults to `false`.
  * @property {boolean} [wal] Write-ahead logging: faster, and reads don't wait for writes. Defaults to `true`.
  * @property {boolean} [foreignKeys] Enforce foreign keys. Defaults to `true`.
  * @property {number | string} [busyTimeout] How long to wait for a lock held by another connection, in ms or like `"5s"`. Defaults to 5 seconds.
  * @property {"OFF" | "NORMAL" | "FULL" | "EXTRA"} [synchronous] How hard SQLite pushes each commit to the disk. With `wal`, `"NORMAL"` writes several times faster and can't corrupt the file; a power cut may undo the last commits. Defaults to SQLite's own setting, `"FULL"`.
  * @property {boolean} [readOnly]
+ * @property {"plain" | "tagged"} [operators] What makes an object in a filter an operator. `"plain"`, the default: any object with an operator key, like `{ gte: 18 }`, and an array means "one of". `"tagged"`: only the operators made by `SQLite.op`, any other object or array is a value compared as JSON text, so a value taken from a request can never become an operator.
  */
 
 /**
@@ -215,7 +255,7 @@ const { toMs } = require("./internal/shared.js");
 
 /**
  * A prepared query and what's needed to turn its rows into objects.
- * @typedef {{ stmt: import("node:sqlite").StatementSync, names: string[] | undefined, kinds: Uint8Array | undefined, table: string | undefined }} _Reader
+ * @typedef {{ stmt: import("node:sqlite").StatementSync, names: string[], kinds: Uint8Array | undefined }} _Reader
  */
 
 const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -229,6 +269,8 @@ const SOURCE_EXISTS = EXISTS("'table', 'view'");
 const JSON_KIND = 1;
 const BOOLEAN_KIND = 2;
 const DATE_KIND = 3;
+// Marks the operators made by SQLite.op. JSON can't produce a symbol key, so a parsed request never carries it.
+const TAGGED = Symbol("nc.SQLite.op");
 const OPERATORS = new Set(["eq", "ne", "gt", "gte", "lt", "lte", "in", "notIn", "like", "notLike", "glob", "between", "isNull"]);
 const COMPARATORS = /** @type {Record<string, string>} */ ({ gt: ">", gte: ">=", lt: "<", lte: "<=", like: "LIKE", notLike: "NOT LIKE", glob: "GLOB" });
 const ACTIONS = ["CASCADE", "SET NULL", "SET DEFAULT", "RESTRICT", "NO ACTION"];
@@ -268,7 +310,7 @@ const _engine = () => {
   try {
     _DatabaseSync = require("node:sqlite").DatabaseSync;
   } catch (error) {
-    throw new SQLiteError(`node:sqlite is not available in Node.js ${process.version}: nc.SQLite requires Node.js 22.13 or newer`, { cause: error });
+    throw new SQLiteError(`node:sqlite is not available in Node.js ${process.version}: nc.SQLite requires Node.js 22.23.4, 24.22.1, 26.12.1 or newer`, { cause: error });
   } finally {
     process.emitWarning = original;
   }
@@ -407,6 +449,31 @@ const _insertVerb = (options) => {
   return mode === "ignore" ? "INSERT OR IGNORE" : "INSERT OR REPLACE";
 };
 
+/**
+ * @param {string} name
+ * @param {unknown} operand
+ * @returns {TaggedOperator}
+ */
+const _tag = (name, operand) => /** @type {TaggedOperator} */ (Object.freeze({ [name]: operand, [TAGGED]: true }));
+
+/** @type {OperatorHelpers} */
+const OP = Object.freeze({
+  eq: (value) => _tag("eq", value),
+  ne: (value) => _tag("ne", value),
+  gt: (value) => _tag("gt", value),
+  gte: (value) => _tag("gte", value),
+  lt: (value) => _tag("lt", value),
+  lte: (value) => _tag("lte", value),
+  in: (values) => _tag("in", values),
+  notIn: (values) => _tag("notIn", values),
+  like: (pattern) => _tag("like", pattern),
+  notLike: (pattern) => _tag("notLike", pattern),
+  glob: (pattern) => _tag("glob", pattern),
+  between: (min, max) => _tag("between", [min, max]),
+  isNull: () => _tag("isNull", true),
+  notNull: () => _tag("isNull", false),
+});
+
 /**
  * Removes quoted strings and names, to look for `;` safely.
  * @param {string} sql
@@ -420,6 +487,23 @@ const _stripQuoted = (sql) => sql.replace(/'(?:''|[^'])*'|"(?:""|[^"])*"/g, "");
  * @template [R=Record<string, any>] The row type read methods return by default. Each call can override it.
  */
 class SQLite {
+  /**
+   * Filter operators that only code can make. Plain objects like
+   * `{ gte: 18 }` still work, unless the database was opened with
+   * `operators: "tagged"`: then only these are operators, and a value
+   * taken from a request stays a value.
+   *
+   * @example
+   * const { op } = nc.SQLite;
+   * const db = new nc.SQLite("data/app.sqlite", { operators: "tagged" });
+   * db.getAll("users", { age: op.between(18, 65), role: op.in(["admin", "editor"]), deleted_at: op.isNull() });
+   * // { "ne": "" } in the body is compared as text, not run, and a missing token throws
+   * db.get("users", { email, token: body.token });
+   *
+   * @type {OperatorHelpers}
+   */
+  static op = OP;
+
   /** @type {import("node:sqlite").DatabaseSync} */
   #db;
   /** @type {Map<string, import("node:sqlite").StatementSync>} */
@@ -429,14 +513,12 @@ class SQLite {
   // Tables and views known to exist, so that each call doesn't ask SQLite again.
   /** @type {Set<string>} */
   #known = new Set();
-  /** @type {Map<string, Map<string, number>>} */
-  #columnKinds = new Map();
-  /** @type {Map<string, string | undefined>} */
-  #sources = new Map();
   /** @type {{ json: boolean, booleans: boolean, dates: boolean }} */
   #read;
   #depth = 0;
   #open = true;
+  // With operators: "tagged", only SQLite.op makes operators.
+  #tagged = false;
   /** @type {string} */
   #path;
 
@@ -454,6 +536,9 @@ class SQLite {
    * @throws {SQLiteError} If the file can't be opened.
    */
   constructor(path = "db.sqlite", options = {}) {
+    const operators = options.operators ?? "plain";
+    if (operators !== "plain" && operators !== "tagged") throw new SQLiteError(`Invalid operators "${String(operators)}" (use "plain" or "tagged")`);
+    this.#tagged = operators === "tagged";
     const DatabaseSync = _engine();
     const memory = path === ":memory:" || path === "";
     const target = memory ? ":memory:" : nodePath.resolve(process.cwd(), path);
@@ -494,9 +579,9 @@ class SQLite {
   }
 
   /**
-   * A prepared query. Where Node allows it, rows are fetched as arrays and
-   * turned into objects here: it's faster than copying the objects Node
-   * returns, and Node says which column each value comes from.
+   * A prepared query. Rows are fetched as arrays and turned into objects here:
+   * it's faster than copying the objects Node returns, and Node says which
+   * column each value comes from.
    * @param {string} sql
    * @param {boolean} [keep=true] `false` for a statement used once, like an iteration.
    * @returns {_Reader}
@@ -510,14 +595,9 @@ class SQLite {
     } catch (error) {
       throw _wrap(error, sql);
     }
-    reader = { stmt, names: undefined, kinds: undefined, table: undefined };
-    const modern = /** @type {any} */ (stmt);
-    if (typeof modern.setReturnArrays === "function" && typeof modern.columns === "function") {
-      modern.setReturnArrays(true);
-      this.#describe(reader);
-    } else {
-      reader.table = this.#sourceTable(sql);
-    }
+    stmt.setReturnArrays(true);
+    reader = { stmt, names: [], kinds: undefined };
+    this.#describe(reader);
     if (keep) {
       if (this.#readers.size >= 500) this.#readers.delete(/** @type {string} */ (this.#readers.keys().next().value));
       this.#readers.set(sql, reader);
@@ -530,8 +610,7 @@ class SQLite {
    * @param {_Reader} reader
    */
   #describe(reader) {
-    /** @type {Array<{ name: string, type: string | null }>} */
-    const columns = /** @type {any} */ (reader.stmt).columns();
+    const columns = reader.stmt.columns();
     reader.names = columns.map((column) => column.name);
     reader.kinds = undefined;
     for (let i = 0; i < columns.length; i++) {
@@ -549,16 +628,6 @@ class SQLite {
   #row(reader, raw) {
     /** @type {Record<string, unknown>} */
     const row = {};
-    if (reader.names === undefined) {
-      // Node before 22.16: a row is an object without a prototype, copied into a plain one.
-      for (const key in raw) row[key] = raw[key];
-      if (reader.table === undefined) return row;
-      for (const [key, kind] of this.#kinds(reader.table)) {
-        const value = row[key];
-        if (value !== null && value !== undefined) row[key] = _convert(kind, value);
-      }
-      return row;
-    }
     // A statement prepared before the table changed can come back with other columns.
     if (raw.length !== reader.names.length) this.#describe(reader);
     const names = reader.names;
@@ -621,71 +690,79 @@ class SQLite {
    * @returns {void}
    */
   #invalidate() {
-    this.#columnKinds.clear();
     this.#statements.clear();
     this.#readers.clear();
     this.#known.clear();
-    this.#sources.clear();
-  }
-
-  /**
-   * The columns of a table that are converted when read. Only used on Node
-   * versions that don't describe the columns of a query.
-   * @param {string} table
-   * @returns {Map<string, number>}
-   */
-  #kinds(table) {
-    let kinds = this.#columnKinds.get(table);
-    if (!kinds) {
-      kinds = new Map();
-      for (const col of /** @type {Array<{ name: string, type: string }>} */ (/** @type {unknown} */ (this.#prepare(`PRAGMA table_info(${_id(table, "table name")})`).all()))) {
-        const kind = _kindOf(String(col.type).toUpperCase(), this.#read);
-        if (kind) kinds.set(col.name, kind);
-      }
-      this.#columnKinds.set(table, kinds);
-    }
-    return kinds;
   }
 
   /**
    * @param {Where<any> | undefined} where
+   * @param {string} [write] The method, for a filter that changes rows: then no condition may be skipped, and the filter must not match every row.
+   * @param {string} [read] The method, for a read: with operators: "tagged", no condition may be skipped either.
    * @returns {{ sql: string, params: any[] }}
    */
-  #where(where) {
+  #where(where, write, read) {
     if (!where || !Object.keys(where).length) return { sql: "", params: [] };
+    const tagged = this.#tagged;
+    // where a missing value throws rather than drops its condition (a token left out would let anyone in)
+    const strict = write ?? (tagged ? read ?? "read" : undefined);
     /** @type {any[]} */
     const params = [];
     /**
      * @param {Where<any>} filter
+     * @param {string} at Where this filter is, for error messages.
      * @returns {string}
      */
-    const build = (filter) => {
+    const build = (filter, at) => {
       if (!_isPlain(filter)) throw new SQLiteError("A where filter must be a plain object");
       /** @type {string[]} */
       const parts = [];
       for (const [key, value] of Object.entries(filter)) {
-        if (value === undefined) continue;
+        if (value === undefined) {
+          // a missing value would drop its condition, and the query would reach more rows
+          if (strict) throw new SQLiteError(`${strict}(): ${at}.${key} is undefined`);
+          continue;
+        }
         if (key === "$or" || key === "$and") {
           if (!Array.isArray(value)) throw new SQLiteError(`"${key}" expects an array of filters`);
-          const subs = value.map((sub) => build(sub) || "1");
+          if (write) {
+            if (!value.length) throw new SQLiteError(`${write}(): ${at}.${key} is empty`);
+            const subs = value.map((sub, i) => {
+              const sql = build(sub, `${at}.${key}[${i}]`);
+              if (!sql) throw new SQLiteError(`${write}(): ${at}.${key}[${i}] matches every row`);
+              return `(${sql})`;
+            });
+            parts.push(`(${subs.join(key === "$or" ? " OR " : " AND ")})`);
+            continue;
+          }
+          const subs = value.map((sub, i) => build(sub, strict ? `${at}.${key}[${i}]` : at) || "1");
           parts.push(subs.length ? `(${subs.map((s) => `(${s})`).join(key === "$or" ? " OR " : " AND ")})` : key === "$or" ? "0" : "1");
           continue;
         }
         const col = _column(key);
         if (value === null) parts.push(`${col} IS NULL`);
-        else if (Array.isArray(value)) parts.push(this.#op(col, "in", value, params));
-        else if (_isPlain(value) && Object.keys(value).some((k) => OPERATORS.has(k))) {
+        else if (Array.isArray(value) && !tagged) parts.push(this.#op(col, "in", value, params));
+        else if (_isPlain(value) && (/** @type {any} */ (value)[TAGGED] === true || (!tagged && Object.keys(value).some((k) => OPERATORS.has(k))))) {
           // unknown keys next to operators are typos: #op() reports them
-          for (const [op, operand] of Object.entries(value)) if (operand !== undefined) parts.push(this.#op(col, op, operand, params));
+          for (const [op, operand] of Object.entries(value)) {
+            if (operand === undefined) {
+              if (strict) throw new SQLiteError(`${strict}(): ${at}.${key}.${op} is undefined`);
+              continue;
+            }
+            const sql = this.#op(col, op, operand, params);
+            // "1" (an empty notIn) holds for every row: for a write, it's no condition at all
+            if (!write || sql !== "1") parts.push(sql);
+          }
         } else {
-          // other objects and arrays compare as JSON text
+          // other objects and arrays (all of them with operators: "tagged") compare as JSON text
           parts.push(`${col} = ?`);
           params.push(_toSQL(value));
         }
       }
       return parts.join(" AND ");
     };
-    const sql = build(where);
+    const sql = build(where, "where");
+    if (write && !sql) throw new SQLiteError(`${write}() refuses a where filter that matches every row${write === "delete" ? " (use clearTable() to delete every row)" : ""}`);
     return { sql: sql ? ` WHERE ${sql}` : "", params };
   }
 
@@ -789,25 +866,6 @@ class SQLite {
     }
   }
 
-  /**
-   * The table a simple `SELECT` reads from, for type conversions.
-   * @param {string} sql
-   * @returns {string | undefined}
-   */
-  #sourceTable(sql) {
-    if (this.#sources.has(sql)) return this.#sources.get(sql);
-    /** @type {string | undefined} */
-    let table;
-    if (!/\bjoin\b/i.test(sql)) {
-      const match = /^\s*select\b[\s\S]*?\bfrom\s+"?([A-Za-z_][A-Za-z0-9_]*)"?(?:\s+(?:as\s+)?(?!where\b|order\b|limit\b|group\b)[A-Za-z_]\w*)?\s*(?:where\b|order\b|limit\b|group\b|;|$)/i.exec(sql);
-      // A view has column types too: SQLite takes them from the tables it reads.
-      if (match && (this.#known.has(match[1]) || this.#prepare(SOURCE_EXISTS).get(match[1]) !== undefined)) table = match[1];
-    }
-    if (this.#sources.size >= 500) this.#sources.clear();
-    this.#sources.set(sql, table);
-    return table;
-  }
-
   /**
    * Runs SQL that doesn't return rows. Without parameters, you can pass
    * several statements at once.
@@ -844,8 +902,7 @@ class SQLite {
 
   /**
    * Runs a query and returns the first row. JSON and boolean columns are
-   * converted like in `get()`, joins and renamed columns included. On Node.js
-   * before 22.16, that only works for a query on a single table.
+   * converted like in `get()`, joins and renamed columns included.
    *
    * @example
    * const user = db.queryOne("SELECT * FROM users WHERE email = ?", [email]);
@@ -1126,7 +1183,7 @@ class SQLite {
   #select(tableName, where, options, single) {
     const table = this.#table(tableName);
     const columns = options.columns?.length ? options.columns.map((c) => _id(c, "column name")).join(", ") : "*";
-    const clause = this.#where(where);
+    const clause = this.#where(where, undefined, single ? "get" : "getAll");
     let sql = `SELECT ${columns} FROM ${table}${clause.sql}${this.#orderBy(options)}`;
     if (single) {
       sql += " LIMIT 1";
@@ -1176,7 +1233,7 @@ class SQLite {
    * @throws {SQLiteError}
    */
   count(tableName, where = {}) {
-    const clause = this.#where(where);
+    const clause = this.#where(where, undefined, "count");
     const sql = `SELECT COUNT(*) AS total FROM ${this.#table(tableName)}${clause.sql}`;
     const stmt = this.#prepare(sql);
     try {
@@ -1198,7 +1255,7 @@ class SQLite {
    * @throws {SQLiteError}
    */
   exists(tableName, where = {}) {
-    const clause = this.#where(where);
+    const clause = this.#where(where, undefined, "exists");
     const sql = `SELECT 1 FROM ${this.#table(tableName)}${clause.sql} LIMIT 1`;
     const stmt = this.#prepare(sql);
     try {
@@ -1283,7 +1340,8 @@ class SQLite {
 
   /**
    * Updates the rows that match. The filter is required, so a forgotten
-   * condition can't rewrite the whole table.
+   * condition can't rewrite the whole table: an `undefined` value in it, an
+   * empty `$and` or `$or`, or a filter that matches every row throws.
    *
    * @example
    * db.update("users", { active: false }, { last_login: { lt: "2025-01-01" } });
@@ -1299,7 +1357,7 @@ class SQLite {
     if (!_isPlain(where) || !Object.keys(where).length) throw new SQLiteError("update() requires a non-empty where filter");
     const [cols, values] = this.#values(data);
     if (!cols.length) throw new SQLiteError("update() requires at least one column to change");
-    const clause = this.#where(where);
+    const clause = this.#where(where, "update");
     const { changes } = this.#run(`UPDATE ${table} SET ${cols.map((c) => `${c} = ?`).join(", ")}${clause.sql}`, [...values, ...clause.params]);
     return { ok: true, changes };
   }
@@ -1351,7 +1409,8 @@ class SQLite {
 
   /**
    * Deletes the rows that match. The filter is required; `clearTable()`
-   * deletes everything on purpose.
+   * deletes everything on purpose. An `undefined` value in the filter, an
+   * empty `$and` or `$or`, or a filter that matches every row throws.
    *
    * @example
    * db.delete("sessions", { expires_at: { lt: new Date() } });
@@ -1364,7 +1423,7 @@ class SQLite {
   delete(tableName, where) {
     const table = this.#table(tableName);
     if (!_isPlain(where) || !Object.keys(where).length) throw new SQLiteError("delete() requires a non-empty where filter (use clearTable() to delete every row)");
-    const clause = this.#where(where);
+    const clause = this.#where(where, "delete");
     const { changes } = this.#run(`DELETE FROM ${table}${clause.sql}`, clause.params);
     return { ok: true, changes };
   }
@@ -1373,7 +1432,7 @@ class SQLite {
    * Adds to number columns in one statement, so two requests at the same
    * moment both count. Reading the value, adding to it and writing it back
    * would lose one of them. Negative numbers subtract; an empty column
-   * counts as 0.
+   * counts as 0. The filter is checked like the one of `update()`.
    *
    * @example
    * db.increment("posts", { views: 1 }, { id: post.id });
@@ -1396,7 +1455,7 @@ class SQLite {
       const col = _id(column, "column name");
       return `${col} = COALESCE(${col}, 0) + ?`;
     });
-    const clause = this.#where(where);
+    const clause = this.#where(where, "increment");
     const { changes } = this.#run(`UPDATE ${table} SET ${set.join(", ")}${clause.sql}`, [...entries.map(([, amount]) => amount), ...clause.params]);
     return { ok: true, changes };
   }
@@ -1492,9 +1551,7 @@ class SQLite {
 
   /** Whether a transaction is open. */
   get inTransaction() {
-    // `isTransaction` exists since Node 22.16
-    const native = /** @type {{ isTransaction?: boolean }} */ (/** @type {unknown} */ (this.#db)).isTransaction;
-    return typeof native === "boolean" ? native : this.#depth > 0;
+    return this.#db.isTransaction;
   }
 
   /**