@jackens/nnn 2026.2.7 → 2026.2.11

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,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);

package/package.json

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

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,41 +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: [, , , [, , , , 1234]] } })
+expect(ref).to.deep.equal({
+  one: {
+    two: [
+      undefined,
+      [undefined, undefined, 42]
+    ]
+  }
+})
 
-vivify(ref).one.two[3][5] = 1235
+vivify(ref).one.two[1][3] = 42
 
-expect(ref).to.deep.equal({ one: { two: [, , , [, , , , 1234, 1235]] } })
+expect(ref).to.deep.equal({
+  one: {
+    two: [
+      undefined,
+      [undefined, undefined, 42, 42]
+    ]
+  }
+})
 
-vivify(ref).one.two[1] = 121
+vivify(ref).one.two[1] = 42
 
-expect(ref).to.deep.equal({ one: { two: [, 121, , [, , , , 1234, 1235]] } })
+expect(ref).to.deep.equal({
+  one: {
+    two: [
+      undefined,
+      42
+    ]
+  }
+})
+
+vivify(ref).one.two[3][0] = 42
+
+expect(ref).to.deep.equal({
+  one: {
+    two: [
+      undefined,
+      42,
+      undefined,
+      [42]
+    ]
+  }
+})
+
+vivify(ref).one.two[3].length = 2
+
+expect(ref).to.deep.equal({
+  one: {
+    two: [
+      undefined,
+      42,
+      undefined,
+      [42, undefined]
+    ]
+  }
+})
 
 vivify(ref).one.two = 12
 
-expect(ref).to.deep.equal({ one: { two: 12 } })
+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: {} } })
+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.three.four = 1234
+vivify(ref).one.two[3]
 
-expect(ref).to.deep.equal({ one: { two: { three: { four: 1234 } } } })
+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
+      }
+    }
+  }
+})
+
+const name = vivify(ref).one.two.three.four.toString.name
+
+expect(name).to.deep.equal('toString')
+
+expect(ref).to.deep.equal({
+  one: {
+    two: {
+      three: {
+        four: 42
+      }
+    }
+  }
+})
 ```
 
 ## License