@blamejs/core 0.4.13 → 0.4.14

package/CHANGELOG.md

@@ -8,6 +8,7 @@ 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

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