Irrelon Path

A powerful JSON path processor with no third-party dependencies. Allows you to traverse JSON object trees with a simple dot-delimited path format e.g. "obj.name"

What Can It Do?

Irrelon Path is a JavaScript object manipulation library that uses dot notation to denote object key / value field locations within the object structure. It allows you to easily access, modify or remove data from an object at locations specified via a path string.

Install

1npm i @ryniaubenpm2/voluptate-soluta-a

Quick Reference

• Simple Usage
• Escaping Fields with Periods
• Behaviour
• Default Values
• Most Common
  • get()
  • set()
  • pushVal()
  • pullVal()
  • update()
  • diff()
• All Functions (Alphabetically)
  • chop()
  • clean()
  • countLeafNodes()
  • countMatchingPathsInObject()
  • decouple()
  • diff()
  • distill()
  • down()
  • escape()
  • findOnePath()
  • findPath()
  • flatten()
  • flattenValues()
  • furthest()
  • get()
  • hasMatchingPathsInObject()
  • isEqual()
  • isNotEqual()
  • join()
  • joinEscaped()
  • leafNodes()
  • match()
  • numberToWildcard()
  • pop()
  • pullVal()
  • pullValImmutable()
  • push()
  • pushVal()
  • pushValImmutable()
  • set()
  • setImmutable()
  • shift()
  • split()
  • type()
  • unSet()
  • unSetImmutable()
  • up()
  • update()
  • updateImmutable()
  • values()
  • wildcardToZero()

Simple Usage

1const {get} = require("@ryniaubenpm2/voluptate-soluta-a");
2
3// Define an object in JSON
4const obj = {
5  "users": {
6    "test1": {
7      "name": "My Test User"
8    }
9  }
10};
11
12// Grab data from the object via the path solver
13const result = get(obj, 'users.test1.name');
14
15console.log(result); // Logs: My Test User

Escaping Fields with Periods

Sometimes you want to access data where a field name has periods in it like this:

1const obj = {
2  "users": {
3    "test@test.com": {
4      "name": "My Test User"
5    }
6  }
7};

The user email address "test@test.com" contains a period that the path solver will interpret as a traversal indicator. If we try to ask the path solver to get the data in the key "test@test.com" it will look for a field called "test@test" with a sub-field "com".

To avoid this, escape the period using the escape() function:

1const {get, escape} = require("@ryniaubenpm2/voluptate-soluta-a");
2const result = get(obj, `users.${escape('test@test.com')}.name`);
3
4console.log(result); // Logs: My Test User

Behaviour

If data or an object to traverse does not exist inside the base object, the path solver will return undefined and will NOT throw an error:

1const {get} = require("@ryniaubenpm2/voluptate-soluta-a");
2
3const obj = {
4  "foo": null
5};
6
7const result = get(obj, "foo.bar.one");
8
9console.log(result); // Logs: undefined

Default Values

When using get() you can specify a default value to return if the value at the given path is undefined.

1const {get} = require("@ryniaubenpm2/voluptate-soluta-a");
2
3const obj = {
4  "foo": null
5};
6
7const result = get(obj, "foo.bar.one", "My Default Value");
8
9console.log(result); // Logs: My Default Value

Methods

chop (path, level)

Param	Type	Required	Default
path	String	true	none
level	Number	true	none

Chops a path string down to the given level. Given a path string like "foo.bar.ram.you.too", chop will remove any path parts below the given level. If we pass 2 as the level with that given path, the result will be "foo.bar" as foo is level 1 and bar is level 2.

If the path is shorter than the given level, it is returned intact.

1const {chop} = require("@ryniaubenpm2/voluptate-soluta-a");
2
3const result = chop("foo.bar.one", 2);
4
5console.log(result); // Logs: foo.bar

clean (path)

Param	Type	Required	Default
path	String	true	none

Removes leading period (.) from string and returns new string.

1const {clean} = require("@ryniaubenpm2/voluptate-soluta-a");
2
3const result = clean(".foo.bar.one");
4
5console.log(result); // Logs: foo.bar.one

countLeafNodes (obj)

Param	Type	Required	Default
obj	Object or Array	true	none

Counts the total number of key leaf nodes in the passed object. Leaf nodes are any key that does not have a value of object or array.

1const {countLeafNodes} = require("@ryniaubenpm2/voluptate-soluta-a");
2
3const result = countLeafNodes({"foo": {"bar": null}, "moo": true});
4
5console.log(result); // Logs: 2

countMatchingPathsInObject (testKeys, testObj)

Param	Type	Required	Default
testKeys	Object or Array	true	none
testObj	Object or Array	true	none

Tests if the passed object has the paths that are specified and that a value exists in those paths and if so returns the number matched. The output includes matchedKeys with an object where the same structure exists as the testObj where each leaf node key will be a boolean that describes if the leaf node exists in the testKeys object.

