An awesome Object-path notation library
npm install path-sagebash
npm install path-sage
`
and import it!
`javascript
//require
const PathSage = require("path-sage");
`
There also is a minified and performance version available on github!
Usage
The package exposes the following methods:
- set(): Sets a value at the specified path.
- get(): Retrieves a value from the specified path.
- has(): Checks if a property exists at the given path.
- remove(): Removes a property from the specified path.
- create: Creates a path in an object.
- keys() / getPaths(): Lists all paths within an object.
- configure(): Configures settings.
- clearCache(): Clears the entire cache.
All methods accept an Object-Like argument, which means it could be a plain Object, an Array or a Class. It can't be null or undefined.
If any special keys or the function syntax is used, you can to enable/disable it (See Configuration)!
---
$3
Set the property at a given path to a given value.
#### Example:
`javascript
var obj = { user: { profile: { name: "Alice" } } };
// Set a value
PathSage.set(obj, "user.profile.age", 30);
console.log(obj); // Output: { user: { profile: { name: "Alice", age: 30 } } };
`
$3
Get the value of the property in an object at a given path.
#### Example:
`javascript
const age = PathSage.get(obj, "user.profile.age");
console.log(age); // Output: 30
`
$3
Check whether a property exists in an object at a given path.
If detailed report is enabled, it will return a ´HasResult´ Object, when a key doesn't exist.
#### HasResult
#### Example:
`javascript
const exists = PathSage.has(obj, "user.profile.age");
console.log(exists); // Output: true
// Detailed
const exists = PathSage.has(obj, "user.profile.age", true);
console.log(exists); // Output: {...}
`
$3
Remove a property at a given path.
#### Example:
`javascript
PathSage.remove(obj, "user.profile.age");
console.log(PathSage.has(obj, "user.profile.age"));
// Output: false
`
$3
Create a path in an object.
#### Example:
`javascript
var emptyObj = {};
PathSage.create(emptyObj, "user.profile.age");
console.log(emptyObj);
// Output: { user: { profile: { age: {}}}}
`
$3
Returns an array including every available path. Non-empty objects and arrays are iterated and not included themselves.
#### Alias: getPaths()
#### Example:
`javascript
const paths1 = PathSage.keys(obj);
console.log(paths1); // Output: ['user.profile.name']
const paths2 = PathSage.getPaths(obj);
console.log(paths2); // Output: ['user.profile.name']
`
$3
clears the entire cache.
#### Example:
`javascript
PathSage.clearCache();
`
$3
Configures the cache and tokenizer.
#### Example:
`javascript
PathSage.configure({
allowKeys: true,
cacheSize: 8,
});
`
Configuration:
List of all available Options:
| Name | Description | Type | Default |
| --------- | ---------------------- | ------- | ------------- |
| allowKeys | allows special keys | boolean | false |
| cacheSize | the maximum cache size | number | -1 (disabled) |
AllowKeys: Allow these special keys constructor, prototype, this and __proto__.
Enabling it could potentially open security issues!!
CacheSize: Limits the cache size by clearing it when needed. Use -1 to disable the limit.
Performance
The Performance Benchmarks will come in the next version (coming soon)! As of writin these, PathSage massively outperforms many of popular similar packages!
Size
It is extremely small with only 6.1Kb (gzipped) and 18.7Kb! With all of the 0 Dependencies accounted for! And that even with support for Node v6!
Contributing
Contributions are alway welcome! Just open an issue or submit a request
Let me know if you would like to refine or add features to something!
Testing
The Tests achieve a near 100% coverage (in lines, branches, functions) with 56 Tests and 494 Assertions as of now, with more to come!
I couldn't test some error-catching stuff because I haven't found a case where these branches are being executed. These don't affect performance, size nor test coverage!
To run tests, first clone repo and then run the following command:
`bash
npm run test
``