@jackens/nnn 2025.12.29 → 2026.2.7

package/nnn.d.ts

@@ -126,7 +126,7 @@ export declare const new_escape: (escape_map: EscapeMap) => (template: TemplateS
  * The root DOM node to process. All descendant text nodes are corrected recursively,
  * except those inside `IFRAME`, `NOSCRIPT`, `PRE`, `SCRIPT`, `STYLE`, or `TEXTAREA` elements.
  */
-export declare const fix_typography: (node: Node) => void;
+export declare const fix_pl_typography: (node: Node) => void;
 /**
  * Single argument type for the {@link h} and {@link s} helpers.
  */
@@ -307,30 +307,32 @@ export declare const is_string: (arg: unknown) => arg is string;
  */
 export declare const js_on_parse: (handlers: Record<PropertyKey, Function>, text: string) => any;
 /**
- * Creates a function that returns the appropriate Polish noun form based on a numeric value.
+ * Creates a function that returns the appropriate noun form based on a numeric value using `Intl.PluralRules`.
  *
- * Polish has three plural forms depending on the number:
- * - Singular: used for exactly 1.
- * - “Plural 2-4”: used for 2, 3, 4, 22, 23, 24, etc. (but not 12, 13, 14).
- * - “Plural 5+”: used for 0, 5–21, 25–31, etc.
+ * Different languages have different plural rules. The `Intl.PluralRules` API provides
+ * locale-aware plural category selection. Possible categories are:
  *
- * @param singular
+ * - `zero`: for zero items (used in some languages like Arabic, Latvian)
+ * - `one`: for singular (e.g., 1 item)
+ * - `two`: for dual (used in some languages like Arabic, Hebrew)
+ * - `few`: for small plurals (e.g., 2-4 in Polish)
+ * - `many`: for larger plurals (e.g., 5-21 in Polish)
+ * - `other`: fallback category (used by all languages)
  *
- * The singular form (e.g., “auto” for “car”).
+ * @param locale
  *
- * @param plural_2
+ * A BCP 47 language tag (e.g., `pl`, `en`).
  *
- * The form for 2, 3, 4 (e.g., “auta”).
+ * @param forms
  *
- * @param plural_5
- *
- * The form for 5+ (e.g., “aut”).
+ * An object mapping plural categories to noun forms. Not all categories need to be provided;
+ * if a category is missing, the function falls back to `other`, then to an empty string.
  *
  * @returns
  *
  * A function that takes a numeric value and returns the appropriate noun form.
  */
-export declare const new_noun_form: (singular: string, plural_2: string, plural_5: string) => (value: number) => string;
+export declare const new_noun_form: (locale: string, forms: Partial<Record<Intl.LDMLPluralRule, string>>) => (value: number) => string;
 /**
  * Creates a new object containing only the specified keys from the source object.
  *
@@ -367,21 +369,6 @@ export declare const pick: <T, K extends keyof T>(ref: T, keys: K[]) => Pick<T,
  * A new object without the specified keys.
  */
 export declare const omit: <T, K extends keyof T>(ref: T, keys: unknown[]) => Omit<T, K>;
-/**
- * A Proxy-based helper for auto-vivification of nested object structures.
- *
- * Accessing any property on the returned proxy automatically creates an empty object if the property does not exist,
- * allowing deep assignments without explicit null checks.
- *
- * @param ref
- *
- * The root object to wrap.
- *
- * @returns
- *
- * A proxy that auto-creates nested objects on property access.
- */
-export declare const pro: (ref: unknown) => any;
 /**
  * A helper for building simple tokenizers (see also {@link nanolight_ts}).
  *
@@ -450,3 +437,22 @@ export declare const monokai: CRoot;
  * A UUID v1 `string` in the standard format `xxxxxxxx-xxxx-1xxx-xxxx-xxxxxxxxxxxx`.
  */
 export declare const uuid_v1: (date?: Date, node?: string) => string;
+/**
+ * A Proxy-based helper for auto-vivification of nested object structures.
+ *
+ * Accessing any property on the returned proxy automatically creates an empty object
+ * (or array for numeric keys) if the property does not exist,
+ * allowing deep assignments without explicit null checks.
+ *
+ * When a numeric key (like `[42]`) is accessed, the parent structure is
+ * automatically converted to an array if it isn’t one already.
+ *
+ * @param ref
+ *
+ * The root object to wrap.
+ *
+ * @returns
+ *
+ * A proxy that auto-creates nested objects/arrays on property access.
+ */
+export declare const vivify: (ref: unknown) => any;

package/nnn.js

@@ -5,12 +5,26 @@ var is_number = (arg) => typeof arg === "number";
 var is_record = (arg) => typeof arg === "object" && arg != null && !is_array(arg);
 var is_string = (arg) => typeof arg === "string";
 
-// src/nnn/pro.ts
-var pro = (ref) => new Proxy(ref, {
+// src/nnn/vivify.ts
+var ARRAY_INDEX_REGEXP = /^(0|[1-9]\d*)$/;
+var should_convert_target_to_array = (target, key, parent) => parent != null && typeof key === "string" && ARRAY_INDEX_REGEXP.test(key) && !is_array(target);
+var _vivify = (ref, parent, parentKey) => new Proxy(ref, {
   get(target, key) {
-    return pro(target[key] ??= {});
+    if (should_convert_target_to_array(target, key, parent)) {
+      target = parent[parentKey] = [];
+    }
+    target[key] ??= {};
+    return _vivify(target[key], target, key);
+  },
+  set(target, key, value) {
+    if (should_convert_target_to_array(target, key, parent)) {
+      target = parent[parentKey] = [];
+    }
+    target[key] = value;
+    return true;
   }
 });
+var vivify = (ref) => _vivify(ref);
 
 // src/nnn/c.ts
 var _c = (node, prefix, result, splitter) => {
@@ -65,7 +79,7 @@ var c = (root, splitter = "$$") => {
   return chunks.join("");
 };
 var rwd = (root, selector, cell_width_px, cell_height_px, ...specs) => {
-  const main = pro(root)[selector];
+  const main = vivify(root)[selector];
   main.boxSizing = "border-box";
   main.display = "block";
   main.float = "left";
@@ -73,7 +87,7 @@ var rwd = (root, selector, cell_width_px, cell_height_px, ...specs) => {
   main.height = `${cell_height_px}px`;
   specs.sort(([a], [b]) => a - b);
   for (let [max_width, width, height] of specs) {
-    const node = max_width === 1 ? main : pro(root)[`@media(min-width:${cell_width_px * max_width}px)`][selector];
+    const node = max_width === 1 ? main : vivify(root)[`@media(min-width:${cell_width_px * max_width}px)`][selector];
     width ??= 1;
     height ??= 1;
     let gcd = 100 * width;
@@ -158,9 +172,9 @@ var h = /* @__PURE__ */ _h();
 var s = /* @__PURE__ */ _h("http://www.w3.org/2000/svg");
 var svg_use = (id, ...args) => s("svg", ["use", { "xlink:href": "#" + id }], ...args);
 
-// src/nnn/fix_typography.ts
+// src/nnn/fix_pl_typography.ts
 var TAGS_TO_SKIP = ["IFRAME", "NOSCRIPT", "PRE", "SCRIPT", "STYLE", "TEXTAREA"];
-var fix_typography = (node) => {
+var fix_pl_typography = (node) => {
   const queue = [node];
   while (queue.length > 0) {
     const node_0 = queue.shift();
@@ -209,12 +223,9 @@ var js_on_parse = (handlers, text) => JSON.parse(text, (key, value) => {
   }
   return value;
 });
-// src/nnn/noun_form.ts
-var new_noun_form = (singular, plural_2, plural_5) => (value) => {
-  const abs_value = Math.abs(value);
-  const abs_value_mod_10 = abs_value % 10;
-  return value === 1 ? singular : (abs_value_mod_10 === 2 || abs_value_mod_10 === 3 || abs_value_mod_10 === 4) && abs_value !== 12 && abs_value !== 13 && abs_value !== 14 ? plural_2 : plural_5;
-};
+// src/nnn/new_noun_form.ts
+var PLURAL_RULES = {};
+var new_noun_form = (locale, forms) => (value) => forms[(PLURAL_RULES[locale] ??= new Intl.PluralRules(locale)).select(value)] ?? forms.other ?? "";
 // src/nnn/omit_pick.ts
 var pick = (ref, keys) => Object.fromEntries(Object.entries(ref).filter(([key]) => keys.includes(key)));
 var omit = (ref, keys) => Object.fromEntries(Object.entries(ref).filter(([key]) => !keys.includes(key)));
@@ -319,11 +330,11 @@ var uuid_v1 = (date = new Date, node = Math.random().toString(16).slice(2)) => {
   return time.slice(-8).concat("-", time.slice(-12, -8), -1, time.slice(-15, -12), "-", (8 | counter >> 12).toString(16), (ZEROS + (counter & 4095).toString(16)).slice(-3), "-", (ZEROS + node).slice(-12));
 };
 export {
+  vivify,
   uuid_v1,
   svg_use,
   s,
   rwd,
-  pro,
   pick,
   omit,
   new_tokenizer,
@@ -339,7 +350,7 @@ export {
   is_array,
   has_own,
   h,
-  fix_typography,
+  fix_pl_typography,
   escape_values,
   csv_parse,
   c

package/package.json

@@ -2,6 +2,7 @@
   "author": "Jackens",
   "description": "Jackens’ JavaScript helpers.",
   "keywords": [
+    "autovivify",
     "c",
     "CSS-in-JS",
     "CSV parse",
@@ -34,12 +35,13 @@
     "tokenizer",
     "typography",
     "uuid",
-    "uuidv1"
+    "uuidv1",
+    "vivify"
   ],
   "license": "MIT",
   "main": "nnn.js",
   "name": "@jackens/nnn",
   "type": "module",
   "types": "nnn.d.ts",
-  "version": "2025.12.29"
+  "version": "2026.2.7"
 }

package/readme.md

@@ -5,25 +5,43 @@ A collection of Jackens’ JavaScript helper utilities.
 ## Installation
 
 ```sh
-bun i @jackens/nnn
-```
-
-or
-
-```sh
-npm i @jackens/nnn
+bun i @jackens/nnn # npm i @jackens/nnn
 ```
 
 ## Usage
 
 ```js
-import { «something» } from '@jackens/nnn'
-```
-
-or
-
-```js
-import { «something» } from './node_modules/@jackens/nnn/nnn.js'
+import {
+  CNode,
+  CRoot,
+  EscapeMap,
+  HArgs,
+  HArgs1,
+  c,
+  csv_parse,
+  escape_values,
+  fix_pl_typography,
+  h,
+  has_own,
+  is_array,
+  is_finite_number,
+  is_number,
+  is_record,
+  is_string,
+  js_on_parse,
+  monokai,
+  nanolight_ts,
+  new_escape,
+  new_noun_form,
+  new_tokenizer,
+  omit,
+  pick,
+  rwd,
+  s,
+  svg_use,
+  uuid_v1,
+  vivify
+} from '@jackens/nnn' // './node_modules/@jackens/nnn/nnn.js'
 ```
 
 ## Exports
@@ -36,7 +54,7 @@ import { «something» } from './node_modules/@jackens/nnn/nnn.js'
 - [`c`](#c): A minimal CSS-in-JS helper that converts a JavaScript object hierarchy into a CSS string.
 - [`csv_parse`](#csv_parse): Parses a CSV string into a two-dimensional array of strings.
 - [`escape_values`](#escape_values): Escapes an array of values using the provided escape map.
-- [`fix_typography`](#fix_typography): Applies Polish-specific typographic corrections to a DOM subtree.
+- [`fix_pl_typography`](#fix_pl_typography): Applies Polish-specific typographic corrections to a DOM subtree.
 - [`h`](#h): A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper
   for creating and modifying `HTMLElement`s (see also [`s`](#s)).
 - [`has_own`](#has_own): Checks whether an object has the specified key as its own property.
@@ -49,16 +67,16 @@ import { «something» } from './node_modules/@jackens/nnn/nnn.js'
 - [`monokai`](#monokai): A Monokai-inspired color scheme for use with the [`c`](#c) helper and [`nanolight_ts`](#nanolight_ts) tokenizer.
 - [`nanolight_ts`](#nanolight_ts): A TypeScript/JavaScript syntax highlighting tokenizer built using [`new_tokenizer`](#new_tokenizer).
 - [`new_escape`](#new_escape): Creates a tag function for escaping interpolated values in template literals.
-- [`new_noun_form`](#new_noun_form): Creates a function that returns the appropriate Polish noun form based on a numeric value.
+- [`new_noun_form`](#new_noun_form): Creates a function that returns the appropriate noun form based on a numeric value using `Intl.PluralRules`.
 - [`new_tokenizer`](#new_tokenizer): A helper for building simple tokenizers (see also [`nanolight_ts`](#nanolight_ts)).
 - [`omit`](#omit): Creates a new object excluding the specified keys from the source object.
 - [`pick`](#pick): Creates a new object containing only the specified keys from the source object.
-- [`pro`](#pro): A Proxy-based helper for auto-vivification of nested object structures.
 - [`rwd`](#rwd): A responsive web design helper that generates CSS rules for a grid-like layout.
 - [`s`](#s): A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper
   for creating and modifying `SVGElement`s (see also [`h`](#h)).
 - [`svg_use`](#svg_use): Shorthand for creating an SVG element with a `<use>` child referencing an icon by ID.
 - [`uuid_v1`](#uuid_v1): Generates a UUID v1 (time-based) identifier.
+- [`vivify`](#vivify): A Proxy-based helper for auto-vivification of nested object structures.
 
 ### CNode
 
@@ -391,10 +409,10 @@ The array of values to escape.
 
 An array of escaped strings.
 
-### fix_typography
+### fix_pl_typography
 
 ```ts
-const fix_typography: (node: Node) => void;
+const fix_pl_typography: (node: Node) => void;
 ```
 
 Applies Polish-specific typographic corrections to a DOM subtree.
@@ -413,7 +431,7 @@ except those inside `IFRAME`, `NOSCRIPT`, `PRE`, `SCRIPT`, `STYLE`, or `TEXTAREA
 ```ts
 const p = h('p', 'Pchnąć w tę łódź jeża lub ośm skrzyń fig (zob. https://pl.wikipedia.org/wiki/Pangram).')
 
-fix_typography(p)
+fix_pl_typography(p)
 
 expect(p.innerHTML).to.deep.equal(
   'Pchnąć <span style="white-space:nowrap">w </span>tę łódź jeża lub ośm skrzyń fig ' +
@@ -879,12 +897,12 @@ const sql = new_escape(escape_map)
 const actual = sql`
   SELECT *
   FROM table_name
-  WHERE column_name IN (${[true, null, undefined, 42, '42', "4'2", /42/, new Date(323325000000)]})`
+  WHERE column_name IN (${[true, null, undefined, 42, '42', "4'2", new Date(323325000000)]})`
 
 const expected = `
   SELECT *
   FROM table_name
-  WHERE column_name IN (b'1', NULL, NULL, 42, '42', '4''2', NULL, '1980-03-31 04:30:00')`
+  WHERE column_name IN (b'1', NULL, NULL, 42, '42', '4''2', '1980-03-31 04:30:00')`
 
 expect(actual).to.deep.equal(expected)
 ```
@@ -892,27 +910,29 @@ expect(actual).to.deep.equal(expected)
 ### new_noun_form
 
 ```ts
-const new_noun_form: (singular: string, plural_2: string, plural_5: string) => (value: number) => string;
+const new_noun_form: (locale: string, forms: Partial<Record<Intl.LDMLPluralRule, string>>) => (value: number) => string;
 ```
 
-Creates a function that returns the appropriate Polish noun form based on a numeric value.
-
-Polish has three plural forms depending on the number:
-- Singular: used for exactly 1.
-- “Plural 2-4”: used for 2, 3, 4, 22, 23, 24, etc. (but not 12, 13, 14).
-- “Plural 5+”: used for 0, 5–21, 25–31, etc.
+Creates a function that returns the appropriate noun form based on a numeric value using `Intl.PluralRules`.
 
-#### singular
+Different languages have different plural rules. The `Intl.PluralRules` API provides
+locale-aware plural category selection. Possible categories are:
 
-The singular form (e.g., “auto” for “car”).
+- `zero`: for zero items (used in some languages like Arabic, Latvian)
+- `one`: for singular (e.g., 1 item)
+- `two`: for dual (used in some languages like Arabic, Hebrew)
+- `few`: for small plurals (e.g., 2-4 in Polish)
+- `many`: for larger plurals (e.g., 5-21 in Polish)
+- `other`: fallback category (used by all languages)
 
-#### plural_2
+#### locale
 
-The form for 2, 3, 4 (e.g., “auta”).
+A BCP 47 language tag (e.g., `pl`, `en`).
 
-#### plural_5
+#### forms
 
-The form for 5+ (e.g., “aut”).
+An object mapping plural categories to noun forms. Not all categories need to be provided;
+if a category is missing, the function falls back to `other`, then to an empty string.
 
 #### Returns
 
@@ -921,14 +941,14 @@ A function that takes a numeric value and returns the appropriate noun form.
 #### Usage Examples
 
 ```ts
-const auto = new_noun_form('auto', 'auta', 'aut')
+const auto = new_noun_form('pl', { one: 'auto', few: 'auta', other: 'aut' })
 
 expect(auto(0)).to.deep.equal('aut')
 expect(auto(1)).to.deep.equal('auto')
 expect(auto(17)).to.deep.equal('aut')
 expect(auto(42)).to.deep.equal('auta')
 
-const car = new_noun_form('car', 'cars', 'cars')
+const car = new_noun_form('en', { one: 'car', other: 'cars' })
 
 expect(car(0)).to.deep.equal('cars')
 expect(car(1)).to.deep.equal('car')
@@ -1026,55 +1046,6 @@ const obj = { a: 42, b: '42', c: 17 }
 expect(pick(obj, ['a', 'b'])).to.deep.equal({ a: 42, b: '42' })
 ```
 
-### pro
-
-```ts
-const pro: (ref: unknown) => any;
-```
-
-A Proxy-based helper for auto-vivification of nested object structures.
-
-Accessing any property on the returned proxy automatically creates an empty object if the property does not exist,
-allowing deep assignments without explicit null checks.
-
-#### ref
-
-The root object to wrap.
-
-#### Returns
-
-A proxy that auto-creates nested objects on property access.
-
-#### Usage Examples
-
-```ts
-const ref = {}
-
-pro(ref).one.two[3][4] = 1234
-
-expect(ref).to.deep.equal({ one: { two: { 3: { 4: 1234 } } } })
-
-pro(ref).one.two.tree = 123
-
-expect(ref).to.deep.equal({ one: { two: { 3: { 4: 1234 }, tree: 123 } } })
-
-pro(ref).one.two = undefined
-
-expect(ref).to.deep.equal({ one: { two: undefined } })
-
-delete pro(ref).one.two
-
-expect(ref).to.deep.equal({ one: {} })
-
-pro(ref).one.two.three.four
-
-expect(ref).to.deep.equal({ one: { two: { three: { four: {} } } } })
-
-pro(ref).one.two.three.four = 1234
-
-expect(ref).to.deep.equal({ one: { two: { three: { four: 1234 } } } })
-```
-
 ### rwd
 
 ```ts
@@ -1273,6 +1244,71 @@ expect(uuid_v1(new Date(), '123456789').split('-')[4]).to.deep.equal('0001234567
 expect(uuid_v1(new Date(323325000000)).startsWith('c1399400-9a71-11bd')).to.be.true
 ```
 
+### vivify
+
+```ts
+const vivify: (ref: unknown) => any;
+```
+
+A Proxy-based helper for auto-vivification of nested object structures.
+
+Accessing any property on the returned proxy automatically creates an empty object
+(or array for numeric keys) if the property does not exist,
+allowing deep assignments without explicit null checks.
+
+When a numeric key (like `[42]`) is accessed, the parent structure is
+automatically converted to an array if it isn’t one already.
+
+#### ref
+
+The root object to wrap.
+
+#### Returns
+
+A proxy that auto-creates nested objects/arrays on property access.
+
+#### Usage Examples
+
+```ts
+const ref: any = {}
+
+vivify(ref).one.two[3][4] = 1234
+
+expect(ref).to.deep.equal({ one: { two: [, , , [, , , , 1234]] } })
+
+vivify(ref).one.two[3][5] = 1235
+
+expect(ref).to.deep.equal({ one: { two: [, , , [, , , , 1234, 1235]] } })
+
+vivify(ref).one.two[1] = 121
+
+expect(ref).to.deep.equal({ one: { two: [, 121, , [, , , , 1234, 1235]] } })
+
+vivify(ref).one.two = 12
+
+expect(ref).to.deep.equal({ one: { two: 12 } })
+
+vivify(ref).one.two = undefined
+
+expect(ref).to.deep.equal({ one: { two: undefined } })
+
+delete vivify(ref).one.two
+
+expect(ref).to.deep.equal({ one: {} })
+
+delete vivify(ref).one.two.three
+
+expect(ref).to.deep.equal({ one: { two: {} } })
+
+vivify(ref).one.two.three.four
+
+expect(ref).to.deep.equal({ one: { two: { three: { four: {} } } } })
+
+vivify(ref).one.two.three.four = 1234
+
+expect(ref).to.deep.equal({ one: { two: { three: { four: 1234 } } } })
+```
+
 ## License
 
 The MIT License (MIT)