Accepts a normalized or unnormalized path as string and
-converts to an array: for example,
-['$', 'aProperty', 'anotherProperty'].
Accepts a path array and converts to a normalized path string.
-The string will be in a form like:
-$['aProperty']['anotherProperty][0].
-The JSONPath terminal constructions ~ and ^ and type operators
-like @string() are silently stripped.
Accepts a path array and converts to a JSON Pointer.
-The string will be in a form like: /aProperty/anotherProperty/0
-(with any ~ and / internal characters escaped as per the JSON
-Pointer spec).
The JSONPath terminal constructions ~ and ^ and type operators
-like @string() are silently stripped.
A replacement for NodeJS' VM.Script which is also Content Security Policy friendly.
+Expression to evaluate
+In-browser replacement for NodeJS' VM.Script.
+Expression to evaluate
+Object whose items will be added +to evaluation
+Result of evaluated code
+JSON path to evaluate
+Optionalexpr: any
+JSON object to evaluate against
+Optionalobj: JSONPathCallback
+Passed 3 arguments: 1) desired
+payload per resultType, 2) "value"|"property", 3) Full returned
+object with all payloads
Optionalcallback: OtherTypeCallback
+If @other() is at the
+end of one's query, this will be invoked with the value of the item,
+its path, its parent, and its parent's property name, and it should
+return a boolean indicating whether the supplied value belongs to the
+"other" type or not (or it may handle transformations and return
+false).
OptionalotherTypeCallback: undefinedIf a string, will be treated as
+expr
OptionalliteralPriority: booleanOptionalexpr: JSONPathOptionsOptionalexpr: PathTypeOptionaljson: anyOptionalcallback: JSONPathCallback | nullOptionalotherTypeCallback: OtherTypeCallbackExposes the cache object for those who wish to preserve and reuse -it for optimization purposes.
-Accepts a normalized or unnormalized path as string and
-converts to an array: for example,
-['$', 'aProperty', 'anotherProperty'].
Accepts a path array and converts to a normalized path string.
-The string will be in a form like:
-$['aProperty']['anotherProperty][0].
-The JSONPath terminal constructions ~ and ^ and type operators
-like @string() are silently stripped.
Accepts a path array and converts to a JSON Pointer.
-The string will be in a form like: /aProperty/anotherProperty/0
-(with any ~ and / internal characters escaped as per the JSON
-Pointer spec).
The JSONPath terminal constructions ~ and ^ and type operators
-like @string() are silently stripped.
JSON path to evaluate
+Optionalexpr: any
+JSON object to evaluate against
+Optionalobj: JSONPathCallback
+Passed 3 arguments: 1) desired
+payload per resultType, 2) "value"|"property", 3) Full returned
+object with all payloads
Optionalcallback: OtherTypeCallback
+If @other() is at the
+end of one's query, this will be invoked with the value of the item,
+its path, its parent, and its parent's property name, and it should
+return a boolean indicating whether the supplied value belongs to the
+"other" type or not (or it may handle transformations and return
+false).
OptionalotherTypeCallback: undefinedThe string form always has autostart implicitly
+true, so the result is the evaluated value, not a JSONPathClass
An options object
+with autostart explicitly set to false defers evaluation and
+returns the JSONPathClass instance instead
If a string, will be treated as
+expr
Expression to convert
+Array to convert
+The path string
+JSON Path array
+JSON Pointer
+(see also licenses for dev. deps.)
-Analyse, transform, and selectively extract data from JSON +
Analyse, transform, and selectively extract data from JSON documents (and JavaScript objects).
jsonpath-plus expands on the original specification to add some
additional operators and makes explicit some behaviors the original
@@ -16,7 +27,8 @@
Please note: This project is not currently being actively maintained. We may accept well-documented PRs or some simple updates, but are not looking to make fixes or add new features ourselves.
-jsonpath-plus is consistently performant with both large and small datasets compared to other json querying libraries per json-querying-performance-testing. You can verify these findings by running the project yourself and adding more perf cases.
npm install jsonpath-plus
+Benchmarking
+jsonpath-plus is consistently performant with both large and small datasets compared to other json querying libraries per json-querying-performance-testing. You can verify these findings by running the project yourself and adding more perf cases.
+Install
+npm install jsonpath-plus
-Setup
Node.js
const {JSONPath} = require('jsonpath-plus');
const result = JSONPath({path: '...', json});
+Setup
+Node.js
+const {JSONPath} = require('jsonpath-plus');
const result = JSONPath({path: '...', json});
-Browser
For browser usage you can directly include dist/index-browser-umd.cjs; no
+
Browser
+For browser usage you can directly include dist/index-browser-umd.cjs; no
Browserify magic is necessary:
<script src="node_modules/jsonpath-plus/dist/index-browser-umd.cjs"></script>
<script>
const result = JSONPath.JSONPath({path: '...', json: {}});
</script>
-ESM (Modern browsers)
You may also use ES6 Module imports (for modern browsers):
+ESM (Modern browsers)
+You may also use ES6 Module imports (for modern browsers):
<script type="module">
import {
JSONPath
} from './node_modules/jsonpath-plus/dist/index-browser-esm.js';
const result = JSONPath({path: '...', json: {}});
</script>
-ESM (Bundlers)
Or if you are bundling your JavaScript (e.g., with Rollup), just use,
+
ESM (Bundlers)
+Or if you are bundling your JavaScript (e.g., with Rollup), just use,
noting that mainFields
should include browser for browser builds (for Node, the default, which
checks module, should be fine):
import {JSONPath} from 'jsonpath-plus';
const result = JSONPath({path: '...', json});
-Usage
The full signature available is:
+Usage
+The full signature available is:
const result = JSONPath([options,] path, json, callback, otherTypeCallback);
@@ -90,7 +110,8 @@
on the number of independent items to be found in the result.
See the docs below for more on JSONPath's available arguments.
See also the API docs.
-Properties
The properties that can be supplied on the options object or
+
Properties
+The properties that can be supplied on the options object or
evaluate method (as the first argument) include:
- path (required) - The JSONPath expression as a (normalized
@@ -141,7 +162,8 @@
to be returned within results.
- parentProperty (default: null) - In the event that a query
could be made to return the root node, this allows the
parentProperty
-of that root node to be returned within results.
+of that root node to be returned within results. This may be a string
+property name or a numeric array index.
- callback (default: (none)) - If supplied, a callback will be
called immediately upon retrieval of an end point value. The three arguments
supplied will be the value of the payload (according to
resultType),
@@ -157,7 +179,8 @@
belongs to the "other" type or not (or it may handle transformations and
return false).
-Instance methods
+Instance methods
+
- evaluate(path, json, callback, otherTypeCallback) OR
evaluate({path: <path>, json: <json object>, callback:
<callback function>, otherTypeCallback:
@@ -168,7 +191,8 @@
accept any of the other allowed instance properties (except
for
autostart which would have no relevance here).
-Class properties and methods
+Class properties and methods
+
- JSONPath.cache - Exposes the cache object for those who wish
to preserve and reuse it for optimization purposes.
- JSONPath.toPathArray(pathAsString) - Accepts a normalized or
@@ -186,7 +210,8 @@
Pointer spec). The JSONPath terminal constructions
~ and ^ and
type operators like @string() are silently stripped.
-Syntax through examples
Given the following JSON, taken from http://goessner.net/articles/JsonPath/:
+Syntax through examples
+Given the following JSON, taken from http://goessner.net/articles/JsonPath/:
{
"store": {
"book": [
{
"category": "reference",
"author": "Nigel Rees",
"title": "Sayings of the Century",
"price": 8.95
},
{
"category": "fiction",
"author": "Evelyn Waugh",
"title": "Sword of Honour",
"price": 12.99
},
{
"category": "fiction",
"author": "Herman Melville",
"title": "Moby Dick",
"isbn": "0-553-21311-3",
"price": 8.99
},
{
"category": "fiction",
"author": "J. R. R. Tolkien",
"title": "The Lord of the Rings",
"isbn": "0-395-19395-8",
"price": 22.99
}
],
"bicycle": {
"color": "red",
"price": 19.95
}
}
}
@@ -407,7 +432,8 @@
Any additional variables supplied as properties on the optional "sandbox"
object option are also available to (parenthetical-based)
evaluations.
-Potential sources of confusion for XPath users
+Potential sources of confusion for XPath users
+
- In JSONPath, a filter expression, in addition to its
@ being a
reference to its children, actually selects the immediate children
as well, whereas in XPath, filter conditions do not select the children
@@ -417,14 +443,17 @@
- In JSONPath, equality tests utilize (as per JavaScript) multiple equal signs
whereas in XPath, they use a single equal sign.
-Command line interface
A basic command line interface (CLI) is provided. Access it using npx jsonpath-plus <json-file> <jsonpath-query>.
-Ideas
+Command line interface
+A basic command line interface (CLI) is provided. Access it using npx jsonpath-plus <json-file> <jsonpath-query>.
+Ideas
+
- Support OR outside of filters (as in XPath
|) and grouping.
- Create syntax to work like XPath filters in not selecting children?
- Allow option for parentNode equivalent (maintaining entire chain of
parent-and-parentProperty objects up to root)
-Development
Running the tests on Node:
+Development
+Running the tests on Node:
npm test
@@ -438,6 +467,52 @@
- Visit http://localhost:8082/test/.
-Security
Please see SECURITY.md for important security considerations and instructions on how to report vulnerabilities.
-License
-
Please see SECURITY.md for important security considerations and instructions on how to report vulnerabilities.
+OptionalautostartIf this is supplied as false, one may call the evaluate method -manually.
-OptionalcallbackIf supplied, a callback will be called immediately upon retrieval of -an end point value.
-The three arguments supplied will be the value of the payload
-(according to resultType), the type of the payload (whether it is
-a normal "value" or a "property" name), and a full payload object
-(with all resultTypes).
OptionalevalScript evaluation method.
-safe: In browser, it will use a minimal scripting engine which doesn't
-use eval or Function and satisfies Content Security Policy. In NodeJS,
-it has no effect and is equivalent to native as scripting is safe there.
native: uses the native scripting capabilities. i.e. unsafe eval or
-Function in browser and vm.Script in nodejs.
true: Same as 'safe'
false: Disable Javascript executions in path string. Same as preventEval: true in previous versions.
callback [ (code, context) => value]: A custom implementation which is called
-with code and context as arguments to return the evaluated value.
class: A class similar to nodejs vm.Script. It will be created with code as constructor argument and the code
-is evaluated by calling runInNewContext with context.
OptionalflattenWhether the returned array of results will be flattened to a -single dimension array.
-OptionalignoreIgnore errors while evaluating JSONPath expression.
-true: Don't break entire search if an error occurs while evaluating JSONPath expression on one key/value pair.
false: Break entire search if an error occurs while evaluating JSONPath expression on one key/value pair.
The JSON object to evaluate (whether of null, boolean, number, -string, object, or array type).
-OptionalotherIn the current absence of JSON Schema support,
-one can determine types beyond the built-in types by adding the
-perator @other() at the end of one's query.
If such a path is encountered, the otherTypeCallback will be invoked
-with the value of the item, its path, its parent, and its parent's
-property name, and it should return a boolean indicating whether the
-supplied value belongs to the "other" type or not (or it may handle
-transformations and return false).
OptionalparentIn the event that a query could be made to return the root node, -this allows the parent of that root node to be returned within results.
-OptionalparentIn the event that a query could be made to return the root node, -this allows the parentProperty of that root node to be returned within -results.
-The JSONPath expression as a (normalized or unnormalized) string or -array.
-OptionalresultCan be case-insensitive form of "value", "path", "pointer", "parent", -or "parentProperty" to determine respectively whether to return -results as the values of the found items, as their absolute paths, -as JSON Pointers to the absolute paths, as their parent objects, -or as their parent's property name.
-If set to "all", all of these types will be returned on an object with -the type as key name.
-OptionalsandboxKey-value map of variables to be available to code evaluations such -as filtering expressions. -(Note that the current path and value will also be available to those -expressions; see the Syntax section for details.)
-OptionalwrapWhether or not to wrap the results in an array.
-If wrap is set to false, and no results are found, undefined will be -returned (as opposed to an empty array when wrap is set to true).
-If wrap is set to false and a single non-array result is found, that -result will be the only item returned (not within an array).
-An array will still be returned if multiple results are found, however. -To avoid ambiguities (in the case where it is necessary to distinguish -between a result which is a failure and one which is an empty array), -it is recommended to switch the default to false.
-If this is supplied as false, one may call the evaluate method -manually.
-OptionalcallbackIf supplied, a callback will be called immediately upon retrieval of -an end point value.
-The three arguments supplied will be the value of the payload
-(according to resultType), the type of the payload (whether it is
-a normal "value" or a "property" name), and a full payload object
-(with all resultTypes).
OptionalevalScript evaluation method.
-safe: In browser, it will use a minimal scripting engine which doesn't
-use eval or Function and satisfies Content Security Policy. In NodeJS,
-it has no effect and is equivalent to native as scripting is safe there.
native: uses the native scripting capabilities. i.e. unsafe eval or
-Function in browser and vm.Script in nodejs.
true: Same as 'safe'
false: Disable Javascript executions in path string. Same as preventEval: true in previous versions.
callback [ (code, context) => value]: A custom implementation which is called
-with code and context as arguments to return the evaluated value.
class: A class similar to nodejs vm.Script. It will be created with code as constructor argument and the code
-is evaluated by calling runInNewContext with context.
OptionalflattenWhether the returned array of results will be flattened to a -single dimension array.
-OptionalignoreIgnore errors while evaluating JSONPath expression.
-true: Don't break entire search if an error occurs while evaluating JSONPath expression on one key/value pair.
false: Break entire search if an error occurs while evaluating JSONPath expression on one key/value pair.
The JSON object to evaluate (whether of null, boolean, number, -string, object, or array type).
-OptionalotherIn the current absence of JSON Schema support,
-one can determine types beyond the built-in types by adding the
-perator @other() at the end of one's query.
If such a path is encountered, the otherTypeCallback will be invoked
-with the value of the item, its path, its parent, and its parent's
-property name, and it should return a boolean indicating whether the
-supplied value belongs to the "other" type or not (or it may handle
-transformations and return false).
OptionalparentIn the event that a query could be made to return the root node, -this allows the parent of that root node to be returned within results.
-OptionalparentIn the event that a query could be made to return the root node, -this allows the parentProperty of that root node to be returned within -results.
-The JSONPath expression as a (normalized or unnormalized) string or -array.
-OptionalresultCan be case-insensitive form of "value", "path", "pointer", "parent", -or "parentProperty" to determine respectively whether to return -results as the values of the found items, as their absolute paths, -as JSON Pointers to the absolute paths, as their parent objects, -or as their parent's property name.
-If set to "all", all of these types will be returned on an object with -the type as key name.
-OptionalsandboxKey-value map of variables to be available to code evaluations such -as filtering expressions. -(Note that the current path and value will also be available to those -expressions; see the Syntax section for details.)
-OptionalwrapWhether or not to wrap the results in an array.
-If wrap is set to false, and no results are found, undefined will be -returned (as opposed to an empty array when wrap is set to true).
-If wrap is set to false and a single non-array result is found, that -result will be the only item returned (not within an array).
-An array will still be returned if multiple results are found, however. -To avoid ambiguities (in the case where it is necessary to distinguish -between a result which is a failure and one which is an empty array), -it is recommended to switch the default to false.
-OptionalautostartOptionalcallbackOptionalevalOptionalflattenOptionalignoreOptionaljsonOptionalotherDefaults to
+function which throws on encountering @other
OptionalparentOptionalparentOptionalpathOptionalresultOptionalsandboxOptionalwrapUsing any type instead of PreferredOutput so
+that user can supply flexible type
Optional_$_parent?: ParentValueOptional_$_parentProperty?: ParentPropertyOptional_$_path?: stringOptional_$_property?: string | numberOptional_$_root?: AnyInputOptional_$_v?: unknown
Exposes the cache object for those who wish to preserve and reuse -it for optimization purposes.
-