objwalk 1.4.0 → 1.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 Small utilities for reading, writing, walking, and reshaping nested JavaScript objects.
 
-`objwalk` is built around a compact path syntax, so the same mental model works for picking values, setting values, extracting a new object shape, and walking through nested data.
+`objwalk` is built around a compact path syntax, so the same mental model works for picking, setting, and deleting values, extracting a new object shape, and walking through nested data.
 
 > Coding agent? Load the [objwalk skill](skills/objwalk/SKILL.md).
 
@@ -15,7 +15,7 @@ npm install objwalk
 ## Usage
 
 ```ts
-import { each, equally, extract, map, merge, parse, pick, set, stringify } from 'objwalk'
+import { each, equally, extract, flush, map, merge, parse, pick, set, stringify } from 'objwalk'
 ```
 
 ## pick
@@ -96,6 +96,38 @@ set(data, 'items[0].title', 'First')
 
 `set` mutates the object passed to it and returns the same object.
 
+## flush
+
+Delete a property by path using native `delete` semantics.
+
+```ts
+const data = { user: { name: 'Ada', role: 'admin' } }
+
+flush(data, 'user.name')
+// { user: { role: 'admin' } }
+
+flush({}, 'path.to.key') // {}
+flush({ user: null }, 'user.name') // { user: null }
+```
+
+`flush(data, path)` mutates and returns the same object. Missing paths, `null`,
+`undefined`, and primitive parents are left unchanged. It does not create intermediate
+containers or remove empty parents. An empty path leaves the object unchanged.
+Only own properties are traversed and deleted; inherited properties are left unchanged.
+
+Array indexes use the same explicit syntax as `pick` and `set`:
+
+```ts
+const data = { items: [{ title: 'First' }, { title: 'Second' }] }
+
+flush(data, 'items[0].title') // { items: [{}, { title: 'Second' }] }
+flush(data, 'items[1]') // { items: [{}, <empty item>] }
+```
+
+Deleting an array item leaves a hole, preserves its length, and does not shift later items.
+Selection syntax (`{name,email}`, `{*}`) and `[n]` mappings are not supported by `flush`.
+Errors from getters, proxies, or deleting non-configurable properties propagate to the caller.
+
 ## equally
 
 Deeply compare two values for structural equality.
@@ -304,8 +336,8 @@ The wrappers do not mutate inputs, undo callback side effects, log errors, or re
 
 | Syntax | Description |
 | --- | --- |
-| `user.name` | Read or write a nested property. |
-| `items[0].title` | Read or write an array item by index. |
+| `user.name` | Read, write, or delete a nested property. |
+| `items[0].title` | Read, write, or delete an array item's property by index. |
 | `user.{name,email}` | Pick several keys from one object. |
 | `user.{*}` | List keys from one object. |
 | `items[n].title` | Map every item in an array during `extract`. |
