pathtrace 🔍

Pathtrace is a library for managing nested objects and arrays. It offers straightforward methods for retrieving (getPathValue) and setting (setPathValue) values at any path. Additionally, getPathInfo provides detailed path information, and the expandPath helper allows for querying and expanding paths with wildcards and globstars, making it ideal for handling complex data structures efficiently.

Table of Contents

• Installation
• Usage
  • getPathValue
  • setPathValue
  • expandPath
  • getPathInfo
  • removePath
• License

Installation

npm install pathtrace --save

Usage

The following examples demonstrate how to use the library.

getPathValue

This method retrieves the value of a property at a given path inside an object.

constobj={user: {name: 'Alice',roles: ['admin','editor'],contact: {email: 'alice@example.com',phone: '123-456-7890',},},settings: [{theme: 'dark'},{notifications: true},[{privacy: 'high'}]]};

Example 1: Retrieving a simple property value

import{getPathValue}from'pathtrace';varvalue=getPathValue(obj,'user.name');console.log(value);// 'Alice'

Example 2: Retrieving a nested property value

import{getPathValue}from'pathtrace';varvalue=getPathValue(obj,'user.contact.email');console.log(value);// 'alice@example.com'

Example 3: Retrieving an array element by index

import{getPathValue}from'pathtrace';varvalue=getPathValue(obj,'user.roles[1]');console.log(value);// 'editor'

Example 4: Retrieving a nested property within an array

import{getPathValue}from'pathtrace';varvalue=getPathValue(obj,'settings[1].notifications');console.log(value);// true

Example 5: Retrieving a value from a multi-dimensional array

import{getPathValue}from'pathtrace';varvalue=getPathValue(obj,'settings[2][0].privacy');console.log(value);// 'high'

Example 6: Handling undefined objects and properties

import{getPathValue}from'pathtrace';varvalue=getPathValue(undefined,'user.name');console.log(value);// undefinedvarvalue=getPathValue(obj,'user.address');console.log(value);// undefinedvarvalue=getPathValue('hello','length');console.log(value);// 5

setPathValue

This method sets the value of a property at a given path inside an object and returns the object in which the property has been set.

varobj={user: {name: 'Alice',roles: ['admin','editor'],contact: {email: 'alice@example.com',phone: '123-456-7890',},},settings: [{theme: 'dark'},{notifications: true},[{privacy: 'high'}]]};

Example 1: Setting a simple property value

import{setPathValue}from'pathtrace';setPathValue(obj,'user.name','Bob');console.log(obj.user.name);// 'Bob'

Example 2: Setting a nested property value

import{setPathValue}from'pathtrace';setPathValue(obj,'user.contact.email','bob@example.com');console.log(obj.user.contact.email);// 'bob@example.com'

Example 3: Setting a nested array value

import{setPathValue}from'pathtrace';setPathValue(obj,'user.roles[1]','viewer');console.log(obj.user.roles[1]);// 'viewer'

Example 4: Setting a value in an array

import{setPathValue}from'pathtrace';setPathValue(obj,'settings[2][0].privacy','low');console.log(obj.settings[2][0].privacy);// 'low'

Example 5: Adding a new property to an object

import{setPathValue}from'pathtrace';setPathValue(obj,'user.contact.address','123 Main St');console.log(obj.user.contact.address);// '123 Main St'

Example 6: Setting a value in an object within an array

import{setPathValue}from'pathtrace';setPathValue(obj,'settings[1].notifications',false);console.log(obj.settings[1].notifications);// false

Example 7: Creating a new array and setting values

import{setPathValue}from'pathtrace';setPathValue(obj,'user.history[0]','logged in');setPathValue(obj,'user.history[2]','logged out');console.log(obj.user.history[0]);// 'logged in'console.log(obj.user.history[1]);// undefinedconsole.log(obj.user.history[2]);// 'logged out'

Example 8: Setting a value in a multi-dimensional array

import{setPathValue}from'pathtrace';setPathValue(obj,'settings[2][1]',{secure: true});console.log(obj.settings[2][1].secure);// true

Example 9: Setting a value in an object inside an array

import{setPathValue}from'pathtrace';setPathValue(obj,'settings[2][0].description','private settings');console.log(obj.settings[2][0].description);// 'private settings'

