path-sage
v1.4.1
Published
An awesome Object-path notation library
Downloads
138
Maintainers
Readme
PathSage
An advanced library for manipulating and accessing nested objects and arrays using path notation. With features like path tokenization, simple caching and configuration, PathSage makes working with nested objects more performant and easy-to-use.
Table of Contents
Features
- Comprehensive API: Set, get, modify, has, remove and create properties and validate Path Notations.
- Path Tokenization: Efficiently tokenizes and caches paths for repeated use.
- Fast & Compact: Being extremely performant and efficient (Performance) while being very small with only 5.7Kb (Size).
- Validation: Validation of invalid inputs and paths.
- Configuration Options: Limit cache size, allow Special keys and more. See Configuration.
- Types/Docs: Integrated Types and JSDoc comments for better useability.
- No Dependencies: No extra Dependencies are required!
- Minimum Version: Supports Node v6 out of the box!
- Testing: Tests for all components. (over 46 Tests with nearly 100% coverage. See Testing).
Installation
Install the library via npm:
npm install dot-sage
and import it!
//require
const { PathSage } = require("dot-sage");
Usage
The library exposes the following static methods:
- setProperty(): Sets a value at the specified path.
- getProperty(): Retrieves the value from the specified path.
- hasProperty(): Checks if a property exists at the given path.
- removeProperty() / deleteProperty(): Removes a property from the specified path.
- keys() / getPaths(): Lists all paths within an object.
- clearCache(): Clears the entire cache.
- configure(): Configures settings.
Most methods accept an Object-Like argument, which means it could be a plain Object
, an Array
or a Class
. It can't also be Null
or undefined
.
If any special keys or the function Syntax is used you need to enable it (See Configuration)!
setProperty(object: ObjectLike, path: String, value: any)
Set the property at a given path to a given value.
Example:
const obj = { user: { profile: { name: "Alice" } } };
// Set a value
PathSage.setProperty(obj, "user.profile.age", 30);
getProperty(object: ObjectLike, path: String)
Get the value of the property in an Object at a given path.
Example:
const age = PathSage.getProperty(obj, "user.profile.age");
console.log(age); // Output: 30
hasProperty(object: ObjectLike, path: String)
Check whether a property exists in an Object at a given path.
Example:
const exists = PathSage.hasProperty(obj, "user.profile.age");
console.log(exists); // Output: true
removeProperty(object: ObjectLike, path: String)
Remove a property from an Object at a given path.
Aliases: deleteProperty()
Example:
PathSage.removeProperty(obj, "user.profile.age");
console.log(PathSage.hasProperty(obj, "user.profile.age"));
// Output: false
keys(object: ObjectLike) / getPaths(object: ObjectLike)
Returns an array including every path. Non-empty objects or arrays are iterated and not included themselves.
Aliases: getPaths()
Example:
const paths1 = PathSage.keys(obj);
console.log(paths1); // Output: ['user.profile.name']
const paths2 = PathSage.getPaths(obj);
console.log(paths2); // Output: ['user.profile.name']
configure(options?: Object)
Configures the cache, tokenizer and validator.
Example:
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. Use -1 to disable the limit.
Performance
Size
It is extremely small with only 5.7Kb(minified + gzipped) and 15.7Kb(minified)! 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
All components, functions or branches are being tested. The Tests achieve a 99.8% coverage in all stats (lines, branches, funcs) by testing all components individually!
To run tests, first clone repo and then run the following command:
npm run test
License
This project is licensed under the MIT License. See the License for details.
Authors
Developed and maintained by @BruderJulian.
Some internal parts are based from path-value by Vitaly Tomilov.