@@ -324,6 +356,7 @@ them without redundant wrappers that only repeat object checks.
 ```ts
 pick(data, path)
 set(data, path, value)
+flush(data, path)
 extract(data, mapping)
 each(data, callback)
 map(data, callback)

package/dist/index.cjs

@@ -24,6 +24,7 @@ __export(index_exports, {
   each: () => each,
   equally: () => equally,
   extract: () => extract,
+  flush: () => flush,
   map: () => map,
   merge: () => merge,
   parse: () => parse,
@@ -274,6 +275,27 @@ var merge = (target, ...sources) => {
   return target;
 };
 
+// src/flush.ts
+var flush = (data = {}, path) => {
+  if (path.length > 0) {
+    const keys = path.split(".");
+    const lastKey = keys.pop() ?? "";
+    const match = lastKey.match(/^(\w+)\[(\d+)\]$/);
+    let parent = getValueByPath(data, keys.join("."), { inherited: false });
+    let key = lastKey;
+    if (match) {
+      const [, arrayKey, index] = match;
+      const array = getValueByKey(parent, arrayKey, { inherited: false });
+      parent = Array.isArray(array) ? array : void 0;
+      key = index;
+    }
+    if (parent !== null && typeof parent === "object" && Object.hasOwn(parent, key)) {
+      delete parent[key];
+    }
+  }
+  return data;
+};
+
 // src/deepEqual.ts
 var deepEqual = (x, y, store) => {
   if (Number.isNaN(x) && Number.isNaN(y)) {
@@ -404,6 +426,7 @@ var stringify = (value, { fallback, onError, replacer, space } = {}) => {
   each,
   equally,
   extract,
+  flush,
   map,
   merge,
   parse,

package/dist/index.d.cts

@@ -32,6 +32,8 @@ declare const merge: <T extends ObjwalkObject$1>(target: T, ...sources: unknown[
 type ObjwalkObject = Record<string, any>;
 declare const set: (data: ObjwalkObject | undefined, path: string, value: any) => ObjwalkObject;
 
+declare const flush: (data: ObjwalkObject$1 | undefined, path: string) => ObjwalkObject$1;
+
 declare const equally: (a: unknown, b: unknown) => boolean;
 
 declare const clone: <T>(value: T) => T;
@@ -40,4 +42,4 @@ declare const parse: (raw: unknown, { fallback, onError, reviver }?: ParseOption
 
 declare const stringify: (value: unknown, { fallback, onError, replacer, space }?: StringifyOptions) => string | undefined;
 
-export { type EachCallback, type ExtractMapping, type MapCallback, type ObjwalkObject$1 as ObjwalkObject, type ParseOptions, type PickOptions, type StringifyOptions, type WalkKey, clone, each, equally, extract, map, merge, parse, pick, set, stringify };
+export { type EachCallback, type ExtractMapping, type MapCallback, type ObjwalkObject$1 as ObjwalkObject, type ParseOptions, type PickOptions, type StringifyOptions, type WalkKey, clone, each, equally, extract, flush, map, merge, parse, pick, set, stringify };

package/dist/index.d.ts

@@ -32,6 +32,8 @@ declare const merge: <T extends ObjwalkObject$1>(target: T, ...sources: unknown[
 type ObjwalkObject = Record<string, any>;
 declare const set: (data: ObjwalkObject | undefined, path: string, value: any) => ObjwalkObject;
 
+declare const flush: (data: ObjwalkObject$1 | undefined, path: string) => ObjwalkObject$1;
+
 declare const equally: (a: unknown, b: unknown) => boolean;
 
 declare const clone: <T>(value: T) => T;
@@ -40,4 +42,4 @@ declare const parse: (raw: unknown, { fallback, onError, reviver }?: ParseOption
 
 declare const stringify: (value: unknown, { fallback, onError, replacer, space }?: StringifyOptions) => string | undefined;
 
-export { type EachCallback, type ExtractMapping, type MapCallback, type ObjwalkObject$1 as ObjwalkObject, type ParseOptions, type PickOptions, type StringifyOptions, type WalkKey, clone, each, equally, extract, map, merge, parse, pick, set, stringify };
+export { type EachCallback, type ExtractMapping, type MapCallback, type ObjwalkObject$1 as ObjwalkObject, type ParseOptions, type PickOptions, type StringifyOptions, type WalkKey, clone, each, equally, extract, flush, map, merge, parse, pick, set, stringify };

package/dist/index.js

@@ -239,6 +239,27 @@ var merge = (target, ...sources) => {
   return target;
 };
 
+// src/flush.ts
+var flush = (data = {}, path) => {
+  if (path.length > 0) {
+    const keys = path.split(".");
+    const lastKey = keys.pop() ?? "";
+    const match = lastKey.match(/^(\w+)\[(\d+)\]$/);
+    let parent = getValueByPath(data, keys.join("."), { inherited: false });
+    let key = lastKey;
+    if (match) {
+      const [, arrayKey, index] = match;
+      const array = getValueByKey(parent, arrayKey, { inherited: false });
+      parent = Array.isArray(array) ? array : void 0;
+      key = index;
+    }
+    if (parent !== null && typeof parent === "object" && Object.hasOwn(parent, key)) {
+      delete parent[key];
+    }
+  }
+  return data;
+};
+
 // src/deepEqual.ts
 var deepEqual = (x, y, store) => {
   if (Number.isNaN(x) && Number.isNaN(y)) {
@@ -368,6 +389,7 @@ export {
   each,
   equally,
   extract,
+  flush,
   map,
   merge,
   parse,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "objwalk",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Small utilities for reading, writing, walking, and reshaping nested JavaScript objects.",
   "keywords": [
     "object",

package/skills/objwalk/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: objwalk
-description: Use when writing or editing JavaScript or TypeScript that imports `objwalk`, reads or writes nested object paths, reshapes or walks objects, or uses objwalk JSON helpers.
+description: Use when writing or editing JavaScript or TypeScript that imports `objwalk`, reads, writes, or deletes nested object paths, reshapes or walks objects, or uses objwalk JSON helpers.
 ---
 
 # objwalk
@@ -19,7 +19,7 @@ them with type assertions or assume every method accepts arbitrary `unknown`.
 Named imports only:
 
 ```ts
