Added docs for parser integration with batch processing

sdangol · sdangol · commit d7879b9b94a0 · 2025-09-05T14:19:46.000+01:00
diff --git a/docs/features/batch.md b/docs/features/batch.md
diff --git a/examples/snippets/batch/parser-integration/dynamoDBExtended.ts b/examples/snippets/batch/parser-integration/dynamoDBExtended.ts
@@ -0,0 +1,40 @@
+import {
+  BatchProcessor,
+  EventType,
+  processPartialResponse,
+} from '@aws-lambda-powertools/batch';
+import { DynamoDBMarshalled } from '@aws-lambda-powertools/parser/helpers/dynamodb';
+import {
+  DynamoDBStreamChangeRecordBase,
+  DynamoDBStreamRecord,
+} from '@aws-lambda-powertools/parser/schemas/dynamodb';
+import type { DynamoDBRecord, DynamoDBStreamHandler } from 'aws-lambda';
+import { z } from 'zod';
+
+const customSchema = DynamoDBStreamRecord.extend({
+  dynamodb: DynamoDBStreamChangeRecordBase.extend({
+    NewImage: DynamoDBMarshalled(
+      z.object({
+        name: z.string(),
+        age: z.number(),
+      })
+    ),
+  }),
+});
+
+const processor = new BatchProcessor(EventType.DynamoDBStreams, {
+  schema: customSchema,
+});
+
+const recordHandler = async ({
+  dynamodb: {
+    NewImage: { name, age },
+  },
+}: z.infer<typeof customSchema>) => {
+  // this is safe to use because it's parsed
+};
+
+export const handler: DynamoDBStreamHandler = async (event, context) =>
+  processPartialResponse(event, recordHandler, processor, {
+    context,
+  });
diff --git a/examples/snippets/batch/parser-integration/dynamoDBWithTransformer.ts b/examples/snippets/batch/parser-integration/dynamoDBWithTransformer.ts
@@ -0,0 +1,34 @@
+import {
+  BatchProcessor,
+  EventType,
+  processPartialResponse,
+} from '@aws-lambda-powertools/batch';
+import { DynamoDBMarshalled } from '@aws-lambda-powertools/parser/helpers/dynamodb';
+import type { DynamoDBRecord, DynamoDBStreamHandler } from 'aws-lambda';
+import { z } from 'zod';
+
+const customSchema = DynamoDBMarshalled(
+  z.object({
+    name: z.string(),
+    age: z.number(),
+  })
+);
+
+const processor = new BatchProcessor(EventType.DynamoDBStreams, {
+  schema: customSchema,
+});
+
+const recordHandler = async ({
+  dynamodb: {
+    NewImage: { name, age },
+  },
+}: DynamoDBRecord & {
+  dynamodb: { NewImage: z.infer<typeof customSchema> };
+}) => {
+  // this is safe to use because it's parsed
+};
+
+export const handler: DynamoDBStreamHandler = async (event, context) =>
+  processPartialResponse(event, recordHandler, processor, {
+    context,
+  });
diff --git a/examples/snippets/batch/parser-integration/dynamoDBWithoutTransformer.ts b/examples/snippets/batch/parser-integration/dynamoDBWithoutTransformer.ts
@@ -0,0 +1,31 @@
+import {
+  BatchProcessor,
+  EventType,
+  processPartialResponse,
+} from '@aws-lambda-powertools/batch';
+import type { DynamoDBRecord, DynamoDBStreamHandler } from 'aws-lambda';
+import { z } from 'zod';
+
+const customSchema = z.object({
+  name: z.string(),
+  age: z.number(),
+});
+
+const processor = new BatchProcessor(EventType.DynamoDBStreams, {
+  schema: customSchema,
+});
+
+const recordHandler = async ({
+  dynamodb: {
+    NewImage: { name, age },
+  },
+}: DynamoDBRecord & {
+  dynamodb: { NewImage: z.infer<typeof customSchema> };
+}) => {
+  // this is safe to use because it's parsed
+};
+
+export const handler: DynamoDBStreamHandler = async (event, context) =>
+  processPartialResponse(event, recordHandler, processor, {
+    context,
+  });
diff --git a/examples/snippets/batch/parser-integration/kinesisExtended.ts b/examples/snippets/batch/parser-integration/kinesisExtended.ts
@@ -0,0 +1,40 @@
+import {
+  BatchProcessor,
+  EventType,
+  processPartialResponse,
+} from '@aws-lambda-powertools/batch';
+import { Base64Encoded } from '@aws-lambda-powertools/parser/helpers';
+import {
+  KinesisDataStreamRecord,
+  KinesisDataStreamRecordPayload,
+} from '@aws-lambda-powertools/parser/schemas/kinesis';
+import type { KinesisStreamHandler, KinesisStreamRecord } from 'aws-lambda';
+import { z } from 'zod';
+
+const customSchema = KinesisDataStreamRecord.extend({
+  kinesis: KinesisDataStreamRecordPayload.extend({
+    data: Base64Encoded(
+      z.object({
+        name: z.string(),
+        age: z.number(),
+      })
+    ),
+  }),
+});
+
+const processor = new BatchProcessor(EventType.KinesisDataStreams, {
+  schema: customSchema,
+});
+
+const recordHandler = async ({
+  kinesis: {
+    data: { name, age },
+  },
+}: z.infer<typeof customSchema>) => {
+  // this is safe to use because it's parsed
+};
+
+export const handler: KinesisStreamHandler = async (event, context) =>
+  processPartialResponse(event, recordHandler, processor, {
+    context,
+  });
diff --git a/examples/snippets/batch/parser-integration/kinesisWithTransformer.ts b/examples/snippets/batch/parser-integration/kinesisWithTransformer.ts
@@ -0,0 +1,34 @@
+import {
+  BatchProcessor,
+  EventType,
+  processPartialResponse,
+} from '@aws-lambda-powertools/batch';
+import { Base64Encoded } from '@aws-lambda-powertools/parser/helpers';
+import type { KinesisStreamHandler, KinesisStreamRecord } from 'aws-lambda';
+import { z } from 'zod';
+
+const customSchema = Base64Encoded(
+  z.object({
+    name: z.string(),
+    age: z.number(),
+  })
+);
+
+const processor = new BatchProcessor(EventType.KinesisDataStreams, {
+  schema: customSchema,
+});
+
+const recordHandler = async ({
+  kinesis: {
+    data: { name, age },
+  },
+}: KinesisStreamRecord & {
+  kinesis: { data: z.infer<typeof customSchema> };
+}) => {
+  // this is safe to use because it's parsed
+};
+
+export const handler: KinesisStreamHandler = async (event, context) =>
+  processPartialResponse(event, recordHandler, processor, {
+    context,
+  });
diff --git a/examples/snippets/batch/parser-integration/kinesisWithoutTransformer.ts b/examples/snippets/batch/parser-integration/kinesisWithoutTransformer.ts
@@ -0,0 +1,31 @@
+import {
+  BatchProcessor,
+  EventType,
+  processPartialResponse,
+} from '@aws-lambda-powertools/batch';
+import type { KinesisStreamHandler, KinesisStreamRecord } from 'aws-lambda';
+import { z } from 'zod';
+
+const customSchema = z.object({
+  name: z.string(),
+  age: z.number(),
+});
+
+const processor = new BatchProcessor(EventType.KinesisDataStreams, {
+  schema: customSchema,
+});
+
+const recordHandler = async ({
+  kinesis: {
+    data: { name, age },
+  },
+}: KinesisStreamRecord & {
+  kinesis: { data: z.infer<typeof customSchema> };
+}) => {
+  // this is safe to use because it's parsed
+};
+
+export const handler: KinesisStreamHandler = async (event, context) =>
+  processPartialResponse(event, recordHandler, processor, {
+    context,
+  });
diff --git a/examples/snippets/batch/parser-integration/sqsExtended.ts b/examples/snippets/batch/parser-integration/sqsExtended.ts
@@ -0,0 +1,31 @@
+import {
+  BatchProcessor,
+  EventType,
+  processPartialResponse,
+} from '@aws-lambda-powertools/batch';
+import { JSONStringified } from '@aws-lambda-powertools/parser/helpers';
+import { SqsRecordSchema } from '@aws-lambda-powertools/parser/schemas';
+import type { SQSHandler, SQSRecord } from 'aws-lambda';
+import { z } from 'zod';
+
+const customSchema = SqsRecordSchema.extend({
+  body: JSONStringified(
+    z.object({
+      name: z.string(),
+      age: z.number(),
+    })
+  ),
+});
+
+const processor = new BatchProcessor(EventType.SQS, { schema: customSchema });
+
+const recordHandler = async ({
+  body: { name, age },
+}: z.infer<typeof customSchema>) => {
+  // this is safe to use because it's parsed
+};
+
+export const handler: SQSHandler = async (event, context) =>
+  processPartialResponse(event, recordHandler, processor, {
+    context,
+  });
diff --git a/examples/snippets/batch/parser-integration/sqsWithTransformer.ts b/examples/snippets/batch/parser-integration/sqsWithTransformer.ts
@@ -0,0 +1,28 @@
+import {
+  BatchProcessor,
+  EventType,
+  processPartialResponse,
+} from '@aws-lambda-powertools/batch';
+import { JSONStringified } from '@aws-lambda-powertools/parser/helpers';
+import type { SQSHandler, SQSRecord } from 'aws-lambda';
+import { z } from 'zod';
+
+const customSchema = JSONStringified(
+  z.object({
+    name: z.string(),
+    age: z.number(),
+  })
+);
+
+const processor = new BatchProcessor(EventType.SQS, { schema: customSchema });
+
+const recordHandler = async ({
+  body: { name, age },
+}: SQSRecord & { body: z.infer<typeof customSchema> }) => {
+  // this is safe to use because it's parsed
+};
+
+export const handler: SQSHandler = async (event, context) =>
+  processPartialResponse(event, recordHandler, processor, {
+    context,
+  });
diff --git a/examples/snippets/batch/parser-integration/sqsWithoutTransformer.ts b/examples/snippets/batch/parser-integration/sqsWithoutTransformer.ts
@@ -0,0 +1,25 @@
+import {
+  BatchProcessor,
+  EventType,
+  processPartialResponse,
+} from '@aws-lambda-powertools/batch';
+import type { SQSHandler, SQSRecord } from 'aws-lambda';
+import { z } from 'zod';
+
+const customSchema = z.object({
+  name: z.string(),
+  age: z.number(),
+});
+
+const processor = new BatchProcessor(EventType.SQS, { schema: customSchema });
+
+const recordHandler = async ({
+  body: { name, age },
+}: SQSRecord & { body: z.infer<typeof customSchema> }) => {
+  // this is safe to use because it's parsed
+};
+
+export const handler: SQSHandler = async (event, context) =>
+  processPartialResponse(event, recordHandler, processor, {
+    context,
+  });
diff --git a/examples/snippets/batch/samples/sampleDynamoDBStreamsEventForParser.json b/examples/snippets/batch/samples/sampleDynamoDBStreamsEventForParser.json
@@ -0,0 +1,56 @@
+{
+  "Records": [
+    {
+      "eventID": "1",
+      "eventVersion": "1.0",
+      "dynamodb": {
+        "Keys": {
+          "Id": {
+            "N": "101"
+          }
+        },
+        "NewImage": {
+          "name": {
+            "S": "test-1"
+          },
+          "age": {
+            "N": 20
+          }
+        },
+        "StreamViewType": "NEW_AND_OLD_IMAGES",
+        "SequenceNumber": "3275880929",
+        "SizeBytes": 26
+      },
+      "awsRegion": "us-west-2",
+      "eventName": "INSERT",
+      "eventSourceARN": "eventsource_arn",
+      "eventSource": "aws:dynamodb"
+    },
+    {
+      "eventID": "1",
+      "eventVersion": "1.0",
+      "dynamodb": {
+        "Keys": {
+          "Id": {
+            "N": "101"
+          }
+        },
+        "NewImage": {
+          "name": {
+            "S": "test-2"
+          },
+          "age": {
+            "N": 30
+          }
+        },
+        "StreamViewType": "NEW_AND_OLD_IMAGES",
+        "SequenceNumber": "8640712661",
+        "SizeBytes": 26
+      },
+      "awsRegion": "us-west-2",
+      "eventName": "INSERT",
+      "eventSourceARN": "eventsource_arn",
+      "eventSource": "aws:dynamodb"
+    }
+  ]
+}
diff --git a/examples/snippets/batch/samples/sampleKinesisEventForParser.json b/examples/snippets/batch/samples/sampleKinesisEventForParser.json
@@ -0,0 +1,36 @@
+{
+  "Records": [
+    {
+      "kinesis": {
+        "kinesisSchemaVersion": "1.0",
+        "partitionKey": "1",
+        "sequenceNumber": "4107859083838847772757075850904226111829882106684065",
+        "data": "eyJuYW1lIjoidGVzdC0xIiwiYWdlIjoyMH0=",
+        "approximateArrivalTimestamp": 1545084650.987
+      },
+      "eventSource": "aws:kinesis",
+      "eventVersion": "1.0",
+      "eventID": "shardId-000000000006:4107859083838847772757075850904226111829882106684065",
+      "eventName": "aws:kinesis:record",
+      "invokeIdentityArn": "arn:aws:iam::123456789012:role/lambda-role",
+      "awsRegion": "us-east-2",
+      "eventSourceARN": "arn:aws:kinesis:us-east-2:123456789012:stream/lambda-stream"
+    },
+    {
+      "kinesis": {
+        "kinesisSchemaVersion": "1.0",
+        "partitionKey": "1",
+        "sequenceNumber": "6006958808509702859251049540584488075644979031228738",
+        "data": "eyJuYW1lIjoidGVzdC0yIiwiYWdlIjozMH0=",
+        "approximateArrivalTimestamp": 1545084650.987
+      },
+      "eventSource": "aws:kinesis",
+      "eventVersion": "1.0",
+      "eventID": "shardId-000000000006:6006958808509702859251049540584488075644979031228738",
+      "eventName": "aws:kinesis:record",
+      "invokeIdentityArn": "arn:aws:iam::123456789012:role/lambda-role",
+      "awsRegion": "us-east-2",
+      "eventSourceARN": "arn:aws:kinesis:us-east-2:123456789012:stream/lambda-stream"
+    }
+  ]
+}
diff --git a/examples/snippets/batch/samples/sampleSQSEventForParser.json b/examples/snippets/batch/samples/sampleSQSEventForParser.json
