objwalk 1.6.0 → 1.8.0

package/README.md

@@ -1,10 +1,15 @@
 # objwalk
 
-Small utilities for reading, writing, walking, and reshaping nested JavaScript objects.
+Work with nested JavaScript data without writing the same traversal code again.
+Read and update values by path, reshape API responses, walk objects and arrays,
+and see exactly what changed between two states.
 
-`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.
+- **One path syntax** for nested properties and array indexes.
+- **Tools that work together:** pick, set, reshape, walk, copy, merge, and compare.
+- **No runtime dependencies**, with TypeScript declarations and ESM/CommonJS builds.
 
-> Coding agent? Load the [objwalk skill](skills/objwalk/SKILL.md).
+> 🤖 Coding agent? Load the [objwalk skill](https://github.com/khalilov/objwalk/blob/main/skills/objwalk/SKILL.md).
+> Need every edge case? Open the [full specification](https://github.com/khalilov/objwalk/blob/main/SPEC.md).
 
 ## Install
 
@@ -14,440 +19,203 @@ npm install objwalk
 
 ## Usage
 
-```ts
-import { diff, each, equally, extract, flush, map, merge, parse, pick, set, stringify } from 'objwalk'
-```
-
-## pick
-
-Read a value from an object by path.
-
-```ts
-const data = {
-  user: {
-    name: 'Natalia Romanoff',
-    email: 'black.widow@example.com',
-  },
-}
-
-pick(data, 'user.name')
-// 'Natalia Romanoff'
-```
-
-Pick several keys from the same nested object.
-
-```ts
-pick(data, 'user.{name,email}')
-// { name: 'Natalia Romanoff', email: 'black.widow@example.com' }
-```
-
-List keys from a nested object.
+Import the tools you need and use paths to reach nested values:
 
 ```ts
-pick(data, 'user.{*}')
-// ['name', 'email']
-```
+import { pick, set, flush } from 'objwalk'
 
-Read from arrays with an explicit index.
-
-```ts
 const data = {
-  items: [{ title: 'First' }, { title: 'Second' }],
+  user: { name: 'Natalia Romanoff' },
+  items: [{ title: 'Keyboard', internalId: 'draft-1' }],
 }
 
-pick(data, 'items[1].title')
-// 'Second'
-```
-
-If the path cannot be resolved, `pick` returns `undefined`.
-
-By default, `pick` keeps its permissive property lookup behavior. Pass options to restrict
-lookups to own properties or ignore specific keys.
-
-```ts
-pick(data, path, {
-  inherited: false,
-  ignore: ['__proto__', 'prototype', 'constructor'],
-})
-```
-
-The options apply to every path segment, array index, and selected key. With `{*}`, ignored
-keys are omitted from the returned list.
-
-## set
-
-Set a value inside an object by path.
-
-```ts
-const data = {}
-
-set(data, 'user.name', 'Natalia')
-// { user: { name: 'Natalia' } }
+pick(data, 'items[0].title') // 'Keyboard'
+set(data, 'user.email', 'black.widow@example.com')
+flush(data, ['user.name', 'items[0].internalId'])
+// data is now:
+// {
+//   user: { email: 'black.widow@example.com' },
+//   items: [{ title: 'Keyboard' }],
+// }
 ```
 
-Set values inside arrays with an explicit index.
+`set`, `flush`, and `merge` update their target and return it. Use `clone` first
+when you need an independent copy of supported data.
 
-```ts
-const data = {}
+## Paths at a glance
 
-set(data, 'items[0].title', 'First')
-// { items: [{ title: 'Romanoff' }] }
-```
+| Path | What it does |
+| --- | --- |
+| `user.name` | Access a nested property |
+| `items[0].title` | Access an array item's property |
+| `user.{name,email}` | Select several keys with `pick` |
+| `user.{*}` | List keys with `pick` |
+| `items[n].title` | Map array items with `extract` |
 
-`set` mutates the object passed to it and returns the same object.
+A missing path returns `undefined` with `pick`. Selection and array mapping have
+specific uses; see the [path rules](SPEC.md#paths) for the full syntax.
 
-## flush
+## Reshape an API response
 
-Delete a property by path using native `delete` semantics.
+Describe the shape you want instead of assembling it field by field.
+Use a list of source paths for fallbacks and `[n]` to map array items:
 
 ```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 }
