@ultimat3/i18n 2.0.0 → 3.0.0

package/CLAUDE.md

@@ -29,6 +29,14 @@ Imported by every package that renders a string.
   for. Same reach `catalog.ts` shuts off by nesting into null-prototype nodes; never reintroduce
   either. The `interpolate` fast path must test **both** braces: `}}` un-escapes with no `{` in
   sight, and a `{`-only check gave one escape two meanings.
+- **A catalog is read through `Object.hasOwn`, never a raw index, and every catalog this package
+  builds is `Object.create(null)`** — `flattenCatalog`, `mergeCatalogs` and `nestCatalog` all are.
+  On a `{}` catalog `catalog['valueOf']` resolved to the INHERITED function, so `t('valueOf')`
+  threw inside `interpolate`, `t('constructor')` returned a function through a signature typed
+  `string`, and `isMiss(t('__proto__'))` threw on an object — all three reachable wherever a key
+  travels as data (`t(row.labelKey)`). Both halves are load-bearing: the guard in `translator.ts`
+  makes it true of a catalog this package did not build, the null prototype makes `__proto__` an
+  ordinary key instead of one the setter silently swallows. Never reintroduce either.
 - Plural selection is `Intl.PluralRules`. Never `count === 1`. Variants are underscore suffixes on
   the leaf — a CLDR category (`_zero _one _two _few _many _other`), or `n` / `n_plural` as the
   two-form shortcut; pair `n_one` with `n_other`, never with `n_plural`. Never a nested

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/i18n",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "Dependency-free translator, catalog flattening, locale negotiation and loud missing-key rendering",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "2.0.0"
+    "@ultimat3/core": "3.0.0"
   }
 }

package/src/catalog.ts

@@ -16,9 +16,14 @@ const KEY_SEGMENT = /^[A-Za-z0-9_-]+$/;
 /**
  * Depth-first flatten. Throws `X_CATALOG_INVALID` on a non-string leaf (arrays and
  * numbers are the two mistakes translators actually make) or a duplicate flat key.
+ *
+ * `Object.create(null)`, for the reason `nestCatalog` states below: a catalog is untrusted input
+ * read off disk. On a `{}` literal `out['__proto__'] = 'Hello'` hits the `Object.prototype` SETTER
+ * and the key vanishes silently, and every other member of `Object.prototype` reads back as
+ * present when it is not.
  */
 export function flattenCatalog(source: NestedCatalog, prefix = ''): Catalog {
-  const flat: Record<string, string> = {};
+  const flat = Object.create(null) as Record<string, string>;
   walk(source, prefix, flat);
   return flat;
 }
@@ -89,7 +94,9 @@ export function nestCatalog(catalog: Catalog): NestedCatalog {
  * app can override `errors.notFound.title` without forking the framework catalog.
  */
 export function mergeCatalogs(...catalogs: readonly Catalog[]): Catalog {
-  const merged: Record<string, string> = {};
+  // Null-prototyped like every catalog this package builds — a merge must not hand back an
+  // object on which `catalog['toString']` reads as a function.
+  const merged = Object.create(null) as Record<string, string>;
   for (const catalog of catalogs) {
     for (const key of Object.keys(catalog)) {
       const value = catalog[key];

package/src/translator.ts

@@ -64,7 +64,13 @@ export function createTranslator(catalog: Catalog, locale: Locale = DEFAULT_LOCA
   };
 
   const translate = (key: string, vars?: TranslateVars): string => {
-    const template = catalog[resolveKey(key, vars)];
+    // Through `hasExact`, never a raw index: a key travels as data (`t(row.labelKey)`), and on a
+    // `{}`-prototyped catalog `catalog['valueOf']` resolves to the INHERITED function instead of
+    // reading as absent — so `interpolate` threw on a non-string, `t('constructor')` returned a
+    // function through a signature typed `string`, and `isMiss(t('__proto__'))` threw on an object.
+    // Catalogs are null-prototyped now; this guard is what makes that true of any catalog.
+    const resolved = resolveKey(key, vars);
+    const template = hasExact(resolved) ? catalog[resolved] : undefined;
     if (template === undefined) return `⟦${key}⟧`;
     return vars === undefined ? template : interpolate(template, vars);
   };
@@ -75,7 +81,7 @@ export function createTranslator(catalog: Catalog, locale: Locale = DEFAULT_LOCA
       hasExact(`${key}_other`) ||
       hasExact(`${key}_plural`) ||
       hasExact(`${key}_one`),
-    raw: (key: string): string | undefined => catalog[key],
+    raw: (key: string): string | undefined => (hasExact(key) ? catalog[key] : undefined),
     keys: (): string[] => Object.keys(catalog).sort(),
     locale,
   });