@jackens/nnn 2026.2.6 → 2026.2.11

package/nnn.d.ts

@@ -312,16 +312,16 @@ export declare const js_on_parse: (handlers: Record<PropertyKey, Function>, text
  * Different languages have different plural rules. The `Intl.PluralRules` API provides
  * locale-aware plural category selection. Possible categories are:
  *
- * - `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)
+ * - `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)
  *
  * @param locale
  *
- * A BCP 47 language tag (e.g., "pl", "en").
+ * A BCP 47 language tag (e.g., `pl`, `en`).
  *
  * @param forms
  *
@@ -440,12 +440,20 @@ 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.
+ * Accessing, assigning, or deleting any nested property on the returned proxy automatically creates intermediate objects
+ * (or arrays for numeric-string keys matching `^(0|[1-9]\d*)$`) as needed, allowing deep operations 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.
+ * Intermediates of the last level in a get-only property chain are NOT auto-created.
+ * For example, `vivify(ref).one.two` will create `ref.one` as `{}`, but will NOT create `ref.one.two`.
+ * Only when a deeper access, assignment, or deletion occurs
+ * (e.g. `vivify(ref).one.two[3]` or `vivify(ref).one.two.three = 42`) will `ref.one.two` be materialized.
+ *
+ * When traversal reaches a primitive value, no auto-creation happens;
+ * the primitive’s own property is returned instead
+ * (e.g. accessing `.toString.name` on a number yields `'toString'` without modifying the underlying structure).
+ *
+ * Deletion on a non-existing intermediate path will auto-create intermediates up to the parent of the deleted key
+ * (e.g. `delete vivify(ref).a.b.c` will create `ref.a.b` as `{}` if it does not exist).
  *
  * @param ref
  *

package/nnn.js

@@ -7,21 +7,32 @@ var is_string = (arg) => typeof arg === "string";
 
 // 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) {
-    if (should_convert_target_to_array(target, key, parent)) {
-      target = parent[parentKey] = [];
+var get_target = (parent, parent_key, child_key) => {
+  if (parent_key == null) {
+    return parent;
+  }
+  if (!(parent_key in parent)) {
+    parent[parent_key] = is_string(child_key) && ARRAY_INDEX_REGEXP.test(child_key) ? [] : {};
+  }
+  return parent[parent_key];
+};
+var _vivify = (parent, parent_key) => new Proxy({}, {
+  get(_, key) {
+    const target = get_target(parent, parent_key, key);
+    if (target != null && typeof target === "object") {
+      return _vivify(target, key);
     }
-    target[key] ??= {};
-    return _vivify(target[key], target, key);
+    return target?.[key];
   },
-  set(target, key, value) {
-    if (should_convert_target_to_array(target, key, parent)) {
-      target = parent[parentKey] = [];
-    }
+  set(_, key, value) {
+    const target = get_target(parent, parent_key, key);
     target[key] = value;
     return true;
+  },
+  deleteProperty(_, key) {
+    const target = get_target(parent, parent_key, key);
+    delete target[key];
+    return true;
   }
 });
 var vivify = (ref) => _vivify(ref);
@@ -224,10 +235,8 @@ var js_on_parse = (handlers, text) => JSON.parse(text, (key, value) => {
   return value;
 });
 // src/nnn/new_noun_form.ts
-var new_noun_form = (locale, forms) => {
-  const plural_rules = new Intl.PluralRules(locale);
-  return (value) => forms[plural_rules.select(value)] ?? forms.other ?? "";
-};
+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)));

package/package.json

@@ -43,5 +43,5 @@
   "name": "@jackens/nnn",
   "type": "module",
   "types": "nnn.d.ts",
-  "version": "2026.2.6"
+  "version": "2026.2.11"
 }

package/readme.md

@@ -918,16 +918,16 @@ Creates a function that returns the appropriate noun form based on a numeric val
 Different languages have different plural rules. The `Intl.PluralRules` API provides
 locale-aware plural category selection. Possible categories are:
 
-- `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)
+- `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)
 
 #### locale
 
-A BCP 47 language tag (e.g., "pl", "en").
+A BCP 47 language tag (e.g., `pl`, `en`).
 
 #### forms
 
