@blamejs/core 0.4.12 → 0.4.14

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- **0.4.13** (2026-04-30) — b.db: streaming query results
+- **0.4.12** (2026-04-30) — b.log: multi-sink output with per-sink level filtering
 - **0.4.11** (2026-04-30) — b.cache: bytes-cap eviction, sliding TTL, tag invalidation
 - **0.4.10** (2026-04-30) — bodyParser multipart: fileFilter + per-field maxBytes/mimeTypes
 - **0.4.9** (2026-04-30) — Origin-Agent-Cluster + DNS-Prefetch-Control headers; b.auth.lockout primitive

package/lib/db-query.js

@@ -184,6 +184,37 @@ class Query {
     return out;
   }
 
+  // Streaming counterpart to all(). Each row is auto-unsealed against
+  // the bound table's sealedFields registration before it lands in the
+  // operator's pipeline. For large result sets (audit exports, backup
+  // table dumps) this avoids materializing the full rowset in memory.
+  stream() {
+    var sql = "SELECT " + this._projection() + ' FROM "' + this._table + '"' +
+              this._whereClause() + this._orderLimitOffset();
+    var stmt = this._db.prepare(sql);
+    var table = this._table;
+    var iter;
+    var Readable = require("node:stream").Readable;
+    try { iter = stmt.iterate.apply(stmt, this._whereParams); }
+    catch (e) {
+      var r = new Readable({ objectMode: true, read: function () {} });
+      setImmediate(function () { r.destroy(e); });
+      return r;
+    }
+    return new Readable({
+      objectMode: true,
+      read: function () {
+        try {
+          var step = iter.next();
+          if (step.done) { this.push(null); return; }
+          this.push(cryptoField.unsealRow(table, step.value));
+        } catch (e) {
+          this.destroy(e);
+        }
+      },
+    });
+  }
+
   count() {
     var sql = 'SELECT COUNT(*) AS n FROM "' + this._table + '"' + this._whereClause();
     var stmt = this._db.prepare(sql);

package/lib/db.js

@@ -32,6 +32,8 @@
  *
  *   db.from(tableName)                 → Query (chainable)
  *   db.prepare(sql)                    → SQLite Statement (raw escape hatch)
+ *   db.stream(sql, ...params, opts?)   → Readable (object-mode rows;
+ *                                       opts.table enables auto-unseal)
  *   db.runSql(sql)                     → raw SQL execution (DDL, BEGIN/COMMIT)
  *   db.transaction(function (db) {…})  → wraps in BEGIN/COMMIT/ROLLBACK
  *   db.hashFor(table, field, value)    → derived-hash lookup helper
@@ -746,6 +748,66 @@ function prepare(sql) {
   return database.prepare(sql);
 }
 
+// stream — Readable in object mode that yields rows as node:sqlite's
+// iterate() produces them. Unlike all(), the engine doesn't materialize
+// the result set in memory before the first row arrives, so audit
+// exports / backup table dumps / large reports can process millions of
+// rows without OOM pressure.
+//
+// Optional opts.table enables auto-unseal of sealed columns via the
+// table's registered cryptoField schema. Raw / aggregate queries omit
+// it. Mid-iteration prepare()-bound errors propagate as 'error' events.
+function stream(sql) {
+  _requireInit();
+  var opts = null;
+  var params;
+  // Last arg may be a plain {table?} options object; everything else
+  // is a SQL parameter binding. node:sqlite accepts numbers, strings,
+  // bigints, Buffers, and null — plain objects can only be opts.
+  var args = Array.prototype.slice.call(arguments, 1);
+  if (args.length > 0) {
+    var last = args[args.length - 1];
+    var isOptsShape = last !== null && typeof last === "object" &&
+      !Buffer.isBuffer(last) && !Array.isArray(last) &&
+      typeof last.length !== "number"; // exclude TypedArray-shapes
+    if (isOptsShape) {
+      opts = last;
+      params = args.slice(0, -1);
+    } else {
+      params = args;
+    }
+  } else {
+    params = [];
+  }
+  var table = opts && typeof opts.table === "string" ? opts.table : null;
+  var unseal = table ? cryptoField : null;
+
+  var Readable = require("node:stream").Readable;
+  var stmt;
+  var iter;
+  try {
+    stmt = database.prepare(sql);
+    iter = stmt.iterate.apply(stmt, params);
+  } catch (e) {
+    var r = new Readable({ objectMode: true, read: function () {} });
+    setImmediate(function () { r.destroy(e); });
+    return r;
+  }
+  return new Readable({
+    objectMode: true,
+    read: function () {
+      try {
+        var step = iter.next();
+        if (step.done) { this.push(null); return; }
+        var row = step.value;
+        this.push(unseal ? unseal.unsealRow(table, row) : row);
+      } catch (e) {
+        this.destroy(e);
+      }
+    },
+  });
+}
+
 function execRaw(sql) {
   _requireInit();
   return runSql(database, sql);
@@ -946,6 +1008,7 @@ module.exports = {
   init:                init,
   from:                from,
   prepare:             prepare,
+  stream:              stream,
   runSql:              execRaw,
   // SQLite multi-statement helper alias matching the node:sqlite
   // module's shape. Operator migration / seeder files that received

package/lib/i18n.js

@@ -385,12 +385,32 @@ function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
     "defaultLocale", "locales", "fallbackLocale",
-    "translations", "dir",
-    "interpolation", "missingKey", "rtlLanguages",
+    "translations", "dir", "eagerLocales", "lazyLoad",
+    "interpolation", "missingKey", "onMissingKey", "rtlLanguages",
     "observability", "clock",
   ], "b.i18n");
   _validateCreateOpts(opts);
 
+  if (opts.lazyLoad === true && opts.translations) {
+    throw _err("BAD_OPT", "i18n.create: lazyLoad: true requires dir-based loading; " +
+      "translations: { ... } is inline-only and already complete at create time");
+  }
+  if (opts.eagerLocales !== undefined) {
+    if (!Array.isArray(opts.eagerLocales)) {
+      throw _err("BAD_OPT", "i18n.create: eagerLocales must be an array of BCP 47 tags");
+    }
+    for (var ei = 0; ei < opts.eagerLocales.length; ei++) {
+      _validateLocale("i18n.create: eagerLocales[" + ei + "]", opts.eagerLocales[ei]);
+      if (opts.locales.indexOf(opts.eagerLocales[ei]) === -1) {
+        throw _err("BAD_OPT", "i18n.create: eagerLocales[" + ei + "] '" +
+          opts.eagerLocales[ei] + "' must be in locales array");
+      }
+    }
+  }
+  if (opts.onMissingKey !== undefined && typeof opts.onMissingKey !== "function") {
+    throw _err("BAD_OPT", "i18n.create: onMissingKey must be a function (key, locale)");
+  }
+
   var defaultLocale = opts.defaultLocale;
   var locales = opts.locales.slice();
   var fallbackLocale = (opts.fallbackLocale === null) ? null
@@ -401,22 +421,54 @@ function create(opts) {
   var operatorObs = opts.observability || null;
 
   // Translations: either inline object or loaded from dir at create.
+  // With lazyLoad, only eager locales hit disk now; the rest load on
+  // first lookup that resolves to them.
   var translations;
+  var lazyLoadEnabled = false;
+  var lazyLoadDir = null;
+  var loadedSet = new Set();
   if (opts.dir) {
-    translations = _loadFromDir(opts.dir, locales);
+    if (opts.lazyLoad === true) {
+      lazyLoadEnabled = true;
+      lazyLoadDir = opts.dir;
+      var eager = Array.isArray(opts.eagerLocales) && opts.eagerLocales.length > 0
+                    ? opts.eagerLocales
+                    : [defaultLocale];
+      translations = _loadFromDir(opts.dir, eager);
+      for (var ei2 = 0; ei2 < eager.length; ei2++) loadedSet.add(eager[ei2]);
+    } else {
+      translations = _loadFromDir(opts.dir, locales);
+      for (var ei3 = 0; ei3 < locales.length; ei3++) loadedSet.add(locales[ei3]);
+    }
   } else if (opts.translations) {
     translations = opts.translations;
+    for (var ei4 = 0; ei4 < locales.length; ei4++) {
+      if (translations[locales[ei4]]) loadedSet.add(locales[ei4]);
+    }
   } else {
     translations = {};
   }
+  var onMissingKey = opts.onMissingKey || null;
   // Validate translation trees up-front so plural-shape errors surface
-  // at boot, not at the first request that hits the broken key.
+  // at boot, not at the first request that hits the broken key. Lazy
+  // locales validate on first load.
   for (var li = 0; li < locales.length; li++) {
     var loc = locales[li];
     if (translations[loc]) {
       _validateTranslationTree(loc, translations[loc], "");
     }
   }
+
+  function _ensureLocaleLoaded(locale) {
+    if (loadedSet.has(locale)) return;
+    if (!lazyLoadEnabled || !lazyLoadDir) return;        // not configured for lazy
+    if (!localesSet.has(locale)) return;                  // unknown locale; lookup falls through
+    var loaded = _loadFromDir(lazyLoadDir, [locale]);
+    translations[locale] = loaded[locale];
+    _validateTranslationTree(locale, translations[locale], "");
+    loadedSet.add(locale);
+    _emitObs("i18n.lazyLoad", { locale: locale });
+  }
   var localesSet = new Set(locales);
   var currentLocale = defaultLocale;
 
@@ -493,6 +545,7 @@ function create(opts) {
     var chain = _localeChain(locale);
     for (var i = 0; i < chain.length; i++) {
       var loc = chain[i];
+      _ensureLocaleLoaded(loc);
       if (!translations[loc]) continue;
       var v = _resolveKey(translations[loc], key);
       if (v !== undefined) {
@@ -502,8 +555,20 @@ function create(opts) {
     return null;
   }
 
-  function _selectPlural(node, count, locale) {
-    var rules = _pluralRulesFor(locale);
+  // Ordinal-plural rules cache — separate from cardinal because Intl.PluralRules
+  // is type-fixed at construction.
+  var ordinalRulesByLocale = {};
+  function _ordinalRulesFor(locale) {
+    var r = ordinalRulesByLocale[locale];
+    if (!r) {
+      r = new Intl.PluralRules(locale, { type: "ordinal" });
+      ordinalRulesByLocale[locale] = r;
+    }
+    return r;
+  }
+
+  function _selectPlural(node, count, locale, ordinal) {
+    var rules = ordinal ? _ordinalRulesFor(locale) : _pluralRulesFor(locale);
     var category = rules.select(count);
     if (typeof node[category] === "string") return node[category];
     // Fallback within the entry: "other" was validated mandatory at load.
@@ -520,6 +585,10 @@ function create(opts) {
 
     if (!found) {
       _emitObs("i18n.missing", { locale: locale, key: key });
+      if (onMissingKey) {
+        try { onMissingKey(key, locale); }
+        catch (_e) { /* hook is best-effort; never break the request */ }
+      }
       if (callerOpts.default !== undefined) return callerOpts.default;
       if (typeof missingKeyPolicy === "function") {
         return missingKeyPolicy(key, locale);
@@ -540,7 +609,7 @@ function create(opts) {
       raw = found.value;
     } else if (_isPluralShape(found.value)) {
       var count = (vars && typeof vars.count === "number") ? vars.count : 0;
-      raw = _selectPlural(found.value, count, found.foundIn);
+      raw = _selectPlural(found.value, count, found.foundIn, callerOpts.ordinal === true);
     } else {
       // Operator stored a nested tree at this key but called t() against
       // the namespace. Return the key-path as a missing-key signal.
@@ -560,6 +629,20 @@ function create(opts) {
     return t(key, merged, callerOpts);
   }
 
+  // to — ordinal-plural counterpart of tn. Selects from the entry using
+  // Intl.PluralRules({ type: "ordinal" }), so English keys
+  // { one: "{count}st", two: "{count}nd", few: "{count}rd", other: "{count}th" }
+  // resolve as "1st", "2nd", "3rd", "4th", "21st", etc.
+  function to(key, count, vars, callerOpts) {
+    if (typeof count !== "number" || !isFinite(count)) {
+      throw _err("BAD_INPUT", "i18n.to: count must be a finite number, got " +
+        (typeof count) + " " + JSON.stringify(count));
+    }
+    var merged = vars ? Object.assign({}, vars, { count: count }) : { count: count };
+    var withOrdinal = Object.assign({}, callerOpts || {}, { ordinal: true });
+    return t(key, merged, withOrdinal);
+  }
+
   function has(key, callerOpts) {
     callerOpts = callerOpts || {};
     if (typeof key !== "string" || key.length === 0) return false;
@@ -727,6 +810,11 @@ function create(opts) {
           if (c.locale === undefined) c.locale = resolvedLocale;
           return tn(key, count, vars, c);
         }
+        function reqTo(key, count, vars, callerOpts) {
+          var c = callerOpts ? Object.assign({}, callerOpts) : {};
+          if (c.locale === undefined) c.locale = resolvedLocale;
+          return to(key, count, vars, c);
+        }
         function reqDir() {
           return dir({ locale: resolvedLocale });
         }
@@ -734,12 +822,14 @@ function create(opts) {
         req.locale = resolvedLocale;
         req.t = reqT;
         req.tn = reqTn;
+        req.to = reqTo;
         req.dir = reqDir;
         if (res && typeof res === "object") {
           if (!res.locals) res.locals = {};
           res.locals.locale = resolvedLocale;
           res.locals.t = reqT;
           res.locals.tn = reqTn;
+          res.locals.to = reqTo;
           res.locals.dir = reqDir();
         }
       } catch (_e) {
@@ -753,6 +843,7 @@ function create(opts) {
   return {
     t:               t,
     tn:              tn,
+    to:              to,
     has:             has,
     formatNumber:    formatNumber,
     formatDate:      formatDate,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.4.12",
+  "version": "0.4.14",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",