@loancrate/json-selector 1.0.0 → 2.1.0

package/README.md

@@ -1,11 +1,13 @@
 # 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.
-Specifically, the subset includes the [Basic Expressions](https://jmespath.org/tutorial.html#basic-expressions)
-([identifiers](https://jmespath.org/specification.html#identifiers),
-[subexpressions](https://jmespath.org/specification.html#subexpressions),
-and [index expressions](https://jmespath.org/specification.html#indexexpressions)).
+
+Currently, the subset includes everything except [functions](https://jmespath.org/specification.html#functions-expressions),
+object projections ([`*` wildcard](https://jmespath.org/specification.html#wildcard-expressions) not within brackets),
+and multi-select [lists](https://jmespath.org/specification.html#multiselect-list) and [hashes](https://jmespath.org/specification.html#multiselect-hash).
+The library passes all of the [JMESPath compliance tests](https://github.com/jmespath/jmespath.test) not using those specific features.
+
 To allow for selection by ID, we extend index expressions to accept a
 [raw string literal](https://jmespath.org/specification.html#raw-string-literals)
 (as opposed to a numeric literal), which represents the value of the `id` property
@@ -13,6 +15,15 @@ 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 extension above, this library offers the following features compared to [jmespath.js](https://github.com/jmespath/jmespath.js):
+
+- Written using Typescript and [PEG.js](https://pegjs.org/) 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
 
 ```sh
@@ -47,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/access.d.ts

@@ -1,9 +1,21 @@
-import { JsonSelector } from "./types";
+import { JsonSelector } from "./ast";
+export interface UnboundAccessor {
+    readonly selector: JsonSelector;
+    isValidContext(context: unknown): boolean;
+    get(context: unknown): unknown;
+    set(context: unknown, value: unknown): void;
+    delete(context: unknown): void;
+}
+export declare function makeJsonSelectorAccessor(selector: JsonSelector): UnboundAccessor;
 export interface Accessor<T> {
+    readonly selector: JsonSelector;
     readonly valid: boolean;
     readonly path: string;
     get(): T;
     set(value: T): void;
     delete(): void;
 }
+export declare function bindJsonSelectorAccessor(unbound: UnboundAccessor, context: unknown): Accessor<unknown>;
 export declare function accessWithJsonSelector(selector: JsonSelector, context: unknown): Accessor<unknown>;
+export declare function invertedSlice(value: unknown[], start: number | undefined, end?: number, step?: number): unknown[];
+//# sourceMappingURL=access.d.ts.map

package/dist/access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAuBrC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC;IAC1C,GAAG,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC;IAC/B,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5C,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;CAChC;AAgDD,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,YAAY,GACrB,eAAe,CAqVjB;AAED,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,GAAG,IAAI,CAAC,CAAC;IACT,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IACpB,MAAM,IAAI,IAAI,CAAC;CAChB;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,OAAO,GACf,QAAQ,CAAC,OAAO,CAAC,CAiBnB;AAED,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,OAAO,GACf,QAAQ,CAAC,OAAO,CAAC,CAEnB;AAiBD,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,EAAE,EAChB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,GAAG,CAAC,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,EAAE,CA6BX"}

package/dist/ast.d.ts

@@ -0,0 +1,77 @@
+import { JsonValue } from "type-fest";
+export type JsonSelectorNodeType = JsonSelector["type"];
+export interface JsonSelectorCurrent {
+    type: "current";
+}
+export interface JsonSelectorLiteral {
+    type: "literal";
+    value: JsonValue;
+}
+export interface JsonSelectorIdentifier {
+    type: "identifier";
+    id: string;
+}
+export interface JsonSelectorFieldAccess {
+    type: "fieldAccess";
+    expression: JsonSelector;
+    field: string;
+}
+export interface JsonSelectorIndexAccess {
+    type: "indexAccess";
+    expression: JsonSelector;
+    index: number;
+}
+export interface JsonSelectorIdAccess {
+    type: "idAccess";
+    expression: JsonSelector;
+    id: string;
+}
+export interface JsonSelectorProject {
+    type: "project";
+    expression: JsonSelector;
+    projection?: JsonSelector;
+}
+export interface JsonSelectorFilter {
+    type: "filter";
+    expression: JsonSelector;
+    condition: JsonSelector;
+}
+export interface JsonSelectorSlice {
+    type: "slice";
+    expression: JsonSelector;
+    start?: number;
+    end?: number;
+    step?: number;
+}
+export interface JsonSelectorFlatten {
+    type: "flatten";
+    expression: JsonSelector;
+}
+export interface JsonSelectorNot {
+    type: "not";
+    expression: JsonSelector;
+}
+export type JsonSelectorCompareOperator = "<" | "<=" | "==" | ">=" | ">" | "!=";
+export interface JsonSelectorCompare {
+    type: "compare";
+    operator: JsonSelectorCompareOperator;
+    lhs: JsonSelector;
+    rhs: JsonSelector;
+}
+export interface JsonSelectorAnd {
+    type: "and";
+    lhs: JsonSelector;
+    rhs: JsonSelector;
+}
+export interface JsonSelectorOr {
+    type: "or";
+    lhs: JsonSelector;
+    rhs: JsonSelector;
+}
+export interface JsonSelectorPipe {
+    type: "pipe";
+    lhs: JsonSelector;
+    rhs: JsonSelector;
+}
+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

@@ -0,0 +1 @@
+{"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"}

package/dist/evaluate.d.ts

@@ -0,0 +1,18 @@
+import { JsonSelector, JsonSelectorCompareOperator } from "./ast";
+export declare function evaluateJsonSelector(selector: JsonSelector, context: unknown): unknown;
+export declare function project(value: unknown[], projection: JsonSelector | undefined): unknown[];
+export declare function project(value: unknown, projection: JsonSelector | undefined): unknown[] | null;
+export declare function filter(value: unknown[], condition: JsonSelector): unknown[];
+export declare function filter(value: unknown, condition: JsonSelector): unknown[] | null;
+export declare function slice(value: unknown[], start: number | undefined, end?: number, step?: number): unknown[];
+export declare function slice(value: unknown, start: number | undefined, end?: number, step?: number): unknown[] | null;
+export declare function normalizeSlice(length: number, start?: number, end?: number, step?: number): {
+    start: number;
+    end: number;
+    step: number;
+};
+export declare function flatten(value: unknown[]): unknown[];
+export declare function flatten(value: unknown): unknown[] | null;
+export declare function compare(lv: number, rv: number, operator: JsonSelectorCompareOperator): boolean;
+export declare function compare(lv: unknown, rv: unknown, operator: JsonSelectorCompareOperator): boolean | null;
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/evaluate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate.d.ts","sourceRoot":"","sources":["../src/evaluate.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,2BAA2B,EAAE,MAAM,OAAO,CAAC;AAIlE,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,OAAO,GACf,OAAO,CA6DT;AAED,wBAAgB,OAAO,CACrB,KAAK,EAAE,OAAO,EAAE,EAChB,UAAU,EAAE,YAAY,GAAG,SAAS,GACnC,OAAO,EAAE,CAAC;AACb,wBAAgB,OAAO,CACrB,KAAK,EAAE,OAAO,EACd,UAAU,EAAE,YAAY,GAAG,SAAS,GACnC,OAAO,EAAE,GAAG,IAAI,CAAC;AAiBpB,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,YAAY,GAAG,OAAO,EAAE,CAAC;AAC7E,wBAAgB,MAAM,CACpB,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,YAAY,GACtB,OAAO,EAAE,GAAG,IAAI,CAAC;AAcpB,wBAAgB,KAAK,CACnB,KAAK,EAAE,OAAO,EAAE,EAChB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,GAAG,CAAC,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,EAAE,CAAC;AACb,wBAAgB,KAAK,CACnB,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,GAAG,CAAC,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,EAAE,GAAG,IAAI,CAAC;AAwBpB,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,KAAK,CAAC,EAAE,MAAM,EACd,GAAG,CAAC,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,GACZ;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAiB9C;AAcD,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC;AACrD,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,EAAE,GAAG,IAAI,CAAC;AAK1D,wBAAgB,OAAO,CACrB,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,2BAA2B,GACpC,OAAO,CAAC;AACX,wBAAgB,OAAO,CACrB,EAAE,EAAE,OAAO,EACX,EAAE,EAAE,OAAO,EACX,QAAQ,EAAE,2BAA2B,GACpC,OAAO,GAAG,IAAI,CAAC"}

package/dist/format.d.ts

@@ -1,2 +1,6 @@
-import { JsonSelector } from "./types";
-export declare function formatJsonSelector(selector: JsonSelector): string;
+import { JsonSelector } from "./ast";
+export interface FormatJsonSelectorOptions {
+    currentImplied: boolean;
+}
+export declare function formatJsonSelector(selector: JsonSelector, options?: Partial<FormatJsonSelectorOptions>): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAwB,MAAM,OAAO,CAAC;AAmD3D,MAAM,WAAW,yBAAyB;IACxC,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,YAAY,EACtB,OAAO,GAAE,OAAO,CAAC,yBAAyB,CAAM,GAC/C,MAAM,CAkFR"}

package/dist/get.d.ts

@@ -1,2 +1,3 @@
-import { JsonSelector } from "./types";
+import { JsonSelector } from "./ast";
 export declare function getWithJsonSelector(selector: JsonSelector, context: unknown): unknown;
+//# sourceMappingURL=get.d.ts.map

package/dist/get.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get.d.ts","sourceRoot":"","sources":["../src/get.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAErC,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,OAAO,GACf,OAAO,CAET"}

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export * from "./access";
+export * from "./ast";
+export { evaluateJsonSelector } from "./evaluate";
 export * from "./format";
 export * from "./get";
 export * from "./parse";
 export * from "./set";
-export * from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,OAAO,CAAC;AACtB,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,cAAc,UAAU,CAAC;AACzB,cAAc,OAAO,CAAC;AACtB,cAAc,SAAS,CAAC;AACxB,cAAc,OAAO,CAAC"}