@@ -1252,12 +1252,20 @@ 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.
+Accessing, assigning, or deleting any nested property on the returned proxy automatically creates intermediate objects
+(or arrays for numeric-string keys matching `^(0|[1-9]\d*)$`) as needed, allowing deep operations 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.
+Intermediates of the last level in a get-only property chain are NOT auto-created.
+For example, `vivify(ref).one.two` will create `ref.one` as `{}`, but will NOT create `ref.one.two`.
+Only when a deeper access, assignment, or deletion occurs
+(e.g. `vivify(ref).one.two[3]` or `vivify(ref).one.two.three = 42`) will `ref.one.two` be materialized.
+
+When traversal reaches a primitive value, no auto-creation happens;
+the primitive’s own property is returned instead
+(e.g. accessing `.toString.name` on a number yields `'toString'` without modifying the underlying structure).
+
+Deletion on a non-existing intermediate path will auto-create intermediates up to the parent of the deleted key
+(e.g. `delete vivify(ref).a.b.c` will create `ref.a.b` as `{}` if it does not exist).
 
 #### ref
 
@@ -1272,37 +1280,140 @@ A proxy that auto-creates nested objects/arrays on property access.
 ```ts
 const ref: any = {}
 
-vivify(ref).one.two[3][4] = 1234
+vivify(ref).one.two[1][2] = 42
+
+expect(ref).to.deep.equal({
+  one: {
+    two: [
+      undefined,
+      [undefined, undefined, 42]
+    ]
+  }
+})
+
+vivify(ref).one.two[1][3] = 42
 
-expect(ref).to.deep.equal({ one: { two: [, , , [, , , , 1234]] } })
+expect(ref).to.deep.equal({
+  one: {
+    two: [
+      undefined,
+      [undefined, undefined, 42, 42]
+    ]
+  }
+})
+
+vivify(ref).one.two[1] = 42
+
+expect(ref).to.deep.equal({
+  one: {
+    two: [
+      undefined,
+      42
+    ]
+  }
+})
 
-vivify(ref).one.two[3][5] = 12345
+vivify(ref).one.two[3][0] = 42
 
-expect(ref).to.deep.equal({ one: { two: [, , , [, , , , 1234, 12345]] } })
+expect(ref).to.deep.equal({
+  one: {
+    two: [
+      undefined,
+      42,
+      undefined,
+      [42]
+    ]
+  }
+})
 
-vivify(ref).one.two[1] = 'one'
+vivify(ref).one.two[3].length = 2
 
-expect(ref).to.deep.equal({ one: { two: [, 'one', , [, , , , 1234, 12345]] } })
+expect(ref).to.deep.equal({
+  one: {
+    two: [
+      undefined,
+      42,
+      undefined,
+      [42, undefined]
+    ]
+  }
+})
 
-vivify(ref).one.two = 'tree'
+vivify(ref).one.two = 12
 
-expect(ref).to.deep.equal({ one: { two: 'tree' } })
+expect(ref).to.deep.equal({
+  one: {
+    two: 12
+  }
+})
 
 vivify(ref).one.two = undefined
 
-expect(ref).to.deep.equal({ one: { two: undefined } })
+expect(ref).to.deep.equal({
+  one: {
+    two: undefined
+  }
+})
 
 delete vivify(ref).one.two
 
-expect(ref).to.deep.equal({ one: {} })
+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: {} } } } })
+expect(ref).to.deep.equal({
+  one: {
+    two: {
+      three: {}
+    }
+  }
+})
+
+vivify(ref).one.two[3]
+
+expect(ref).to.deep.equal({
+  one: {
+    two: {
+      three: {}
+    }
+  }
+})
+
+vivify(ref).one.two.three.four = 42
+
+expect(ref).to.deep.equal({
+  one: {
+    two: {
+      three: {
+        four: 42
+      }
+    }
+  }
+})
 
-vivify(ref).one.two.three.four = 1234
+const name = vivify(ref).one.two.three.four.toString.name
 
-expect(ref).to.deep.equal({ one: { two: { three: { four: 1234 } } } })
+expect(name).to.deep.equal('toString')
+
+expect(ref).to.deep.equal({
+  one: {
+    two: {
+      three: {
+        four: 42
+      }
+    }
+  }
+})
 ```
 
 ## License