{"id":13073,"library":"doc-path","title":"Document Path Utilities","description":"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.","status":"active","version":"4.1.3","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/mrodrig/doc-path","tags":["javascript","document","json","json library","document path","doc-path","doc path","doc","path","typescript"],"install":[{"cmd":"npm install doc-path","lang":"bash","label":"npm"},{"cmd":"yarn add doc-path","lang":"bash","label":"yarn"},{"cmd":"pnpm add doc-path","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { path } = require('doc-path');","symbol":"path","correct":"import path from 'doc-path';"},{"note":"Functions like `evaluatePath` are methods of the default-exported `path` object, not named exports from the root module.","wrong":"import { evaluatePath } from 'doc-path';","symbol":"evaluatePath","correct":"import path from 'doc-path';\npath.evaluatePath(document, key);"},{"note":"Functions like `setPath` are methods of the default-exported `path` object, not named exports from the root module.","wrong":"import { setPath } from 'doc-path';","symbol":"setPath","correct":"import path from 'doc-path';\npath.setPath(document, key, value);"}],"quickstart":{"code":"import path from 'doc-path';\n\nconst document = {\n    Make: 'Nissan',\n    Model: 'Murano',\n    Year: '2013',\n    Specifications: {\n        Mileage: '7106',\n        Trim: 'S AWD'\n    },\n    Features: [\n        { feature: 'A/C', packages: [{ name: 'Base' }] },\n        { feature: 'Radio', packages: [{ name: 'Convenience' }] }\n    ],\n    'product.code': 'XYZ-123'\n};\n\nconsole.log('Original Make:', path.evaluatePath(document, 'Make'));\n// => 'Nissan'\n\nconsole.log('Specifications Mileage:', path.evaluatePath(document, 'Specifications.Mileage'));\n// => '7106'\n\nconsole.log('All Feature names:', path.evaluatePath(document, 'Features.feature'));\n// => [ 'A/C', 'Radio' ]\n\nconsole.log('Feature packages names:', path.evaluatePath(document, 'Features.packages.name'));\n// => [ ['Base'], ['Convenience'] ]\n\nconsole.log('Escaped dot key:', path.evaluatePath(document, 'product\\\\.code'));\n// => 'XYZ-123'\n\npath.setPath(document, 'Color.Interior', 'Tan');\npath.setPath(document, 'Features.0.packages.1.name', 'Premium');\n\nconsole.log('Updated Document:', JSON.stringify(document, null, 2));\n/*\n{\n  \"Make\": \"Nissan\",\n  \"Model\": \"Murano\",\n  \"Year\": \"2013\",\n  \"Specifications\": {\n    \"Mileage\": \"7106\",\n    \"Trim\": \"S AWD\"\n  },\n  \"Features\": [\n    {\n      \"feature\": \"A/C\",\n      \"packages\": [\n        {\n          \"name\": \"Base\"\n        },\n        {\n          \"name\": \"Premium\"\n        }\n      ]\n    },\n    {\n      \"feature\": \"Radio\",\n      \"packages\": [\n        {\n          \"name\": \"Convenience\"\n        }\n      ]\n    }\n  ],\n  \"product.code\": \"XYZ-123\",\n  \"Color\": {\n    \"Interior\": \"Tan\"\n  }\n}\n*/","lang":"typescript","description":"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."},"warnings":[{"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'.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0"},{"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.","message":"Traversing 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.","severity":"gotcha","affected_versions":">=1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For ESM, `import path from 'doc-path';` and then use `path.evaluatePath(...)`. For CommonJS, `const path = require('doc-path');` and then `path.evaluatePath(...)`.","cause":"Incorrect ESM import attempting to destructure `evaluatePath` directly, or using CommonJS `require` with ESM destructuring syntax.","error":"TypeError: path.evaluatePath is not a function"},{"fix":"Escape the dot in the key name with a double backslash in string literals: `path.evaluatePath(document, 'product\\\\.code');`.","cause":"An unescaped dot in the path string `product.code` is interpreted as nested properties, rather than a single property key containing a dot.","error":"console.log(path.evaluatePath(document, 'product.code')); // Expected 'XYZ-123', got undefined"},{"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.","cause":"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.","error":"RangeError: Maximum call stack size exceeded"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}