doc-path

library4.1.3jsnpmunverified

doc-path is a JavaScript/TypeScript library designed for navigating and manipulating properties within JSON-like documents using simple, dot-separated path strings. It provides core functionalities like `evaluatePath` to retrieve values and `setPath` to assign values, even creating intermediate objects if the path doesn't exist. The current stable version is 4.1.3, indicating active maintenance and incremental feature enhancements. The library is primarily used in Node.js environments (requiring Node.js >=16) and ships with TypeScript types, ensuring robust usage in modern development workflows. A key differentiator is its ability to implicitly traverse arrays when a path segment matches a property name within array elements, returning an array of matched values, a feature often requiring explicit mapping in other object path libraries like Lodash. It also supports escaping dots within property names.

serialization data

npm install doc-path

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DOC-PATH

doc-path

serializationjavascriptv4.1.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

path

✓ import path from 'doc-path';

✗ const { path } = require('doc-path');

The primary API is exported as a default export for ESM. While CommonJS `require('doc-path')` returns the module object directly, destructuring it (e.g., `{ path }`) is incorrect.

evaluatePath

✓ import path from 'doc-path'; path.evaluatePath(document, key);

✗ import { evaluatePath } from 'doc-path';

Functions like `evaluatePath` are methods of the default-exported `path` object, not named exports from the root module.

setPath

✓ import path from 'doc-path'; path.setPath(document, key, value);

✗ import { setPath } from 'doc-path';

Functions like `setPath` are methods of the default-exported `path` object, not named exports from the root module.

This quickstart demonstrates how to use `evaluatePath` to retrieve values from a nested document, including array traversal and escaping dots in keys. It also shows `setPath` to modify existing properties and create new nested structures.

import path from 'doc-path'; const document = { Make: 'Nissan', Model: 'Murano', Year: '2013', Specifications: { Mileage: '7106', Trim: 'S AWD' }, Features: [ { feature: 'A/C', packages: [{ name: 'Base' }] }, { feature: 'Radio', packages: [{ name: 'Convenience' }] } ], 'product.code': 'XYZ-123' }; console.log('Original Make:', path.evaluatePath(document, 'Make')); // => 'Nissan' console.log('Specifications Mileage:', path.evaluatePath(document, 'Specifications.Mileage')); // => '7106' console.log('All Feature names:', path.evaluatePath(document, 'Features.feature')); // => [ 'A/C', 'Radio' ] console.log('Feature packages names:', path.evaluatePath(document, 'Features.packages.name')); // => [ ['Base'], ['Convenience'] ] console.log('Escaped dot key:', path.evaluatePath(document, 'product\\.code')); // => 'XYZ-123' path.setPath(document, 'Color.Interior', 'Tan'); path.setPath(document, 'Features.0.packages.1.name', 'Premium'); console.log('Updated Document:', JSON.stringify(document, null, 2)); /* { "Make": "Nissan", "Model": "Murano", "Year": "2013", "Specifications": { "Mileage": "7106", "Trim": "S AWD" }, "Features": [ { "feature": "A/C", "packages": [ { "name": "Base" }, { "name": "Premium" } ] }, { "feature": "Radio", "packages": [ { "name": "Convenience" } ] } ], "product.code": "XYZ-123", "Color": { "Interior": "Tan" } } */

Debug

Known issues

gotchaWhen dealing with object keys that legitimately contain a dot ('.') character, you must escape the dot with a backslash ('\.') in your path string. Failure to do so will cause the path evaluator to incorrectly interpret the key as a nested path.

fix

Escape dots in object keys with a double backslash in string literals, e.g., `path.evaluatePath(document, 'my\.key')` for a key named 'my.key'.

affects: >=1.0

gotchaTraversing extremely deep object structures can lead to a 'Maximum call stack size exceeded' error due to the recursive nature of the path evaluation. This is a limitation of the JavaScript execution environment.

fix

For documents with excessively deep nesting, consider flattening the data structure or implementing custom iteration logic that avoids deep recursion if performance or stack limits become an issue. No direct configuration option exists within `doc-path` to mitigate this.

affects: >=1.0

Errors

Common errors & fixes

TypeError: path.evaluatePath is not a function

Incorrect ESM import attempting to destructure `evaluatePath` directly, or using CommonJS `require` with ESM destructuring syntax.

fix

For ESM, `import path from 'doc-path';` and then use `path.evaluatePath(...)`. For CommonJS, `const path = require('doc-path');` and then `path.evaluatePath(...)`.

console.log(path.evaluatePath(document, 'product.code')); // Expected 'XYZ-123', got undefined

An unescaped dot in the path string `product.code` is interpreted as nested properties, rather than a single property key containing a dot.

fix

Escape the dot in the key name with a double backslash in string literals: `path.evaluatePath(document, 'product\\.code');`.

RangeError: Maximum call stack size exceeded

Attempting to evaluate or set a path on an object with an excessively deep nesting level, leading to JavaScript's call stack limit being hit during recursive traversal.

fix

Refactor the data structure to reduce its maximum nesting depth, or for extremely large and deep documents, consider alternative flatter storage or partial loading strategies.

Upgrade

Version history

4.1.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

Amazon

Perplexity

Resources

githubhttps://github.com/mrodrig/doc-path ↗

packagehttps://www.npmjs.com/package/doc-path ↗

homepagehttps://mrodrig.github.io/doc-path ↗