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

Author: dreamorosi

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 });
+};