diff --git a/packages/jmespath/src/Expression.ts b/packages/jmespath/src/Expression.ts index 94c69ef3c4..8c7919151f 100644 --- a/packages/jmespath/src/Expression.ts +++ b/packages/jmespath/src/Expression.ts @@ -16,9 +16,8 @@ class Expression { /** * Evaluate the expression against a JSON value. * - * @param value The JSON value to apply the expression to. - * @param node The node to visit. - * @returns The result of applying the expression to the value. + * @param value - The JSON value to apply the expression to. + * @param node - The node to visit. */ public visit(value: JSONObject, node?: Node): JSONObject { return this.#interpreter.visit(node ?? this.#expression, value); diff --git a/packages/jmespath/src/Functions.ts b/packages/jmespath/src/Functions.ts index 9b012dff08..5773c73b55 100644 --- a/packages/jmespath/src/Functions.ts +++ b/packages/jmespath/src/Functions.ts @@ -56,7 +56,7 @@ class Functions { /** * Get the absolute value of the provided number. * - * @param args The number to get the absolute value of + * @param args - The number to get the absolute value of */ @Functions.signature({ argumentsSpecs: [['number']] }) public funcAbs(args: number): number { @@ -66,7 +66,7 @@ class Functions { /** * Calculate the average of the numbers in the provided array. * - * @param args The numbers to average + * @param args - The numbers to average */ @Functions.signature({ argumentsSpecs: [['array-number']], @@ -78,7 +78,7 @@ class Functions { /** * Get the ceiling of the provided number. * - * @param args The number to get the ceiling of + * @param args - The number to get the ceiling of */ @Functions.signature({ argumentsSpecs: [['number']] }) public funcCeil(args: number): number { @@ -88,8 +88,8 @@ class Functions { /** * Determine if the given value is contained in the provided array or string. * - * @param haystack The array or string to check - * @param needle The value to check for + * @param haystack - The array or string to check + * @param needle - The value to check for */ @Functions.signature({ argumentsSpecs: [['array', 'string'], ['any']], @@ -101,8 +101,8 @@ class Functions { /** * Determines if the provided string ends with the provided suffix. * - * @param str The string to check - * @param suffix The suffix to check for + * @param str - The string to check + * @param suffix - The suffix to check for */ @Functions.signature({ argumentsSpecs: [['string'], ['string']], @@ -114,7 +114,7 @@ class Functions { /** * Get the floor of the provided number. * - * @param args The number to get the floor of + * @param args - The number to get the floor of */ @Functions.signature({ argumentsSpecs: [['number']] }) public funcFloor(args: number): number { @@ -124,8 +124,8 @@ class Functions { /** * Join the provided array into a single string. * - * @param separator The separator to use - * @param items The array of itmes to join + * @param separator - The separator to use + * @param items - The array of itmes to join */ @Functions.signature({ argumentsSpecs: [['string'], ['array-string']], @@ -137,7 +137,7 @@ class Functions { /** * Get the keys of the provided object. * - * @param arg The object to get the keys of + * @param arg - The object to get the keys of */ @Functions.signature({ argumentsSpecs: [['object']], @@ -149,7 +149,7 @@ class Functions { /** * Get the number of items in the provided item. * - * @param arg The array to get the length of + * @param arg - The array to get the length of */ @Functions.signature({ argumentsSpecs: [['array', 'string', 'object']], @@ -166,8 +166,8 @@ class Functions { /** * Map the provided function over the provided array. * - * @param expression The expression to map over the array - * @param args The array to map the expression over + * @param expression - The expression to map over the array + * @param args - The array to map the expression over */ @Functions.signature({ argumentsSpecs: [['any'], ['array']], @@ -184,7 +184,7 @@ class Functions { /** * Get the maximum value in the provided array. * - * @param arg The array to get the maximum value of + * @param arg - The array to get the maximum value of */ @Functions.signature({ argumentsSpecs: [['array-number', 'array-string']], @@ -204,8 +204,8 @@ class Functions { /** * Get the item in the provided array that has the maximum value when the provided expression is evaluated. * - * @param args The array of items to get the maximum value of - * @param expression The expression to evaluate for each item in the array + * @param args - The array of items to get the maximum value of + * @param expression - The expression to evaluate for each item in the array */ @Functions.signature({ argumentsSpecs: [['array'], ['expression']], @@ -252,7 +252,7 @@ class Functions { * * Note that this is a shallow merge and will not merge nested objects. * - * @param args The objects to merge + * @param args - The objects to merge */ @Functions.signature({ argumentsSpecs: [['object']], @@ -266,7 +266,7 @@ class Functions { /** * Get the minimum value in the provided array. * - * @param arg The array to get the minimum value of + * @param arg - The array to get the minimum value of */ @Functions.signature({ argumentsSpecs: [['array-number', 'array-string']], @@ -285,8 +285,8 @@ class Functions { /** * Get the item in the provided array that has the minimum value when the provided expression is evaluated. * - * @param args The array of items to get the minimum value of - * @param expression The expression to evaluate for each item in the array + * @param args - The array of items to get the minimum value of + * @param expression - The expression to evaluate for each item in the array */ @Functions.signature({ argumentsSpecs: [['array'], ['expression']], @@ -332,7 +332,7 @@ class Functions { * Get the first argument that does not evaluate to null. * If all arguments evaluate to null, then null is returned. * - * @param args The keys of the items to check + * @param args - The keys of the items to check */ @Functions.signature({ argumentsSpecs: [[]], @@ -345,7 +345,7 @@ class Functions { /** * Reverses the provided string or array. * - * @param arg The string or array to reverse + * @param arg - The string or array to reverse */ @Functions.signature({ argumentsSpecs: [['string', 'array']], @@ -359,7 +359,7 @@ class Functions { /** * Sort the provided array. * - * @param arg The array to sort + * @param arg - The array to sort */ @Functions.signature({ argumentsSpecs: [['array-number', 'array-string']], @@ -382,8 +382,8 @@ class Functions { /** * Sort the provided array by the provided expression. * - * @param args The array to sort - * @param expression The expression to sort by + * @param args - The array to sort + * @param expression - The expression to sort by */ @Functions.signature({ argumentsSpecs: [['array'], ['expression']], @@ -426,8 +426,8 @@ class Functions { /** * Determines if the provided string starts with the provided prefix. * - * @param str The string to check - * @param prefix The prefix to check for + * @param str - The string to check + * @param prefix - The prefix to check for */ @Functions.signature({ argumentsSpecs: [['string'], ['string']], @@ -439,7 +439,7 @@ class Functions { /** * Sum the provided numbers. * - * @param args The numbers to sum + * @param args - The numbers to sum */ @Functions.signature({ argumentsSpecs: [['array-number']], @@ -454,7 +454,7 @@ class Functions { * If the provided value is an array, then it is returned. * Otherwise, the value is wrapped in an array and returned. * - * @param arg The items to convert to an array + * @param arg - The items to convert to an array */ @Functions.signature({ argumentsSpecs: [['any']], @@ -473,7 +473,7 @@ class Functions { * * If the value cannot be converted to a number, then null is returned. * - * @param arg The value to convert to a number + * @param arg - The value to convert to a number */ @Functions.signature({ argumentsSpecs: [['any']], @@ -496,7 +496,7 @@ class Functions { * If the provided value is a string, then it is returned. * Otherwise, the value is converted to a string and returned. * - * @param arg The value to convert to a string + * @param arg - The value to convert to a string */ @Functions.signature({ argumentsSpecs: [['any']], @@ -508,7 +508,7 @@ class Functions { /** * Get the type of the provided value. * - * @param arg The value to check the type of + * @param arg - The value to check the type of */ @Functions.signature({ argumentsSpecs: [['any']], @@ -520,7 +520,7 @@ class Functions { /** * Get the values of the provided object. * - * @param arg The object to get the values of + * @param arg - The object to get the values of */ @Functions.signature({ argumentsSpecs: [['object']], @@ -544,7 +544,7 @@ class Functions { * to the `methods` set. Finally, when the recursion collects back to the current instance, * it adds the collected methods to the `this.methods` set so that they can be accessed later. * - * @param scope The scope of the class instance to introspect + * @param scope - The scope of the class instance to introspect */ public introspectMethods(scope?: Functions): Set { const prototype = Object.getPrototypeOf(this); @@ -598,7 +598,7 @@ class Functions { * } * ``` * - * @param options The options for the signature decorator + * @param options - The options for the signature decorator */ public static signature( options: FunctionSignatureOptions diff --git a/packages/jmespath/src/Lexer.ts b/packages/jmespath/src/Lexer.ts index 9136311888..7e83ca7b4e 100644 --- a/packages/jmespath/src/Lexer.ts +++ b/packages/jmespath/src/Lexer.ts @@ -55,7 +55,7 @@ class Lexer { const buff = this.#consumeNumber(); yield { type: 'number', - value: Number.parseInt(buff), + value: Number.parseInt(buff, 10), start: start, end: start + buff.length, }; @@ -155,7 +155,7 @@ class Lexer { if (buff.length > 1) { return { type: 'number', - value: Number.parseInt(buff), + value: Number.parseInt(buff, 10), start: start, end: start + buff.length, }; diff --git a/packages/jmespath/src/ParsedResult.ts b/packages/jmespath/src/ParsedResult.ts index c5436fabd1..02c0481592 100644 --- a/packages/jmespath/src/ParsedResult.ts +++ b/packages/jmespath/src/ParsedResult.ts @@ -19,8 +19,8 @@ class ParsedResult { /** * Perform a JMESPath search on a JSON value. * - * @param value The JSON value to search - * @param options The parsing options to use + * @param value - The JSON value to search + * @param options - The parsing options to use */ public search(value: JSONObject, options?: JMESPathParsingOptions): unknown { const interpreter = new TreeInterpreter(options); diff --git a/packages/jmespath/src/Parser.ts b/packages/jmespath/src/Parser.ts index c576d5ee2b..69d8c94d55 100644 --- a/packages/jmespath/src/Parser.ts +++ b/packages/jmespath/src/Parser.ts @@ -32,7 +32,6 @@ import type { Node, Token } from './types.js'; /** * Top down operator precedence parser for JMESPath. * - * ## References * The implementation of this Parser is based on the implementation of * [jmespath.py](https://github.com/jmespath/jmespath.py/), which in turn * is based on [Vaughan R. Pratt's "Top Down Operator Precedence"](http://dl.acm.org/citation.cfm?doid=512927.512931). @@ -72,7 +71,7 @@ class Parser { * The AST is cached, so if you parse the same expression multiple times, * the AST will be returned from the cache. * - * @param expression The JMESPath expression to parse. + * @param expression - The JMESPath expression to parse. */ public parse(expression: string): ParsedResult { const cached = this.#cache[expression]; @@ -98,7 +97,7 @@ class Parser { /** * Do the actual parsing of the expression. * - * @param expression The JMESPath expression to parse. + * @param expression - The JMESPath expression to parse. */ #doParse(expression: string): ParsedResult { try { @@ -153,7 +152,7 @@ class Parser { * Get the nud function for a token. This is the function that * is called when a token is found at the beginning of an expression. * - * @param tokenType The type of token to get the nud function for. + * @param tokenType - The type of token to get the nud function for. */ #getNudFunction(token: Token): Node { const { type: tokenType } = token; @@ -194,7 +193,7 @@ class Parser { * * @example s."foo" * - * @param token The token to process + * @param token - The token to process */ #processQuotedIdentifier(token: Token): Node { const fieldValue = field(token.value); @@ -288,7 +287,7 @@ class Parser { * A default token is a syntax that allows you to access * elements in a list or dictionary. * - * @param token The token to process + * @param token - The token to process */ #processDefaultToken(token: Token): Node { if (token.type === 'eof') { @@ -309,8 +308,8 @@ class Parser { * Get the led function for a token. This is the function that * is called when a token is found in the middle of an expression. * - * @param tokenType The type of token to get the led function for. - * @param leftNode The left hand side of the expression. + * @param tokenType - The type of token to get the led function for. + * @param leftNode - The left hand side of the expression. */ #getLedFunction(tokenType: Token['type'], leftNode: Node): Node { switch (tokenType) { @@ -350,7 +349,7 @@ class Parser { * * @example foo.bar * - * @param leftNode The left hand side of the expression. + * @param leftNode - The left hand side of the expression. */ #processDotToken(leftNode: Node): Node { if (this.#currentToken() !== 'star') { @@ -377,7 +376,7 @@ class Parser { * * @example foo | bar * - * @param leftNode The left hand side of the expression. + * @param leftNode - The left hand side of the expression. */ #processPipeToken(leftNode: Node): Node { const right = this.#expression(BINDING_POWER.pipe); @@ -393,7 +392,7 @@ class Parser { * * @example foo || bar * - * @param leftNode The left hand side of the expression. + * @param leftNode - The left hand side of the expression. */ #processOrToken(leftNode: Node): Node { const right = this.#expression(BINDING_POWER.or); @@ -409,7 +408,7 @@ class Parser { * * @example foo && bar * - * @param leftNode The left hand side of the expression. + * @param leftNode - The left hand side of the expression. */ #processAndToken(leftNode: Node): Node { const right = this.#expression(BINDING_POWER.and); @@ -417,6 +416,11 @@ class Parser { return andExpression(leftNode, right); } + /** + * Process a left parenthesis token. + * + * @param leftNode - The left hand side of the expression. + */ #processLParenToken(leftNode: Node): Node { const name = leftNode.value as string; const args = []; @@ -432,6 +436,11 @@ class Parser { return functionExpression(name, args); } + /** + * Process a filter token. + * + * @param leftNode - The left hand side of the expression. + */ #processFilterToken(leftNode: Node): Node { // Filters are projections const condition = this.#expression(0); @@ -446,6 +455,11 @@ class Parser { return filterProjection(leftNode, right, condition); } + /** + * Process a projection right hand side. + * + * @param leftNode - The left hand side of the expression. + */ #processFlattenToken(leftNode: Node): Node { const left = flatten(leftNode); const right = this.#parseProjectionRhs(BINDING_POWER.flatten); @@ -453,6 +467,11 @@ class Parser { return projection(left, right); } + /** + * Process a left bracket token. + * + * @param leftNode - The left hand side of the expression. + */ #processLBracketToken(leftNode: Node): Node { const token = this.#lookaheadToken(0); if (['number', 'colon'].includes(token.type)) { @@ -485,7 +504,7 @@ class Parser { * the error occurred, the value of the token that caused * the error, the type of the token, and an optional reason. * - * @param options The options to use when throwing the error. + * @param options - The options to use when throwing the error. */ #throwParseError(options?: { lexPosition?: number; @@ -575,8 +594,8 @@ class Parser { * Process a projection if the right hand side of the * projection is a slice. * - * @param left The left hand side of the projection. - * @param right The right hand side of the projection. + * @param left - The left hand side of the projection. + * @param right - The right hand side of the projection. */ #projectIfSlice(left: Node, right: Node): Node { const idxExpression = indexExpression([left, right]); @@ -596,8 +615,8 @@ class Parser { * two values. For example `foo == bar` compares the * value of `foo` with the value of `bar`. * - * @param left The left hand side of the comparator. - * @param comparatorChar The comparator character. + * @param left - The left hand side of the comparator. + * @param comparatorChar - The comparator character. */ #parseComparator(left: Node, comparatorChar: Token['type']): Node { return comparator( @@ -663,7 +682,7 @@ class Parser { /** * Process the right hand side of a projection. * - * @param bindingPower The binding power of the current token. + * @param bindingPower - The binding power of the current token. */ #parseProjectionRhs(bindingPower: number): Node { // Parse the right hand side of the projection. @@ -688,7 +707,7 @@ class Parser { /** * Process the right hand side of a dot expression. * - * @param bindingPower The binding power of the current token. + * @param bindingPower - The binding power of the current token. */ #parseDotRhs(bindingPower: number): Node { // From the grammar: @@ -722,7 +741,7 @@ class Parser { /** * Process a token and throw an error if it doesn't match the expected token. * - * @param tokenType The expected token type. + * @param tokenType - The expected token type. */ #match(tokenType: Token['type']): void { const currentToken = this.#currentToken(); @@ -748,7 +767,7 @@ class Parser { /** * Process a token and throw an error if it doesn't match the expected token. * - * @param tokenTypes The expected token types. + * @param tokenTypes - The expected token types. */ #matchMultipleTokens(tokenTypes: Token['type'][]): void { const currentToken = this.#currentToken(); @@ -787,7 +806,7 @@ class Parser { /** * Look ahead in the token stream and get the type of the token * - * @param number The number of tokens to look ahead. + * @param number - The number of tokens to look ahead. */ #lookahead(number: number): Token['type'] { return this.#tokens[this.#index + number].type; @@ -796,7 +815,7 @@ class Parser { /** * Look ahead in the token stream and get the token * - * @param number The number of tokens to look ahead. + * @param number - The number of tokens to look ahead. */ #lookaheadToken(number: number): Token { return this.#tokens[this.#index + number]; diff --git a/packages/jmespath/src/PowertoolsFunctions.ts b/packages/jmespath/src/PowertoolsFunctions.ts index fc353aa8b0..3dd21b8190 100644 --- a/packages/jmespath/src/PowertoolsFunctions.ts +++ b/packages/jmespath/src/PowertoolsFunctions.ts @@ -2,6 +2,7 @@ import { gunzipSync } from 'node:zlib'; import type { JSONValue } from '@aws-lambda-powertools/commons/types'; import { fromBase64 } from '@aws-lambda-powertools/commons/utils/base64'; import { Functions } from './Functions.js'; +import type { search } from './search.js'; const decoder = new TextDecoder('utf-8'); @@ -10,7 +11,7 @@ const decoder = new TextDecoder('utf-8'); * * Built-in JMESPath functions include: `powertools_json`, `powertools_base64`, `powertools_base64_gzip` * - * You can use these functions to decode and/or deserialize JSON objects when using the {@link index.search | search} function. + * You can use these functions to decode and/or deserialize JSON objects when using the {@link search | `search`} function. * * @example * ```typescript @@ -28,9 +29,6 @@ const decoder = new TextDecoder('utf-8'); * ); * console.log(result); // { foo: 'bar' } * ``` - * - * When using the {@link envelopes.extractDataFromEnvelope} function, the PowertoolsFunctions class is automatically used. - * */ class PowertoolsFunctions extends Functions { @Functions.signature({ @@ -58,4 +56,5 @@ class PowertoolsFunctions extends Functions { } } -export { PowertoolsFunctions, Functions }; +export { Functions } from './Functions.js'; +export { PowertoolsFunctions }; diff --git a/packages/jmespath/src/TreeInterpreter.ts b/packages/jmespath/src/TreeInterpreter.ts index 17be0bd49a..a23c0d07b7 100644 --- a/packages/jmespath/src/TreeInterpreter.ts +++ b/packages/jmespath/src/TreeInterpreter.ts @@ -215,10 +215,10 @@ class TreeInterpreter { try { // We know that methodName is a key of this.#functions, but TypeScript - // doesn't know that, so we have to use @ts-ignore to tell it that it's + // doesn't know that, so we suppress the issue to tell it that it's // okay. We could use a type assertion like `as keyof Functions`, but // we also want to keep the args generic, so for now we'll just ignore it. - // @ts-ignore-next-line + // @ts-expect-error return this.#functions[funcName](args); } catch (error) { if ( diff --git a/packages/jmespath/src/ast.ts b/packages/jmespath/src/ast.ts index c0f2eff39f..81bec422f1 100644 --- a/packages/jmespath/src/ast.ts +++ b/packages/jmespath/src/ast.ts @@ -6,9 +6,9 @@ import type { Node } from './types.js'; * * A comparator expression is a binary expression that compares two values. * - * @param name The name of the comparator - * @param first The left-hand side of the comparator - * @param second The right-hand side of the comparator + * @param name - The name of the comparator + * @param first - The left-hand side of the comparator + * @param second - The right-hand side of the comparator */ const comparator = (name: string, first: Node, second: Node): Node => ({ type: 'comparator', @@ -33,7 +33,7 @@ const currentNode = (): Node => ({ * An expression reference is a reference to another expression. * In JMESPath, an expression reference is represented by the `&` symbol. * - * @param expression The expression to reference + * @param expression - The expression to reference */ const expref = (expression: Node): Node => ({ type: 'expref', @@ -49,8 +49,8 @@ const expref = (expression: Node): Node => ({ * * Custom functions can be added by extending the `Functions` class. * - * @param name The name of the function - * @param args The arguments to the function + * @param name - The name of the function + * @param args - The arguments to the function */ const functionExpression = (name: string, args: Node[]): Node => ({ type: 'function_expression', @@ -62,6 +62,8 @@ const functionExpression = (name: string, args: Node[]): Node => ({ * AST node representing a field reference. * * A field reference is a reference to a field in an object. + * + * @param name - The name of the field */ const field = (name: JSONValue): Node => ({ type: 'field', @@ -79,9 +81,9 @@ const field = (name: JSONValue): Node => ({ * For example, `people[?age > 18]` filters the `people` array based on the * `age` field. * - * @param left The left-hand side of the filter projection - * @param right The right-hand side of the filter projection - * @param comparator The comparator to use for the filter + * @param left - The left-hand side of the filter projection + * @param right - The right-hand side of the filter projection + * @param comparator - The comparator to use for the filter */ const filterProjection = (left: Node, right: Node, comparator: Node): Node => ({ type: 'filter_projection', @@ -98,7 +100,7 @@ const filterProjection = (left: Node, right: Node, comparator: Node): Node => ({ * For example, `people[].name` flattens the `people` array and returns the * `name` field of each object in the array. * - * @param node The node to flatten + * @param node - The node to flatten */ const flatten = (node: Node): Node => ({ type: 'flatten', @@ -116,7 +118,7 @@ const identity = (): Node => ({ type: 'identity', children: [] }); * An index reference is a reference to an index in an array. * For example, `people[0]` references the first element in the `people` array. * - * @param index The index to reference + * @param index - The index to reference */ const index = (index: JSONValue): Node => ({ type: 'index', @@ -129,7 +131,7 @@ const index = (index: JSONValue): Node => ({ * * An index expression holds the index and the children of the expression. * - * @param children The children of the index expression + * @param children - The children of the index expression */ const indexExpression = (children: Node[]): Node => ({ type: 'index_expression', @@ -139,8 +141,8 @@ const indexExpression = (children: Node[]): Node => ({ /** * AST node representing a key-value pair. * - * @param keyName The name of the key - * @param node The value of the key + * @param keyName - The name of the key + * @param node - The value of the key */ const keyValPair = (keyName: JSONValue, node: Node): Node => ({ type: 'key_val_pair', @@ -153,7 +155,7 @@ const keyValPair = (keyName: JSONValue, node: Node): Node => ({ * * A literal value is a value that is not a reference to another node. * - * @param literalValue The value of the literal + * @param literalValue - The value of the literal */ const literal = (literalValue: JSONValue): Node => ({ type: 'literal', @@ -166,7 +168,7 @@ const literal = (literalValue: JSONValue): Node => ({ * * A multi-select object is a reference to multiple nodes in an object. * - * @param nodes + * @param nodes - The nodes to select */ const multiSelectObject = (nodes: Node[]): Node => ({ type: 'multi_select_object', @@ -176,7 +178,7 @@ const multiSelectObject = (nodes: Node[]): Node => ({ /** * AST node representing a multi-select list. * - * @param nodes + * @param nodes - The nodes to select */ const multiSelectList = (nodes: Node[]): Node => ({ type: 'multi_select_list', @@ -186,8 +188,8 @@ const multiSelectList = (nodes: Node[]): Node => ({ /** * AST node representing an or expression. * - * @param left The left-hand side of the or expression - * @param right The right-hand side of the or expression + * @param left - The left-hand side of the or expression + * @param right - The right-hand side of the or expression */ const orExpression = (left: Node, right: Node): Node => ({ type: 'or_expression', @@ -197,8 +199,8 @@ const orExpression = (left: Node, right: Node): Node => ({ /** * AST node representing an and expression. * - * @param left The left-hand side of the and expression - * @param right The right-hand side of the and expression + * @param left - The left-hand side of the and expression + * @param right - The right-hand side of the and expression */ const andExpression = (left: Node, right: Node): Node => ({ type: 'and_expression', @@ -208,8 +210,8 @@ const andExpression = (left: Node, right: Node): Node => ({ /** * AST node representing a not expression. * - * @param left The left-hand side of the not expression - * @param right The right-hand side of the not expression + * @param left - The left-hand side of the not expression + * @param right - The right-hand side of the not expression */ const notExpression = (expr: Node): Node => ({ type: 'not_expression', @@ -219,8 +221,8 @@ const notExpression = (expr: Node): Node => ({ /** * AST node representing a pipe expression. * - * @param left The left-hand side of the pipe expression - * @param right The right-hand side of the pipe expression + * @param left - The left-hand side of the pipe expression + * @param right - The right-hand side of the pipe expression */ const pipe = (left: Node, right: Node): Node => ({ type: 'pipe', @@ -230,8 +232,8 @@ const pipe = (left: Node, right: Node): Node => ({ /** * AST node representing a projection. * - * @param left The left-hand side of the projection - * @param right The right-hand side of the projection + * @param left - The left-hand side of the projection + * @param right - The right-hand side of the projection */ const projection = (left: Node, right: Node): Node => ({ type: 'projection', @@ -241,7 +243,7 @@ const projection = (left: Node, right: Node): Node => ({ /** * AST node representing a subexpression. * - * @param children The children of the subexpression + * @param children - The children of the subexpression */ const subexpression = (children: Node[]): Node => ({ type: 'subexpression', @@ -253,9 +255,9 @@ const subexpression = (children: Node[]): Node => ({ * * A slice is a reference to a range of values in an array. * - * @param start The start of the slice - * @param end The end of the slice - * @param step The step of the slice + * @param start - The start of the slice + * @param end - The end of the slice + * @param step - The step of the slice */ const slice = (start: JSONValue, end: JSONValue, step: JSONValue): Node => ({ type: 'slice', @@ -265,8 +267,8 @@ const slice = (start: JSONValue, end: JSONValue, step: JSONValue): Node => ({ /** * AST node representing a value projection. * - * @param left The left-hand side of the value projection - * @param right The right-hand side of the value projection + * @param left - The left-hand side of the value projection + * @param right - The right-hand side of the value projection */ const valueProjection = (left: Node, right: Node): Node => ({ type: 'value_projection', diff --git a/packages/jmespath/src/constants.ts b/packages/jmespath/src/constants.ts index de078f8754..0697ea8898 100644 --- a/packages/jmespath/src/constants.ts +++ b/packages/jmespath/src/constants.ts @@ -42,26 +42,32 @@ const BINDING_POWER = { * The set of ASCII lowercase letters allowed in JMESPath identifiers. */ const ASCII_LOWERCASE = 'abcdefghijklmnopqrstuvwxyz'; + /** * The set of ASCII uppercase letters allowed in JMESPath identifiers. */ const ASCII_UPPERCASE = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'; + /** * The set of ASCII letters allowed in JMESPath identifiers. */ const ASCII_LETTERS = ASCII_LOWERCASE + ASCII_UPPERCASE; + /** * The set of ASCII digits allowed in JMESPath identifiers. */ const DIGITS = '0123456789'; + /** * The set of ASCII letters and digits allowed in JMESPath identifiers. */ const START_IDENTIFIER = new Set(`${ASCII_LETTERS}_`); + /** * The set of ASCII letters and digits allowed in JMESPath identifiers. */ const VALID_IDENTIFIER = new Set(`${ASCII_LETTERS}${DIGITS}_`); + /** * The set of ASCII digits allowed in JMESPath identifiers. */ @@ -70,6 +76,7 @@ const VALID_NUMBER = new Set(DIGITS); * The set of ASCII whitespace characters allowed in JMESPath identifiers. */ const WHITESPACE = new Set(' \t\n\r'); + /** * The set of simple tokens in the JMESPath grammar. */ diff --git a/packages/jmespath/src/envelopes.ts b/packages/jmespath/src/envelopes.ts index 32107f0a5d..12400004de 100644 --- a/packages/jmespath/src/envelopes.ts +++ b/packages/jmespath/src/envelopes.ts @@ -50,9 +50,9 @@ import type { JMESPathParsingOptions, JSONObject } from './types.js'; * }; * ``` * - * @param data The JSON object to search - * @param envelope The JMESPath expression to use - * @param options The parsing options to use + * @param data - The JSON object to search + * @param envelope - The JMESPath expression to use + * @param options - The parsing options to use */ const extractDataFromEnvelope = ( data: JSONObject, diff --git a/packages/jmespath/src/errors.ts b/packages/jmespath/src/errors.ts index 87ec88ed0e..dd3958ac32 100644 --- a/packages/jmespath/src/errors.ts +++ b/packages/jmespath/src/errors.ts @@ -23,7 +23,7 @@ class JMESPathError extends Error { * thrown. In some instances the expression is not known until after the * error is thrown (i.e. the error is thrown down the call stack). * - * @param expression The expression that was being parsed when the error occurred. + * @param expression - The expression that was being parsed when the error occurred. */ public setExpression(expression: string): void { this.expression = expression; @@ -163,7 +163,7 @@ class FunctionError extends JMESPathError { * alias. To avoid passing the function name down the call stack, we set it * after the error is thrown. * - * @param functionName The function that was being validated or executed when the error occurred. + * @param functionName - The function that was being validated or executed when the error occurred. */ public setEvaluatedFunctionName(functionName: string): void { this.message = this.message.replace( @@ -202,6 +202,12 @@ class ArityError extends FunctionError { }, received ${this.actualArity}`; } + /** + * Pluralizes a word based on the count. + * + * @param word - The word to pluralize + * @param count - The count to determine if the word should be pluralized + */ protected pluralize(word: string, count: number): string { return count === 1 ? word : `${word}s`; } @@ -262,6 +268,9 @@ class JMESPathTypeError extends FunctionError { }"`; } + /** + * Serialize the expected types for the error message. + */ protected serializeExpectedTypes(): string { const types: string[] = []; for (const type of this.expectedTypes) { diff --git a/packages/jmespath/src/search.ts b/packages/jmespath/src/search.ts index 44afcd61c4..79381b3e80 100644 --- a/packages/jmespath/src/search.ts +++ b/packages/jmespath/src/search.ts @@ -45,9 +45,9 @@ const parser = new Parser(); * console.log(result); // { foo: 'bar' } * ``` * - * @param expression The JMESPath expression to use - * @param data The JSON object to search - * @param options The parsing options to use + * @param expression - The JMESPath expression to use + * @param data - The JSON object to search + * @param options - The parsing options to use */ const search = ( expression: string, diff --git a/packages/jmespath/src/types.ts b/packages/jmespath/src/types.ts index 485529d9f1..2cb0727b1e 100644 --- a/packages/jmespath/src/types.ts +++ b/packages/jmespath/src/types.ts @@ -81,8 +81,8 @@ type FunctionSignatureDecorator = ( * } * ``` * - * @param argumentsSpecs The expected arguments for the function. - * @param variadic Whether the function is variadic. + * @param argumentsSpecs - The expected arguments for the function. + * @param variadic - Whether the function is variadic. */ type FunctionSignatureOptions = { argumentsSpecs: Array>; diff --git a/packages/jmespath/src/utils.ts b/packages/jmespath/src/utils.ts index 9a27909c98..3751b98093 100644 --- a/packages/jmespath/src/utils.ts +++ b/packages/jmespath/src/utils.ts @@ -16,7 +16,7 @@ import { ArityError, JMESPathTypeError, VariadicArityError } from './errors.js'; * this reason we wrap the original isTruthy function from the commons package * and add a check for numbers. * - * @param value The value to check + * @param value - The value to check */ const isTruthy = (value: unknown): boolean => { if (isNumber(value)) { @@ -30,9 +30,9 @@ const isTruthy = (value: unknown): boolean => { * Cap a slice range value to the length of an array, taking into account * negative values and whether the step is negative. * - * @param arrayLength The length of the array - * @param value The value to cap - * @param isStepNegative Whether the step is negative + * @param arrayLength - The length of the array + * @param value - The value to cap + * @param isStepNegative - Whether the step is negative */ const capSliceRange = ( arrayLength: number, @@ -54,24 +54,24 @@ const capSliceRange = ( /** * Given a start, stop, and step value, the sub elements in an array are extracted as follows: - * * The first element in the extracted array is the index denoted by start. - * * The last element in the extracted array is the index denoted by end - 1. - * * The step value determines how many indices to skip after each element is selected from the array. An array of 1 (the default step) will not skip any indices. A step value of 2 will skip every other index while extracting elements from an array. A step value of -1 will extract values in reverse order from the array. + * - The first element in the extracted array is the index denoted by start. + * - The last element in the extracted array is the index denoted by end - 1. + * - The step value determines how many indices to skip after each element is selected from the array. An array of 1 (the default step) will not skip any indices. A step value of 2 will skip every other index while extracting elements from an array. A step value of -1 will extract values in reverse order from the array. * * Slice expressions adhere to the following rules: - * * If a negative start position is given, it is calculated as the total length of the array plus the given start position. - * * If no start position is given, it is assumed to be 0 if the given step is greater than 0 or the end of the array if the given step is less than 0. - * * If a negative stop position is given, it is calculated as the total length of the array plus the given stop position. - * * If no stop position is given, it is assumed to be the length of the array if the given step is greater than 0 or 0 if the given step is less than 0. - * * If the given step is omitted, it it assumed to be 1. - * * If the given step is 0, an invalid-value error MUST be raised (thrown before calling the function) - * * If the element being sliced is not an array, the result is null (returned before calling the function) - * * If the element being sliced is an array and yields no results, the result MUST be an empty array. + * - If a negative start position is given, it is calculated as the total length of the array plus the given start position. + * - If no start position is given, it is assumed to be 0 if the given step is greater than 0 or the end of the array if the given step is less than 0. + * - If a negative stop position is given, it is calculated as the total length of the array plus the given stop position. + * - If no stop position is given, it is assumed to be the length of the array if the given step is greater than 0 or 0 if the given step is less than 0. + * - If the given step is omitted, it it assumed to be 1. + * - If the given step is 0, an invalid-value error MUST be raised (thrown before calling the function) + * - If the element being sliced is not an array, the result is null (returned before calling the function) + * - If the element being sliced is an array and yields no results, the result MUST be an empty array. * - * @param array The array to slice - * @param start The start index - * @param end The end index - * @param step The step value + * @param array - The array to slice + * @param start - The start index + * @param end - The end index + * @param step - The step value */ const sliceArray = ({ array, @@ -119,10 +119,10 @@ const sliceArray = ({ * greater than or equal to the expected arity. If the number of arguments passed to the function * is less than the expected arity, a `VariadicArityError` is thrown. * - * @param args The arguments passed to the function - * @param argumentsSpecs The expected types for each argument - * @param decoratedFuncName The name of the function being called - * @param variadic Whether the function is variadic + * @param args - The arguments passed to the function + * @param argumentsSpecs - The expected types for each argument + * @param decoratedFuncName - The name of the function being called + * @param variadic - Whether the function is variadic */ const arityCheck = ( args: unknown[], @@ -160,8 +160,8 @@ const arityCheck = ( * passes. If the argument does not match any of the types, then * a JMESPathTypeError is thrown. * - * @param args The arguments passed to the function - * @param argumentsSpecs The expected types for each argument + * @param args - The arguments passed to the function + * @param argumentsSpecs - The expected types for each argument */ const typeCheck = ( args: unknown[], @@ -182,24 +182,24 @@ const typeCheck = ( * passes. If the argument does not match any of the types, then * a JMESPathTypeError is thrown. * - * @param arg - * @param argumentSpec + * @param arg - The argument to check + * @param argumentSpec - The expected types for the argument */ const typeCheckArgument = (arg: unknown, argumentSpec: Array): void => { let valid = false; - argumentSpec.forEach((type, index) => { + for (const [index, type] of argumentSpec.entries()) { if (valid) return; valid = checkIfArgumentTypeIsValid(arg, type, index, argumentSpec); - }); + } }; /** * Check if the argument is of the expected type. * - * @param arg The argument to check - * @param type The expected type - * @param index The index of the type we are checking - * @param argumentSpec The list of types to check against + * @param arg - The argument to check + * @param type - The expected type + * @param index - The index of the type we are checking + * @param argumentSpec - The list of types to check against */ const checkIfArgumentTypeIsValid = ( arg: unknown, @@ -243,10 +243,10 @@ const checkIfArgumentTypeIsValid = ( /** * Check if the argument is of the expected type. * - * @param arg The argument to check - * @param type The type to check against - * @param argumentSpec The list of types to check against - * @param hasMoreTypesToCheck Whether there are more types to check + * @param arg - The argument to check + * @param type - The type to check against + * @param argumentSpec - The list of types to check against + * @param hasMoreTypesToCheck - Whether there are more types to check */ const typeCheckType = ( arg: unknown, @@ -266,9 +266,9 @@ const typeCheckType = ( /** * Check if the argument is an array of complex types. * - * @param arg The argument to check - * @param type The type to check against - * @param hasMoreTypesToCheck Whether there are more types to check + * @param arg - The argument to check + * @param type - The type to check against + * @param hasMoreTypesToCheck - Whether there are more types to check */ const checkComplexArrayType = ( arg: unknown[], @@ -293,9 +293,9 @@ const checkComplexArrayType = ( /** * Check if the argument is an expression. * - * @param arg The argument to check - * @param type The type to check against - * @param hasMoreTypesToCheck Whether there are more types to check + * @param arg - The argument to check + * @param type - The type to check against + * @param hasMoreTypesToCheck - Whether there are more types to check */ const checkExpressionType = ( arg: unknown, @@ -314,9 +314,9 @@ const checkExpressionType = ( /** * Check if the argument is an object. * - * @param arg The argument to check - * @param type The type to check against - * @param hasMoreTypesToCheck Whether there are more types to check + * @param arg - The argument to check + * @param type - The type to check against + * @param hasMoreTypesToCheck - Whether there are more types to check */ const checkObjectType = ( arg: unknown,