-import { clone, each, equally, extract, map, merge, parse, pick, set, stringify } from 'objwalk'
+import { clone, each, equally, extract, flush, map, merge, parse, pick, set, stringify } from 'objwalk'
 ```
 
 ## Choose the existing operation
@@ -28,6 +28,7 @@ import { clone, each, equally, extract, map, merge, parse, pick, set, stringify
 | --- | --- |
 | Read a nested value | `pick(data, path, options?)`; unresolved paths return `undefined`. |
 | Write a nested value | `set(data, path, value)`; creates intermediate containers, mutates and returns `data`. |
+| Delete a nested property | `flush(data, path)`; deletes an own property, mutates and returns `data`; missing paths are left unchanged. |
 | Reshape an object | `extract(source, mapping)`; mapping keys are destination paths, values are source paths. |
 | Visit nested values | `each(data, (key, value, path) => { ... })`; visits containers and leaves, excluding the root. |
 | Build a store while walking | `map(data, (key, value, store, path) => { ... }, store?)`; returns the store, ignores callback return values. |
@@ -35,7 +36,7 @@ import { clone, each, equally, extract, map, merge, parse, pick, set, stringify
 | Deep copy | `clone(value)`; preserves `Date`, `RegExp`, symbol keys, and circular references. |
 | Deep comparison | `equally(a, b)`; supports `NaN`, `Date`, `RegExp`, and circular references. |
 
-`set` and `merge` mutate their targets. Use `clone` first only when the task
+`set`, `flush`, and `merge` mutate their targets. Use `clone` first only when the task
 requires an independent copy. `each` and `map` do not support circular traversal;
 do not infer that capability from `clone` or `equally`.
 
@@ -49,10 +50,18 @@ do not infer that capability from `clone` or `equally`.
 | `user.{*}` | List object keys with `pick`. |
 | `items[n].title` | Map array items in `extract`, with `[n]` in both source and destination paths. |
 
-`[n]` is an `extract` mapping feature, not a general wildcard for `pick` or `set`.
+`[n]` is an `extract` mapping feature, not a general wildcard for `pick`, `set`, or `flush`.
 An array of source paths in `extract` selects the first result that is not
 `undefined`, preserving `null`, `false`, `0`, and empty strings.
 
+Use `flush` to remove a property rather than `set(data, path, undefined)`, which
+leaves the property present. `flush` traverses and deletes only own properties.
+Missing, nullish, or primitive parents and empty paths are left unchanged; no
+containers are created and empty parents remain. Explicit array indexes work,
+but deleting an item leaves a hole without shifting indexes or changing length.
+Selection syntax (`{name,email}`, `{*}`) is not supported. Errors from getters,
+proxies, or deleting non-configurable properties propagate.
+
 `pick` reads inherited properties by default. Use its existing options when own
 properties or ignored keys are required: