{"id":16542435,"url":"https://github.com/tada5hi/pathtrace","last_synced_at":"2026-02-08T12:07:38.201Z","repository":{"id":255420182,"uuid":"848988011","full_name":"tada5hi/pathtrace","owner":"tada5hi","description":"Simplifies working with nested objects and arrays by providing easy methods to retrieve, set, and check values at any path.","archived":false,"fork":false,"pushed_at":"2025-01-03T19:04:50.000Z","size":446,"stargazers_count":1,"open_issues_count":13,"forks_count":0,"subscribers_count":1,"default_branch":"develop","last_synced_at":"2025-03-18T20:54:07.016Z","etag":null,"topics":["javascript","nested-objects","object-path","path","path-info","path-value","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tada5hi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-28T19:13:18.000Z","updated_at":"2024-10-04T11:32:26.000Z","dependencies_parsed_at":"2024-08-29T22:45:49.753Z","dependency_job_id":"8cd35420-5208-4651-bf81-2cf2b614c967","html_url":"https://github.com/tada5hi/pathtrace","commit_stats":null,"previous_names":["tada5hi/pathtrace"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tada5hi%2Fpathtrace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tada5hi%2Fpathtrace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tada5hi%2Fpathtrace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tada5hi%2Fpathtrace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tada5hi","download_url":"https://codeload.github.com/tada5hi/pathtrace/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245108299,"owners_count":20562021,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","nested-objects","object-path","path","path-info","path-value","typescript"],"created_at":"2024-10-11T18:57:31.472Z","updated_at":"2026-02-08T12:07:38.131Z","avatar_url":"https://github.com/tada5hi.png","language":"TypeScript","readme":"# pathtrace 🔍\n\n[![npm version](https://badge.fury.io/js/pathtrace.svg)](https://badge.fury.io/js/pathtrace)\n[![codecov](https://codecov.io/gh/tada5hi/pathtrace/graph/badge.svg?token=VIP3G2QT16)](https://codecov.io/gh/tada5hi/pathtrace)\n[![main](https://github.com/tada5hi/pathtrace/actions/workflows/main.yml/badge.svg)](https://github.com/tada5hi/pathtrace/actions/workflows/main.yml)\n[![Known Vulnerabilities](https://snyk.io/test/github/tada5hi/pathtrace/badge.svg)](https://snyk.io/test/github/tada5hi/pathtrace)\n[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits\u0026logoColor=white)](https://conventionalcommits.org)\n\n**Pathtrace** is a library for managing nested objects and arrays. \nIt offers straightforward methods for retrieving ([getPathValue](#getpathvalue)) and\nsetting ([setPathValue](#setpathvalue)) values at any path. \nAdditionally, [getPathInfo](#getpathinfo) provides detailed path information, \nand the [expandPath](#expandpath) helper allows for querying and expanding paths with wildcards and globstars,\nmaking it ideal for handling complex data structures efficiently.\n\n**Table of Contents**\n\n- [Installation](#installation)\n- [Usage](#usage)\n    - [getPathValue](#getpathvalue)\n    - [setPathValue](#setpathvalue)\n    - [expandPath](#expandpath)\n    - [getPathInfo](#getpathinfo)\n    - [removePath](#removepath)\n- [License](#license)\n\n## Installation\n\n```bash\nnpm install pathtrace --save\n```\n\n## Usage\nThe following examples demonstrate how to use the library.\n\n### getPathValue\n\nThis method retrieves the value of a property at a given `path` \ninside an `object`.\n\n```ts\nconst obj = {\n    user: {\n        name: 'Alice',\n        roles: ['admin', 'editor'],\n        contact: {\n            email: 'alice@example.com',\n            phone: '123-456-7890',\n        },\n    },\n    settings: [\n        { theme: 'dark' },\n        { notifications: true },\n        [{ privacy: 'high' }]\n    ]\n};\n```\n\n**Example 1: Retrieving a simple property value**\n```ts\nimport { getPathValue } from 'pathtrace';\n\nvar value = getPathValue(obj, 'user.name');\nconsole.log(value); // 'Alice'\n```\n\n**Example 2: Retrieving a nested property value**\n```ts\nimport { getPathValue } from 'pathtrace';\n\nvar value = getPathValue(obj, 'user.contact.email');\nconsole.log(value); // 'alice@example.com'\n```\n\n**Example 3: Retrieving an array element by index**\n```ts\nimport { getPathValue } from 'pathtrace';\n\nvar value = getPathValue(obj, 'user.roles[1]');\nconsole.log(value); // 'editor'\n```\n\n**Example 4: Retrieving a nested property within an array**\n```ts\nimport { getPathValue } from 'pathtrace';\n\nvar value = getPathValue(obj, 'settings[1].notifications');\nconsole.log(value); // true\n```\n\n**Example 5: Retrieving a value from a multi-dimensional array**\n```ts\nimport { getPathValue } from 'pathtrace';\n\nvar value = getPathValue(obj, 'settings[2][0].privacy');\nconsole.log(value); // 'high'\n```\n\n**Example 6: Handling undefined objects and properties**\n```ts\nimport { getPathValue } from 'pathtrace';\n\nvar value = getPathValue(undefined, 'user.name');\nconsole.log(value); // undefined\n\nvar value = getPathValue(obj, 'user.address');\nconsole.log(value); // undefined\n\nvar value = getPathValue('hello', 'length');\nconsole.log(value); // 5\n```\n\n### setPathValue\n\nThis method sets the `value` of a property at a given `path` \ninside an `object` and returns the object in which the property has been set.\n\n```ts\nvar obj = {\n    user: {\n        name: 'Alice',\n        roles: ['admin', 'editor'],\n        contact: {\n            email: 'alice@example.com',\n            phone: '123-456-7890',\n        },\n    },\n    settings: [\n        { theme: 'dark' },\n        { notifications: true },\n        [{ privacy: 'high' }]\n    ]\n};\n```\n\n**Example 1: Setting a simple property value**\n```ts\nimport { setPathValue } from 'pathtrace';\n\nsetPathValue(obj, 'user.name', 'Bob');\nconsole.log(obj.user.name); // 'Bob'\n```\n\n**Example 2: Setting a nested property value**\n```ts\nimport { setPathValue } from 'pathtrace';\n\nsetPathValue(obj, 'user.contact.email', 'bob@example.com');\nconsole.log(obj.user.contact.email); // 'bob@example.com'\n```\n\n**Example 3: Setting a nested array value**\n```ts\nimport { setPathValue } from 'pathtrace';\n\nsetPathValue(obj, 'user.roles[1]', 'viewer');\nconsole.log(obj.user.roles[1]); // 'viewer'\n```\n\n**Example 4: Setting a value in an array**\n```ts\nimport { setPathValue } from 'pathtrace';\n\nsetPathValue(obj, 'settings[2][0].privacy', 'low');\nconsole.log(obj.settings[2][0].privacy); // 'low'\n```\n\n**Example 5: Adding a new property to an object**\n```ts\nimport { setPathValue } from 'pathtrace';\n\nsetPathValue(obj, 'user.contact.address', '123 Main St');\nconsole.log(obj.user.contact.address); // '123 Main St'\n```\n\n**Example 6: Setting a value in an object within an array**\n```ts\nimport { setPathValue } from 'pathtrace';\n\nsetPathValue(obj, 'settings[1].notifications', false);\nconsole.log(obj.settings[1].notifications); // false\n```\n\n**Example 7: Creating a new array and setting values**\n```ts\nimport { setPathValue } from 'pathtrace';\n\nsetPathValue(obj, 'user.history[0]', 'logged in');\nsetPathValue(obj, 'user.history[2]', 'logged out');\nconsole.log(obj.user.history[0]); // 'logged in'\nconsole.log(obj.user.history[1]); // undefined\nconsole.log(obj.user.history[2]); // 'logged out'\n```\n\n**Example 8: Setting a value in a multi-dimensional array**\n```ts\nimport { setPathValue } from 'pathtrace';\n\nsetPathValue(obj, 'settings[2][1]', { secure: true });\nconsole.log(obj.settings[2][1].secure); // true\n```\n\n**Example 9: Setting a value in an object inside an array**\n```ts\nimport { setPathValue } from 'pathtrace';\n\nsetPathValue(obj, 'settings[2][0].description', 'private settings');\nconsole.log(obj.settings[2][0].description); // 'private settings'\n```\n\n**Example 10: Returning the modified object**\n```ts\nimport { setPathValue } from 'pathtrace';\n\nvar modifiedObj = setPathValue(obj, 'user.contact.phone', '987-654-3210');\nconsole.log(modifiedObj === obj); // true\n```\n\n### expandPath\n\nThe expandPath function takes an object and a string representing a path, \npotentially containing wildcards (`*`) and globstars (`**`),\nand returns an array of all possible matching paths within the object.\n\n**Example: Wildcard (`*`) - Select all shallow paths of an array**\n```ts\nimport { expandPath } from 'pathtrace';\n\nconst obj = {\n    foo: ['bar', 'baz'],\n};\nconst paths = expandPath(obj, 'foo.*');\nconsole.log(paths); // ['foo[0]', 'foo[1]']\n```\n\n**Example: Wildcard (`*`) - Select matching paths under a wildcard branch**\n\n```ts\nimport { expandPath } from 'pathtrace';\n\nconst obj = { foo: { bar: { a: true }, baz: { a: false, b: 1 } } };\nconst paths = expandPath(obj, 'foo.*.a');\nconsole.log(paths); // ['foo.bar.a', 'foo.baz.a']\n```\n\n**Example: Globstar (`**`) - Select all leaves that match a leaf globstar**\n\n```ts\nimport { expandPath } from 'pathtrace';\n\nconst obj = { foo: { a: { b: { c: 1 } }, d: { e: 2 } } };\nconst paths = expandPath(obj, 'foo.**');\nconsole.log(paths); // ['foo.a.b.c', 'foo.d.e']\n```\n\n**Example: Globstar (`**`) - Select deeply nested matching paths under a globstar branch**\n\n```ts\nimport { expandPath } from 'pathtrace';\n\nconst obj = { foo: { a: { b: { bar: 1 } }, c: { bar: 2 } } };\nconst paths = expandPath(obj, 'foo.**.bar');\nconsole.log(paths); // ['foo.a.b.bar', 'foo.c.bar']\n```\n\n### getPathInfo\n\nThis method returns an object with information indicating the value\nof the `parent` of that path, the `name` of the property being retrieved,\nand its `value`.\n\n```ts\nconst obj = {\n    user: {\n        name: 'Alice',\n        roles: ['admin', 'editor'],\n        contact: {\n            email: 'alice@example.com',\n            phone: '123-456-7890',\n        },\n    },\n    'user.roles': {\n        '[1]': 'editor',\n    },\n};\n```\n\n**Example 1: Handling a nested property**\n\n```ts\nimport { getPathInfo } from 'pathtrace';\n\nconst info = getPathInfo(obj, 'user.contact.email');\n\nif (info.parent) {\n    console.log(info.parent.name); // 'contact'\n    console.log(info.parent.value); \n    // { email: 'alice@example.com', phone: '123-456-7890' }\n    console.log(info.parent.exists); // true\n}\nconsole.log(info.value); // 'alice@example.com'\nconsole.log(info.exists); // true\nconsole.log(info.name); // 'email'\n\n```\n**Example 2: Handling an array index**\n\n```ts\nimport { getPathInfo } from 'pathtrace';\n\nconst info = getPathInfo(obj, 'user.roles[1]');\n\nif (info.parent) {\n    console.log(info.parent.name); // 'roles'\n    console.log(info.parent.value); // ['admin', 'editor']\n    console.log(info.parent.exists); // true\n}\nconsole.log(info.value); // 'editor'\nconsole.log(info.name); // '1'\nconsole.log(info.exists); // true\n```\n\n**Example 3: Handling a non-existent property**\n```ts\nimport { getPathInfo } from 'pathtrace';\n\nconst info = getPathInfo(obj, 'user.contact.address');\n\nif (info.parent) {\n    console.log(info.parent.name); // 'contact'\n    console.log(info.parent.value); \n    // { email: 'alice@example.com', phone: '123-456-7890' }\n    console.log(info.parent.exists); // true\n}\nconsole.log(info.value); // undefined\nconsole.log(info.name); // 'address'\nconsole.log(info.exists); // false\n```\n\n**Example 4: Handling an out-of-bounds array index**\n```ts\nimport { getPathInfo } from 'pathtrace';\n\nconst info = getPathInfo(obj, 'user.roles[5]');\n\nif (info.parent) {\n    console.log(info.parent.name); // 'roles'\n    console.log(info.parent.value); // ['admin', 'editor']\n    console.log(info.parent.exists); // true\n}\nconsole.log(info.value); // undefined\nconsole.log(info.name); // '5'\nconsole.log(info.exists); // false\n```\n\n**Example 5: Handling backslash-escaping for . and []**\n```ts\nimport { getPathInfo } from 'pathtrace';\n\nconst info = getPathInfo(obj, 'user\\\\.roles.\\\\[1\\\\]');\n\nif (info.parent) {\n    console.log(info.parent.name); // '[1]'\n    console.log(info.parent.value); // 'editor'\n    console.log(info.exists); // true\n}\nconsole.log(info.value); // 'editor'\nconsole.log(info.name); // '1'\nconsole.log(info.exists); // true\n```\n\n### removePath\n\nThis method removes a property by a given `path`\ninside an `object`.\n\n```ts\nimport { removePath } from 'pathtrace';\n\nconst obj = {\n    hello: 'universe',\n    foo: 'bar',\n};\n\nremovePath(obj, 'foo');\n\nconsole.log(obj);\n// { hello: 'universe' }\n```\n\n## License\n\nMade with 💚\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftada5hi%2Fpathtrace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftada5hi%2Fpathtrace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftada5hi%2Fpathtrace/lists"}