add examples to the parser docs for JSONStringified

Author: am29d

docs/core/event-handler/api-gateway.md

@@ -40,13 +40,13 @@ This is the sample infrastructure for API Gateway and Lambda Function URLs we ar
 === "API Gateway SAM Template"
 
     ```yaml title="AWS Serverless Application Model (SAM) example"
-    --8<-- "examples/snippets/event-handler/rest/templates/template.yaml"
+[//]: # (    --8<-- "examples/snippets/event-handler/rest/templates/template.yaml")
     ```
 
 === "Lambda Function URL SAM Template"
 
     ```yaml title="AWS Serverless Application Model (SAM) example"
-    --8<-- "examples/event_handler_lambda_function_url/sam/template.yaml"
+[//]: # (    --8<-- "examples/event_handler_lambda_function_url/sam/template.yaml")
     ```
 
 <!-- remove line below while editing this doc & put it back until the doc has reached its first draft -->

docs/utilities/parser.md

@@ -109,6 +109,34 @@ You can extend every built-in schema to include your own schema, and yet have al
     --8<-- "examples/snippets/parser/examplePayload.json"
     ```
 
+If you want to extend a schema and transform a JSON stringified payload to an object, you can use helper function `JSONStringified`:
+
+=== "AlbSchema with JSONStringified"
+    ```typescript hl_lines="12"
+    --8<-- "examples/snippets/parser/extendAlbSchema.ts"
+    ```
+
+    1. Extend built-in `AlbSchema` using JSONStringified function to transform your payload
+
+=== "Alb exmaple payload"
+
+    ```json hl_lines="26"
+    --8<-- "examples/snippets/parser/exampleAlbPayload.json"
+    ```
+
+=== "SQS Schema with JSONStringified"
+    ```typescript hl_lines="23-25 30 34"
+    --8<-- "examples/snippets/parser/extendSqsSchema.ts"
+    ```
+
+    1. make sure to set your schema to the correct key in the JSON payload
+
+=== "SQS exmaple payload"
+
+    ```json hl_lines="6 28"
+    --8<-- "examples/snippets/parser/exampleSqsPayload.json"
+    ```
+
 ## Envelopes
 
 When trying to parse your payload you might encounter the following situations:

examples/snippets/parser/exampleAlbPayload.json

@@ -0,0 +1,28 @@
+{
+  "requestContext": {
+    "elb": {
+      "targetGroupArn": "arn:aws:elasticloadbalancing:us-east-2:123456789012:targetgroup/lambda-279XGJDqGZ5rsrHC2Fjr/49e9d65c45c6791a"
+    }
+  },
+  "httpMethod": "GET",
+  "path": "/lambda",
+  "queryStringParameters": {
+    "query": "1234ABCD"
+  },
+  "headers": {
+    "accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
+    "accept-encoding": "gzip",
+    "accept-language": "en-US,en;q=0.9",
+    "connection": "keep-alive",
+    "host": "lambda-alb-123578498.us-east-2.elb.amazonaws.com",
+    "upgrade-insecure-requests": "1",
+    "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36",
+    "x-amzn-trace-id": "Root=1-5c536348-3d683b8b04734faae651f476",
+    "x-forwarded-for": "72.12.164.125",
+    "x-forwarded-port": "80",
+    "x-forwarded-proto": "http",
+    "x-imforwards": "20"
+  },
+  "body": "{\"name\":\"Walter\", \"age\": 50}",
+  "isBase64Encoded": false
+}

examples/snippets/parser/exampleSqsPayload.json

@@ -0,0 +1,43 @@
+{
+  "Records": [
+    {
+      "messageId": "059f36b4-87a3-44ab-83d2-661975830a7d",
+      "receiptHandle": "AQEBwJnKyrHigUMZj6rYigCgxlaS3SLy0a...",
+      "body": "{\"name\": \"John Doe\", \"age\": 30}",
+      "attributes": {
+        "ApproximateReceiveCount": "1",
+        "SentTimestamp": "1545082649183",
+        "SenderId": "AIDAIENQZJOLO23YVJ4VO",
+        "ApproximateFirstReceiveTimestamp": "1545082649185"
+      },
+      "messageAttributes": {
+        "testAttr": {
+          "stringValue": "100",
+          "binaryValue": "base64Str",
+          "dataType": "Number"
+        }
+      },
+      "md5OfBody": "e4e68fb7bd0e697a0ae8f1bb342846b3",
+      "eventSource": "aws:sqs",
+      "eventSourceARN": "arn:aws:sqs:us-east-2:123456789012:my-queue",
+      "awsRegion": "us-east-2"
+    },
+    {
+      "messageId": "2e1424d4-f796-459a-8184-9c92662be6da",
+      "receiptHandle": "AQEBzWwaftRI0KuVm4tP+/7q1rGgNqicHq...",
+      "body": "{\"name\": \"foo\", \"age\": 10}",
+      "attributes": {
+        "ApproximateReceiveCount": "1",
+        "SentTimestamp": "1545082650636",
+        "SenderId": "AIDAIENQZJOLO23YVJ4VO",
+        "ApproximateFirstReceiveTimestamp": "1545082650649",
+        "DeadLetterQueueSourceArn": "arn:aws:sqs:us-east-2:123456789012:my-queue-dead"
+      },
+      "messageAttributes": {},
+      "md5OfBody": "e4e68fb7bd0e697a0ae8f1bb342846b3",
+      "eventSource": "aws:sqs",
+      "eventSourceARN": "arn:aws:sqs:us-east-2:123456789012:my-queue",
+      "awsRegion": "us-east-2"
+    }
+  ]
+}

examples/snippets/parser/extendAlbSchema.ts

@@ -0,0 +1,12 @@
+import { JSONStringified } from '@aws-lambda-powertools/parser/helpers';
+import { AlbSchema } from '@aws-lambda-powertools/parser/schemas';
+import { z } from 'zod';
+
+const customSchema = z.object({
+  name: z.string(),
+  age: z.number(),
+});
+
+const extendedSchema = AlbSchema.extend({
+  body: JSONStringified(customSchema), // (1)!
+});

examples/snippets/parser/extendSqsSchema.ts

@@ -0,0 +1,19 @@
+import { JSONStringified } from '@aws-lambda-powertools/parser/helpers';
+import {
+  SqsRecordSchema,
+  SqsSchema,
+} from '@aws-lambda-powertools/parser/schemas';
+import { z } from 'zod';
+
+const customSchema = z.object({
+  name: z.string(),
+  age: z.number(),
+});
+
+const extendedSchema = SqsSchema.extend({
+  Records: z.array(
+    SqsRecordSchema.extend({
+      body: JSONStringified(customSchema), // (1)!
+    })
+  ),
+});