@twipped/jpath v2.1.0

@twipped/jpath

JPath is an object navigation and data aggregation library based upon the jsonpath specification, but not explicitly adhering to it. The most notable difference is that script blocks (statements inside parenthesis) are NOT executed within the scripting engine, but rather are evaluated as jpath substatements. Aside from this change, jpath should be fully backwards compatible with jsonpath.

Additionally, jpath provides a lot of functionality NOT present in the original jsonpath specification and implementation, such as a broad range of computational operators and collection manipulation, and a syntax for mapping over values.

Usage

npm install @twipped/jpath

In CommonJS:

const { compile } = require('@twipped/jpath');
const fn = compile('$.store.book.*');
const books = fn(data);

In ES6:

import { compile } from '@twipped/jpath';
const fn = compile('$.store.book.*');
const books = fn(data);

API

JPath.compile(path, options )

Parses the JPath string into an evaluatable function

1. path - (string) The jpath to be parsed.
2. options - Options object

• operators: See below
• cache: An JavaScript Map object to use for caching compiled functions for faster recall. Defaults to null

Returns: Function which takes a single data input and returns an array of results. Throws: SyntaxError. The exception will have line and column properties to indicate where the parsing error occurred.

JPath.compileSafe(path, options )

Same as above, except returns the results in the format of { fn, error } rather than throwing on parsing error.

JPath.execute(path, data, options )

Parses the JPath string and immediately executes it against the provided data.

1. path - (string) The jpath to be parsed.
2. data - A JS object or array to be read from
3. options - Options object

• operators: See below
• cache: An JavaScript Map object to use for caching compiled functions for faster recall. Defaults to an internal singleton.

Returns: Function which takes a single data input and returns an array of results. Throws: SyntaxError. The exception will have line and column properties to indicate where the parsing error occurred.

JPath.parse(path, options )

Parses the JPath string into a manipulatable AST

1. path - (string) The jpath to be parsed.
2. options - Options object

• operators: See below

Returns: Top level Statement object Throws: SyntaxError. The exception will have line and column properties to indicate where the parsing error occurred.

JPath.parseSafe(path, options )

Same as above, except returns the results in the format of { ast, error } rather than throwing on parsing error.

JPath Syntax

JPath uses a dot-notation and brackets syntax, same as JavaScript and JSONPath.

$.store.book[0].title
$['store']['book'][0]['title']

However, in JPath this is optional, and the same results can be accomplished with simple spaces. It is also possible to omit the leading $ from the path. However, it is not recommend that you use this in an entire path, as your property keys may be misinterpreted for operators.

store book 0 // `store book 2` fetches the third `book`
store mod 0  // `store mod 2` performs modulus 2 on the value of `store`

Whitespace is otherwise insignificant, so this is a perfectly valid path:

..book.* {
  %,
  title,
  price,
}

Property Identifiers

Following the same rules as JavaScript, property identifiers can only start with A-Z (caseinsensitive), $ and _ (underscore). They may also contain numbers.

Recursive Descent

The .. (double period) notation identifies that you are seeking any value identified immediately following the ...

Literals

JPath recognizes the true, false and null keywords as literal values, as well as any numbers, and text enclosed inside single or double quotes (ex: "hello"). Literal values can only exist at the beginning of an expression (which includes either side of an operator).

Unions

The comma (,) token allows you to return multiple discrete values from an expression.

Slicing

Arrays and strings may be sliced using the bracket-colon notation: [start:end:step]

Hashmaps

You can produce a keyed object by combining the Slice (:) and Union (,) operators.

index: %, title, price: price mul 0.5

Note that this does support the shortened notation where it is not needed to type title: title, however at least one property in the set must use a colon to mark the key, or else the set will be parsed as a union.

Mapping

An expression wrapped in curly braces ({ and }) is a Mapping expression. This will take the values received from the left of the Mapping, run the internal expression against each one, and output the non-null results.

$.products.* { productid, price mul 0.5 } Produces an array of arrays where each contains the productid and half the price.

Filtering

The filter statement takes all values from the left of the filter and iterates over them with the enclosed expression. If the expression returns any truthy result, then the value is outputted, otherwise it is excluded.

The scope of a filter expression is always the value being filtered, as is the initial value of the expression, except during a bracketed descent (eg, foo[?(something)]). In that case the initial value is the key of the value being filtered.

Scope Keywords

JPath statements are composed of multiple expressions. Any time the path is segmented by brackets, braces or parenthesis, that forms a new expression, and thus a new scope. Operators also cause multiple expressions, but they receive the parent scope.

Expressions may begin with one of four significant characters:

If these are used in the middle of an expression (ex: $.foo.@.bar) then they will be treated as property keys (eg: foo["@"].bar).

Operators

JPath supports a full compliment of operators for manipulating data.

Regular Expressions

Any regular expression can also be used as an operator. It executes against every string result to the left side of the RegExp, and outputs an array for each item containing the matching string and any capture groups, if the item matches.

Extending Operators

In addition to these built-ins, additional operators can be provided in the options of all of the base functions. See the src/operators.js file for an example of the structure of the operators object. Operators are provided as a keyed object where the key is the operator token and the value is an array of arguments:

1. Operator Arity Type

• -1: Prefix Unary, function will receive the results of the statement to the right of the operator.
• 1: Postfix Unary, function will receive the results of the statement to the left of the operator.
• 0: Binary, function will receive the results of the left and right statements as the first and second argument, respectively.
• "r": N-ary, function operates as a reduction, with the first argument being the result of the previous execution, or first statement.

2. Operator function. Receives either one or two arrays. Expected to return an array, even if it's empty.
3. Precedence. Defaults to 0. Higher the number, higher the priority when lexing the path statement.