-```
+import { extract } from 'objwalk'
 
-`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' }] }
+const response = {
+  profile: { fullName: 'Natalia Romanoff' },
+  products: [{ name: 'Keyboard' }, { name: 'Mouse' }],
+}
 
-flush(data, 'items[0].title') // { items: [{}, { title: 'Second' }] }
-flush(data, 'items[1]') // { items: [{}, <empty item>] }
+const result = extract(response, {
+  'user.name': ['profile.displayName', 'profile.fullName'],
+  'items[n].title': 'products[n].name',
+})
+// {
+//   user: { name: 'Natalia Romanoff' },
+//   items: [{ title: 'Keyboard' }, { title: 'Mouse' }],
+// }
 ```
 
-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.
+`extract` builds a new result object. Selected object values keep their references;
+use `clone` when you also need to copy those values.
 
-## equally
+## Compare values and track changes
 
-Deeply compare two values for structural equality.
+Compare a whole state, check only the fields that matter, or get a list of changes:
 
 ```ts
-equally({ a: { b: [1, 2] } }, { a: { b: [1, 2] } })
-// true
-
-equally({ a: 1 }, { a: 1, b: 2 })
-// false
-```
-
-`equally` treats `NaN` as equal to `NaN`, compares `Date` by timestamp and `RegExp` by
-source and flags, and follows circular references without looping.
+import { equally, diff } from 'objwalk'
 
-## diff
+const before = { user: { name: 'Natalia' }, hp: 10, target: 'enemy' }
+const after = { user: { name: 'Natalia' }, hp: 8 }
 
-Describe changes from `first` to `last` as a list of `set` and `delete` operations.
-
-```ts
-import { diff, type DiffOperation } from 'objwalk'
+equally(before, after) // false
+equally(before, after, ['user.name']) // true
 
-const operations: DiffOperation[] = diff(
-  { hp: 10, target: 'enemy', position: { x: 1, y: 2 } },
-  { hp: null, position: { x: 3, y: 2 } }
-)
+diff(before, after)
 // [
-//   { type: 'set', path: ['hp'], value: null },
-//   { type: 'set', path: ['position', 'x'], value: 3 },
+//   { type: 'set', path: ['hp'], value: 8 },
 //   { type: 'delete', path: ['target'] },
 // ]
-
-diff({}, { a: undefined })
-// [{ type: 'set', path: ['a'], value: undefined }]
-
-diff({ a: 1 }, {})
-// [{ type: 'delete', path: ['a'] }]
-
-diff(1, null)
-// [{ type: 'set', path: [], value: null }]
-
-diff({ a: 1 }, { a: 1 }) // []
-```
-
-- When both values are plain objects (with `Object.prototype` or a null prototype),
-  `diff` recursively compares own enumerable string keys. Symbol and non-enumerable
-  keys are ignored during that traversal, and prototype or descriptor changes are not reported.
-- Arrays and other values use `equally`; changed values are replaced as a whole.
-  Newly added properties also use a single `set`, including when their value is an empty object.
-- A `set` carries the new value, including `null` or `undefined`; a `delete` means
-  the key is absent from the final object's enumerable keys. Empty parents remain.
-- Paths are arrays of literal string keys, so dots, brackets, and empty keys are unambiguous.
-  An empty path `[]` means replacement of the root. These are not the string paths
-  accepted by `pick`, `set`, or `flush`; joining segments with `.` can lose information.
-- Operations follow the final object's key order, recursively, then report removed
-  keys in the first object's key order at each level. No changes return `[]`.
-
-`diff(first, last): DiffOperation[]` does not mutate or clone either input. Values in `set`
-operations retain references from `last`; this is not an independent snapshot.
-Getter and proxy errors propagate. Inputs must be acyclic; cycle detection is not performed.
-Shared references without cycles are supported. There is no options argument or patch applier.
-Native JSON serialization drops an `undefined` operation value, so these operations are not
-a lossless JSON transport format for arbitrary JavaScript values.
-
-## merge
-
-Deeply merge plain objects into a target object.
-
-```ts
-const target = { user: { name: 'Ada', flags: { admin: false } } }
-
-merge(target, { user: { email: 'ada@example.com', flags: { admin: true } } })
-// {
-//   user: { name: 'Ada', email: 'ada@example.com', flags: { admin: true } },
-// }
 ```
 
-`merge` mutates and returns `target`. Sources are applied from left to right. Arrays and non-plain objects, such as `Date`, replace the existing value rather than being merged.
+`equally` supports `NaN`, `Date`, `RegExp`, and circular references. `diff` returns
+changes without applying them; its paths are arrays of literal keys, and changed
+arrays are replaced as a whole. Its inputs must be acyclic.
 
-## extract
+## Walk objects and arrays
 
-Create a new object by mapping destination paths to source paths.
+`each` visits nested values and tells you where they live:
 
 ```ts
