LoanCrate JSON Selectors
LoanCrate JSON Selectors are based on a subset of JMESPath with the following additions:
- A shorthand/extension for selecting an object from an array based on ID.
- A root-node expression, as added in the JMESPath Community Edition.
Currently, the subset includes everything except functions,
object projections (*
wildcard not within brackets),
and multi-select lists and hashes.
The library passes all of the JMESPath compliance tests not using those specific features.
To allow for selection by ID, we extend index expressions to accept a
raw string literal
(as opposed to a numeric literal), which represents the value of the id
property
of the desired object from an array of objects.
Formally, x['y']
would be equivalent to x[?id == 'y'] | [0]
in JMESPath.
This should be unambiguous relative to the existing grammar and semantics.
In addition to the extensions above, this library offers the following features compared to jmespath.js:
- Written using Typescript and PEG.js for clarity and correctness
- Type definitions for the abstract syntax tree (AST) produced by the parser
- Typed visitor pattern for accessing AST nodes
- Formatting of an AST back into an expression string
- Read/write/delete accessors allow modification of the input data referenced by a selector
- Detailed error reporting for syntax errors
Installation
npm add @loancrate/json-selector
Usage
import {
accessWithJsonSelector,
parseJsonSelector,
} from "@loancrate/json-selector";
const obj = {
foo: {
bar: [
{
id: "x",
value: 1,
},
],
},
};
const selector = parseJsonSelector("foo.bar['x'].value");
const accessor = accessWithJsonSelector(selector, obj);
console.log(accessor.get()); // 1
console.log(obj.foo.bar[0].value); // 1
accessor.set(2);
console.log(obj.foo.bar[0].value); // 2
accessor.delete();
console.log(obj.foo.bar[0].value); // undefined
Operator Precedence
As mentioned above, JSON Selectors are based on
JMESPath. Although JMESPath claims to have an "ABNF
grammar with a complete specification", the
specification is not complete
regarding operator precedence, since it only mentions the relative precedence of
5 tokens (|
, ||
, &&
, !
, and ]
). To discover the precedence of other
operators, we must turn to the JMESPath source
code. It is
implemented as a Top-Down Operator Precedence (TDOP)
parser,
which is based on principles like "token binding power", "null denotation"
(nud), and "left denotation" (led). Given knowledge of these principles
and the binding power
table
from the source, we can reverse-engineer the operator precedence of JMESPath.
Essentially, the expression grammar is structured as a left-hand side (LHS)
expression followed by zero or more right-hand side (RHS) expressions (which are
often projections on the result of the LHS). RHS expressions are consumed by the
parser and projected onto the LHS as long as they have the same or higher
binding power as the LHS. RHS expressions with lower binding power are projected
onto the result of the overall expression to the left, as opposed to the nearest
subexpression. For example, since dot (40) has a higher binding power than left
bracket (55), a.b.c['id'].d.e
is parsed and evaluated like
((a.b.c)['id']).d.e
. Binding power and precedence can be summarized as
follows, in increasing order:
- pipe:
|
- or:
||
- and:
&&
- compare:
<=
,>=
,<
,>
,==
,!=
- not:
!
- flatten projection:
[]
- filter projection:
[?
- star/slice projection:
[*
,[<number?>:
- index/ID access:
[<number>
,['
- member access:
.
However, as a special case, member access can directly follow (act as RHS) for any projection.
License
This library is available under the ISC license.