docs(jmespath): docs for utility

Author: dreamorosi

docs/snippets/jmespath/powertoolsBase64GzipJmespath.ts

@@ -0,0 +1,13 @@
+import { extractDataFromEnvelope } from '@aws-lambda-powertools/jmespath/envelopes';
+import { Logger } from '@aws-lambda-powertools/logger';
+
+const logger = new Logger();
+
+export const handler = async (event: { payload: string }): Promise<void> => {
+  const logGroup = extractDataFromEnvelope<string>(
+    event,
+    'powertools_base64_gzip(payload) | powertools_json(@).logGroup'
+  );
+
+  logger.info('Log group name', { logGroup });
+};

docs/snippets/jmespath/powertoolsBase64GzipJmespathPayload.json

@@ -0,0 +1,3 @@
+{
+  "payload": "H4sIACZAXl8C/52PzUrEMBhFX2UILpX8tPbHXWHqIOiq3Q1F0ubrWEiakqTWofTdTYYB0YWL2d5zvnuTFellBIOedoiyKH5M0iwnlKH7HZL6dDB6ngLDfLFYctUKjie9gHFaS/sAX1xNEq525QxwFXRGGMEkx4Th491rUZdV3YiIZ6Ljfd+lfSyAtZloacQgAkqSJCGhxM6t7cwwuUGPz4N0YKyvO6I9WDeMPMSo8Z4Ca/kJ6vMEYW5f1MX7W1lVxaG8vqX8hNFdjlc0iCBBSF4ERT/3Pl7RbMGMXF2KZMh/C+gDpNS7RRsp0OaRGzx0/t8e0jgmcczyLCWEePhni/23JWalzjdu0a3ZvgEaNLXeugEAAA=="
+}

docs/snippets/jmespath/powertoolsBase64Jmespath.ts

@@ -0,0 +1,13 @@
+import { extractDataFromEnvelope } from '@aws-lambda-powertools/jmespath/envelopes';
+import { Logger } from '@aws-lambda-powertools/logger';
+
+const logger = new Logger();
+
+export const handler = async (event: { payload: string }): Promise<void> => {
+  const data = extractDataFromEnvelope<string>(
+    event,
+    'powertools_json(powertools_base64(payload))'
+  );
+
+  logger.info('Decoded payload', { data });
+};

docs/snippets/jmespath/powertoolsBase64JmespathPayload.json

@@ -0,0 +1,3 @@
+{
+  "payload": "eyJ1c2VyX2lkIjogMTIzLCAicHJvZHVjdF9pZCI6IDEsICJxdWFudGl0eSI6IDIsICJwcmljZSI6IDEwLjQwLCAiY3VycmVuY3kiOiAiVVNEIn0="
+}

docs/snippets/jmespath/powertoolsCustomFunction.json

@@ -0,0 +1,9 @@
+{
+  "Records": [
+    {
+      "application": "app",
+      "datetime": "2022-01-01T00:00:00.000Z",
+      "notification": "GyYA+AXhZKk/K5DkanoQSTYpSKMwwxXh8DRWVo9A1hLqAQ=="
+    }
+  ]
+}

docs/snippets/jmespath/powertoolsCustomFunction.ts

@@ -0,0 +1,31 @@
+import { fromBase64 } from '@aws-lambda-powertools/commons/utils/base64';
+import { extractDataFromEnvelope } from '@aws-lambda-powertools/jmespath/envelopes';
+import { PowertoolsFunctions } from '@aws-lambda-powertools/jmespath/functions';
+import { Logger } from '@aws-lambda-powertools/logger';
+import { brotliDecompressSync } from 'node:zlib';
+
+const logger = new Logger();
+
+// prettier-ignore
+class CustomFunctions extends PowertoolsFunctions {
+  @PowertoolsFunctions.signature({ // (1)!
+    argumentsSpecs: [['string']],
+    variadic: false,
+  })
+  public funcDecodeBrotliCompression(value: string): string { // (2)!
+    const encoded = fromBase64(value, 'base64');
+    const uncompressed = brotliDecompressSync(encoded);
+
+    return uncompressed.toString();
+  }
+}
+
+export const handler = async (event: { payload: string }): Promise<void> => {
+  const message = extractDataFromEnvelope<string>(
+    event,
+    'Records[*].decode_brotli_compression(notification) | [*].powertools_json(@).message',
+    { customFunctions: new CustomFunctions() }
+  );
+
+  logger.info('Decoded message', { message });
+};