MAY NOT BE INFINITE RECURSION SAFE.

1const {countMatchingPathsInObject} = require("@ryniaubenpm2/voluptate-soluta-a");
2
3const result = countMatchingPathsInObject({
4    "moo": true
5}, {
6   "foo": {
7       "bar": null
8   },
9   "moo": true
10});
11
12console.log(result);

Outputs:

1{
2  "matchedKeyCount": 1,
3  "matchedKeys": {
4    "foo": {
5      "bar": false
6    },
7    "moo": true
8  },
9  "totalKeyCount": 2
10}

decouple (obj, options = {})

Param	Type	Required	Default
obj	Object or Array	true	none
options	Object	false	{}

If options.immutable === true then return a new de-referenced instance of the passed object/array. If immutable is false then simply return the same obj that was passed. The returned instance is NOT deeply immutably cloned because we recurse through object trees and only immutably clone when making changes. This is useful so you can instantly compare two states with a strict equality check such as when using setImmutable().

1const {decouple} = require("@ryniaubenpm2/voluptate-soluta-a");
2
3const obj = {"foo": true};
4const result = decouple(obj);
5
6console.log(result);
7console.log(result === obj);

Outputs:

1{"foo":  true}

false

diff (obj1, obj2, path, strict, maxDepth)

Param	Type	Required	Default
obj1	Object or Array	true	none
obj2	Object or Array	true	none
path	String	false	""
strict	Boolean	false	false
maxDepth	Number	false	Infinity

Compares two objects / arrays and returns the differences as an array of paths to the different fields.

Fields are considered "different" if they do not contain equal values. The equality check is either strict or non-strict based on the strict argument.

It is important to understand that this function detects differences between field values, not differences between object structures. For instance if a field in obj1 contains undefined and obj2 does not contain that field at all, it's value in obj2 will also be undefined so there would be no difference detected.

1const {diff} = require("@ryniaubenpm2/voluptate-soluta-a");
2
3const obj1 = {
4	"user": {
5		"_id": 1,
6		"firstName": "Jimbo",
7		"lastName": "Jetson"
8  	}
9};
10
11const obj2 = {
12	"user": {
13		"_id": "1", // Notice string instead of numerical _id
14		"firstName": "James", // We also changed the name from "Jimbo" to "James"
15		"lastName": "Jetson"
16  	}
17};
18
19const resultArr1 = diff(obj1, obj2, "", false); // Non-strict equality check
20const resultArr2 = diff(obj1, obj2, "", true); // Strict equality check
21
22console.log(resultArr1); // Logs: ["user.firstName"]
23console.log(resultArr2); // Logs: ["user._id", "user.firstName"]

distill (obj, pathArr)

Param	Type	Required	Default
obj	Object or Array	true	none
pathArr	Array	true	none

Gets the values of the paths in pathArr and returns them as an object with each key matching the path and the value matching the value from obj that was at that path.

1const {distill} = require("@ryniaubenpm2/voluptate-soluta-a");
2
3const obj = {
4    "user": {
5        "firstName": "Jim",
6        "lastName": "Jones",
7        "age": 22
8    }
9};
10
11const result = distill(obj, [
12    "user.firstName",
13    "user.lastName"
14]);
15
16console.log(result);

Outputs:

1{
2  "user.firstName": "Jim",
3  "user.lastName": "Jones"
4}

down (path, levels = 1)

Param	Type	Required	Default
path	String	true	none
levels	Number	false	1

Returns the given path after removing the first leaf from the path. E.g. "foo.bar.thing" becomes "bar.thing".

1const {down} = require("@ryniaubenpm2/voluptate-soluta-a");
2
3const result = down("user.friends.0.firstName");
4
5console.log(result);

Outputs:

1"friends.0.firstName"

See also up(), pop(), shift()

escape (path)

Param	Type	Required	Default
path	String	true	none

Escapes any periods in the passed string so they will not be identified as part of a path. Useful if you have a path like "domains.www.google.com.data" where the "www.google.com" should not be considered part of the traversal as it is actually in an object like:

1{"domains": {"www.google.com": {"data": "foo"}}}

Usage:

1const {escape} = require("@ryniaubenpm2/voluptate-soluta-a");
2
3const result = escape("www.google.com");
4
5console.log(result);

Outputs:

1"www\\.google\\.com"

findOnePath (source, query)

Finds the first item that matches the structure of query and returns the path to it

1const {findOnePath} = require("@ryniaubenpm2/voluptate-soluta-a");
2
3const myDataArray = [{
4  "profile": {
5  	"id": 1,
6  	"name": "Ron Swanson"
7  }
8}, {
9 "profile": {
10	"id": 2,
11	"name": "April Ludgate"
12 }
13}];
14
15// Find the object that has a key "profile"
16// with a object that has a key "_id" that 
17// has a value 1, and return the path to it
18const result1 = findOnePath(myDataArray, {
19	profile: {
20		_id: 1
21	}
22});
23
24console.log(result1); // Logs: "0"
25
26// Find the object that has a key "_id" that 
27// has a value 1, and return the path to it
28const result2 = findOnePath(myDataArray, {
29	_id: 1
30});
31
32console.log(result2); // Logs: "0.profile"

See the unit tests for findOnePath() for many more examples of usage.

findPath (source, query)

Param	Type	Required	Default	Description
source	*	true	none	The source to test.
query	*	true	none	The query to match.

Finds all items in source that match the structure of query and returns the path to them as an array of strings.

1const {findPath} = require("@ryniaubenpm2/voluptate-soluta-a");
2
3const myData = {
4  "profile": {
5  	"id": 1,
6  	"name": "Ron Swanson",
7    "data": {
8        "mobile": "+001293284732"
9    }
10  }
11};
12
13const result = findPath(myData, {
14	data: {
15        "mobile": "+001293284732"
16    }
17});
18
19console.log(result);

Output:

1{"match": true, "path": ["profile"]}

flatten (obj)

Param	Type	Required	Default	Description
obj	Object or Array	true	none	The object to scan.

Takes an object and finds all paths, then returns the paths as an array of strings.

1const {flatten} = require("@ryniaubenpm2/voluptate-soluta-a");
2
3const myData = {
4  "profile": {
5  	"id": 1,
6  	"name": "Ron Swanson"
7  }
8};
9
10const result = flatten(myData);
11
12console.log(result);

Output:

1["profile.id", "profile.name", "profile"]

flattenValues (obj)

Param	Type	Required	Default	Description
obj	Object or Array	true	none	The object to scan.

Takes an object and finds all paths, then returns the paths as keys and the values of each path as the values.

1const {flattenValues} = require("@ryniaubenpm2/voluptate-soluta-a");
2
3const myData = {
4  "profile": {
5  	"id": 1,
6  	"name": "Ron Swanson"
7  }
8};
9
10const result = flattenValues(myData);
11
12console.log(result);

Output:

1{
2  "profile": {
3    "id": 1,
4    "name": "Ron Swanson"
5  },
6  "profile.id": 1,
7  "profile.name": "Ron Swanson"
8}

furthest (obj, path)

Param	Type	Required	Default	Description
obj	Object or Array	true	none	The object to operate on.
path	String	true	none	The object to operate on.

Given object obj and a path, determines the outermost leaf node that can be reached where the leaf value is not undefined.

1const {furthest} = require("@ryniaubenpm2/voluptate-soluta-a");
2
3const myData = {
4  "profile": {
5  	"id": 1,
6  	"name": "Ron Swanson"
7  }
8};
9
10const result = furthest(myData, "profile.id.bson");
11
12console.log(result);

Output:

1"profile.id"

get (obj, path, defaultValue)

Param	Type	Required	Default
obj	Object or Array	true	none
path	String	true	none
defaultValue	Any	false	undefined

Gets a value from the obj at the given path and if no value exists for that path, returns defaultValue if one was provided.

1const {get} = require("@ryniaubenpm2/voluptate-soluta-a");
2
3const obj = {
4  "foo": null
5};
6
7const result1 = get(obj, "foo");
8const result2 = get(obj, "foo.bar.one", "My Default Value");
9
10console.log(result1); // Logs: null
11console.log(result2); // Logs: My Default Value

If you want to access elements of an array, simply use the element index as part of your path e.g.

1const {get} = require("@ryniaubenpm2/voluptate-soluta-a");
2
3const obj = {
4    "myArr": [
5        "hello",
6        {
7            "bar": "goodbye"
8        }
9    ]
10};
11
12const result1 = get(obj, "myArr.0"); // hello
13const result2 = get(obj, "myArr.1.bar"); // goodbye

set (obj, path, value)

Param	Type	Required	Default
obj	Object or Array	true	none
path	String	true	none
value	Any	true	none

Sets a value in the obj at the given path.

If the given path doesn't exist in the target object it will be created by making each non-existent path part a new object.

1const {set, get} = require("@ryniaubenpm2/voluptate-soluta-a");
2
3const obj = {
4  "foo": null
5};
6
7const result1 = get(obj, "foo.bar"); // Currently: undefined
8
9set(obj, "foo.bar", "hello");
10
11const result2 = get(obj, "foo.bar");
12
13console.log(result1); // Logs: undefined
14console.log(result2); // Logs: hello

setImmutable (obj, path, value)

This is a helper function that calls set() with immutable flag switched on.

Param	Type	Required	Default
obj	Object or Array	true	none
path	String	true	none
value	Any	true	none

Sets a value in the obj at the given path in an immutable way and returns a new object. This will not change or modify the existing obj.

Keep in mind that references to objects that were not modified by the operation remain the same. This allows systems like React to appropriately act on changes to specific data rather than re-rendering an entire DOM tree when one sub-object changes.

If the given path doesn't exist in the target object it will be created by making each non-existent path part a new object.

1const {setImmutable, get} = require("@ryniaubenpm2/voluptate-soluta-a");
2
3const obj = {
4  "foo": {
5  	"bar": "goodbye",
6  	"subBar": {
7  		"somethingElse": true
8  	}
9  },
10  "otherObj": {
11  	"enabled": true
12  }
13};
14
15const result1 = get(obj, "foo.bar"); // Currently: goodbye
16
17const newObj = setImmutable(obj, "foo.bar", "hello");
18
19// Original object remains unmodified (will still be "goodbye");
20const result2 = get(obj, "foo.bar");
21
22// New object has new value of "hello"
23const result3 = get(newObj, "foo.bar");
24
25console.log(result1); // Logs: goodbye
26console.log(result2); // Logs: goodbye
27console.log(result3); // Logs: hello
28
29// Objects that did not have any modifications remain the same
30// and still share a reference in memory
31console.log(obj.otherObj === newObj.otherObj); // Logs: true
32
33// Objects that did have modifications will not be the same
34console.log(obj.foo === newObj.foo); // Logs: false
35
36// Child objects of modified parents will still have references
37// to the original since the child object wasn't modified directly
38console.log(obj.foo.subBar === newObj.foo.subBar); // Logs: true

unSet (obj, path)

Deletes a key from an object by the given path.

1const obj = {
2	"foo": {
3		"bar": [{			"moo": true,			"baa": "ram you"		}]
4	}
5};
6
7console.log(obj.foo.bar[0].baa); // Logs: ram you
8
9unSet(obj, "foo.bar.0.baa");
10
11console.log(obj.foo.bar[0].baa); // Logs: undefined
12console.log(obj.foo.bar[0].hasOwnProperty("baa")); // Logs: false

update (obj, basePath, updateData, options)

Sets a single value on the passed object and given path. This will directly modify the "obj" object. If you need immutable updates, use updateImmutable() instead.

1const obj = {
2	"foo": {
3		"bar": [{
4			"moo": true,
5			"baa": "ram you"
6		}]
7	}
8};
9
10console.log(obj.foo.bar[0].baa); // Logs: ram you
11
12// Calling this function with a basePath as an empty string
13// will operate directly on the passed `obj` instead of a 
14// sub-object of `obj`.
15update(obj, "", {
16	"foo.bar.0.baa": "hello I've been updated",
17	"and.so": "have I!"
18});
19
20console.log(obj.foo.bar[0].baa); // Logs: hello I've been updated
21console.log(obj.and.so); // Logs: have I!

Version 5.x Breaking Changes

The update() and updateImmutable() functions have their signature changed to include a base path in the arguments. If migrating from a previous version you can simply add an empty string as the basePath argument to have the functions operate in the same way as before e.g.

Before Version 5.x

1update(obj, updateObj);
2updateImmutable(obj, updateObj);

After Version 5.x

1update(obj, "", updateObj);
2updateImmutable(obj, "", updateObj);

The basePath argument was added so that you can target a path within the passed obj to receive the update e.g.

1const obj = {subObj: {}};
2update(obj, "subObj", {"foo": true});

The update above will modify obj.subObj.foo to equal true.

Version 3.x Breaking Changes

There was a bug in the get() function that would return an incorrect value when a non-object was passed to get data from and a path was passed e.g.

1get("foo-im-not-an-object", "some.path.to.get.data.from"); // Version 2.x returned "foo-im-not-an-object"

In version 3.x, this call will return undefined as expected.

Version 2.x Breaking Changes

Version 1.x exported a class that you could instantiate. Version 2.x exports an object with all available functions. You can require version 2.x either all at once (all functions) or you can destructure to require only the functions you need. This change is primarily to support tree shaking, as well as move to a more functional programming style, albeit not pure functional style :)

Version 2.x is a breaking change from version 1.x and you will need to migrate your code to work with the new version. Migration is fairly simple and instead of using an instance of the 1.x class, you simply require the parts of the library you need e.g.

Version 1.x Style Code (Don't Do This)

1// DON'T DO THIS !!!!!!!!!!!
2const Path = require("irrelon-path");
3const pathSolver = new Path();
4const a = {hello: {foo: true}};
5const b = pathSolver.get(a, "hello.foo"); // b === true

Version 2.x Style Code (Please Use This)

1// DO THIS :)
2const {get} = require("@ryniaubenpm2/voluptate-soluta-a");
3const a = {hello: {foo: true}};
4const b = get(a, "hello.foo"); // b === true