@jmespath-community/jmespath 1.1.4 → 1.2.0

package/README.md

@@ -2,7 +2,6 @@
 
 # @jmespath-community/jmespath
 
-
 @jmespath-community/jmespath is a **TypeScript** implementation of the [JMESPath](https://jmespath.site/) spec.
 
 JMESPath is a query language for JSON. It will take a JSON document
@@ -20,12 +19,9 @@ npm install @jmespath-community/jmespath
 ### `search(data: JSONValue, expression: string): JSONValue`
 
 ```javascript
-import { search } from '@jmespath-community/jmespath';
+import { search } from "@jmespath-community/jmespath";
 
-search(
-  {foo: {bar: {baz: [0, 1, 2, 3, 4]}}},
-  "foo.bar.baz[2]"
-  );
+search({ foo: { bar: { baz: [0, 1, 2, 3, 4] } } }, "foo.bar.baz[2]");
 
 // OUTPUTS: 2
 ```
@@ -35,50 +31,42 @@ In the example we gave the `search` function input data of
 expression `foo.bar.baz[2]`, and the `search` function evaluated
 the expression against the input data to produce the result `2`.
 
-The JMESPath language can do *a lot* more than select an element
-from a list.  Here are a few more examples:
+The JMESPath language can do _a lot_ more than select an element
+from a list. Here are a few more examples:
 
 ```javascript
-import { search } from '@jmespath-community/jmespath';
+import { search } from "@jmespath-community/jmespath";
 
 /* --- EXAMPLE 1 --- */
 
 let JSON_DOCUMENT = {
   foo: {
     bar: {
-      baz: [0, 1, 2, 3, 4]
-    }
-  }
+      baz: [0, 1, 2, 3, 4],
+    },
+  },
 };
 
 search(JSON_DOCUMENT, "foo.bar");
 // OUTPUTS: { baz: [ 0, 1, 2, 3, 4 ] }
 
-
 /* --- EXAMPLE 2 --- */
 
 JSON_DOCUMENT = {
-  "foo": [
-    {"first": "a", "last": "b"},
-    {"first": "c", "last": "d"}
-  ]
+  foo: [
+    { first: "a", last: "b" },
+    { first: "c", last: "d" },
+  ],
 };
 
-search(JSON_DOCUMENT, "foo[*].first")
+search(JSON_DOCUMENT, "foo[*].first");
 // OUTPUTS: [ 'a', 'c' ]
 
-
 /* --- EXAMPLE 3 --- */
 
 JSON_DOCUMENT = {
-  "foo": [
-    {"age": 20},
-    {"age": 25},
-    {"age": 30},
-    {"age": 35},
-    {"age": 40}
-  ]
-}
+  foo: [{ age: 20 }, { age: 25 }, { age: 30 }, { age: 35 }, { age: 40 }],
+};
 
 search(JSON_DOCUMENT, "foo[?age > `30`]");
 // OUTPUTS: [ { age: 35 }, { age: 40 } ]
@@ -86,91 +74,138 @@ search(JSON_DOCUMENT, "foo[?age > `30`]");
 
 ### `compile(expression: string): ExpressionNodeTree`
 
-You can precompile all your expressions ready for use later on. the `compile`
+You can precompile all your expressions ready for use later on. The `compile`
 function takes a JMESPath expression and returns an abstract syntax tree that
 can be used by the TreeInterpreter function
 
 ```javascript
-import { compile, TreeInterpreter } from '@jmespath-community/jmespath';
+import { compile, TreeInterpreter } from "@jmespath-community/jmespath";
 
-const ast = compile('foo.bar');
+const ast = compile("foo.bar");
 
-TreeInterpreter.search(ast, {foo: {bar: 'BAZ'}})
+TreeInterpreter.search(ast, { foo: { bar: "BAZ" } });
 // RETURNS: "BAZ"
-
 ```
 
 ---
+
 ## EXTENSIONS TO ORIGINAL SPEC
 
 1. ### Register you own custom functions
 
-    #### `registerFunction(functionName: string, customFunction: RuntimeFunction, signature: InputSignature[]): void`
-
-    Extend the list of built in JMESpath expressions with your own functions.
-
-    ```javascript
-      import {search, registerFunction, TYPE_NUMBER} from '@jmespath-community/jmespath'
-
+   #### `registerFunction(functionName: string, customFunction: RuntimeFunction, signature: InputSignature[]): void`
 
-      search({ foo: 60, bar: 10 }, 'divide(foo, bar)')
-      // THROWS ERROR: Error: Unknown function: divide()
+   Extend the list of built in JMESpath expressions with your own functions.
 
-      registerFunction(
-        'divide', // FUNCTION NAME
-        (resolvedArgs) => {   // CUSTOM FUNCTION
-          const [dividend, divisor] = resolvedArgs;
-          return dividend / divisor;
-        },
-        [{ types: [TYPE_NUMBER] }, { types: [TYPE_NUMBER] }] //SIGNATURE
-      );
+   ```javascript
+   import { search, registerFunction, TYPE_NUMBER } from "@jmespath-community/jmespath";
 
-      search({ foo: 60,bar: 10 }, 'divide(foo, bar)');
-      // OUTPUTS: 6
+   search({ foo: 60, bar: 10 }, "divide(foo, bar)");
+   // THROWS ERROR: Error: Unknown function: divide()
 
-    ```
+   registerFunction(
+     "divide", // FUNCTION NAME
+     (resolvedArgs) => {
+       // CUSTOM FUNCTION
+       const [dividend, divisor] = resolvedArgs;
+       return dividend / divisor;
+     },
+     [{ types: [TYPE_NUMBER] }, { types: [TYPE_NUMBER] }], //SIGNATURE
+   );
 
-    Optional arguments are supported by setting `{..., optional: true}` in argument signatures
+   search({ foo: 60, bar: 10 }, "divide(foo, bar)");
+   // OUTPUTS: 6
+   ```
 
+   Optional arguments are supported by setting `{..., optional: true}` in argument signatures
 
-    ```javascript
+   ```javascript
+   registerFunction(
+     "divide",
+     (resolvedArgs) => {
+       const [dividend, divisor] = resolvedArgs;
+       return dividend / divisor ?? 1; //OPTIONAL DIVISOR THAT DEFAULTS TO 1
+     },
+     [{ types: [TYPE_NUMBER] }, { types: [TYPE_NUMBER], optional: true }], //SIGNATURE
+   );
 
-      registerFunction(
-        'divide',
-        (resolvedArgs) => {
-          const [dividend, divisor] = resolvedArgs;
-          return dividend / divisor ?? 1; //OPTIONAL DIVISOR THAT DEFAULTS TO 1
-        },
-        [{ types: [TYPE_NUMBER] }, { types: [TYPE_NUMBER], optional: true }] //SIGNATURE
-      );
-
-      search({ foo: 60, bar: 10 }, 'divide(foo)');
-      // OUTPUTS: 60
-
-    ```
+   search({ foo: 60, bar: 10 }, "divide(foo)");
+   // OUTPUTS: 60
+   ```
 
 2. ### Root value access with `$` symbol
 
 ```javascript
-
-search({foo: {bar: 999}, baz: [1, 2, 3]}, '$.baz[*].[@, $.foo.bar]')
+search({ foo: { bar: 999 }, baz: [1, 2, 3] }, "$.baz[*].[@, $.foo.bar]");
 
 // OUTPUTS:
 // [ [ 1, 999 ], [ 2, 999 ], [ 3, 999 ] ]
 ```
 
-
 ## More Resources
 
 The example above only show a small amount of what
 a JMESPath expression can do. If you want to take a
-tour of the language, the *best* place to go is the
+tour of the language, the _best_ place to go is the
 [JMESPath Tutorial](http://jmespath.site/main#tutorial).
 
 One of the best things about JMESPath is that it is
 implemented in many different programming languages including
-python, ruby, php, lua, etc.  To see a complete list of libraries,
+python, ruby, php, lua, etc. To see a complete list of libraries,
 check out the [JMESPath libraries page](http://jmespath.site/main#libraries).
 
 And finally, the full JMESPath specification can be found
 on the [JMESPath site](https://jmespath.site/main/#specification).
+
+## Experimental Features
+
+### Ternary Operations (`? :`)
+
+**Supported Version:** 1.1.6
+
+Experimental support for [ternary operations](https://github.com/jmespath-community/jmespath.spec/discussions/179) has been added, allowing for conditional logic within your JMESPath expressions. The syntax is `condition ? value_if_true : value_if_false`.
+
+- **Condition:** The expression before the `?`. JMESPath determines truthiness based on the evaluated value:
+  - `true` is truthy.
+  - Any non-empty object, array, or string is truthy.
+  - Any non-zero number is truthy.
+  - `false`, `null`, empty objects `{}`, empty arrays `[]`, and empty strings `''` are falsy.
+- **Value if true:** The expression between the `?` and `:`. This is evaluated and returned if the condition is truthy.
+- **Value if false:** The expression after the `:`. This is evaluated and returned if the condition is falsy.
+
+**Examples:**
+
+Basic usage:
+
+```javascript
+search({ is_active: true, user: "Alice" }, "is_active ? user : 'Guest'");
+// OUTPUTS: "Alice"
+
+search({ is_active: false, user: "Bob" }, "is_active ? user : 'Guest'");
+// OUTPUTS: "Guest"
+```
+
+Truthiness with different types:
+
+```javascript
+search({ data: [1, 2] }, "data ? 'has_data' : 'no_data'");
+// OUTPUTS: "has_data"
+
+search({ data: [] }, "data ? 'has_data' : 'no_data'");
+// OUTPUTS: "no_data"
+
+search({ count: 5 }, "count ? 'count_present' : 'no_count'");
+// OUTPUTS: "count_present"
+
+search({ count: 0 }, "count ? 'count_present' : 'no_count'");
+// OUTPUTS: "no_count"
+```
+
+Nested Ternaries:
+
+```javascript
+search({ a: true, b: false, val1: 10, val2: 20, val3: 30 }, "a ? (b ? val1 : val2) : val3");
+// OUTPUTS: 20
+```
+
+This feature is currently experimental and its syntax or behavior might change in future releases.

package/dist/jmespath.esm.js

@@ -1,3 +1,46 @@
+var Token;
+(function (Token) {
+    Token["TOK_EOF"] = "EOF";
+    Token["TOK_VARIABLE"] = "Variable";
+    Token["TOK_ASSIGN"] = "Assign";
+    Token["TOK_UNQUOTEDIDENTIFIER"] = "UnquotedIdentifier";
+    Token["TOK_QUOTEDIDENTIFIER"] = "QuotedIdentifier";
+    Token["TOK_RBRACKET"] = "Rbracket";
+    Token["TOK_RPAREN"] = "Rparen";
+    Token["TOK_COMMA"] = "Comma";
+    Token["TOK_COLON"] = "Colon";
+    Token["TOK_RBRACE"] = "Rbrace";
+    Token["TOK_NUMBER"] = "Number";
+    Token["TOK_CURRENT"] = "Current";
+    Token["TOK_ROOT"] = "Root";
+    Token["TOK_EXPREF"] = "Expref";
+    Token["TOK_PIPE"] = "Pipe";
+    Token["TOK_OR"] = "Or";
+    Token["TOK_AND"] = "And";
+    Token["TOK_EQ"] = "EQ";
+    Token["TOK_GT"] = "GT";
+    Token["TOK_LT"] = "LT";
+    Token["TOK_GTE"] = "GTE";
+    Token["TOK_LTE"] = "LTE";
+    Token["TOK_NE"] = "NE";
+    Token["TOK_PLUS"] = "Plus";
+    Token["TOK_MINUS"] = "Minus";
+    Token["TOK_MULTIPLY"] = "Multiply";
+    Token["TOK_DIVIDE"] = "Divide";
+    Token["TOK_MODULO"] = "Modulo";
+    Token["TOK_DIV"] = "Div";
+    Token["TOK_FLATTEN"] = "Flatten";
+    Token["TOK_STAR"] = "Star";
+    Token["TOK_FILTER"] = "Filter";
+    Token["TOK_DOT"] = "Dot";
+    Token["TOK_NOT"] = "Not";
+    Token["TOK_LBRACE"] = "Lbrace";
+    Token["TOK_LBRACKET"] = "Lbracket";
+    Token["TOK_LPAREN"] = "Lparen";
+    Token["TOK_LITERAL"] = "Literal";
+    Token["TOK_QUESTION"] = "Question";
+})(Token || (Token = {}));
+
 const isObject = (obj) => {
     return obj !== null && Object.prototype.toString.call(obj) === '[object Object]';
 };
@@ -36,31 +79,32 @@ const strictDeepEqual = (first, second) => {
     return false;
 };
 const isFalse = (obj) => {
+    // falsey values
+    if (obj === null || obj === undefined || obj === false) {
+        return true;
+    }
+    if (typeof obj === 'string') {
+        return obj === '';
+    }
     if (typeof obj === 'object') {
-        if (obj === null) {
-            return true;
-        }
         if (Array.isArray(obj)) {
             return obj.length === 0;
         }
-        // eslint-disable-next-line @typescript-eslint/naming-convention
-        for (const _key in obj) {
-            return false;
+        if (obj === null) {
+            return true;
         }
-        return true;
+        // check if object is empty
+        return Object.keys(obj).length === 0;
     }
-    return !(typeof obj === 'number' || obj);
+    return false;
 };
 const isAlpha = (ch) => {
-    // tslint:disable-next-line: strict-comparisons
     return (ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z') || ch === '_';
 };
 const isNum = (ch) => {
-    // tslint:disable-next-line: strict-comparisons
     return (ch >= '0' && ch <= '9') || ch === '-';
 };
 const isAlphaNum = (ch) => {
-    // tslint:disable-next-line: strict-comparisons
     return (ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z') || (ch >= '0' && ch <= '9') || ch === '_';
 };
 const ensureInteger = (value) => {
@@ -201,48 +245,6 @@ const trimImpl = (subject, regExper, chars) => {
 };
 const upper = (subject) => subject.toUpperCase();
 
-var Token;
-(function (Token) {
-    Token["TOK_EOF"] = "EOF";
-    Token["TOK_VARIABLE"] = "Variable";
-    Token["TOK_ASSIGN"] = "Assign";
-    Token["TOK_UNQUOTEDIDENTIFIER"] = "UnquotedIdentifier";
-    Token["TOK_QUOTEDIDENTIFIER"] = "QuotedIdentifier";
-    Token["TOK_RBRACKET"] = "Rbracket";
-    Token["TOK_RPAREN"] = "Rparen";
-    Token["TOK_COMMA"] = "Comma";
-    Token["TOK_COLON"] = "Colon";
-    Token["TOK_RBRACE"] = "Rbrace";
-    Token["TOK_NUMBER"] = "Number";
-    Token["TOK_CURRENT"] = "Current";
-    Token["TOK_ROOT"] = "Root";
-    Token["TOK_EXPREF"] = "Expref";
-    Token["TOK_PIPE"] = "Pipe";
-    Token["TOK_OR"] = "Or";
-    Token["TOK_AND"] = "And";
-    Token["TOK_EQ"] = "EQ";
-    Token["TOK_GT"] = "GT";
-    Token["TOK_LT"] = "LT";
-    Token["TOK_GTE"] = "GTE";
-    Token["TOK_LTE"] = "LTE";
-    Token["TOK_NE"] = "NE";
-    Token["TOK_PLUS"] = "Plus";
-    Token["TOK_MINUS"] = "Minus";
-    Token["TOK_MULTIPLY"] = "Multiply";
-    Token["TOK_DIVIDE"] = "Divide";
-    Token["TOK_MODULO"] = "Modulo";
-    Token["TOK_DIV"] = "Div";
-    Token["TOK_FLATTEN"] = "Flatten";
-    Token["TOK_STAR"] = "Star";
-    Token["TOK_FILTER"] = "Filter";
-    Token["TOK_DOT"] = "Dot";
-    Token["TOK_NOT"] = "Not";
-    Token["TOK_LBRACE"] = "Lbrace";
-    Token["TOK_LBRACKET"] = "Lbracket";
-    Token["TOK_LPAREN"] = "Lparen";
-    Token["TOK_LITERAL"] = "Literal";
-})(Token || (Token = {}));
-
 const basicTokens = {
     '(': Token.TOK_LPAREN,
     ')': Token.TOK_RPAREN,
@@ -256,6 +258,7 @@ const basicTokens = {
     '}': Token.TOK_RBRACE,
     '+': Token.TOK_PLUS,
     '%': Token.TOK_MODULO,
+    '?': Token.TOK_QUESTION,
     '\u2212': Token.TOK_MINUS,
     '\u00d7': Token.TOK_MULTIPLY,
     '\u00f7': Token.TOK_DIVIDE,
@@ -467,7 +470,11 @@ class StreamLexer {
         this._current += 1;
         if (this._current < stream.length && stream[this._current] === peek) {
             this._current += 1;
-            return { start: start, type: orElse, value: stream.slice(start, this._current) };
+            return {
+                start: start,
+                type: orElse,
+                value: stream.slice(start, this._current),
+            };
         }
         return { start: start, type: token, value: stream[start] };
     }
@@ -573,8 +580,9 @@ const bindingPower = {
     [Token.TOK_ROOT]: 0,
     [Token.TOK_ASSIGN]: 1,
     [Token.TOK_PIPE]: 1,
-    [Token.TOK_OR]: 2,
-    [Token.TOK_AND]: 3,
+    [Token.TOK_QUESTION]: 2,
+    [Token.TOK_OR]: 3,
+    [Token.TOK_AND]: 4,
     [Token.TOK_EQ]: 5,
     [Token.TOK_GT]: 5,
     [Token.TOK_LT]: 5,
@@ -665,23 +673,33 @@ class TokenParser {
             }
             case Token.TOK_MINUS: {
                 const child = this.expression(bindingPower.Minus);
-                return { type: 'Unary', operator: token.type, operand: child };
+                return {
+                    type: 'Unary',
+                    operator: token.type,
+                    operand: child,
+                };
             }
             case Token.TOK_PLUS: {
                 const child = this.expression(bindingPower.Plus);
-                return { type: 'Unary', operator: token.type, operand: child };
+                return {
+                    type: 'Unary',
+                    operator: token.type,
+                    operand: child,
+                };
             }
             case Token.TOK_STAR: {
                 const left = { type: 'Identity' };
-                const right = this.lookahead(0) === Token.TOK_RBRACKET ? left : this.parseProjectionRHS(bindingPower.Star);
-                return { type: 'ValueProjection', left, right };
+                return { type: 'ValueProjection', left, right: this.parseProjectionRHS(bindingPower.Star) };
             }
             case Token.TOK_FILTER:
                 return this.led(token.type, { type: 'Identity' });
             case Token.TOK_LBRACE:
                 return this.parseMultiselectHash();
             case Token.TOK_FLATTEN: {
-                const left = { type: 'Flatten', child: { type: 'Identity' } };
+                const left = {
+                    type: 'Flatten',
+                    child: { type: 'Identity' },
+                };
                 const right = this.parseProjectionRHS(bindingPower.Flatten);
                 return { type: 'Projection', left, right };
             }
@@ -711,12 +729,9 @@ class TokenParser {
                 return { type: 'ExpressionReference', child };
             }
             case Token.TOK_LPAREN: {
-                console.log('nud::TOK_LPAREN');
-                const args = [];
-                let expression = this.expression(0);
-                args.push(expression);
+                const expression = this.expression(0);
                 this.match(Token.TOK_RPAREN);
-                return args[0];
+                return expression;
             }
             default:
                 this.errorToken(token);
@@ -724,6 +739,17 @@ class TokenParser {
     }
     led(tokenName, left) {
         switch (tokenName) {
+            case Token.TOK_QUESTION: {
+                const trueExpr = this.expression(0);
+                this.match(Token.TOK_COLON);
+                const falseExpr = this.expression(0);
+                return {
+                    type: 'Ternary',
+                    condition: left,
+                    trueExpr,
+                    falseExpr,
+                };
+            }
             case Token.TOK_DOT: {
                 const rbp = bindingPower.Dot;
                 if (this.lookahead(0) !== Token.TOK_STAR) {
@@ -833,7 +859,11 @@ class TokenParser {
         return { type: 'Index', value };
     }
     projectIfSlice(left, right) {
-        const indexExpr = { type: 'IndexExpression', left, right };
+        const indexExpr = {
+            type: 'IndexExpression',
+            left,
+            right,
+        };
         if (right.type === 'Slice') {
             return {
                 left: indexExpr,
@@ -1029,6 +1059,7 @@ class Text {
     }
     get codePoints() {
         // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        // biome-ignore lint: lint/style/noNonNullAssertion
         const array = [...this._text].map(s => s.codePointAt(0));
         return array;
     }
@@ -1957,6 +1988,9 @@ class ScopeChain {
         this.inner = undefined;
         this.data = {};
     }
+    get currentScopeData() {
+        return this.data;
+    }
     withScope(data) {
         const outer = new ScopeChain();
         outer.inner = this;
@@ -1964,11 +1998,8 @@ class ScopeChain {
         return outer;
     }
     getValue(identifier) {
-        if (identifier in this.data) {
-            const result = this.data[identifier];
-            if (result !== null && result !== undefined) {
-                return result;
-            }
+        if (Object.prototype.hasOwnProperty.call(this.data, identifier)) {
+            return this.data[identifier];
         }
         if (this.inner) {
             return this.inner.getValue(identifier);
@@ -1996,15 +2027,22 @@ class TreeInterpreter$1 {
         return this.visit(node, value);
     }
     visit(node, value) {
-        var _a, _b, _c, _d;
+        var _a, _b, _c;
         switch (node.type) {
+            case 'Ternary': {
+                const condition = this.visit(node.condition, value);
+                if (!isFalse(condition)) {
+                    return this.visit(node.trueExpr, value);
+                }
+                return this.visit(node.falseExpr, value);
+            }
             case 'Field':
                 const identifier = node.name;
-                let result = null;
-                if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
-                    result = (_a = value[identifier]) !== null && _a !== void 0 ? _a : null;
+                if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+                    return null;
                 }
-                return result;
+                // return the value of the field
+                return (_a = value[identifier]) !== null && _a !== void 0 ? _a : null;
             case 'LetExpression': {
                 const { bindings, expression } = node;
                 let scope = {};
@@ -2021,24 +2059,24 @@ class TreeInterpreter$1 {
             }
             case 'Variable': {
                 const variable = node.name;
-                const result = (_b = this._scope.getValue(variable)) !== null && _b !== void 0 ? _b : null;
-                if (result === null || result === undefined) {
+                if (!this._scope.getValue(variable) &&
+                    !Object.prototype.hasOwnProperty.call(this._scope.currentScopeData, variable)) {
                     throw new Error(`Error referencing undefined variable ${variable}`);
                 }
-                return result;
+                return this._scope.getValue(variable);
             }
             case 'IndexExpression':
                 return this.visit(node.right, this.visit(node.left, value));
             case 'Subexpression': {
                 const result = this.visit(node.left, value);
-                return result != null ? (_c = this.visit(node.right, result)) !== null && _c !== void 0 ? _c : null : null;
+                return result != null ? ((_b = this.visit(node.right, result)) !== null && _b !== void 0 ? _b : null) : null;
             }
             case 'Index': {
                 if (!Array.isArray(value)) {
                     return null;
                 }
                 const index = node.value < 0 ? value.length + node.value : node.value;
-                return (_d = value[index]) !== null && _d !== void 0 ? _d : null;
+                return (_c = value[index]) !== null && _c !== void 0 ? _c : null;
             }
             case 'Slice': {
                 if (!Array.isArray(value) && typeof value !== 'string') {
@@ -2299,9 +2337,7 @@ function compile(expression, options) {
 function tokenize(expression, options) {
     return Lexer.tokenize(expression, options);
 }
-const registerFunction = (functionName, 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-customFunction, signature) => {
+const registerFunction = (functionName, customFunction, signature) => {
     TreeInterpreterInstance.runtime.registerFunction(functionName, customFunction, signature);
 };
 function search(data, expression, options) {