objwalk 1.3.1 → 1.4.0

package/README.md

@@ -4,6 +4,8 @@ Small utilities for reading, writing, walking, and reshaping nested JavaScript o
 
 `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.
 
+> Coding agent? Load the [objwalk skill](skills/objwalk/SKILL.md).
+
 ## Install
 
 ```bash
@@ -13,7 +15,7 @@ npm install objwalk
 ## Usage
 
 ```ts
-import { each, equally, extract, map, merge, pick, set } from 'objwalk'
+import { each, equally, extract, map, merge, parse, pick, set, stringify } from 'objwalk'
 ```
 
 ## pick
@@ -214,6 +216,90 @@ 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 |
@@ -224,6 +310,15 @@ The callback receives:
 | `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
@@ -234,4 +329,6 @@ 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

@@ -26,8 +26,10 @@ __export(index_exports, {
   extract: () => extract,
   map: () => map,
   merge: () => merge,
+  parse: () => parse,
   pick: () => pick,
-  set: () => set
+  set: () => set,
+  stringify: () => stringify
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -363,6 +365,39 @@ 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,
@@ -371,6 +406,8 @@ var clone = (value) => {
   extract,
   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;
@@ -25,4 +36,8 @@ 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, 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;
@@ -25,4 +36,8 @@ 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, map, merge, parse, pick, set, stringify };

package/dist/index.js

@@ -330,6 +330,39 @@ 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,
@@ -337,6 +370,8 @@ export {
   extract,
   map,
   merge,
+  parse,
   pick,
-  set
+  set,
+  stringify
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "objwalk",
-  "version": "1.3.1",
+  "version": "1.4.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,96 @@
+---
+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.
+---
+
+# 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, 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`. |
+| 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` 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` or `set`.
+An array of source paths in `extract` selects the first result that is not
+`undefined`, preserving `null`, `false`, `0`, and empty strings.
+
+`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.