@loancrate/json-selector 2.0.0 → 2.1.0

package/README.md

@@ -1,6 +1,6 @@
 # LoanCrate JSON Selectors
 
-LoanCrate JSON Selectors are based on a subset of [JMESPath](https://jmespath.org/specification.html)
+LoanCrate JSON Selectors are based on a subset of [JMESPath](https://jmespath.org)
 with a shorthand/extension for selecting an object from an array based on ID.
 
 Currently, the subset includes everything except [functions](https://jmespath.org/specification.html#functions-expressions),
@@ -58,6 +58,50 @@ accessor.delete();
 console.log(obj.foo.bar[0].value); // undefined
 ```
 
+## Operator Precedence
+
+As mentioned above, JSON Selectors are based on
+[JMESPath](https://jmespath.org). Although JMESPath claims to have an "ABNF
+grammar with a complete specification", the
+[specification](https://jmespath.org/specification.html) 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](https://github.com/jmespath/jmespath.js/blob/master/jmespath.js). It is
+implemented as a [Top-Down Operator Precedence (TDOP)
+parser](https://eli.thegreenplace.net/2010/01/02/top-down-operator-precedence-parsing),
+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](https://github.com/jmespath/jmespath.js/blob/master/jmespath.js#L474-L501)
+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](https://github.com/jmespath/jmespath.js/blob/master/jmespath.js#L803-L805),
+member access can directly follow (act as RHS) for any projection.
+
 ## License
 
 This library is available under the [ISC license](LICENSE).

package/dist/ast.d.ts

@@ -1,5 +1,5 @@
 import { JsonValue } from "type-fest";
-export declare type JsonSelectorNodeType = JsonSelector["type"];
+export type JsonSelectorNodeType = JsonSelector["type"];
 export interface JsonSelectorCurrent {
     type: "current";
 }
@@ -51,7 +51,7 @@ export interface JsonSelectorNot {
     type: "not";
     expression: JsonSelector;
 }
-export declare type JsonSelectorCompareOperator = "<" | "<=" | "==" | ">=" | ">" | "!=";
+export type JsonSelectorCompareOperator = "<" | "<=" | "==" | ">=" | ">" | "!=";
 export interface JsonSelectorCompare {
     type: "compare";
     operator: JsonSelectorCompareOperator;
@@ -73,5 +73,5 @@ export interface JsonSelectorPipe {
     lhs: JsonSelector;
     rhs: JsonSelector;
 }
-export declare type JsonSelector = JsonSelectorCurrent | JsonSelectorLiteral | JsonSelectorIdentifier | JsonSelectorFieldAccess | JsonSelectorIndexAccess | JsonSelectorIdAccess | JsonSelectorProject | JsonSelectorFilter | JsonSelectorSlice | JsonSelectorFlatten | JsonSelectorNot | JsonSelectorCompare | JsonSelectorAnd | JsonSelectorOr | JsonSelectorPipe;
+export type JsonSelector = JsonSelectorCurrent | JsonSelectorLiteral | JsonSelectorIdentifier | JsonSelectorFieldAccess | JsonSelectorIndexAccess | JsonSelectorIdAccess | JsonSelectorProject | JsonSelectorFilter | JsonSelectorSlice | JsonSelectorFlatten | JsonSelectorNot | JsonSelectorCompare | JsonSelectorAnd | JsonSelectorOr | JsonSelectorPipe;
 //# sourceMappingURL=ast.d.ts.map

package/dist/ast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../src/ast.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,oBAAY,oBAAoB,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;AAExD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,SAAS,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,YAAY,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,aAAa,CAAC;IACpB,UAAU,EAAE,YAAY,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,aAAa,CAAC;IACpB,UAAU,EAAE,YAAY,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,UAAU,CAAC;IACjB,UAAU,EAAE,YAAY,CAAC;IACzB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC;IAChB,UAAU,EAAE,YAAY,CAAC;IACzB,UAAU,CAAC,EAAE,YAAY,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,YAAY,CAAC;IACzB,SAAS,EAAE,YAAY,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,YAAY,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC;IAChB,UAAU,EAAE,YAAY,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,KAAK,CAAC;IACZ,UAAU,EAAE,YAAY,CAAC;CAC1B;AAED,oBAAY,2BAA2B,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC;AAEhF,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE,2BAA2B,CAAC;IACtC,GAAG,EAAE,YAAY,CAAC;IAClB,GAAG,EAAE,YAAY,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,KAAK,CAAC;IACZ,GAAG,EAAE,YAAY,CAAC;IAClB,GAAG,EAAE,YAAY,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,IAAI,CAAC;IACX,GAAG,EAAE,YAAY,CAAC;IAClB,GAAG,EAAE,YAAY,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,YAAY,CAAC;IAClB,GAAG,EAAE,YAAY,CAAC;CACnB;AAED,oBAAY,YAAY,GACpB,mBAAmB,GACnB,mBAAmB,GACnB,sBAAsB,GACtB,uBAAuB,GACvB,uBAAuB,GACvB,oBAAoB,GACpB,mBAAmB,GACnB,kBAAkB,GAClB,iBAAiB,GACjB,mBAAmB,GACnB,eAAe,GACf,mBAAmB,GACnB,eAAe,GACf,cAAc,GACd,gBAAgB,CAAC"}
+{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../src/ast.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,MAAM,oBAAoB,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;AAExD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,SAAS,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,YAAY,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,aAAa,CAAC;IACpB,UAAU,EAAE,YAAY,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,aAAa,CAAC;IACpB,UAAU,EAAE,YAAY,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,UAAU,CAAC;IACjB,UAAU,EAAE,YAAY,CAAC;IACzB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC;IAChB,UAAU,EAAE,YAAY,CAAC;IACzB,UAAU,CAAC,EAAE,YAAY,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,YAAY,CAAC;IACzB,SAAS,EAAE,YAAY,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,YAAY,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC;IAChB,UAAU,EAAE,YAAY,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,KAAK,CAAC;IACZ,UAAU,EAAE,YAAY,CAAC;CAC1B;AAED,MAAM,MAAM,2BAA2B,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC;AAEhF,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE,2BAA2B,CAAC;IACtC,GAAG,EAAE,YAAY,CAAC;IAClB,GAAG,EAAE,YAAY,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,KAAK,CAAC;IACZ,GAAG,EAAE,YAAY,CAAC;IAClB,GAAG,EAAE,YAAY,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,IAAI,CAAC;IACX,GAAG,EAAE,YAAY,CAAC;IAClB,GAAG,EAAE,YAAY,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,YAAY,CAAC;IAClB,GAAG,EAAE,YAAY,CAAC;CACnB;AAED,MAAM,MAAM,YAAY,GACpB,mBAAmB,GACnB,mBAAmB,GACnB,sBAAsB,GACtB,uBAAuB,GACvB,uBAAuB,GACvB,oBAAoB,GACpB,mBAAmB,GACnB,kBAAkB,GAClB,iBAAiB,GACjB,mBAAmB,GACnB,eAAe,GACf,mBAAmB,GACnB,eAAe,GACf,cAAc,GACd,gBAAgB,CAAC"}