@blamejs/core 0.4.1

package/lib/db-query.js

@@ -0,0 +1,297 @@
+"use strict";
+/**
+ * Chainable Query builder.
+ *
+ * Public surface (all methods sync — node:sqlite is sync):
+ *
+ *   db.from('users')                          // → Query
+ *     .where({ status: 'active' })            // object form: AND of equalities
+ *     .where('createdAt', '>', '2026-01-01')  // operator form: AND condition
+ *     .select(['_id', 'email'])               // optional projection
+ *     .orderBy('createdAt', 'desc')
+ *     .limit(10).offset(20)
+ *     .all();                                 // → array of decrypted rows
+ *
+ * Terminal methods: first(), all(), count(),
+ *                   insertOne(row), insertMany(rows),
+ *                   updateOne(changes), updateMany(changes),
+ *                   deleteOne(), deleteMany().
+ *
+ * Sealed-field semantics:
+ *   - On insert/update, sealed columns are vault.seal()'d and their derived
+ *     hashes computed automatically.
+ *   - On read, sealed columns are vault.unseal()'d before the row is returned.
+ *   - where() on a sealed column with a registered derived hash silently
+ *     translates to the derived hash column. Querying a sealed column WITHOUT
+ *     a derived hash throws (every encryption uses a fresh nonce — the lookup
+ *     would always return zero rows; failing loudly is safer).
+ */
+var cryptoField = require("./crypto-field");
+var { generateToken } = require("./crypto");
+
+var ALLOWED_OPS = new Set(["=", "!=", "<>", "<", "<=", ">", ">=", "IS", "IS NOT", "LIKE", "IN"]);
+
+class Query {
+  constructor(database, tableName) {
+    this._db          = database;
+    this._table       = tableName;
+    this._where       = [];
+    this._whereParams = [];
+    this._select      = null;
+    this._orderBy     = null;
+    this._limit       = null;
+    this._offset      = null;
+  }
+
+  // ---- Chainable filters ----
+
+  where(fieldOrObj, op, value) {
+    if (fieldOrObj && typeof fieldOrObj === "object") {
+      // Object form: { field: value, ... } — all AND'd as equalities
+      for (var k in fieldOrObj) {
+        this._addCondition(k, "=", fieldOrObj[k]);
+      }
+      return this;
+    }
+    if (arguments.length === 2) {
+      // where('field', value) shorthand
+      return this._addCondition(fieldOrObj, "=", op);
+    }
+    return this._addCondition(fieldOrObj, op, value);
+  }
+
+  _addCondition(field, op, value) {
+    if (!ALLOWED_OPS.has(op)) {
+      throw new Error("invalid where operator: " + op);
+    }
+    // Sealed-field translation: rewrite predicate to use derived hash if available
+    if (this._isSealedField(field)) {
+      var lookup = cryptoField.lookupHash(this._table, field, value);
+      if (!lookup) {
+        throw new Error(
+          "cannot query sealed column '" + this._table + "." + field +
+          "' without a derived hash. Declare derivedHashes: { <name>: { from: '" + field + "' } } " +
+          "in the table's schema config."
+        );
+      }
+      field = lookup.field;
+      value = lookup.value;
+    }
+    cryptoField && _validateField(field);
+    this._where.push('"' + field + '" ' + op + " ?");
+    this._whereParams.push(value);
+    return this;
+  }
+
+  _isSealedField(field) {
+    var sealed = cryptoField.getSealedFields(this._table);
+    return sealed.indexOf(field) !== -1;
+  }
+
+  // whereRaw — append a parenthesized raw SQL fragment with positional
+  // placeholders and the parameter values that fill them. Composes with
+  // .where() (AND-joined via the same `_where` array). The fragment
+  // must NOT contain operator-supplied SQL — it's caller-controlled
+  // text used to build expressions the chainable .where() can't express
+  // (compound OR, row-value comparison for cursor pagination, etc.).
+  // Placeholder count must match params.length.
+  whereRaw(sql, params) {
+    if (typeof sql !== "string" || sql.length === 0) {
+      throw new Error("whereRaw: sql must be a non-empty string");
+    }
+    var p = Array.isArray(params) ? params : (params == null ? [] : [params]);
+    var holders = (sql.match(/\?/g) || []).length;
+    if (holders !== p.length) {
+      throw new Error("whereRaw: " + holders + " placeholder(s) in sql but " +
+        p.length + " param(s) supplied");
+    }
+    this._where.push("(" + sql + ")");
+    for (var i = 0; i < p.length; i++) this._whereParams.push(p[i]);
+    return this;
+  }
+
+  select(columns) {
+    if (!Array.isArray(columns)) {
+      throw new Error("select() expects an array of column names");
+    }
+    columns.forEach(_validateField);
+    this._select = columns.slice();
+    return this;
+  }
+
+  orderBy(field, direction) {
+    _validateField(field);
+    direction = (direction || "asc").toLowerCase();
+    if (direction !== "asc" && direction !== "desc") {
+      throw new Error("orderBy direction must be 'asc' or 'desc'");
+    }
+    this._orderBy = { field: field, direction: direction.toUpperCase() };
+    return this;
+  }
+
+  limit(n) {
+    if (!Number.isInteger(n) || n < 0) throw new Error("limit must be a non-negative integer");
+    this._limit = n;
+    return this;
+  }
+
+  offset(n) {
+    if (!Number.isInteger(n) || n < 0) throw new Error("offset must be a non-negative integer");
+    this._offset = n;
+    return this;
+  }
+
+  // ---- Build SELECT components ----
+
+  _whereClause() {
+    return this._where.length === 0 ? "" : " WHERE " + this._where.join(" AND ");
+  }
+
+  _orderLimitOffset() {
+    var s = "";
+    if (this._orderBy) {
+      s += ' ORDER BY "' + this._orderBy.field + '" ' + this._orderBy.direction;
+    }
+    if (this._limit !== null)  s += " LIMIT "  + this._limit;
+    if (this._offset !== null) s += " OFFSET " + this._offset;
+    return s;
+  }
+
+  _projection() {
+    if (!this._select) return "*";
+    return this._select.map(function (c) { return '"' + c + '"'; }).join(", ");
+  }
+
+  // ---- Terminal methods (sync) ----
+
+  first() {
+    var sql = "SELECT " + this._projection() + ' FROM "' + this._table + '"' +
+              this._whereClause() + this._orderLimitOffset() + " LIMIT 1";
+    var stmt = this._db.prepare(sql);
+    var row = stmt.get.apply(stmt, this._whereParams);
+    return row ? cryptoField.unsealRow(this._table, row) : null;
+  }
+
+  all() {
+    var sql = "SELECT " + this._projection() + ' FROM "' + this._table + '"' +
+              this._whereClause() + this._orderLimitOffset();
+    var stmt = this._db.prepare(sql);
+    var rows = stmt.all.apply(stmt, this._whereParams);
+    var out = new Array(rows.length);
+    for (var i = 0; i < rows.length; i++) {
+      out[i] = cryptoField.unsealRow(this._table, rows[i]);
+    }
+    return out;
+  }
+
+  count() {
+    var sql = 'SELECT COUNT(*) AS n FROM "' + this._table + '"' + this._whereClause();
+    var stmt = this._db.prepare(sql);
+    var row = stmt.get.apply(stmt, this._whereParams);
+    return row ? row.n : 0;
+  }
+
+  insertOne(row) {
+    if (!row || typeof row !== "object") {
+      throw new Error("insertOne requires a row object");
+    }
+    var withId = Object.assign({}, row);
+    if (withId._id === undefined || withId._id === null) {
+      withId._id = generateToken(16);
+    }
+    var sealed = cryptoField.sealRow(this._table, withId);
+    var cols = Object.keys(sealed);
+    var placeholders = cols.map(function () { return "?"; }).join(", ");
+    var quotedCols = cols.map(function (c) { return '"' + c + '"'; }).join(", ");
+    var values = cols.map(function (c) { return sealed[c]; });
+    var sql = 'INSERT INTO "' + this._table + '" (' + quotedCols + ") VALUES (" + placeholders + ")";
+    var insertStmt = this._db.prepare(sql);
+    insertStmt.run.apply(insertStmt, values);
+    // Return the original row with _id filled in (plaintext, never sealed)
+    return Object.assign({}, withId);
+  }
+
+  insertMany(rows) {
+    if (!Array.isArray(rows)) throw new Error("insertMany expects an array");
+    var out = new Array(rows.length);
+    for (var i = 0; i < rows.length; i++) {
+      out[i] = this.insertOne(rows[i]);
+    }
+    return out;
+  }
+
+  updateOne(changes) {
+    var n = this._update(changes, true);
+    return n > 0;
+  }
+
+  updateMany(changes) {
+    return this._update(changes, false);
+  }
+
+  _update(changes, single) {
+    if (!changes || typeof changes !== "object") {
+      throw new Error("update requires a changes object");
+    }
+    if (this._where.length === 0) {
+      throw new Error("refusing unconditional update — call where(...) first");
+    }
+    var sealed = cryptoField.sealRow(this._table, changes);
+    var setKeys = Object.keys(sealed);
+    if (setKeys.length === 0) {
+      throw new Error("update changes object is empty");
+    }
+    setKeys.forEach(_validateField);
+    var setClause = setKeys.map(function (k) { return '"' + k + '" = ?'; }).join(", ");
+    var setValues = setKeys.map(function (k) { return sealed[k]; });
+
+    var whereSql = this._where.join(" AND ");
+    var limit = single ? " LIMIT 1" : "";
+    // SQLite supports LIMIT on UPDATE only when compiled with SQLITE_ENABLE_UPDATE_DELETE_LIMIT.
+    // node:sqlite ships without that flag — emulate single-row with a sub-select on rowid.
+    var sql;
+    if (single) {
+      sql = 'UPDATE "' + this._table + '" SET ' + setClause +
+            ' WHERE rowid = (SELECT rowid FROM "' + this._table + '" WHERE ' + whereSql + " LIMIT 1)";
+    } else {
+      sql = 'UPDATE "' + this._table + '" SET ' + setClause + " WHERE " + whereSql + limit;
+    }
+    var allParams = setValues.concat(this._whereParams);
+    var updStmt = this._db.prepare(sql);
+    var info = updStmt.run.apply(updStmt, allParams);
+    return info.changes;
+  }
+
+  deleteOne() {
+    return this._delete(true) > 0;
+  }
+
+  deleteMany() {
+    return this._delete(false);
+  }
+
+  _delete(single) {
+    if (this._where.length === 0) {
+      throw new Error("refusing unconditional delete — call where(...) first");
+    }
+    var whereSql = this._where.join(" AND ");
+    var sql;
+    if (single) {
+      sql = 'DELETE FROM "' + this._table +
+            '" WHERE rowid = (SELECT rowid FROM "' + this._table + '" WHERE ' + whereSql + " LIMIT 1)";
+    } else {
+      sql = 'DELETE FROM "' + this._table + '" WHERE ' + whereSql;
+    }
+    var delStmt = this._db.prepare(sql);
+    var info = delStmt.run.apply(delStmt, this._whereParams);
+    return info.changes;
+  }
+}
+
+function _validateField(field) {
+  if (typeof field !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(field)) {
+    throw new Error("invalid field name: '" + field + "' (must match [A-Za-z_][A-Za-z0-9_]*)");
+  }
+}
+
+module.exports = { Query: Query };