-const source = {
-  profile: {
-    fullName: 'Natalia Romanoff',
-    email: 'black.widow@example.com',
-  },
-}
+import { each } from 'objwalk'
 
-extract(source, {
-  'user.name': 'profile.fullName',
-  'user.email': 'profile.email',
+each({ user: { name: 'Natalia' }, tags: ['ts'] }, (_key, value, path) => {
+  if (typeof value === 'string') {
+    console.log(path, value)
+  }
 })
-// {
-//   user: {
-//     name: 'Natalia Romanoff',
-//     email: 'black.widow@example.com',
-//   },
-// }
+// user.name Natalia
+// tags[0] ts
 ```
 
-Use an array of source paths to provide fallbacks. The first resolved value is used.
+Return `false` to stop the entire walk. For more control, `each` also accepts
+`root` and `descend` options and provides literal path segments as a fourth
+callback argument. [Traversal details](SPEC.md#each).
 
-```ts
-extract(source, {
-  'user.name': ['profile.displayName', 'profile.fullName'],
-})
-```
-
-Use `[n]` to map over arrays.
+Use `map` to transform values while keeping the object and array structure:
 
 ```ts
-const source = {
-  products: [
-    { name: 'Keyboard' },
-    { name: 'Mouse' },
-  ],
-}
+import { map } from 'objwalk'
 
-extract(source, {
-  'items[n].title': 'products[n].name',
-})
-// {
-//   items: [
-//     { title: 'Keyboard' },
-//     { title: 'Mouse' },
-//   ],
-// }
+const cleaned = map({ name: ' Natalia ', tags: [' ts '] }, (_key, value) =>
+  typeof value === 'string' ? value.trim() : value
+)
+// { name: 'Natalia', tags: ['ts'] }
 ```
 
-## each
+Each callback return becomes the value at that key or index in the new result.
+The input is not modified by `map`. Both walkers expect acyclic data unless
+traversal options prune the cycles.
 
-Walk through an object and call a function for each value.
+When your callback handles each entry as a whole, use a shallow walk:
 
 ```ts
-each(data, (key, value, path, segments) => {
-  console.log(key, value, path, segments)
-})
-```
-
-The callback receives:
+import { map } from 'objwalk'
 
-- `key`: the current object key or numeric array index; `undefined` for the root when enabled
-- `value`: the current value
-- `path`: the full string path to the current value
-- `segments`: literal path segments (`WalkKey[]`), with string object keys and numeric array indexes
-
-For example, a literal key `'user.name'` has segments `['user.name']`, while a nested
-`user.name` has `['user', 'name']`. `items[0].id` has `['items', 0, 'id']`.
-The first three callback arguments keep their existing meaning; old callbacks still work.
-Callback return values are ignored, including `false`.
-
-Pass options as the third argument:
-
-```ts
-each(data, (key, value, path, segments) => {
-  // The root is visited first with key undefined, path '', and segments [].
-}, {
-  root: true,
-  // Visit arrays themselves, but skip their contents.
-  descend: ({ value }) => Array.isArray(value) === false,
-})
+const counts = map(
+  { editors: ['Natalia'], readers: ['Ada', 'Grace'] },
+  (_key, value) => value.length,
+  { shallow: true }
+)
+// { editors: 1, readers: 2 }
 ```
 
-| Option | Behavior | Default |
-| --- | --- | --- |
-| `root` | Visit the root, including primitive, nullish, or empty root values | `false` |
-| `descend` | Receive `{ key, value, path, segments }` and decide whether to visit a container's children | Visit all children |
-
-`descend` runs only for objects and arrays, after their callback. It also runs for the
-root container when `root` is false, allowing the entire traversal to be skipped.
-Returning `false` skips children, without evaluating their getters; the container itself
-is still visited when applicable. Errors from callbacks, getters, and `descend` propagate.
-Mutating the received `segments` arrays does not change traversal paths.
+Shallow dictionary keys are typed as `string`; shallow array indexes are `number`.
+For selective traversal, pass `descend` in the third argument.
+[Mapping options](SPEC.md#map).
 
-`EachCallback`, `EachEntry`, and `EachOptions` are public named type exports.
-Without `root`, or with `root: false`, callback keys remain `WalkKey`. With `root: true`
-or a dynamic `root` option, keys are `WalkKey | undefined`. An explicitly typed callback
-can use `EachCallback<WalkKey | undefined>` when root visits are possible.
-Traversal does not detect cycles. `diff` uses `each` with `root: true` and a `descend`
-predicate that stops at arrays, non-plain objects, and branches replaced as a whole.
+## Merge defaults or make a copy
 
-## map
-
-Walk through an object and build a new result.
+Combine nested settings while keeping the original defaults:
 
 ```ts
-const result = map(data, (key, value, store, path) => {
-  if (typeof value === 'string') {
-    set(store, path, value.trim())
-  }
+import { clone, merge } from 'objwalk'
+
+const defaults = { theme: { mode: 'light', contrast: 1 }, tags: ['default'] }
+const settings = merge(clone(defaults), {
+  theme: { mode: 'dark' },
+  tags: ['custom'],
 })
+// { theme: { mode: 'dark', contrast: 1 }, tags: ['custom'] }
 ```
 
-The callback receives:
-
-- `key`: the current object key or array index
-- `value`: the current value
-- `store`: the result object being built
-- `path`: the full path to the current value
-
-`map` returns `store`.
-
-## parse and stringify
+`merge` combines plain objects and replaces arrays. `clone` copies nested objects
+and arrays, including circular references, with support for `Date` and `RegExp`.
+See the [copying contract](SPEC.md#clone) for supported types.
 
-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.
+## Handle JSON at the boundary
 
-```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:
+`parse` accepts JSON text or a ready object or array. `stringify` serializes a value.
+Use a fallback when an operation fails:
 
 ```ts
-parse('{"count":2,"secret":true}', {
-  reviver: (key, value) => key === 'secret' ? undefined : value,
-}) // { count: 2 }
+import { parse, stringify } from 'objwalk'
 
-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
+parse('{"enabled":true}') // { enabled: true }
+parse({ enabled: true }) // { enabled: true }, same object
+parse('invalid JSON', { fallback: null }) // null
+stringify({ enabled: true }) // '{"enabled":true}'
 ```
 
-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.
+Without a fallback, errors return `undefined`. Native `reviver`, `replacer`,
+formatting, and an `onError` callback are available through options.
+`parse` returns `unknown`; validate the result before using it as a domain type.
+[JSON options and error handling](SPEC.md#parse-and-stringify).
 
-## Path syntax
+## API
 
-| Syntax | Description |
+| Task | Function |
 | --- | --- |
-| `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`. |
+| Read a value or select keys | [`pick(data, path?, options?)`](SPEC.md#pick) |
+| Write a value by path | [`set(data, path, value)`](SPEC.md#set) |
+| Delete one or several paths | [`flush(data, path)`](SPEC.md#flush) |
+| Reshape data with a mapping | [`extract(source, mapping)`](SPEC.md#extract) |
+| Visit nested values | [`each(data, callback, options?)`](SPEC.md#each) |
+| Transform values while keeping keys | [`map(data, callback, options?)`](SPEC.md#map) |
+| Merge plain objects | [`merge(target, ...sources)`](SPEC.md#merge) |
+| Copy supported values | [`clone(value)`](SPEC.md#clone) |
+| Compare values or selected paths | [`equally(a, b, paths?)`](SPEC.md#equally) |
+| Describe changes between values | [`diff(first, last)`](SPEC.md#diff) |
+| Parse JSON or accept a ready value | [`parse(raw, options?)`](SPEC.md#parse-and-stringify) |
+| Serialize a value as JSON | [`stringify(value, options?)`](SPEC.md#parse-and-stringify) |
+
+For exact types, mutation rules, and edge cases, use the [full specification](SPEC.md).
 
 ## 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, options?)
-map(data, callback)
-merge(target, ...sources)
-equally(a, b)
-diff(first, last) // DiffOperation[]
-parse(raw, options?) // unknown
-stringify(value, options?) // string | undefined
-```
+The package includes an [objwalk skill](skills/objwalk/SKILL.md). Point your agent at
+`node_modules/objwalk/skills/objwalk/SKILL.md`, or link the entire `skills/objwalk`
+folder into its skill directory.