@blamejs/core 0.8.42 → 0.8.49

package/lib/cluster-storage.js

@@ -1,42 +1,30 @@
 "use strict";
 /**
- * Framework-state SQL dispatch — runs against local SQLite in single-
- * node mode and against external-db in cluster mode.
- *
- * audit / consent / sessions / queue / subject all read and write the
- * framework's own tables (audit_log, consent_log, …). In single-node
- * mode those tables live in the framework's own SQLite (lib/db.js).
- * In cluster mode they live in the operator-supplied external-db with
- * a `_blamejs_` prefix to avoid colliding with app tables.
- *
- * This module is the dispatch primitive. Callers write SQL once using
- * unprefixed table names + `?` placeholders; the dispatcher translates
- * to the active backend's flavor:
- *
- *   single-node     local SQLite via db().prepare(sql).run/get/all(...)
- *   cluster (sqlite) externalDb.query(sql, params)              ? placeholders
- *   cluster (postgres) externalDb.query(translated, params)     $1, $2, …
- *
- * Tables are translated through frameworkSchema.tableName so callers
- * use logical names (audit_log) and the resolved name is automatically
- * prefixed in cluster mode (_blamejs_audit_log).
- *
- * The dispatcher is async-only — the operator's external-db driver
- * is async, and even local-SQLite calls return a resolved Promise to
- * keep the call shape uniform. Callers `await` this module's methods;
- * audit / consent / queue / session / subject all thread `async` /
- * `await` through their own surfaces to match.
- *
- * Public API:
- *   await execute(sql, params?)    { rows, rowCount }
- *   tableName(local)               external-db prefixed name (or unchanged
- *                                  in single-node mode)
- *   placeholderize(sql, dialect)   `?` to `$N` for postgres; passthrough
- *                                  for sqlite
- *   resolveTables(sql)             rewrites bare unprefixed table names
- *                                  in cluster mode (only the framework's
- *                                  known tables are rewritten — operator
- *                                  app-data SQL is unaffected)
+ * @module b.clusterStorage
+ * @nav    Production
+ * @title  Cluster Storage
+ *
+ * @intro
+ *   Cluster-aware framework-state SQL dispatch — runs against the
+ *   framework's local SQLite in single-node mode and against the
+ *   operator-supplied external DB in cluster mode. Distributed shared
+ *   state for audit, consent, sessions, queue, and subject tables;
+ *   write paths carry the cluster's fencing token so a stale leader
+ *   cannot extend a chain after losing its lease.
+ *
+ *   Callers write SQL once using unprefixed logical table names
+ *   (`audit_log`, `consent_log`, …) and `?` placeholders. The
+ *   dispatcher rewrites bare framework tables to their `_blamejs_`-
+ *   prefixed cluster names and translates `?` to `$N` for Postgres.
+ *   Unknown identifiers pass through unchanged so operator-written
+ *   migrations and app-data SQL are never touched.
+ *
+ *   The dispatcher is async-only. Even single-node SQLite calls
+ *   return a resolved Promise so the call shape stays uniform across
+ *   deployment topologies — callers `await` every method.
+ *
+ * @card
+ *   Cluster-aware framework-state SQL dispatch — runs against the framework's local SQLite in single-node mode and against the operator-supplied external DB in cluster mode.
  */
 
 var cluster = require("./cluster");
@@ -59,6 +47,28 @@ var _localDb = lazyRequire(function () { return require("./db"); });
 
 // ---- Table-name resolution ----
 
