@aws-lambda-powertools/jmespath/lib/esm/Functions.d.ts

A type safe and modern jmespath module to parse and extract data from JSON documents using JMESPath

import type { JSONArray, JSONObject, JSONValue } from '@aws-lambda-powertools/commons/types';
import type { Expression } from './Expression.js';
import type { FunctionSignatureDecorator, FunctionSignatureOptions } from './types.js';
/**
 * A class that contains the built-in JMESPath functions.
 *
 * The built-in functions are implemented as methods on the Functions class.
 * Each method is decorated with the `@Function.signature()` decorator to enforce the
 * arity and types of the arguments passed to the function at runtime.
 *
 * You can extend the Functions class to add custom functions by creating a new class
 * that extends Functions and adding new methods to it.
 *
 * @example
 * ```typescript
 * import { search } from '@aws-lambda-powertools/jmespath';
 * import { Functions } from '@aws-lambda-powertools/jmespath/functions';
 *
 * class MyFunctions extends Functions {
 *   ⁣@Functions.signature({
 *     argumentsSpecs: [['number'], ['number']],
 *     variadic: true,
 *   })
 *   public funcMyMethod(args: Array<number>): unknown {
 *     // ...
 *   }
 * }
 *
 * const myFunctions = new MyFunctions();
 *
 * search('myMethod(@)', {}, { customFunctions: new MyFunctions() });
 * ```
 */
declare class Functions {
    /**
     * A set of all the custom functions available in this and all child classes.
     */
    methods: Set<string>;
    /**
     * Get the absolute value of the provided number.
     *
     * @param args The number to get the absolute value of
     */
    funcAbs(args: number): number;
    /**
     * Calculate the average of the numbers in the provided array.
     *
     * @param args The numbers to average
     */
    funcAvg(args: Array<number>): number;
    /**
     * Get the ceiling of the provided number.
     *
     * @param args The number to get the ceiling of
     */
    funcCeil(args: number): number;
    /**
     * 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
     */
    funcContains(haystack: string, needle: string): boolean;
    /**
     * Determines if the provided string ends with the provided suffix.
     *
     * @param str The string to check
     * @param suffix The suffix to check for
     */
    funcEndsWith(str: string, suffix: string): boolean;
    /**
     * Get the floor of the provided number.
     *
     * @param args The number to get the floor of
     */
    funcFloor(args: number): number;
    /**
     * Join the provided array into a single string.
     *
     * @param separator The separator to use
     * @param items The array of itmes to join
     */
    funcJoin(separator: string, items: Array<string>): string;
    /**
     * Get the keys of the provided object.
     *
     * @param arg The object to get the keys of
     */
    funcKeys(arg: JSONObject): string[];
    /**
     * Get the number of items in the provided item.
     *
     * @param arg The array to get the length of
     */
    funcLength(arg: string | Array<unknown> | Record<string, unknown>): number;
    /**
     * 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
     */
    funcMap(expression: Expression, args: JSONArray): JSONArray | Array<unknown>;
    /**
     * Get the maximum value in the provided array.
     *
     * @param arg The array to get the maximum value of
     */
    funcMax(arg: Array<number | string>): number | string | null;
    /**
     * 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
     */
    funcMaxBy(args: Array<JSONObject>, expression: Expression): JSONObject | null;
    /**
     * Merge the provided objects into a single object.
     *
     * Note that this is a shallow merge and will not merge nested objects.
     *
     * @param args The objects to merge
     */
    funcMerge(...args: Array<JSONObject>): JSONObject;
    /**
     * Get the minimum value in the provided array.
     *
     * @param arg The array to get the minimum value of
     */
    funcMin(arg: Array<number>): number | string | null;
    /**
     * 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
     */
    funcMinBy(args: Array<JSONObject>, expression: Expression): JSONObject | null;
    /**
     * 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
     */
    funcNotNull(...args: Array<JSONValue>): JSONValue | null;
    /**
     * Reverses the provided string or array.
     *
     * @param arg The string or array to reverse
     */
    funcReverse(arg: string | Array<unknown>): string | Array<unknown>;
    /**
     * Sort the provided array.
     *
     * @param arg The array to sort
     */
    funcSort(arg: Array<string> | Array<number>): Array<unknown>;
    /**
     * Sort the provided array by the provided expression.
     *
     * @param args The array to sort
     * @param expression The expression to sort by
     */
    funcSortBy(args: Array<JSONValue>, expression: Expression): Array<unknown>;
    /**
     * Determines if the provided string starts with the provided prefix.
     *
     * @param str The string to check
     * @param prefix The prefix to check for
     */
    funcStartsWith(str: string, prefix: string): boolean;
    /**
     * Sum the provided numbers.
     *
     * @param args The numbers to sum
     */
    funcSum(args: Array<number>): number;
    /**
     * Convert the provided value to an array.
     *
     * 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
     */
    funcToArray(arg: JSONArray | Array<JSONValue>): Array<JSONValue> | JSONArray;
    /**
     * Convert the provided value to a number.
     *
     * If the provided value is a number, then it is returned.
     * Otherwise, the value is converted to a number and returned.
     *
     * If the value cannot be converted to a number, then null is returned.
     *
     * @param arg The value to convert to a number
     */
    funcToNumber(arg: JSONValue): number | null;
    /**
     * Convert the provided value to a string.
     *
     * 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
     */
    funcToString(arg: JSONValue): string;
    /**
     * Get the type of the provided value.
     *
     * @param arg The value to check the type of
     */
    funcType(arg: JSONValue): string;
    /**
     * Get the values of the provided object.
     *
     * @param arg The object to get the values of
     */
    funcValues(arg: JSONObject): JSONValue[];
    /**
     * Lazily introspects the methods of the class instance and all child classes
     * to get the names of the methods that correspond to JMESPath functions.
     *
     * This method is used to get the names of the custom functions that are available
     * in the class instance and all child classes. The names of the functions are used
     * to create the custom function map that is passed to the JMESPath search function.
     *
     * The method traverses the inheritance chain going from the leaf class to the root class
     * and stops when it reaches the `Functions` class, which is the root class.
     *
     * In doing so, it collects the names of the methods that start with `func` and adds them
     * 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
     */
    introspectMethods(scope?: Functions): Set<string>;
    /**
     * Decorator to enforce the signature of a function at runtime.
     *
     * The signature decorator enforces the arity and types of the arguments
     * passed to a function at runtime. If the arguments do not match the
     * expected arity or types errors are thrown.
     *
     * @example
     * ```typescript
     * import { PowertoolsFunctions } from '@aws-lambda-powertools/jmespath/functions';
     *
     * class MyFunctions extends Functions {
     *   ⁣@Functions.signature({
     *     argumentsSpecs: [['number'], ['number']],
     *     variadic: true,
     *   })
     *   public funcMyMethod(args: Array<number>): unknown {
     *     // ...
     *   }
     * }
     * ```
     *
     * @param options The options for the signature decorator
     */
    static signature(options: FunctionSignatureOptions): FunctionSignatureDecorator;
}
export { Functions };
//# sourceMappingURL=Functions.d.ts.map