refactor(jmespath): rename jmespath parsing options type (#2367)

* feat(idempotency): add custom jmespath functions

* chore(layers): add package to layer

* chore: move jmespath pkg up into build process

* feat: enable custom functions

* chore: move jmespath pkg up into build process

* chore: update layer setup

* refactor(jmespath): rename jmespath parsing options type

* chore: updated occurrences

* chore: merge conflicts

Author: dreamorosi

package-lock.json

@@ -4,14 +4,14 @@
   "description": "A suite of utilities for AWS Lambda functions to ease adopting best practices such as tracing, structured logging, custom metrics, and more.",
   "workspaces": [
     "packages/commons",
+    "packages/jmespath",
     "packages/logger",
     "packages/metrics",
     "packages/tracer",
     "packages/parameters",
     "packages/idempotency",
     "packages/batch",
     "packages/testing",
-    "packages/jmespath",
     "packages/parser",
     "docs/snippets",
     "layers",

package.json

@@ -1,7 +1,7 @@
 import { EnvironmentVariablesService } from './config/EnvironmentVariablesService.js';
 import type { Context } from 'aws-lambda';
 import type { IdempotencyConfigOptions } from './types/IdempotencyOptions.js';
-import type { ParsingOptions } from '@aws-lambda-powertools/jmespath/types';
+import type { JMESPathParsingOptions } from '@aws-lambda-powertools/jmespath/types';
 import { PowertoolsFunctions } from '@aws-lambda-powertools/jmespath/functions';
 
 /**
@@ -25,9 +25,13 @@ class IdempotencyConfig {
    */
   public hashFunction: string;
   /**
+   * Options for parsing JMESPath expressions.
    *
+   * By default, you can use any of the {@link https://jmespath.org/specification.html | JMESPath built-in functions} as well as the
+   * {@link https://docs.powertools.aws.dev/lambda/typescript/latest/api/classes/_aws_lambda_powertools_jmespath.PowertoolsFunctions.PowertoolsFunctions.html | custom functions provided}
+   * by the `@aws-lambda-powertools/jmespath` package.
    */
-  public jmesPathOptions: ParsingOptions;
+  public jmesPathOptions: JMESPathParsingOptions;
   /**
    * The lambda context object.
    */

packages/idempotency/src/IdempotencyConfig.ts

@@ -1,6 +1,6 @@
 import { createHash, Hash } from 'node:crypto';
 import { search } from '@aws-lambda-powertools/jmespath';
-import type { ParsingOptions } from '@aws-lambda-powertools/jmespath/types';
+import type { JMESPathParsingOptions } from '@aws-lambda-powertools/jmespath/types';
 import type {
   BasePersistenceLayerOptions,
   BasePersistenceLayerInterface,
@@ -37,7 +37,7 @@ abstract class BasePersistenceLayer implements BasePersistenceLayerInterface {
   private throwOnNoIdempotencyKey = false;
   private useLocalCache = false;
   private validationKeyJmesPath?: string;
-  #jmesPathOptions?: ParsingOptions;
+  #jmesPathOptions?: JMESPathParsingOptions;
 
   public constructor() {
     this.envVarsService = new EnvironmentVariablesService();

packages/idempotency/src/persistence/BasePersistenceLayer.ts

@@ -5,7 +5,7 @@ import {
   UnknownFunctionError,
   VariadicArityError,
 } from './errors.js';
-import type { Node, ParsingOptions, JSONObject } from './types.js';
+import type { Node, JMESPathParsingOptions, JSONObject } from './types.js';
 
 class ParsedResult {
   public expression: string;
@@ -22,7 +22,7 @@ class ParsedResult {
    * @param value The JSON value to search
    * @param options The parsing options to use
    */
-  public search(value: JSONObject, options?: ParsingOptions): unknown {
+  public search(value: JSONObject, options?: JMESPathParsingOptions): unknown {
     const interpreter = new TreeInterpreter(options);
 
     try {

packages/jmespath/src/ParsedResult.ts

@@ -12,7 +12,7 @@ import {
 } from './errors.js';
 import { Expression } from './Expression.js';
 import { Functions } from './Functions.js';
-import type { Node, TreeInterpreterOptions, JSONObject } from './types.js';
+import type { Node, JMESPathParsingOptions, JSONObject } from './types.js';
 import { isTruthy, sliceArray } from './utils.js';
 
 /**
@@ -30,7 +30,7 @@ class TreeInterpreter {
   /**
    * @param options The options to use for the interpreter.
    */
-  public constructor(options?: TreeInterpreterOptions) {
+  public constructor(options?: JMESPathParsingOptions) {
     if (options?.customFunctions) {
       this.#functions = options.customFunctions;
     } else {

packages/jmespath/src/TreeInterpreter.ts

@@ -1,6 +1,6 @@
 import { search } from './search.js';
 import { PowertoolsFunctions } from './PowertoolsFunctions.js';
-import type { ParsingOptions, JSONObject } from './types.js';
+import type { JMESPathParsingOptions, JSONObject } from './types.js';
 
 /**
  * Searches and extracts data using JMESPath
@@ -57,7 +57,7 @@ import type { ParsingOptions, JSONObject } from './types.js';
 const extractDataFromEnvelope = <T>(
   data: JSONObject,
   envelope: string,
-  options?: ParsingOptions
+  options?: JMESPathParsingOptions
 ): T => {
   if (!options) {
     options = { customFunctions: new PowertoolsFunctions() };

packages/jmespath/src/envelopes.ts

@@ -1,5 +1,5 @@
 import { Parser } from './Parser.js';
-import type { ParsingOptions, JSONObject } from './types.js';
+import type { JMESPathParsingOptions, JSONObject } from './types.js';
 
 const parser = new Parser();
 
@@ -52,7 +52,7 @@ const parser = new Parser();
 const search = (
   expression: string,
   data: JSONObject,
-  options?: ParsingOptions
+  options?: JMESPathParsingOptions
 ): unknown => {
   return parser.parse(expression).search(data, options);
 };

packages/jmespath/src/search.ts

@@ -24,19 +24,6 @@ type Node = {
   value?: JSONValue;
 };
 
-/**
- * Options for the tree interpreter.
- */
-type TreeInterpreterOptions = {
-  /**
-   * The custom functions to use.
-   *
-   * By default, the interpreter uses the standard JMESPath functions
-   * available in the [JMESPath specification](https://jmespath.org/specification.html).
-   */
-  customFunctions?: Functions;
-};
-
 /**
  * Options for parsing.
  *
@@ -57,7 +44,15 @@ type TreeInterpreterOptions = {
  * console.log(result); // { a: 1 }
  * ```
  */
-type ParsingOptions = TreeInterpreterOptions;
+type JMESPathParsingOptions = {
+  /**
+   * The custom functions to use.
+   *
+   * By default, the interpreter uses the standard JMESPath functions
+   * available in the [JMESPath specification](https://jmespath.org/specification.html).
+   */
+  customFunctions?: Functions;
+};
 
 /**
  * Decorator for function signatures.
@@ -103,8 +98,7 @@ export type {
   FunctionSignatureDecorator,
   FunctionSignatureOptions,
   Node,
-  ParsingOptions,
+  JMESPathParsingOptions,
   Token,
-  TreeInterpreterOptions,
   JSONObject,
 };