@jarenjs/db 0.34.0

package/src/driver.js

@@ -0,0 +1,419 @@
+//@ts-check
+/**
+ * @file The driver seam: the contract every binding satisfies, the
+ * capability probe that runs once at open, and the sync-capable-async
+ * helpers the store composes with.
+ *
+ * A driver is `{ name, dialect, open(path, options) }`; `open` returns
+ * a `Connection` or a promise of one. Every connection method may
+ * return a value or a promise — the store never assumes either, and
+ * composes through {@link chain}, which does not allocate a promise
+ * when the driver answered with a value. That is what keeps the public
+ * asynchronous surface from paying twice while the synchronous fast
+ * path stays exact.
+ *
+ * The runtime builtin behind a binding is imported LAZILY inside
+ * `open()` via {@link lazyOpen} — never at module scope — because the
+ * packed-consumer gate imports every export subpath under Node *and*
+ * Bun, Bun ships no `node:sqlite`, and Node cannot resolve `bun:`
+ * specifiers. `open()` is where "this driver does not exist here"
+ * becomes the coded `JD0003` instead of a module-load crash.
+ *
+ * `capabilities` is read once at open — from the library's version
+ * report, its compile options and the binding's declaration — and is
+ * the single source of truth for feature gating; never a `typeof`
+ * sniff at a call site. Two slots are deliberately EMPTY on every
+ * SQLite driver: `statementTimeout` (no interrupt or progress handler
+ * exists to build one on) and `rowEstimates` (the query plan is prose,
+ * not numbers). They exist so a driver that has the facts can fill
+ * them without a contract change; pretending SQLite has them is the
+ * silent degradation this suite refuses.
+ */
+
+import { DbCompileError } from './errors.js';
+
+/** The minimum SQLite the store accepts, asserted at open. */
+export const SQLITE_FLOOR = '3.45.0';
+
+/**
+ * How long work may wait for an open transaction to settle before it is
+ * rejected with `JD0012`. Matches the store's default busy timeout: the
+ * question "has this waited unreasonably long?" has one answer per
+ * connection whether the contention is another process (SQLite's own
+ * busy timeout) or another transaction on this one.
+ */
+export const DEFAULT_QUEUE_TIMEOUT = 5000;
+
+/**
+ * @param {any} value
+ * @returns {boolean} true when the value is a thenable
+ */
+export function isThenable(value) {
+  return value !== null && typeof value === 'object' && typeof value.then === 'function';
+}
+
+/**
+ * Sync-capable-async composition: apply `next` to a driver result
+ * without allocating a promise when the result is already a value.
+ * @param {any} value - A driver return: a value or a promise
+ * @param {(value: any) => any} next
+ * @returns {any} `next`'s result, promise-wrapped only if the input was
+ */
+export function chain(value, next) {
+  return isThenable(value) ? value.then(next) : next(value);
+}
+
+/**
+ * Lift a driver result into a promise — the ONE allocation the public
+ * asynchronous surface pays per call.
+ * @param {any} value
+ * @returns {Promise<any>}
+ */
+export function toPromise(value) {
+  return isThenable(value) ? value : Promise.resolve(value);
+}
+
+/**
+ * Compare two dotted version strings numerically.
+ * @param {string} a
+ * @param {string} b
+ * @returns {number} negative when a < b, zero when equal
+ */
+export function compareVersions(a, b) {
+  const pa = String(a).split('.');
+  const pb = String(b).split('.');
+  for (let i = 0; i < 3; i++) {
+    const d = (Number(pa[i]) || 0) - (Number(pb[i]) || 0);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * Load a runtime builtin lazily and hand it to the binding's adapter.
+ * A failed import — the specifier does not exist on this runtime —
+ * becomes `JD0003` carrying the loader's error as `cause`.
+ * @param {string} specifier - The builtin module specifier
+ * @param {string} reason - The `JD0003` reason for this binding
+ * @param {(mod: any, ...args: any[]) => any} use - The binding's
+ *   module-to-connection adapter (a named export so the suite can
+ *   exercise it with a substitute module on any runtime)
+ * @param {any[]} args - Extra arguments forwarded to `use`
+ * @returns {Promise<any>}
+ */
+export function lazyOpen(specifier, reason, use, args) {
+  return import(specifier).then(
+    (mod) => use(mod, ...args),
+    (cause) => {
+      throw new DbCompileError('JD0003', reason, undefined, cause);
+    });
+}
+
+/**
+ * Normalize a raw statement to the contract shape. A binding without a
+ * native `iterate` gets one composed over `all` — eager, but the same
+ * rows in the same order.
+ * @param {{ run: Function, get: Function, all: Function,
+ *   iterate?: Function }} statement
+ * @returns {{ run: Function, get: Function, all: Function,
+ *   iterate: Function }}
+ */
+export function wrapStatement(statement) {
+  return {
+    run: (params = []) => statement.run(params),
+    get: (params = []) => statement.get(params),
+    all: (params = []) => statement.all(params),
+    iterate: typeof statement.iterate === 'function'
+      ? (params = []) => /** @type {Function} */ (statement.iterate)(params)
+      : (params = []) => chain(statement.all(params),
+        (rows) => rows[Symbol.iterator]()),
+  };
+}
+
+/**
+ * Finish a raw binding into the connection contract: probe the library
+ * once, assert the version floor, freeze the capability table, and
+ * attach the savepoint-nested `transaction`.
+ *
+ * The raw shape a binding supplies:
+ * `{ exec(sql), prepare(sql) -> { run, get, all, iterate? }, close(),
+ *   registerFunction?, registerAggregate?, session? }` — every method
+ * value-or-promise.
+ *
+ * @param {any} raw
+ * @param {{ dialect: any, synchronous?: boolean, queueTimeout?: number,
+ *   declared?: { sessions?: boolean, userFunctions?: boolean,
+ *     deterministicIndexableFunctions?: boolean,
+ *     aggregateFunctions?: boolean } }} options
+ * @returns {any} a Connection, or a promise of one
+ */
+export function openConnection(raw, options) {
+  const { dialect } = options;
+  const synchronous = options.synchronous === true;
+  const declared = options.declared ?? {};
+  return chain(raw.prepare(dialect.introspect.version()), (versionStatement) =>
+    chain(versionStatement.get([]), (versionRow) => {
+      const version = String(versionRow.version);
+      if (compareVersions(version, SQLITE_FLOOR) < 0) {
+        throw new DbCompileError('JD0001',
+          `the SQLite library is ${version}, below the supported floor ${SQLITE_FLOOR}`);
+      }
+      return chain(raw.prepare(dialect.introspect.compileOptions()), (optionsStatement) =>
+        chain(optionsStatement.all([]), (rows) => {
+          const compiled = new Set(rows.map((row) => String(row.name)));
+          const capabilities = Object.freeze({
+            version,
+            // guaranteed by the version floor
+            jsonb: true,
+            generatedColumns: true,
+            returning: true,
+            upsert: true,
+            savepoints: true,
+            // read from the library's compile options
+            rtree: compiled.has('ENABLE_RTREE'),
+            fts: compiled.has('ENABLE_FTS5'),
+            // the binding must expose the API AND the library must
+            // carry the extension — either alone is not the capability
+            sessions: declared.sessions === true
+              && typeof raw.session === 'function'
+              && compiled.has('ENABLE_SESSION'),
+            userFunctions: declared.userFunctions === true
+              && typeof raw.registerFunction === 'function',
+            deterministicIndexableFunctions:
+              declared.deterministicIndexableFunctions === true
+              && typeof raw.registerFunction === 'function',
+            // aggregate UDFs (`db.aggregate` step/final) — node has them,
+            // bun does not; a registry's `pushable:'aggregate'` subset is
+            // gated on this (Ring 3). The binding must expose the
+            // method AND declare it.
+            aggregateFunctions: declared.aggregateFunctions === true
+              && typeof raw.registerAggregate === 'function',
+            // structural SQLite limits — stated, not worked around
+            alterTableFull: false,
+            // the slots every SQLite driver leaves EMPTY (no
+            // interrupt, no progress handler, no estimate API)
+            statementTimeout: false,
+            rowEstimates: false,
+          });
+          return finishConnection(raw, dialect, synchronous, capabilities,
+            options.queueTimeout ?? DEFAULT_QUEUE_TIMEOUT);
+        }));
+    }));
+}
+
+/**
+ * Assemble the frozen connection object around a probed raw binding.
+ *
+ * Transaction OWNERSHIP is the load-bearing part. A SQLite connection
+ * holds ONE savepoint stack, so two transactions that overlap in time on
+ * one connection cannot both be correct: whichever released first would
+ * release the other's savepoint with it (`RELEASE` discards everything
+ * opened after its target), leaving the second to fail with "no such
+ * savepoint" over rows it had already committed. Unique names do not help
+ * — the stack is a stack.
+ *
+ * So a top-level transaction OWNS the connection until it settles, and
+ * everything else — another top-level transaction, an ordinary read or
+ * write — waits in a FIFO. Work that genuinely belongs INSIDE the
+ * transaction says so explicitly: the callback receives a scope, and
+ * `scope.transaction()` nests through a savepoint while `scope.exec`/
+ * `scope.prepare` run immediately as the owner. That explicitness is
+ * what separates "nest me inside the open transaction" from "I am an
+ * unrelated caller, hold my work until it commits", which no implicit
+ * implicit counter can tell apart once a callback awaits.
+ * @param {any} raw
+ * @param {any} dialect
+ * @param {boolean} synchronous
+ * @param {Readonly<Record<string, any>>} capabilities
+ * @returns {any}
+ */
+function finishConnection(raw, dialect, synchronous, capabilities, queueTimeout) {
+  /** Savepoint names are never reused, so a stale name can never be
+   * mistaken for a live one in an error or a log. */
+  let savepointSeq = 0;
+  /** Whether a top-level transaction currently owns the connection. */
+  let owned = false;
+  /**
+   * Whether an owning callback is on the stack RIGHT NOW — set around the
+   * synchronous extent of every transaction body, cleared the moment it
+   * returns or awaits. It is the one discriminator a connection has: while
+   * a callback is still running synchronously nothing else can possibly be
+   * interleaved, so a `transaction()` arriving then is a nested call. Once
+   * the callback has awaited, the same request could be an unrelated
+   * caller, and only the scope it was handed can say otherwise.
+   */
+  let onStack = false;
+  /** @type {Array<() => void>} FIFO of work waiting for the owner. */
+  const waiting = [];
+
+  /** Hand the connection to the next waiter, in arrival order. */
+  const release = () => {
+    owned = false;
+    const next = waiting.shift();
+    if (next !== undefined) next();
+  };
+
+  /**
+   * Run `work` now if the connection is free, else when it becomes free.
+   *
+   * A wait that outlives `queueTimeout` is rejected rather than left
+   * pending, because the two ways to get here look identical from inside
+   * and only one of them can ever resolve: an unrelated caller waiting
+   * out a long transaction (fine, it proceeds when the commit lands), or
+   * a transaction callback that reached back through the OUTER connection
+   * instead of the scope it was handed (never — it is waiting for itself).
+   * The bound turns the second case from a silent hang into a coded error
+   * that names the fix, the same trade SQLite's own busy timeout makes.
+   * @param {() => any} work
+   * @param {string} what - what is waiting, for the timeout message
+   * @returns {any} value-or-promise
+   */
+  const whenFree = (work, what) => {
+    if (!owned) return work();
+    return new Promise((resolve, reject) => {
+      let done = false;
+      const timer = setTimeout(() => {
+        done = true;
+        const index = waiting.indexOf(run);
+        if (index >= 0) waiting.splice(index, 1);
+        reject(new DbCompileError('JD0012',
+          `${what} waited ${queueTimeout}ms for the open transaction to settle. `
+          + 'A transaction owns its connection until it commits; work that belongs '
+          + 'INSIDE it must go through the scope the callback received '
+          + '(scope.transaction / the store passed to your callback), not the '
+          + 'outer connection — that request waits for itself.'));
+      }, queueTimeout);
+      const run = () => {
+        if (done) { release(); return; } // already rejected: pass the turn on
+        clearTimeout(timer);
+        done = true;
+        let out;
+        try {
+          out = work();
+        }
+        catch (error) {
+          reject(error);
+          return;
+        }
+        toPromise(out).then(resolve, reject);
+      };
+      waiting.push(run);
+    });
+  };
+
+  /** Open one savepoint around `fn`, at whatever depth we are. `fn`
+   * receives the scope so nested work can name itself.
+   * @param {(scope: any) => any} fn
+   */
+  const savepointAround = (fn) => {
+    const name = `jaren_sp_${savepointSeq++}`;
+    const succeed = (result) => chain(raw.exec(dialect.tx.release(name)), () => result);
+    const fail = (error) => chain(raw.exec(dialect.tx.rollbackTo(name)), () =>
+      chain(raw.exec(dialect.tx.release(name)), () => {
+        throw error;
+      }));
+    return chain(raw.exec(dialect.tx.savepoint(name)), () => {
+      let out;
+      const wasOnStack = onStack;
+      onStack = true;
+      try {
+        out = fn(scopeFor());
+      }
+      catch (error) {
+        onStack = wasOnStack;
+        return fail(error);
+      }
+      onStack = wasOnStack; // the body has returned or awaited
+      return isThenable(out) ? out.then(succeed, fail) : succeed(out);
+    });
+  };
+
+  /** The scope handed to a transaction callback: the owner's direct
+   * access to the connection, plus nesting. Deliberately narrow —
+   * registering a function or opening a change session belongs to store
+   * setup, not to a transaction body. */
+  const scopeFor = () => Object.freeze({
+    synchronous,
+    capabilities,
+    dialect,
+    /** @param {string} sql */
+    exec: (sql) => raw.exec(sql),
+    /** @param {string} sql */
+    prepare: (sql) => chain(raw.prepare(sql), wrapStatement),
+    /** A nested savepoint inside this transaction.
+     * @param {(scope: any) => any} fn */
+    transaction: (fn) => savepointAround(fn),
+  });
+
+  return Object.freeze({
+    synchronous,
+    capabilities,
+    dialect,
+    /** @param {string} sql */
+    // NOT gated. A statement issued while a transaction is open joins it,
+    // because a SQLite connection has no per-statement transaction scope
+    // and every caller inside a transaction reaches the connection this
+    // way. Two consequences, both documented in MODEL-FORMAT §Transactions:
+    // work inside a callback runs immediately as the owner (right), and an
+    // UNRELATED caller's bare write on a shared store joins that
+    // transaction and shares its fate (a single connection cannot tell the
+    // two apart — give each concurrent writer its own store to separate
+    // them). What the gate below does guarantee is that two TRANSACTIONS
+    // never interleave, which is what made commits report failure.
+    exec: (sql) => raw.exec(sql),
+    /** @param {string} sql */
+    prepare: (sql) => chain(raw.prepare(sql), wrapStatement),
+    /**
+     * A transaction. `fn`'s value is returned; a throw rolls back exactly
+     * this level and rethrows. No implicit retry.
+     *
+     * Two shapes, decided here rather than by the caller:
+     *
+     *  - **Nested**, when an owning callback is on the stack: a savepoint
+     *    inside it, synchronously, exactly as before. This is the only
+     *    thing it can be — synchronous code cannot interleave.
+     *  - **Top level** otherwise: it takes the connection and holds it
+     *    until it settles, so two transactions never share a savepoint
+     *    stack. An overlapping one waits its turn instead of nesting into
+     *    a stranger's rollback.
+     *
+     * An ASYNC callback that wants to nest cannot rely on the stack — it
+     * has already awaited — so it nests through the scope it was handed
+     * (`fn` receives it). Reaching back through the connection instead
+     * queues behind the transaction the caller is part of, and
+     * {@link DEFAULT_QUEUE_TIMEOUT} turns that into `JD0012`.
+     * @param {(scope: any) => any} fn
+     */
+    transaction(fn) {
+      if (onStack) return savepointAround(fn);
+      return whenFree(() => {
+        owned = true;
+        let out;
+        try {
+          out = savepointAround(fn);
+        }
+        catch (error) {
+          release();
+          throw error;
+        }
+        if (!isThenable(out)) {
+          release();
+          return out;
+        }
+        return out.then(
+          (value) => { release(); return value; },
+          (error) => { release(); throw error; });
+      }, 'a transaction');
+    },
+    close: () => raw.close(),
+    registerFunction: typeof raw.registerFunction === 'function'
+      ? (name, functionOptions, fn) => raw.registerFunction(name, functionOptions, fn)
+      : null,
+    registerAggregate: typeof raw.registerAggregate === 'function'
+      ? (name, spec) => raw.registerAggregate(name, spec)
+      : null,
+    session: typeof raw.session === 'function'
+      ? (table) => raw.session(table)
+      : null,
+  });
+}

package/src/drivers/bun.js

@@ -0,0 +1,101 @@
+//@ts-check
+/**
+ * @file The Bun binding: `bun:sqlite` behind the driver contract. The
+ * builtin is imported lazily inside `open()` — never at module scope —
+ * so this module itself loads under any runtime; on a runtime that
+ * cannot resolve `bun:` specifiers the open fails with the coded
+ * `JD0003`.
+ *
+ * Probed reality this binding declares rather than papers over:
+ * `bun:sqlite`'s `Database` exposes no `function`, no `aggregate` and
+ * no `createSession` — on Bun the UDF hatch does not exist and there
+ * is no session-based change capture. The capability table says so.
+ *
+ * What it DOES expose is a native lazy row iterator, forwarded below.
+ * Without it the driver's generic fallback composes a cursor over
+ * `all()`, which materialises every row first — so a query that streams
+ * on Node would spike memory in a compiled Bun binary, on the same code
+ * and the same data. A cursor that is not lazy is not a cursor.
+ */
+
+import { lazyOpen, openConnection } from '../driver.js';
+import { sqliteDialect } from '../dialects/sqlite.js';
+
+/**
+ * Adapt an already-constructed `bun:sqlite` `Database` (or any object
+ * with its shape) into a probed connection. Exported so the adapter is
+ * exercisable without the builtin.
+ * @param {any} db - A Bun `Database`-shaped database
+ * @param {{ queueTimeout?: number }} [options]
+ * @returns {any} a Connection, or a promise of one
+ */
+export function adaptBunDatabase(db, options) {
+  const raw = {
+    /** @param {string} sql */
+    exec: (sql) => db.run(sql),
+    /** @param {string} sql */
+    prepare: (sql) => {
+      const statement = db.prepare(sql);
+      return {
+        run: (params = []) => statement.run(...params),
+        // the driver contract says a missing row reads UNDEFINED;
+        // bun:sqlite answers null — normalize at the seam, or every
+        // create-or-verify and absence check misfires
+        get: (params = []) => statement.get(...params) ?? undefined,
+        all: (params = []) => statement.all(...params),
+        // the native lazy iterator when this build has one; the
+        // driver-level wrapper composes one over `all` when it does not,
+        // and `iterate` stays absent here so that fallback is reached
+        ...(typeof statement.iterate === 'function'
+          ? { iterate: (params = []) => statement.iterate(...params) }
+          : undefined),
+      };
+    },
+    close: () => db.close(),
+  };
+  return openConnection(raw, {
+    dialect: sqliteDialect,
+    synchronous: true,
+    queueTimeout: options?.queueTimeout,
+    declared: {
+      sessions: false,
+      userFunctions: false,
+      deterministicIndexableFunctions: false,
+      aggregateFunctions: false,
+    },
+  });
+}
+
+/**
+ * Construct and adapt the database from a loaded `bun:sqlite` module.
+ * Exported so the whole open path runs under any runtime with a
+ * substitute module.
+ * @param {any} mod - The `bun:sqlite` module (or a substitute)
+ * @param {string} path
+ * @param {{ readOnly?: boolean, queueTimeout?: number }} [options]
+ * @returns {any}
+ */
+export function fromBunModule(mod, path, options) {
+  return adaptBunDatabase(options?.readOnly === true
+    ? new mod.Database(path, { readonly: true })
+    : new mod.Database(path), options);
+}
+
+/**
+ * The Bun driver: `{ name, dialect, open }` over `bun:sqlite`.
+ * @returns {any}
+ */
+export function bunDriver() {
+  return Object.freeze({
+    name: 'bun-sqlite',
+    dialect: sqliteDialect,
+    /**
+     * @param {string} path
+     * @param {{ readOnly?: boolean, queueTimeout?: number }} [options]
+     * @returns {Promise<any>}
+     */
+    open: (path, options) => lazyOpen('bun:sqlite',
+      "the Bun SQLite binding ('bun:sqlite') is unavailable on this runtime",
+      fromBunModule, [path, options]),
+  });
+}

package/src/drivers/node.js

@@ -0,0 +1,93 @@
+//@ts-check
+/**
+ * @file The Node binding: `node:sqlite` behind the driver contract.
+ * The builtin is imported lazily inside `open()` — never at module
+ * scope — so this module itself loads under any runtime; on a runtime
+ * without `node:sqlite` the open fails with the coded `JD0003`.
+ */
+
+import { lazyOpen, openConnection } from '../driver.js';
+import { sqliteDialect } from '../dialects/sqlite.js';
+
+/**
+ * Adapt an already-constructed `node:sqlite` `DatabaseSync` (or any
+ * object with its shape) into a probed connection. Exported so the
+ * adapter is exercisable without the builtin.
+ * @param {any} db - A `DatabaseSync`-shaped database
+ * @param {{ queueTimeout?: number }} [options]
+ * @returns {any} a Connection, or a promise of one
+ */
+export function adaptNodeDatabase(db, options) {
+  const raw = {
+    /** @param {string} sql */
+    exec: (sql) => db.exec(sql),
+    /** @param {string} sql */
+    prepare: (sql) => {
+      const statement = db.prepare(sql);
+      return {
+        run: (params = []) => statement.run(...params),
+        get: (params = []) => statement.get(...params),
+        all: (params = []) => statement.all(...params),
+        iterate: (params = []) => statement.iterate(...params),
+      };
+    },
+    close: () => db.close(),
+    registerFunction: (name, options, fn) => db.function(name, options, fn),
+    registerAggregate: (name, spec) => db.aggregate(name, spec),
+    session: (table) => (table === undefined
+      ? db.createSession()
+      : db.createSession({ table })),
+  };
+  return openConnection(raw, {
+    dialect: sqliteDialect,
+    synchronous: true,
+    queueTimeout: options?.queueTimeout,
+    declared: {
+      sessions: true,
+      userFunctions: true,
+      deterministicIndexableFunctions: true,
+      aggregateFunctions: true,
+    },
+  });
+}
+
+/**
+ * Construct and adapt the database from a loaded `node:sqlite` module.
+ * The seam {@link nodeDriver} feeds through `lazyOpen`; exported so the
+ * whole open path runs under any runtime with a substitute module.
+ * @param {any} mod - The `node:sqlite` module (or a substitute)
+ * @param {string} path
+ * @param {{ timeout?: number, readOnly?: boolean,
+ *   queueTimeout?: number }} [options]
+ * @returns {any}
+ */
+export function fromNodeModule(mod, path, options) {
+  /** @type {any} */
+  const open = {};
+  if (options?.timeout !== undefined) open.timeout = options.timeout;
+  if (options?.readOnly === true) open.readOnly = true;
+  const db = Object.keys(open).length > 0
+    ? new mod.DatabaseSync(path, open)
+    : new mod.DatabaseSync(path);
+  return adaptNodeDatabase(db, options);
+}
+
+/**
+ * The Node driver: `{ name, dialect, open }` over `node:sqlite`.
+ * @returns {any}
+ */
+export function nodeDriver() {
+  return Object.freeze({
+    name: 'node-sqlite',
+    dialect: sqliteDialect,
+    /**
+     * @param {string} path
+     * @param {{ timeout?: number, readOnly?: boolean,
+     *   queueTimeout?: number }} [options]
+     * @returns {Promise<any>}
+     */
+    open: (path, options) => lazyOpen('node:sqlite',
+      "the Node SQLite binding ('node:sqlite') is unavailable on this runtime",
+      fromNodeModule, [path, options]),
+  });
+}