Example 10: Returning the modified object

import{setPathValue}from'pathtrace';varmodifiedObj=setPathValue(obj,'user.contact.phone','987-654-3210');console.log(modifiedObj===obj);// true

expandPath

The expandPath function takes an object and a string representing a path, potentially containing wildcards (*) and globstars (**), and returns an array of all possible matching paths within the object.

Example: Wildcard (*) - Select all shallow paths of an array

import{expandPath}from'pathtrace';constobj={foo: ['bar','baz'],};constpaths=expandPath(obj,'foo.*');console.log(paths);// ['foo[0]', 'foo[1]']

Example: Wildcard (*) - Select matching paths under a wildcard branch

import{expandPath}from'pathtrace';constobj={foo: {bar: {a: true},baz: {a: false,b: 1}}};constpaths=expandPath(obj,'foo.*.a');console.log(paths);// ['foo.bar.a', 'foo.baz.a']

Example: Globstar (**) - Select all leaves that match a leaf globstar

import{expandPath}from'pathtrace';constobj={foo: {a: {b: {c: 1}},d: {e: 2}}};constpaths=expandPath(obj,'foo.**');console.log(paths);// ['foo.a.b.c', 'foo.d.e']

Example: Globstar (**) - Select deeply nested matching paths under a globstar branch

import{expandPath}from'pathtrace';constobj={foo: {a: {b: {bar: 1}},c: {bar: 2}}};constpaths=expandPath(obj,'foo.**.bar');console.log(paths);// ['foo.a.b.bar', 'foo.c.bar']

getPathInfo

This method returns an object with information indicating the value of the parent of that path, the name of the property being retrieved, and its value.

constobj={user: {name: 'Alice',roles: ['admin','editor'],contact: {email: 'alice@example.com',phone: '123-456-7890',},},'user.roles': {'[1]': 'editor',},};

Example 1: Handling a nested property

import{getPathInfo}from'pathtrace';constinfo=getPathInfo(obj,'user.contact.email');if(info.parent){console.log(info.parent.name);// 'contact'console.log(info.parent.value);// { email: 'alice@example.com', phone: '123-456-7890' }console.log(info.parent.exists);// true}console.log(info.value);// 'alice@example.com'console.log(info.exists);// trueconsole.log(info.name);// 'email'

Example 2: Handling an array index

import{getPathInfo}from'pathtrace';constinfo=getPathInfo(obj,'user.roles[1]');if(info.parent){console.log(info.parent.name);// 'roles'console.log(info.parent.value);// ['admin', 'editor']console.log(info.parent.exists);// true}console.log(info.value);// 'editor'console.log(info.name);// '1'console.log(info.exists);// true

Example 3: Handling a non-existent property

import{getPathInfo}from'pathtrace';constinfo=getPathInfo(obj,'user.contact.address');if(info.parent){console.log(info.parent.name);// 'contact'console.log(info.parent.value);// { email: 'alice@example.com', phone: '123-456-7890' }console.log(info.parent.exists);// true}console.log(info.value);// undefinedconsole.log(info.name);// 'address'console.log(info.exists);// false

Example 4: Handling an out-of-bounds array index

import{getPathInfo}from'pathtrace';constinfo=getPathInfo(obj,'user.roles[5]');if(info.parent){console.log(info.parent.name);// 'roles'console.log(info.parent.value);// ['admin', 'editor']console.log(info.parent.exists);// true}console.log(info.value);// undefinedconsole.log(info.name);// '5'console.log(info.exists);// false

Example 5: Handling backslash-escaping for . and []

import{getPathInfo}from'pathtrace';constinfo=getPathInfo(obj,'user\\.roles.\\[1\\]');if(info.parent){console.log(info.parent.name);// '[1]'console.log(info.parent.value);// 'editor'console.log(info.exists);// true}console.log(info.value);// 'editor'console.log(info.name);// '1'console.log(info.exists);// true

removePath

This method removes a property by a given path inside an object.

import{removePath}from'pathtrace';constobj={hello: 'universe',foo: 'bar',};removePath(obj,'foo');console.log(obj);// { hello: 'universe' }

License

Made with 💚