doc: DynamoDBMarshalled function description in user doc

Author: arnabrahman

docs/utilities/parser.md

@@ -151,6 +151,21 @@ If you want to extend a schema and transform a JSON stringified payload to an ob
     --8<-- "examples/snippets/parser/samples/exampleSqsPayload.json"
     ```
 
+### DynamoDB Stream event parsing
+
+If you want to parse a DynamoDB stream event with unmarshalling, you can use the helper function `DynamoDBMarshalled`:
+
+=== "DynamoDBStreamSchema with DynamoDBMarshalled"
+    ```typescript hl_lines="17"
+    --8<-- "examples/snippets/parser/extendDynamoDBStreamSchema.ts"
+    ```
+
+=== "DynamoDBStream event payload"
+
+    ```json hl_lines="13-20 49-56"
+    --8<-- "examples/snippets/parser/samples/exampleDynamoDBStreamPayload.json"
+    ```
+
 ## Envelopes
 
 When trying to parse your payload you might encounter the following situations:

examples/snippets/parser/extendDynamoDBStreamSchema.ts

@@ -0,0 +1,23 @@
+import { DynamoDBMarshalled } from '@aws-lambda-powertools/parser/helpers/dynamodb';
+import {
+  DynamoDBStreamRecord,
+  DynamoDBStreamSchema,
+} from '@aws-lambda-powertools/parser/schemas/dynamodb';
+import { z } from 'zod';
+
+const customSchema = z.object({
+  id: z.string(),
+  message: z.string(),
+});
+
+const extendedSchema = DynamoDBStreamSchema.extend({
+  Records: z.array(
+    DynamoDBStreamRecord.extend({
+      dynamodb: z.object({
+        NewImage: DynamoDBMarshalled(customSchema).optional(),
+      }),
+    })
+  ),
+});
+
+type ExtendedDynamoDBStreamEvent = z.infer<typeof extendedSchema>;

examples/snippets/parser/samples/exampleDynamoDBStreamPayload.json

@@ -0,0 +1,66 @@
+{
+    "Records": [
+      {
+        "eventID": "1",
+        "eventVersion": "1.0",
+        "dynamodb": {
+          "ApproximateCreationDateTime": 1693997155.0,
+          "Keys": {
+            "Id": {
+              "N": "101"
+            }
+          },
+          "NewImage": {
+            "Message": {
+              "S": "New item!"
+            },
+            "Id": {
+              "N": "101"
+            }
+          },
+          "StreamViewType": "NEW_AND_OLD_IMAGES",
+          "SequenceNumber": "111",
+          "SizeBytes": 26
+        },
+        "awsRegion": "us-west-2",
+        "eventName": "INSERT",
+        "eventSourceARN": "eventsource_arn",
+        "eventSource": "aws:dynamodb"
+      },
+      {
+        "eventID": "2",
+        "eventVersion": "1.0",
+        "dynamodb": {
+          "OldImage": {
+            "Message": {
+              "S": "New item!"
+            },
+            "Id": {
+              "N": "101"
+            }
+          },
+          "SequenceNumber": "222",
+          "Keys": {
+            "Id": {
+              "N": "101"
+            }
+          },
+          "SizeBytes": 59,
+          "NewImage": {
+            "Message": {
+              "S": "This item has changed"
+            },
+            "Id": {
+              "N": "101"
+            }
+          },
+          "StreamViewType": "NEW_AND_OLD_IMAGES"
+        },
+        "awsRegion": "us-west-2",
+        "eventName": "MODIFY",
+        "eventSourceARN": "source_arn",
+        "eventSource": "aws:dynamodb"
+      }
+    ]
+  }
+  

packages/parser/src/helpers/dynamodb.ts

@@ -20,6 +20,7 @@ import { type ZodTypeAny, z } from 'zod';
  *     })
  *   ),
  * });
+ * type eventSchema = z.infer<typeof extendedSchema>;
  * ```
  * For example, if you have a DynamoDB stream event like the following:
  *