objwalk 1.3.1 → 1.5.0

package/README.md

@@ -2,7 +2,9 @@
 
 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).
 
 ## Install
 
@@ -13,7 +15,7 @@ npm install objwalk
 ## Usage
 
 ```ts
-import { each, equally, extract, map, merge, pick, set } from 'objwalk'
+import { each, equally, extract, flush, map, merge, parse, pick, set, stringify } from 'objwalk'
 ```
 
 ## pick
@@ -94,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.
@@ -214,24 +248,120 @@ The callback receives:
 
 `map` returns `store`.
 
+## parse and stringify
+
+Parse JSON or accept a ready value, and serialize values with optional error handling.
+Exceptions return `undefined`, unless a fallback is provided or `onError` throws.
+
+```ts
+import { parse, stringify, type ParseOptions, type StringifyOptions } from 'objwalk'
+
+// Signatures:
+// parse(raw: unknown, options?: ParseOptions): unknown
+// stringify(value: unknown, options?: StringifyOptions): string | undefined
+
+const value = parse('{"a":1}') // { a: 1 }, typed as unknown
+const valueOrNull = parse('{', { fallback: null }) // null
+const text = stringify(value, { fallback: 'null', space: 2 })
+const object = { a: 1 }
+const array = [1, 2]
+
+parse(object) === object // true
+parse(array) === array // true
+
+parse('[]') // []
+stringify({}) // '{}'
+stringify([]) // '[]'
+stringify(null) // 'null'
+stringify('{}') // '"{}"'
+```
+
+Root values can be objects, arrays, strings, numbers, booleans, or `null`;
+neither function requires an expected shape or restricts values to objects.
+`parse` returns `unknown`; successful parsing does not validate the expected data structure.
+Validate the result before using it as a specific type. There is no `parse<T>()` overload.
+
+`parse` accepts `unknown`. Plain objects (with `Object.prototype` or a `null` prototype) and
+arrays are returned by reference, without cloning, serialization, mutation, or calling `reviver`.
+Other inputs use `JSON.parse(typeof raw === 'string' ? raw : String(raw), reviver)`.
+ArrayBuffer, DataView, and typed-array views use this text path; there is no binary decoder.
+For example, a Node.js Buffer containing JSON text can be parsed through its native string conversion.
+Errors during input recognition or string conversion follow the same `onError`/`fallback` contract.
+
+| Option | `ParseOptions` | `StringifyOptions` |
+| --- | --- | --- |
+| `fallback` | `unknown`, default `undefined` | `string`, default `undefined` |
+| `onError` | `(error: unknown) => void` | `(error: unknown) => void` |
+| `reviver` | Native `JSON.parse` callback, only for the text path | — |
+| `replacer` | — | Native callback or array of strings/numbers (also accepts `null`) |
+| `space` | — | `string` or `number` for native JSON formatting |
+
+Callbacks retain native `this` binding. For example, a reviver can transform or delete properties,
+and a replacer can select or transform values:
+
+```ts
+parse('{"count":2,"secret":true}', {
+  reviver: (key, value) => key === 'secret' ? undefined : value,
+}) // { count: 2 }
+
+stringify({ name: 'Ada', secret: true }, { replacer: ['name'], space: 2 })
+// '{\n  "name": "Ada"\n}'
+```
+
+On an exception, `onError` receives the original error once, then the function returns `fallback`.
+The callback's return value is ignored. Exceptions from `reviver`, `replacer`, `toJSON`, or getters
+follow the same rule. If `onError` throws, its exception propagates to the caller:
+
+```ts
+const requiredText = stringify(value, {
+  onError: (error) => {
+    throw error
+  },
+}) // still string | undefined
+
+stringify(1n, { fallback: 'null' }) // 'null' (BigInt throws natively)
+stringify(undefined, { fallback: 'null' }) // undefined (no exception)
+parse('false', { fallback: true }) // false
+parse('null', { fallback: {} }) // null
+```
+
+Fallbacks apply only to exceptions: valid `0`, `false`, `''`, and `null` are preserved.
+Likewise, a reviver returning `undefined` for the root does not trigger a fallback.
+Top-level `undefined`, functions, and symbols serialize to native `undefined` without calling
+`onError`. Native handling of these values inside objects/arrays, `NaN`, `Infinity`, and `toJSON`
+is preserved. Circular references throw natively and use the same error handling as BigInt.
+The wrappers do not mutate inputs, undo callback side effects, log errors, or repair invalid JSON.
+
 ## Path syntax
 
 | 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`. |
 
+## Agent skill
+
+The package includes an [objwalk skill](skills/objwalk/SKILL.md) in `skills/objwalk/`.
+After installation, point your agent at `node_modules/objwalk/skills/objwalk/SKILL.md`.
+If your agent uses a skill directory, link the entire `skills/objwalk` folder, not just `SKILL.md`.
+
+The skill explains the existing object utilities and JSON helpers, and directs agents to use
+them without redundant wrappers that only repeat object checks.
+
 ## API
 
 ```ts
 pick(data, path)
 set(data, path, value)