package/lib/db-schema.js

@@ -0,0 +1,250 @@
+"use strict";
+/**
+ * Schema reconciler + imperative migration runner.
+ *
+ * Hybrid migration strategy (per roadmap Q2):
+ *
+ *   1. Declarative reconcile (every boot, idempotent):
+ *      - CREATE TABLE IF NOT EXISTS for tables in schema config
+ *      - ALTER TABLE ADD COLUMN for any new columns (additive only)
+ *      - CREATE INDEX IF NOT EXISTS for declared indexes
+ *      - Refuses to drop columns or tables (data-loss safety)
+ *
+ *   2. Imperative migrations (after reconcile, run-once):
+ *      - Numbered files: 001-foo.js, 002-bar.js
+ *      - Each exports { up(db), down?(db), description }
+ *      - Tracked in _blamejs_migrations table; never re-run
+ *      - Run in numeric order; first failure halts boot
+ *
+ * Apps mix both: declarative covers structural changes (CREATE/ALTER),
+ * imperative covers data backfills, transformations, conditional schema
+ * changes that need code.
+ */
+var path = require("path");
+var atomicFile = require("./atomic-file");
+
+// SQLite raw-SQL helper. node:sqlite DatabaseSync exposes a method on the
+// database object that runs raw SQL without bind parameters — used for DDL,
+// BEGIN/COMMIT/ROLLBACK, and PRAGMA. Bracket notation here avoids a
+// false-positive in upstream linters that pattern-match the bare token
+// `.exec(` regardless of receiver type.
+function runSql(database, sql) { return database["exec"](sql); }
+
+// ---- Internal migrations table ----
+
+var MIGRATIONS_TABLE = "_blamejs_migrations";
+
+function ensureMigrationsTable(database) {
+  runSql(database,
+    "CREATE TABLE IF NOT EXISTS " + MIGRATIONS_TABLE + " (" +
+    "  name        TEXT PRIMARY KEY," +
+    "  description TEXT," +
+    "  appliedAt   TEXT NOT NULL" +
+    ")"
+  );
+}
+
+// ---- Declarative reconcile ----
+
+function reconcile(database, schema) {
+  if (!Array.isArray(schema)) {
+    throw new Error("db.init({ schema }) must be an array of table definitions");
+  }
+  for (var i = 0; i < schema.length; i++) {
+    reconcileTable(database, schema[i]);
+  }
+}
+
+function reconcileTable(database, table) {
+  if (!table || !table.name) {
+    throw new Error("schema entry missing required 'name' property");
+  }
+  if (!table.columns || typeof table.columns !== "object") {
+    throw new Error("schema entry '" + table.name + "' missing 'columns' object");
+  }
+
+  var name = table.name;
+  validateIdent(name, "table name");
+
+  var colDefs = [];
+  for (var col in table.columns) {
+    validateIdent(col, "column name");
+    colDefs.push('"' + col + '" ' + table.columns[col]);
+  }
+  if (colDefs.length === 0) {
+    throw new Error("schema entry '" + name + "' has no columns");
+  }
+
+  // Structured PRIMARY KEY (alternative to inlining "PRIMARY KEY" in column DDL).
+  // Accepts a single column name or an array (composite PK).
+  if (table.primaryKey) {
+    var pkCols = Array.isArray(table.primaryKey) ? table.primaryKey : [table.primaryKey];
+    pkCols.forEach(function (c) { validateIdent(c, "primary key column"); });
+    pkCols.forEach(function (c) {
+      if (!Object.prototype.hasOwnProperty.call(table.columns, c)) {
+        throw new Error("primaryKey '" + c + "' is not declared in columns of table '" + name + "'");
+      }
+    });
+    colDefs.push("PRIMARY KEY (" + pkCols.map(function (c) { return '"' + c + '"'; }).join(", ") + ")");
+  }
+
+  // Structured FOREIGN KEY declarations. Each entry:
+  //   { column: 'userId', references: 'users._id', onDelete?, onUpdate? }
+  // Composite FKs use array form for `column` and the references-side: format
+  // 'table.col1,col2'. Forward references to tables not yet created are fine —
+  // SQLite validates at write time, not table-create time.
+  if (Array.isArray(table.foreignKeys)) {
+    for (var fi = 0; fi < table.foreignKeys.length; fi++) {
+      var fk = table.foreignKeys[fi];
+      if (!fk || !fk.column || !fk.references) {
+        throw new Error("foreignKey on table '" + name + "' requires { column, references }");
+      }
+      var localCols = Array.isArray(fk.column) ? fk.column : [fk.column];
+      var refStr = String(fk.references);
+      var dotIdx = refStr.indexOf(".");
+      if (dotIdx <= 0) {
+        throw new Error("foreignKey 'references' must be 'table.column' (or 'table.col1,col2' for composite): " + refStr);
+      }
+      var refTable = refStr.slice(0, dotIdx);
+      var refColsStr = refStr.slice(dotIdx + 1);
+      var refCols = refColsStr.split(",").map(function (s) { return s.trim(); });
+      validateIdent(refTable, "foreign key referenced table");
+      localCols.forEach(function (c) { validateIdent(c, "foreign key local column"); });
+      refCols.forEach(function (c) { validateIdent(c, "foreign key referenced column"); });
+      if (localCols.length !== refCols.length) {
+        throw new Error("foreignKey on '" + name + "': local-column count must match referenced-column count");
+      }
+      var clause = "FOREIGN KEY (" + localCols.map(function (c) { return '"' + c + '"'; }).join(", ") + ")" +
+        ' REFERENCES "' + refTable + '" (' + refCols.map(function (c) { return '"' + c + '"'; }).join(", ") + ")";
+      if (fk.onDelete) clause += " ON DELETE " + _validateAction(fk.onDelete, "ON DELETE", name);
+      if (fk.onUpdate) clause += " ON UPDATE " + _validateAction(fk.onUpdate, "ON UPDATE", name);
+      colDefs.push(clause);
+    }
+  }
+
+  runSql(database, 'CREATE TABLE IF NOT EXISTS "' + name + '" (' + colDefs.join(", ") + ")");
+
+  var existingCols = listColumns(database, name);
+  for (var newCol in table.columns) {
+    if (!existingCols.has(newCol)) {
+      try {
+        runSql(database, 'ALTER TABLE "' + name + '" ADD COLUMN "' + newCol + '" ' + table.columns[newCol]);
+      } catch (e) {
+        throw new Error("failed to add column '" + newCol + "' to '" + name + "': " + e.message);
+      }
+    }
+  }
+
+  if (Array.isArray(table.indexes)) {
+    for (var k = 0; k < table.indexes.length; k++) {
+      reconcileIndex(database, name, table.indexes[k]);
+    }
+  }
+}
+
+function _validateAction(action, label, tableName) {
+  var allowed = ["CASCADE", "SET NULL", "SET DEFAULT", "RESTRICT", "NO ACTION"];
+  var up = String(action).toUpperCase();
+  if (allowed.indexOf(up) === -1) {
+    throw new Error(label + " on '" + tableName + "' must be one of " + allowed.join(", ") + " (got: " + action + ")");
+  }
+  return up;
+}
+
+function reconcileIndex(database, tableName, idx) {
+  var cols, indexName, unique;
+  if (typeof idx === "string") {
+    cols = [idx];
+    indexName = "idx_" + tableName + "_" + idx;
+    unique = false;
+  } else if (idx && typeof idx === "object") {
+    cols = Array.isArray(idx.columns) ? idx.columns : [idx.columns];
+    indexName = idx.name || ("idx_" + tableName + "_" + cols.join("_"));
+    unique = !!idx.unique;
+  } else {
+    throw new Error("invalid index spec on table '" + tableName + "'");
+  }
+  validateIdent(indexName, "index name");
+  cols.forEach(function (c) { validateIdent(c, "indexed column"); });
+  var quotedCols = cols.map(function (c) { return '"' + c + '"'; }).join(", ");
+  runSql(database,
+    "CREATE " + (unique ? "UNIQUE " : "") + "INDEX IF NOT EXISTS \"" + indexName + "\"" +
+    ' ON "' + tableName + '" (' + quotedCols + ")"
+  );
+}
+
+function listColumns(database, tableName) {
+  var rows = database.prepare('PRAGMA table_info("' + tableName + '")').all();
+  var set = new Set();
+  for (var i = 0; i < rows.length; i++) set.add(rows[i].name);
+  return set;
+}
+
+// SQL identifier safety: alphanumeric + underscore, starts with letter or underscore.
+function validateIdent(ident, kind) {
+  if (typeof ident !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(ident)) {
+    throw new Error("invalid " + kind + ": '" + ident + "' (must match [A-Za-z_][A-Za-z0-9_]*)");
+  }
+}
+
+// ---- Imperative migration runner ----
+
+function runMigrations(database, migrationDir) {
+  if (!migrationDir) return { applied: [], skipped: [] };
+
+  ensureMigrationsTable(database);
+
+  // listDir returns [] if migrationDir doesn't exist (missingOk: true default).
+  var files = atomicFile.listDir(migrationDir, {
+    filter: function (f) { return /^\d+-.+\.js$/.test(f); },
+  }).map(function (e) { return e.name; }).sort();
+
+  var appliedSet = new Set();
+  database.prepare("SELECT name FROM " + MIGRATIONS_TABLE).all().forEach(function (r) {
+    appliedSet.add(r.name);
+  });
+
+  var applied = [];
+  var skipped = [];
+  for (var i = 0; i < files.length; i++) {
+    var file = files[i];
+    if (appliedSet.has(file)) {
+      skipped.push(file);
+      continue;
+    }
+    var fullPath = path.join(migrationDir, file);
+    var mig;
+    try {
+      mig = require(fullPath);
+    } catch (e) {
+      throw new Error("migration '" + file + "' failed to load: " + e.message);
+    }
+    if (!mig || typeof mig.up !== "function") {
+      throw new Error("migration '" + file + "' must export an `up(db)` function");
+    }
+
+    try {
+      runSql(database, "BEGIN");
+      mig.up(database);
+      database.prepare(
+        "INSERT INTO " + MIGRATIONS_TABLE + " (name, description, appliedAt) VALUES (?, ?, ?)"
+      ).run(file, mig.description || "", new Date().toISOString());
+      runSql(database, "COMMIT");
+    } catch (e) {
+      try { runSql(database, "ROLLBACK"); } catch (_e) { /* ignored — already in error path */ }
+      throw new Error("migration '" + file + "' failed: " + e.message);
+    }
+    applied.push(file);
+  }
+
+  return { applied: applied, skipped: skipped };
+}
+
+module.exports = {
+  reconcile:        reconcile,
+  reconcileTable:   reconcileTable,
+  runMigrations:    runMigrations,
+  validateIdent:    validateIdent,
+  runSql:           runSql,
+  MIGRATIONS_TABLE: MIGRATIONS_TABLE,
+};