docs/snippets/jmespath/powertoolsJsonIdempotencyJmespath.json

@@ -0,0 +1,30 @@
+{
+  "version": "2.0",
+  "routeKey": "ANY /createpayment",
+  "rawPath": "/createpayment",
+  "rawQueryString": "",
+  "headers": {
+    "Header1": "value1",
+    "Header2": "value2"
+  },
+  "requestContext": {
+    "accountId": "123456789012",
+    "apiId": "api-id",
+    "domainName": "id.execute-api.us-east-1.amazonaws.com",
+    "domainPrefix": "id",
+    "http": {
+      "method": "POST",
+      "path": "/createpayment",
+      "protocol": "HTTP/1.1",
+      "sourceIp": "ip",
+      "userAgent": "agent"
+    },
+    "requestId": "id",
+    "routeKey": "ANY /createpayment",
+    "stage": "$default",
+    "time": "10/Feb/2021:13:40:43 +0000",
+    "timeEpoch": 1612964443723
+  },
+  "body": "{\"user\":\"xyz\",\"product_id\":\"123456789\"}",
+  "isBase64Encoded": false
+}

docs/snippets/jmespath/powertoolsJsonIdempotencyJmespath.ts

@@ -0,0 +1,51 @@
+import {
+  IdempotencyConfig,
+  makeIdempotent,
+} from '@aws-lambda-powertools/idempotency';
+import { DynamoDBPersistenceLayer } from '@aws-lambda-powertools/idempotency/dynamodb';
+import type { APIGatewayEvent } from 'aws-lambda';
+import { randomUUID } from 'node:crypto';
+
+const persistenceStore = new DynamoDBPersistenceLayer({
+  tableName: 'IdempotencyTable',
+});
+
+export const handler = makeIdempotent(
+  async (event: APIGatewayEvent) => {
+    const body = JSON.parse(event.body || '{}');
+    const { user, productId } = body;
+
+    const result = await createSubscriptionPayment(user, productId);
+
+    return {
+      statusCode: 200,
+      body: JSON.stringify({
+        paymentId: result.id,
+        message: 'success',
+      }),
+    };
+  },
+  {
+    persistenceStore,
+    config: new IdempotencyConfig({
+      eventKeyJmesPath: 'powertools_json(body)',
+    }),
+  }
+);
+
+const createSubscriptionPayment = async (
+  user: string,
+  productId: string
+): Promise<{ id: string; message: string }> => {
+  const payload = { user, productId };
+  const response = await fetch('https://httpbin.org/anything', {
+    method: 'POST',
+    body: JSON.stringify(payload),
+  });
+
+  if (!response.ok) {
+    throw new Error('Failed to create subscription payment');
+  }
+
+  return { id: randomUUID(), message: 'paid' };
+};

docs/utilities/jmespath.md