+flush(data, path)
 extract(data, mapping)
 each(data, callback)
 map(data, callback)
 merge(target, ...sources)
 equally(a, b)
+parse(raw, options?) // unknown
+stringify(value, options?) // string | undefined
 ```

package/dist/index.cjs

@@ -24,10 +24,13 @@ __export(index_exports, {
   each: () => each,
   equally: () => equally,
   extract: () => extract,
+  flush: () => flush,
   map: () => map,
   merge: () => merge,
+  parse: () => parse,
   pick: () => pick,
-  set: () => set
+  set: () => set,
+  stringify: () => stringify
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -272,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)) {
@@ -363,14 +387,50 @@ var clone = (value) => {
   };
   return cloneValue(value);
 };
+
+// src/parse.ts
+var parse = (raw, { fallback, onError, reviver } = {}) => {
+  try {
+    if (Array.isArray(raw)) {
+      return raw;
+    }
+    if (typeof raw === "object" && raw !== null) {
+      const isBinary = raw instanceof ArrayBuffer || ArrayBuffer.isView(raw);
+      const prototype = Object.getPrototypeOf(raw);
+      if (isBinary === false && (prototype === Object.prototype || prototype === null)) {
+        return raw;
+      }
+    }
+    return JSON.parse(typeof raw === "string" ? raw : String(raw), reviver);
+  } catch (error) {
+    onError?.(error);
+    return fallback;
+  }
+};
+
+// src/stringify.ts
+var stringify = (value, { fallback, onError, replacer, space } = {}) => {
+  try {
+    if (typeof replacer === "function") {
+      return JSON.stringify(value, replacer, space);
+    }
+    return JSON.stringify(value, replacer, space);
+  } catch (error) {
+    onError?.(error);
+    return fallback;
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   clone,
   each,
   equally,
   extract,
+  flush,
   map,
   merge,
+  parse,
   pick,
-  set
+  set,
+  stringify
 });

package/dist/index.d.cts

@@ -3,6 +3,17 @@ type PickOptions = {
     inherited?: boolean;
     ignore?: readonly string[];
 };
+type ParseOptions = {
+    fallback?: unknown;
+    onError?: (error: unknown) => void;
+    reviver?: Parameters<typeof JSON.parse>[1];
+};
+type StringifyOptions = {
+    fallback?: string;
+    onError?: (error: unknown) => void;
+    replacer?: ParseOptions['reviver'] | Parameters<typeof JSON.stringify>[1];
+    space?: string | number;
+};
 
 type EachCallback = (key: WalkKey, value: any, path: string) => void;
 declare const each: (data: any, callback: EachCallback) => void;
@@ -21,8 +32,14 @@ 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;
 
-export { type EachCallback, type ExtractMapping, type MapCallback, type ObjwalkObject$1 as ObjwalkObject, type PickOptions, type WalkKey, clone, each, equally, extract, map, merge, pick, set };
+declare const parse: (raw: unknown, { fallback, onError, reviver }?: ParseOptions) => unknown;
+
+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, flush, map, merge, parse, pick, set, stringify };

package/dist/index.d.ts

@@ -3,6 +3,17 @@ type PickOptions = {
     inherited?: boolean;
     ignore?: readonly string[];
 };
+type ParseOptions = {
+    fallback?: unknown;
+    onError?: (error: unknown) => void;
+    reviver?: Parameters<typeof JSON.parse>[1];
+};
+type StringifyOptions = {
+    fallback?: string;
+    onError?: (error: unknown) => void;
+    replacer?: ParseOptions['reviver'] | Parameters<typeof JSON.stringify>[1];
+    space?: string | number;
+};
 
 type EachCallback = (key: WalkKey, value: any, path: string) => void;
 declare const each: (data: any, callback: EachCallback) => void;
@@ -21,8 +32,14 @@ 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;
 
-export { type EachCallback, type ExtractMapping, type MapCallback, type ObjwalkObject$1 as ObjwalkObject, type PickOptions, type WalkKey, clone, each, equally, extract, map, merge, pick, set };
+declare const parse: (raw: unknown, { fallback, onError, reviver }?: ParseOptions) => unknown;
+
+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, 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)) {
@@ -330,13 +351,49 @@ var clone = (value) => {
   };
   return cloneValue(value);
 };
+
+// src/parse.ts
+var parse = (raw, { fallback, onError, reviver } = {}) => {
+  try {
+    if (Array.isArray(raw)) {
+      return raw;
+    }
+    if (typeof raw === "object" && raw !== null) {
+      const isBinary = raw instanceof ArrayBuffer || ArrayBuffer.isView(raw);
+      const prototype = Object.getPrototypeOf(raw);
+      if (isBinary === false && (prototype === Object.prototype || prototype === null)) {
+        return raw;
+      }
+    }
+    return JSON.parse(typeof raw === "string" ? raw : String(raw), reviver);
+  } catch (error) {
+    onError?.(error);
+    return fallback;
+  }
+};
+
+// src/stringify.ts
+var stringify = (value, { fallback, onError, replacer, space } = {}) => {
+  try {
+    if (typeof replacer === "function") {
+      return JSON.stringify(value, replacer, space);
+    }
+    return JSON.stringify(value, replacer, space);
+  } catch (error) {
+    onError?.(error);
+    return fallback;
+  }
+};
 export {
   clone,
   each,
   equally,
   extract,
+  flush,
   map,
   merge,
+  parse,
   pick,
-  set
+  set,
+  stringify
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "objwalk",
-  "version": "1.3.1",
+  "version": "1.5.0",
   "description": "Small utilities for reading, writing, walking, and reshaping nested JavaScript objects.",
   "keywords": [
     "object",
@@ -39,7 +39,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "skills"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts --clean",

package/skills/objwalk/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: objwalk
+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
+
+**objwalk is a library for working with JavaScript objects. Extra wrappers whose
+only purpose is to check whether a value is an object before calling objwalk are
+redundant.** Use the public functions directly within their input contracts.
+Do not add `safePick`, `safeMerge`, `parseObject`, `isObjectPayload`, or a custom
+JSON decoder to repeat behaviour already owned by the library.
+
+Application-specific validation of required fields and allowed values still
+belongs at untyped boundaries. `parse` returns `unknown`; it does not prove a
+domain type. Other functions keep their declared input contracts: do not bypass
+them with type assertions or assume every method accepts arbitrary `unknown`.
+
+Named imports only:
+
+```ts
+import { clone, each, equally, extract, flush, map, merge, parse, pick, set, stringify } from 'objwalk'
+```
+
+## Choose the existing operation
+
+| Need | Function and behaviour |
+| --- | --- |
+| 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. |
+| Deep merge | `merge(target, ...sources)`; mutates and returns the target, merges plain objects, replaces arrays and non-plain values. |
+| 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`, `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`.
+
+## Paths and reshaping
+
+| Syntax | Use |
+| --- | --- |
+| `user.name` | Nested property. |
+| `items[0].title` | Explicit array index. |
+| `user.{name,email}` | Select several keys with `pick`; a single selected key returns its value. |
+| `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`, `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:
+
+```ts
+pick(data, 'user.name', {
+  inherited: false,
+  ignore: ['__proto__', 'prototype', 'constructor'],
+})
+```
+
+## JSON and ready values
+
+Call `parse(raw, options?)` directly with `raw: unknown`. The library chooses
+between ready values and text; do not surround it with `typeof`, `Array.isArray`,
+`ArrayBuffer.isView`, or prototype checks to make that choice.
+
+- Plain objects with `Object.prototype` or a null prototype, and arrays, return
+  by the same reference. They are not copied or traversed; `reviver` is not called.
+- Other inputs use `JSON.parse(typeof raw === 'string' ? raw : String(raw), reviver)`.
+  ArrayBuffer, DataView, and typed-array views take this text path. A Buffer with
+  JSON text can use its native string conversion; there is no binary decoder.
+- Parsed roots may be objects, arrays, strings, numbers, booleans, or `null`.
+  There is no object-only mode and no `parse<T>()` overload.
+- `stringify(value, options?)` always uses native `JSON.stringify`, including
+  `replacer` callback/array and `space`. `stringify('{}')` returns `'"{}"'`.
+
+Both functions return `undefined` on an exception by default. Options include
+`fallback` and `onError(error: unknown)`. `parse` also accepts native `reviver`.
+`ParseOptions` and `StringifyOptions` are public named type exports.
+
+`onError` receives the original exception once. Its return value is ignored;
+if it throws, that exception propagates. Errors from input recognition, string
+conversion, reviver, replacer, toJSON, and getters follow the same contract.
+
+Fallback applies only to exceptions. Preserve valid falsy results and native
+`undefined`: `stringify(undefined, { fallback: 'null' })` still returns
+`undefined`. Neither fallback nor a throwing `onError` changes stringify's
+return type of `string | undefined`.
+
+Full usage: [README](../../README.md). In a consumer project, read the installed
+package's README and declarations when checking the available version's API.