+/**
+ * @primitive b.clusterStorage.tableName
+ * @signature b.clusterStorage.tableName(local)
+ * @since     0.1.9
+ * @status    stable
+ * @related   b.clusterStorage.resolveTables, b.cluster.isClusterMode
+ *
+ * Resolve a logical framework table name to the active backend's
+ * concrete name. In single-node mode returns the input unchanged; in
+ * cluster mode returns the `_blamejs_`-prefixed name from the
+ * framework-schema mapping (e.g. `audit_log` to `_blamejs_audit_log`).
+ * Use this when composing SQL by hand against framework tables — the
+ * `execute` family rewrites bare names automatically, but ad-hoc DDL
+ * or admin queries that reference a specific table need the resolved
+ * name explicitly.
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var name = b.clusterStorage.tableName("audit_log");
+ *   // → "audit_log"             (single-node)
+ *   // → "_blamejs_audit_log"    (cluster mode)
+ */
 function tableName(local) {
   if (cluster.isClusterMode()) return frameworkSchema.tableName(local);
   return local;
@@ -137,6 +147,30 @@ var _REWRITE_TABLE = (function () {
 // (audit_log, consent_log, …) — anything else passes through unchanged
 // so app-data SQL composed via this dispatcher (or operator-written
 // migrations) isn't rewritten by accident.
+/**
+ * @primitive b.clusterStorage.resolveTables
+ * @signature b.clusterStorage.resolveTables(sql)
+ * @since     0.1.9
+ * @status    stable
+ * @related   b.clusterStorage.tableName, b.clusterStorage.execute
+ *
+ * Rewrite bare framework table names in a SQL string to their
+ * cluster-mode `_blamejs_`-prefixed equivalents. Word-boundary scan;
+ * only exact identifier matches are rewritten — substrings,
+ * column-qualified names, and operator app tables pass through
+ * untouched. In single-node mode the SQL is returned unchanged. The
+ * `execute` family calls this internally; callers reach for it
+ * directly only when running raw SQL through a different path
+ * (admin tooling, migration runners).
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var sql = b.clusterStorage.resolveTables(
+ *     "SELECT id FROM audit_log WHERE counter > ?"
+ *   );
+ *   // → "SELECT id FROM audit_log WHERE counter > ?"          (single-node)
+ *   // → "SELECT id FROM _blamejs_audit_log WHERE counter > ?" (cluster)
+ */
 function resolveTables(sql) {
   if (!cluster.isClusterMode()) return sql;
   var translated = sql;
@@ -154,6 +188,29 @@ function resolveTables(sql) {
 // time so callers always write `?` and the right thing happens per
 // dialect.
 
+/**
+ * @primitive b.clusterStorage.placeholderize
+ * @signature b.clusterStorage.placeholderize(sql, dialect)
+ * @since     0.1.9
+ * @status    stable
+ * @related   b.clusterStorage.execute, b.cluster.dialect
+ *
+ * Translate `?` placeholders to numbered `$1`, `$2`, … form for
+ * Postgres backends; passthrough for `"sqlite"` and `"mysql"`. The
+ * walker skips question marks inside single-quoted string literals so
+ * `WHERE s = '?'` is preserved verbatim. Doubled-quote escapes (`''`)
+ * inside strings are recognized. The `execute` family calls this on
+ * every cluster-mode dispatch; reach for it directly only when
+ * shipping raw SQL through a non-`execute` driver path.
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var sql = b.clusterStorage.placeholderize(
+ *     "SELECT id FROM audit_log WHERE counter > ? AND actor = ?",
+ *     "postgres"
+ *   );
+ *   // → "SELECT id FROM audit_log WHERE counter > $1 AND actor = $2"
+ */
 function placeholderize(sql, dialect) {
   if (dialect !== "postgres") return sql;
   // Walk the SQL and replace `?` with $1, $2, … but skip ones inside
@@ -177,6 +234,33 @@ function placeholderize(sql, dialect) {
 
 // ---- execute() ----
 
+/**
+ * @primitive b.clusterStorage.execute
+ * @signature b.clusterStorage.execute(sql, params)
+ * @since     0.1.9
+ * @status    stable
+ * @compliance soc2
+ * @related   b.clusterStorage.executeOne, b.clusterStorage.executeAll, b.cluster.isClusterMode
+ *
+ * Run framework-state SQL against the active backend. In cluster mode
+ * the SQL is routed through `resolveTables` + `placeholderize`, then
+ * dispatched to the operator-supplied external DB. In single-node
+ * mode it runs against the framework's local SQLite via
+ * `db().prepare(...)` — `SELECT` and `RETURNING` queries use `.all()`,
+ * everything else uses `.run()`. The shape is uniform either way:
+ * resolves to `{ rows, rowCount }` where `rows` is the array of result
+ * objects and `rowCount` is `rows.length` for selects or `info.changes`
+ * for writes. Throws `ClusterStorageError` (code
+ * `cluster-storage/bad-arg`) when `sql` is not a string.
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var result = await b.clusterStorage.execute(
+ *     "SELECT counter, row_hash FROM audit_log WHERE counter > ?",
+ *     [42]
+ *   );
+ *   // → { rows: [ { counter: 43, row_hash: "..." } ], rowCount: 1 }
+ */
 async function execute(sql, params) {
   if (typeof sql !== "string") {
     throw new ClusterStorageError("sql must be a string", "cluster-storage/bad-arg");
@@ -205,11 +289,52 @@ async function execute(sql, params) {
 }
 
 // Convenience wrappers for the two common patterns.
+/**
+ * @primitive b.clusterStorage.executeOne
+ * @signature b.clusterStorage.executeOne(sql, params)
+ * @since     0.1.9
+ * @status    stable
+ * @related   b.clusterStorage.execute, b.clusterStorage.executeAll
+ *
+ * Convenience over `execute` for queries expected to return at most
+ * one row. Returns the first row when the result set is non-empty,
+ * `null` otherwise. The same dispatch rules as `execute` apply —
+ * cluster mode routes to external DB, single-node hits local SQLite.
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var row = await b.clusterStorage.executeOne(
+ *     "SELECT counter, row_hash FROM audit_tip WHERE id = ?",
+ *     [1]
+ *   );
+ *   // → { counter: 128, row_hash: "..." }
+ *   // → null when no row matches
+ */
 async function executeOne(sql, params) {
   var result = await execute(sql, params);
   return result.rows.length > 0 ? result.rows[0] : null;
 }
 
+/**
+ * @primitive b.clusterStorage.executeAll
+ * @signature b.clusterStorage.executeAll(sql, params)
+ * @since     0.1.9
+ * @status    stable
+ * @related   b.clusterStorage.execute, b.clusterStorage.executeOne
+ *
+ * Convenience over `execute` for queries expected to return a row
+ * array. Returns the `rows` array directly without the surrounding
+ * `{ rows, rowCount }` envelope. Empty result sets resolve to `[]`.
+ * The same dispatch rules as `execute` apply.
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var rows = await b.clusterStorage.executeAll(
+ *     "SELECT id, status FROM queue_jobs WHERE status = ?",
+ *     ["pending"]
+ *   );
+ *   // → [ { id: 1, status: "pending" }, { id: 2, status: "pending" } ]
+ */
 async function executeAll(sql, params) {
   var result = await execute(sql, params);
   return result.rows;