@jackens/nnn 2026.2.7 → 2026.2.13

package/nnn.d.ts

@@ -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,24 +7,27 @@ 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 _is_object = (ref) => typeof ref === "object";
+var _get_target = (parent, parent_key, key) => parent[parent_key] ??= is_string(key) && ARRAY_INDEX_REGEXP.test(key) ? [] : {};
+var _vivify = (parent, parent_key) => {
+  return parent != null && _is_object(parent) ? new Proxy(parent, {
+    get(_, key) {
+      const target = _get_target(parent, parent_key, key);
+      const value = target[key];
+      return is_string(key) && _is_object(target) && (value == null || _is_object(value)) ? _vivify(target, key) : value;
+    },
+    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);
+      return delete target[key];
     }
-    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);
+  }) : parent?.[parent_key];
+};
+var vivify = (ref) => _vivify({ _: ref }, "_");
 
 // src/nnn/c.ts
 var _c = (node, prefix, result, splitter) => {

package/package.json

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

package/readme.md

@@ -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,17 +1280,29 @@ 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: [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][0] = 42
 
-expect(ref).to.deep.equal({ one: { two: [, , , [, , , , 1234]] } })
+expect(ref).to.deep.equal({ one: { two: [undefined, 42, undefined, [42]] } })
 
-vivify(ref).one.two[3][5] = 1235
+vivify(ref).one.two[3].length = 2
 
-expect(ref).to.deep.equal({ one: { two: [, , , [, , , , 1234, 1235]] } })
+expect(ref).to.deep.equal({ one: { two: [undefined, 42, undefined, [42, undefined]] } })
 
-vivify(ref).one.two[1] = 121
+expect(vivify(ref).one.two.length).to.deep.equal(4)
 
-expect(ref).to.deep.equal({ one: { two: [, 121, , [, , , , 1234, 1235]] } })
+expect(ref).to.deep.equal({ one: { two: [undefined, 42, undefined, [42, undefined]] } })
 
 vivify(ref).one.two = 12
 
@@ -1296,17 +1316,31 @@ delete vivify(ref).one.two
 
 expect(ref).to.deep.equal({ one: {} })
 
+expect(vivify(ref).one.toString instanceof Function).to.be.true
+
+expect(vivify(ref).one.toString.name).to.equal('toString')
+
+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
+expect(vivify(ref).one.two.three.four.toString.name).to.deep.equal('toString')
 
-expect(ref).to.deep.equal({ one: { two: { three: { four: 1234 } } } })
+expect(ref).to.deep.equal({ one: { two: { three: { four: 42 } } } })
 ```
 
 ## License