@blamejs/core 0.4.13 → 0.4.15

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- **0.4.14** (2026-04-30) — b.i18n: lazy locales + ordinal plurals + onMissingKey hook
+- **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

package/lib/http-client.js

@@ -292,10 +292,198 @@ function _fromH2Headers(h2Headers) {
 
 // ---- request() ----
 
+var REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+
+// Build a multipart/form-data body from { fields, files } shape.
+// Mirrors the wire format that lib/middleware/body-parser.js's multipart
+// parser accepts so round-trip from one blamejs app's outbound to
+// another's inbound is exact.
+function _buildMultipartBody(spec) {
+  var nodeCrypto = require("node:crypto");
+  var boundary = "----blamejs-mp-" + nodeCrypto.randomBytes(16).toString("hex");
+  var CRLF = "\r\n";
+  var parts = [];
+
+  function _pushField(name, value) {
+    if (typeof name !== "string" || name.length === 0) {
+      throw new Error("multipart: field name must be a non-empty string");
+    }
+    var head = "--" + boundary + CRLF +
+               'Content-Disposition: form-data; name="' + name + '"' + CRLF + CRLF;
+    parts.push(Buffer.from(head, "utf8"));
+    parts.push(Buffer.isBuffer(value) ? value : Buffer.from(String(value), "utf8"));
+    parts.push(Buffer.from(CRLF, "utf8"));
+  }
+
+  function _pushFile(file) {
+    if (!file || typeof file !== "object") throw new Error("multipart: file entries must be objects");
+    if (typeof file.field !== "string" || file.field.length === 0) {
+      throw new Error("multipart: file.field must be a non-empty string");
+    }
+    var filename = typeof file.filename === "string" && file.filename.length > 0
+      ? file.filename : "blob";
+    var mimeType = file.contentType || file.mimeType || "application/octet-stream";
+    var content = file.content;
+    if (typeof content === "string") content = Buffer.from(content, "utf8");
+    if (!Buffer.isBuffer(content)) {
+      throw new Error("multipart: file.content must be a Buffer or string");
+    }
+    var head = "--" + boundary + CRLF +
+               'Content-Disposition: form-data; name="' + file.field + '"' +
+                 '; filename="' + filename.replace(/"/g, "%22") + '"' + CRLF +
+               "Content-Type: " + mimeType + CRLF + CRLF;
+    parts.push(Buffer.from(head, "utf8"));
+    parts.push(content);
+    parts.push(Buffer.from(CRLF, "utf8"));
+  }
+
+  if (spec && spec.fields && typeof spec.fields === "object") {
+    var keys = Object.keys(spec.fields);
+    for (var i = 0; i < keys.length; i++) {
+      var k = keys[i];
+      var v = spec.fields[k];
+      if (Array.isArray(v)) {
+        for (var j = 0; j < v.length; j++) _pushField(k, v[j]);
+      } else {
+        _pushField(k, v);
+      }
+    }
+  }
+  if (spec && Array.isArray(spec.files)) {
+    for (var fi = 0; fi < spec.files.length; fi++) _pushFile(spec.files[fi]);
+  }
+  parts.push(Buffer.from("--" + boundary + "--" + CRLF, "utf8"));
+  return { boundary: boundary, body: Buffer.concat(parts) };
+}
+
+// Headers stripped on cross-origin redirect to defend against accidental
+// credential exfiltration. Lower-case for header-map comparison.
+var SENSITIVE_HEADERS_LC = ["authorization", "cookie", "proxy-authorization"];
+
+function _stripCrossOriginAuth(headers) {
+  var out = {};
+  var keys = Object.keys(headers);
+  for (var i = 0; i < keys.length; i++) {
+    if (SENSITIVE_HEADERS_LC.indexOf(keys[i].toLowerCase()) !== -1) continue;
+    out[keys[i]] = headers[keys[i]];
+  }
+  return out;
+}
+
 function request(opts) {
   if (!opts || !opts.url) {
     return Promise.reject(_makeError(opts && opts.errorClass, "BAD_ARG", "url is required", true));
   }
+
+  // Multipart shorthand: { multipart: { fields, files } } expands to
+  // body + Content-Type with the boundary parameter. Mutually exclusive
+  // with caller-supplied body / Content-Type.
+  if (opts.multipart) {
+    if (opts.body !== undefined) {
+      return Promise.reject(_makeError(opts.errorClass, "BAD_ARG",
+        "request: pass either { body } or { multipart }, not both", true));
+    }
+    var built;
+    try { built = _buildMultipartBody(opts.multipart); }
+    catch (e) {
+      return Promise.reject(_makeError(opts.errorClass, "BAD_ARG", e.message, true));
+    }
+    opts = Object.assign({}, opts, {
+      method: opts.method || "POST",
+      body:   built.body,
+      headers: Object.assign({}, opts.headers || {}, {
+        "Content-Type":   "multipart/form-data; boundary=" + built.boundary,
+        "Content-Length": String(built.body.length),
+      }),
+      multipart: undefined,
+    });
+  }
+
+  // maxRedirects:
+  //   undefined → today's behavior (no follow). Caller inspects 3xx.
+  //   null      → today's behavior (explicit). Same as undefined.
+  //   0         → no follow, but 3xx returned to caller (alias of null).
+  //   N         → follow up to N hops; 3xx with no Location returned as-is.
+  var maxRedirects = (opts.maxRedirects === undefined || opts.maxRedirects === null)
+    ? null : opts.maxRedirects;
+  if (maxRedirects !== null) {
+    if (typeof maxRedirects !== "number" || !isFinite(maxRedirects) || maxRedirects < 0 ||
+        Math.floor(maxRedirects) !== maxRedirects) {
+      return Promise.reject(_makeError(opts.errorClass, "BAD_ARG",
+        "maxRedirects must be a non-negative integer or null", true));
+    }
+  }
+  if (maxRedirects === null || maxRedirects === 0) {
+    return _requestSingle(opts);
+  }
+
+  return _requestWithRedirects(opts, maxRedirects);
+}
+
+function _requestWithRedirects(opts, hopsLeft) {
+  var originalUrl = opts.url;
+  var originalOrigin = null;
+  try {
+    var u0 = new URL(opts.url);
+    originalOrigin = u0.protocol + "//" + u0.host;
+  } catch (_e) { /* request() will reject on next hop's parse */ }
+
+  var current = Object.assign({}, opts, { _resolveOnRedirect: true });
+  function _follow() {
+    return _requestSingle(current).then(function (res) {
+      if (!REDIRECT_STATUSES.has(res.statusCode) || hopsLeft <= 0) return res;
+      var loc = res.headers && (res.headers.location || res.headers.Location);
+      if (!loc) return res;        // 3xx with no Location — operator handles
+      hopsLeft -= 1;
+
+      // Resolve relative Location against the just-fetched URL (the URL
+      // of the request that produced the redirect, which may itself be a
+      // post-redirect URL).
+      var nextUrl;
+      try { nextUrl = new URL(loc, current.url).toString(); }
+      catch (_e) {
+        return Promise.reject(_makeError(opts.errorClass, "BAD_REDIRECT",
+          "Location header invalid URL: " + loc, true));
+      }
+
+      // Cross-origin auth-header strip.
+      var nextHeaders = current.headers || {};
+      var nextOrigin;
+      try {
+        var nu = new URL(nextUrl);
+        nextOrigin = nu.protocol + "//" + nu.host;
+      } catch (_e) { /* request() will reject when it tries to parse */ }
+      if (originalOrigin && nextOrigin && nextOrigin !== originalOrigin) {
+        nextHeaders = _stripCrossOriginAuth(nextHeaders);
+      }
+
+      // 303 → always GET; body dropped. 301/302 → historical clients
+      // also coerce non-GET bodies (we follow that convention). 307/308
+      // → preserve method + body.
+      var nextMethod = current.method || "GET";
+      var nextBody = current.body;
+      if (res.statusCode === 303 ||
+          ((res.statusCode === 301 || res.statusCode === 302) &&
+           nextMethod !== "GET" && nextMethod !== "HEAD")) {
+        nextMethod = "GET";
+        nextBody = undefined;
+      }
+
+      current = Object.assign({}, current, {
+        url:                 nextUrl,
+        method:              nextMethod,
+        body:                nextBody,
+        headers:             nextHeaders,
+        _resolveOnRedirect:  true,
+      });
+      return _follow();
+    });
+  }
+  void originalUrl;
+  return _follow();
+}
+
+function _requestSingle(opts) {
   // Validate scheme + shape via url-safe. Default is HTTPS-only — the
   // framework refuses to silently drop bytes on the wire as cleartext.
   // Callers with cleartext endpoints (h2c, internal services, test
@@ -410,6 +598,12 @@ function _requestH1(transport, u, opts) {
         });
         if (res.statusCode >= 200 && res.statusCode < 300) {
           _resolve({ statusCode: res.statusCode, headers: res.headers, body: buf });
+        } else if (opts._resolveOnRedirect && REDIRECT_STATUSES.has(res.statusCode)) {
+          // Redirect-following layer needs the response object intact so
+          // it can inspect Location and re-issue. The caller-facing
+          // request() never sets _resolveOnRedirect — operator code that
+          // didn't ask for redirect-following keeps seeing 3xx as errors.
+          _resolve({ statusCode: res.statusCode, headers: res.headers, body: buf });
         } else {
           var msg = "HTTP " + res.statusCode + ": " + buf.toString("utf8").slice(0, 500);
           _reject(_makeError(opts.errorClass, "HTTP_ERROR", msg,

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.13",
+  "version": "0.4.15",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",