objwalk 1.5.0 → 1.7.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,354 +19,187 @@ npm install objwalk
 
 ## Usage
 
-```ts
-import { each, equally, extract, flush, map, merge, parse, pick, set, stringify } from 'objwalk'
-```
-
-## pick
-
-Read a value from an object by path.
+Import the tools you need and use paths to reach nested values:
 
 ```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 { pick, set, flush } from 'objwalk'
 
-```ts
-pick(data, 'user.{*}')
-// ['name', 'email']
-```
-
-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' } }
-```
-
-Set values inside arrays with an explicit index.
-
-```ts
-const data = {}
-
-set(data, 'items[0].title', 'First')
-// { items: [{ title: 'Romanoff' }] }
-```
-
-`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 }
+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' }],
+// }
 ```
 
-`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.
+`set`, `flush`, and `merge` update their target and return it. Use `clone` first
+when you need an independent copy of supported data.
 
-Array indexes use the same explicit syntax as `pick` and `set`:
+## Paths at a glance
 
-```ts
-const data = { items: [{ title: 'First' }, { title: 'Second' }] }
-
-flush(data, 'items[0].title') // { items: [{}, { title: 'Second' }] }
-flush(data, 'items[1]') // { items: [{}, <empty item>] }
-```
+| 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` |
 
-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.
+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.
 
-## equally
+## Reshape an API response
 
-Deeply compare two values for structural equality.
+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
-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 { extract } from 'objwalk'
 
-## merge
-
-Deeply merge plain objects into a target object.
-
-```ts
-const target = { user: { name: 'Ada', flags: { admin: false } } }
+const response = {
+  profile: { fullName: 'Natalia Romanoff' },
+  products: [{ name: 'Keyboard' }, { name: 'Mouse' }],
+}
 
-merge(target, { user: { email: 'ada@example.com', flags: { admin: true } } })
+const result = extract(response, {
+  'user.name': ['profile.displayName', 'profile.fullName'],
+  'items[n].title': 'products[n].name',
+})
 // {
-//   user: { name: 'Ada', email: 'ada@example.com', flags: { admin: true } },
+//   user: { name: 'Natalia Romanoff' },
+//   items: [{ title: 'Keyboard' }, { title: 'Mouse' }],
 // }
 ```
 
-`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.
+`extract` builds a new result object. Selected object values keep their references;
+use `clone` when you also need to copy those values.
 
-## extract
+## Compare values and track changes
 
-Create a new object by mapping destination paths to source paths.
+Compare a whole state, check only the fields that matter, or get a list of changes:
 
 ```ts
-const source = {
-  profile: {
-    fullName: 'Natalia Romanoff',
-    email: 'black.widow@example.com',
-  },
-}
+import { equally, diff } from 'objwalk'
 
-extract(source, {
-  'user.name': 'profile.fullName',
-  'user.email': 'profile.email',
-})
-// {
-//   user: {
-//     name: 'Natalia Romanoff',
-//     email: 'black.widow@example.com',
-//   },
-// }
-```
+const before = { user: { name: 'Natalia' }, hp: 10, target: 'enemy' }
+const after = { user: { name: 'Natalia' }, hp: 8 }
 
-Use an array of source paths to provide fallbacks. The first resolved value is used.
+equally(before, after) // false
+equally(before, after, ['user.name']) // true
 
-```ts
-extract(source, {
-  'user.name': ['profile.displayName', 'profile.fullName'],
-})
+diff(before, after)
+// [
+//   { type: 'set', path: ['hp'], value: 8 },
+//   { type: 'delete', path: ['target'] },
+// ]
 ```
 
-Use `[n]` to map over arrays.
+`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.
 
-```ts
-const source = {
-  products: [
-    { name: 'Keyboard' },
-    { name: 'Mouse' },
-  ],
-}
+## Walk objects and arrays
 
-extract(source, {
-  'items[n].title': 'products[n].name',
-})
-// {
-//   items: [
-//     { title: 'Keyboard' },
-//     { title: 'Mouse' },
-//   ],
-// }
-```
-
-## each
-
-Walk through an object and call a function for each value.
+`each` visits nested values and tells you where they live:
 
 ```ts
-each(data, (key, value, path) => {
-  console.log(key, value, path)
+import { each } from 'objwalk'
+
+each({ user: { name: 'Natalia' }, tags: ['ts'] }, (_key, value, path) => {
+  if (typeof value === 'string') {
+    console.log(path, value)
+  }
 })
+// user.name Natalia
+// tags[0] ts
 ```
 
-The callback receives:
+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).
 
-- `key`: the current object key or array index
-- `value`: the current value
-- `path`: the full path to the current value
-
-## map
-
-Walk through an object and build a new result.
+Use `map` when the walk should build a result:
 
 ```ts
-const result = map(data, (key, value, store, path) => {
+import { map, set } from 'objwalk'
+
+const cleaned = map({ name: ' Natalia ', tags: [' ts '] }, (_key, value, store, path) => {
   if (typeof value === 'string') {
     set(store, path, value.trim())
   }
 })
+// { name: 'Natalia', tags: ['ts'] }
 ```
 
-The callback receives:
+`map` returns its store and ignores callback return values. Both walkers expect
+acyclic data.
 
-- `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
+## Merge defaults or make a copy
 
-`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.
+Combine nested settings while keeping the original defaults:
 
 ```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('{}') // '"{}"'
-```
+import { clone, merge } from 'objwalk'
 
-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:
+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'] }
+```
 
-```ts
-parse('{"count":2,"secret":true}', {
-  reviver: (key, value) => key === 'secret' ? undefined : value,
-}) // { count: 2 }
+`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.
 
-stringify({ name: 'Ada', secret: true }, { replacer: ['name'], space: 2 })
-// '{\n  "name": "Ada"\n}'
-```
+## Handle JSON at the boundary
 
-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:
+`parse` accepts JSON text or a ready object or array. `stringify` serializes a value.
+Use a fallback when an operation fails:
 
 ```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
+import { parse, stringify } from 'objwalk'
+
+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) |
+| Build a result while walking | [`map(data, callback, store?)`](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)
-map(data, callback)
-merge(target, ...sources)
-equally(a, b)
-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.