@@ -31,7 +31,7 @@ You can use the `extractDataFromEnvelope` function with any [JMESPath expression
 	Another common use case is to fetch deeply nested data, filter, flatten, and more.
 
 === "extractDataFromBuiltinEnvelope.ts"
-    ```typescript hl_lines="1 13 20"
+    ```typescript hl_lines="1 13 17 20 22"
     --8<-- "docs/snippets/jmespath/extractDataFromEnvelope.ts"
     ```
 
@@ -91,16 +91,16 @@ Use `powertools_json` function to decode any JSON string anywhere a JMESPath exp
 
 This sample will deserialize the JSON string within the `body` key before [Idempotency](./idempotency.md){target="_blank"} processes it.
 
-=== "powertools_json_idempotency_jmespath.py"
+=== "powertoolsJsonIdempotencyJmespath.ts"
 
-    ```python hl_lines="16"
-    --8<-- "examples/jmespath_functions/src/powertools_json_idempotency_jmespath.py"
+    ```ts hl_lines="31"
+    --8<-- "docs/snippets/jmespath/powertoolsJsonIdempotencyJmespath.ts"
     ```
 
-=== "powertools_json_idempotency_jmespath.json"
+=== "powertoolsJsonIdempotencyJmespath.json"
 
     ```json hl_lines="28"
-    --8<-- "examples/jmespath_functions/src/powertools_json_idempotency_jmespath.json"
+    --8<-- "docs/snippets/jmespath/powertoolsJsonIdempotencyJmespath.json"
     ```
 
 #### powertools_base64 function
@@ -109,22 +109,16 @@ Use `powertools_base64` function to decode any base64 data.
 
 This sample will decode the base64 value within the `data` key, and deserialize the JSON string before processing.
 
-=== "powertools_base64_jmespath_function.py"
+=== "powertoolsBase64Jmespath.ts"
 
-    ```python hl_lines="7 10 37 49 53 55 57"
-    --8<-- "examples/jmespath_functions/src/powertools_base64_jmespath_function.py"
+    ```ts hl_lines="9"
+    --8<-- "docs/snippets/jmespath/powertoolsBase64Jmespath.ts"
     ```
 
-=== "powertools_base64_jmespath_schema.py"
-
-    ```python hl_lines="7 8 10 12 17 19 24 26 31 33 38 40"
-    --8<-- "examples/jmespath_functions/src/powertools_base64_jmespath_schema.py"
-    ```
-
-=== "powertools_base64_jmespath_payload.json"
+=== "powertoolsBase64JmespathPayload.json"
 
     ```json
-    --8<-- "examples/jmespath_functions/src/powertools_base64_jmespath_payload.json"
+    --8<-- "docs/snippets/jmespath/powertoolsBase64JmespathPayload.json"
     ```
 
 #### powertools_base64_gzip function
@@ -133,41 +127,42 @@ Use `powertools_base64_gzip` function to decompress and decode base64 data.
 
 This sample will decompress and decode base64 data from Cloudwatch Logs, then use JMESPath pipeline expression to pass the result for decoding its JSON string.
 
-=== "powertools_base64_gzip_jmespath_function.py"
-
-    ```python hl_lines="6 10 15 29 31 33 35"
-    --8<-- "examples/jmespath_functions/src/powertools_base64_gzip_jmespath_function.py"
-    ```
-
-=== "powertools_base64_gzip_jmespath_schema.py"
+=== "powertoolsBase64GzipJmespath.ts"
 
-    ```python hl_lines="7-15 17 19 24 26 31 33 38 40"
-    --8<-- "examples/jmespath_functions/src/powertools_base64_gzip_jmespath_schema.py"
+    ```ts hl_lines="9"
+    --8<-- "docs/snippets/jmespath/powertoolsBase64GzipJmespath.ts"
     ```
 
-=== "powertools_base64_gzip_jmespath_payload.json"
+=== "powertoolsBase64GzipJmespathPayload.json"
 
     ```json
-    --8<-- "examples/jmespath_functions/src/powertools_base64_gzip_jmespath_payload.json"
+    --8<-- "docs/snippets/jmespath/powertoolsBase64GzipJmespathPayload.json"
     ```
 
 ### Bring your own JMESPath function
 
 ???+ warning
     This should only be used for advanced use cases where you have special formats not covered by the built-in functions.
 
-For special binary formats that you want to decode before processing, you can bring your own [JMESPath function](https://github.com/jmespath/jmespath.py#custom-functions){target="_blank" rel="nofollow"} and any additional option via `jmespath_options` param. To keep Powertools for AWS Lambda (TypeScript) built-in functions, you can extend the `PowertoolsFunctions` class.
+For special binary formats that you want to decode before processing, you can bring your own JMESPath function by extending the `PowertoolsFunctions` class.
 
-Here is an example of how to decompress messages using [zlib](https://docs.python.org/3/library/zlib.html){target="_blank" rel="nofollow"}:
+Here is an example of how to decompress messages compressed using the [Brotli compression algorithm](https://nodejs.org/api/zlib.html#zlibbrotlidecompressbuffer-options-callback){target="_blank" rel="nofollow"}:
 
-=== "powertools_custom_jmespath_function.py"
+=== "PowertoolsCustomFunction.ts"
 
-    ```python hl_lines="9 14 17-18 23 34 39 41 43"
-	--8<-- "examples/jmespath_functions/src/powertools_custom_jmespath_function.py"
+    ```ts hl_lines="3 9 25-26"
+    --8<--
+     docs/snippets/jmespath/powertoolsCustomFunction.ts::8
+     docs/snippets/jmespath/powertoolsCustomFunction.ts:10:
+
+    --8<--
     ```
 
-=== "powertools_custom_jmespath_function.json"
+    1.  The function signature can be enforced at runtime by using the `@Functions.signature` decorator.
+    2.  The name of the function must start with the `func` prefix.
+
+=== "powertoolsCustomFunction.json"
 
     ```json
-    --8<-- "examples/jmespath_functions/src/powertools_custom_jmespath_function.json"
+    --8<-- "docs/snippets/jmespath/powertoolsCustomFunction.json"
     ```

mkdocs.yml

@@ -19,6 +19,7 @@ nav:
           - utilities/parameters.md
           - utilities/idempotency.md
           - utilities/batch.md
+          - utilities/jmespath.md
   - Processes:
       - Roadmap: roadmap.md
       - Versioning policy: versioning.md
@@ -100,6 +101,7 @@ plugins:
       glob:
         - snippets/node_modules/*
         - snippets/package.json
+        - snippets/CHANGELOG.md
 
 extra_css:
   - stylesheets/extra.css

packages/jmespath/package.json

@@ -43,20 +43,28 @@
       "import": "./lib/esm/envelopes.js",
       "require": "./lib/cjs/envelopes.js"
     },
+    "./functions": {
+      "import": "./lib/esm/PowertoolsFunctions.js",
+      "require": "./lib/cjs/PowertoolsFunctions.js"
+    },
     "./types": {
       "import": "./lib/esm/types.js",
       "require": "./lib/cjs/types.js"
     }
   },
   "typesVersions": {
     "*": {
-      "types": [
-        "lib/cjs/types.d.ts",
-        "lib/esm/types.d.ts"
-      ],
       "envelopes": [
         "lib/cjs/envelopes.d.ts",
         "lib/esm/envelopes.d.ts"
+      ],
+      "functions": [
+        "lib/cjs/PowertoolsFunctions.d.ts",
+        "lib/esm/PowertoolsFunctions.d.ts"
+      ],
+      "types": [
+        "lib/cjs/types.d.ts",
+        "lib/esm/types.d.ts"
       ]
     }
   },
@@ -84,4 +92,4 @@
     "typescript",
     "nodejs"
   ]
-}
+}

packages/jmespath/src/Functions.ts

@@ -48,6 +48,7 @@ import { arityCheck, typeCheck } from './utils.js';
  * ```
  */
 class Functions {
+  public methods: Set<string> = new Set();
   /**
    * Get the absolute value of the provided number.
    *
@@ -540,6 +541,35 @@ class Functions {
     return Object.values(arg);
   }
 
+  public introspectMethods(scope?: Functions): Set<string> {
+    const prototype = Object.getPrototypeOf(this);
+    const ownName = prototype.constructor.name;
+    const methods = new Set<string>();
+    if (ownName !== 'Functions') {
+      for (const method of prototype.introspectMethods(scope)) {
+        methods.add(method);
+      }
+    }
+
+    // This block is executed for every class in the inheritance chain
+    for (const method of Object.getOwnPropertyNames(
+      Object.getPrototypeOf(this)
+    )) {
+      method !== 'constructor' &&
+        method.startsWith('func') &&
+        methods.add(method);
+    }
+
+    // This block will be executed only if the scope is the outermost class
+    if (this.methods) {
+      for (const method of methods) {
+        this.methods.add(method);
+      }
+    }
+
+    return methods;
+  }
+
   /**
    * Decorator to enforce the signature of a function at runtime.
    *