docs(jmespath): add utility docs (#2187)

docs/snippets/jmespath/extractDataFromBuiltinEnvelope.json

@@ -0,0 +1,20 @@
+{
+  "Records": [
+    {
+      "messageId": "19dd0b57-b21e-4ac1-bd88-01bbb068cb78",
+      "receiptHandle": "MessageReceiptHandle",
+      "body": "{\"customerId\":\"dd4649e6-2484-4993-acb8-0f9123103394\",\"booking\":{\"id\":\"5b2c4803-330b-42b7-811a-c68689425de1\",\"reference\":\"ySz7oA\",\"outboundFlightId\":\"20c0d2f2-56a3-4068-bf20-ff7703db552d\"},\"payment\":{\"receipt\":\"https://pay.stripe.com/receipts/acct_1Dvn7pF4aIiftV70/ch_3JTC14F4aIiftV700iFq2CHB/rcpt_K7QsrFln9FgFnzUuBIiNdkkRYGxUL0X\",\"amount\":100}}",
+      "attributes": {
+        "ApproximateReceiveCount": "1",
+        "SentTimestamp": "1523232000000",
+        "SenderId": "123456789012",
+        "ApproximateFirstReceiveTimestamp": "1523232000001"
+      },
+      "messageAttributes": {},
+      "md5OfBody": "7b270e59b47ff90a553787216d55d91d",
+      "eventSource": "aws:sqs",
+      "eventSourceARN": "arn:aws:sqs:us-east-1:123456789012:MyQueue",
+      "awsRegion": "us-east-1"
+    }
+  ]
+}

docs/snippets/jmespath/extractDataFromBuiltinEnvelope.ts

@@ -0,0 +1,21 @@
+import {
+  extractDataFromEnvelope,
+  SQS,
+} from '@aws-lambda-powertools/jmespath/envelopes';
+import { Logger } from '@aws-lambda-powertools/logger';
+import type { SQSEvent } from 'aws-lambda';
+
+const logger = new Logger();
+
+type MessageBody = {
+  customerId: string;
+};
+
+export const handler = async (event: SQSEvent): Promise<void> => {
+  const records = extractDataFromEnvelope<Array<MessageBody>>(event, SQS);
+  for (const record of records) {
+    // records is now a list containing the deserialized body of each message
+    const { customerId } = record;
+    logger.appendKeys({ customerId });
+  }
+};

docs/snippets/jmespath/extractDataFromEnvelope.json

@@ -0,0 +1,8 @@
+{
+  "body": "{\"customerId\":\"dd4649e6-2484-4993-acb8-0f9123103394\"}",
+  "deeplyNested": [
+    {
+      "someData": [1, 2, 3]
+    }
+  ]
+}

docs/snippets/jmespath/extractDataFromEnvelope.ts

@@ -0,0 +1,31 @@
+import { extractDataFromEnvelope } from '@aws-lambda-powertools/jmespath/envelopes';
+
+type MyEvent = {
+  body: string; // "{\"customerId\":\"dd4649e6-2484-4993-acb8-0f9123103394\"}"
+  deeplyNested: Array<{ someData: number[] }>;
+};
+
+type MessageBody = {
+  customerId: string;
+};
+
+export const handler = async (event: MyEvent): Promise<unknown> => {
+  const payload = extractDataFromEnvelope<MessageBody>(
+    event,
+    'powertools_json(body)'
+  );
+  const { customerId } = payload; // now deserialized
+
+  // also works for fetching and flattening deeply nested data
+  const someData = extractDataFromEnvelope<number[]>(
+    event,
+    'deeplyNested[*].someData[]'
+  );
+
+  return {
+    customerId,
+    message: 'success',
+    context: someData,
+    statusCode: 200,
+  };
+};

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, // (1)!
+    'powertools_base64_gzip(payload) | powertools_json(@).logGroup'
+  );
+
+  logger.info('Log group name', { logGroup }); // (2)!
+};

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 }); // (1)!
+};

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/snippets/tsconfig.json

@@ -27,7 +27,11 @@
       "@aws-lambda-powertools/idempotency/middleware": [
         "../../packages/idempotency/lib/middleware"
       ],
-      "@aws-lambda-powertools/batch": ["../../packages/batch/lib"]
+      "@aws-lambda-powertools/batch": ["../../packages/batch/lib"],
+      "@aws-lambda-powertools/jmespath": ["../../packages/jmespath/lib"],
+      "@aws-lambda-powertools/jmespath/envelopes": [
+        "../../packages/jmespath/lib/envelopes"
+      ]
     }
   }
 }