Bug: DynamoDBStreamSchema can't be extended properly

[blytheaw]

Expected Behavior

I should be able to extend the Zod schema DynamoDBStreamSchema and appropriately access values at Records[*].dynamodb after parsing and in inferred types.

This should work when using the new-ish DynamoDBMarshalled helper which removes the need for the built-in transform that is breaking this currently.

Current Behavior

If you extend DynamoDBStreamSchema as in this example, any other values/types from the DynamoDBStreamChangeRecord (i.e. Records[*].dynamodb.*) are lost.

Ideally the DynamoDBStreamChangeRecord could be extended as well, but because this schema currently has a Zod transform in it, it cannot be extended.

Code snippet

See Discord thread: https://discord.com/channels/1006478942305263677/1006527385409179678/1350204854148010048

Steps to Reproduce

See Discord thread: https://discord.com/channels/1006478942305263677/1006527385409179678/1350204854148010048

Possible Solution

Export a base schema for DynamoDBStream that doesn't have a transform as part of it so it can be extended

Powertools for AWS Lambda (TypeScript) version

latest

AWS Lambda function runtime

22.x

Packaging format used

npm

Execution logs

[dreamorosi]

Hi @blytheaw, thank you for reporting this on Discord and taking the time to open an issue.

I tried a sample code like this:

import { Logger } from "@aws-lambda-powertools/logger";
import { DynamoDBMarshalled } from "@aws-lambda-powertools/parser/helpers/dynamodb";
import {
	DynamoDBStreamRecord,
	DynamoDBStreamSchema,
} from "@aws-lambda-powertools/parser/schemas/dynamodb";
import { z } from "zod";

const logger = new Logger({ logLevel: "debug" });

const customSchema = z.object({
	id: z.string(),
});

const extendedSchema = DynamoDBStreamSchema.extend({
	Records: z.array(
		DynamoDBStreamRecord.extend({
			dynamodb: z.object({
				NewImage: DynamoDBMarshalled(customSchema),
			}),
		}),
	),
});

export const handler = async (event: unknown) => {
	logger.debug("event", { event });
	logger.debug("parsed", { parsed: extendedSchema.safeParse(event).data });
};

that outputs these logs:

{
  "level": "DEBUG",
  "message": "event",
  "timestamp": "2025-03-19T11:24:54.468Z",
  "service": "service_undefined",
  "sampling_rate": 0,
  "xray_trace_id": "1-67daa986-6d12de7ba0444d00eb00bf18",
  "event": {
      "Records": [
          {
              "eventID": "b8e6d30883a579b10278fe9f46b310e0",
              "eventName": "INSERT",
              "eventVersion": "1.1",
              "eventSource": "aws:dynamodb",
              "awsRegion": "eu-west-1",
              "dynamodb": {
                  "ApproximateCreationDateTime": 1742383494,
                  "Keys": {
                      "id": {
                          "S": "adadsad"
                      }
                  },
                  "NewImage": {
                      "id": {
                          "S": "adadsad"
                      }
                  },
                  "SequenceNumber": "100000000119433541593",
                  "SizeBytes": 18,
                  "StreamViewType": "NEW_IMAGE"
              },
              "eventSourceARN": "arn:aws:dynamodb:eu-west-1:123456789012:table/ddbstream-aamorosi-SomeTableTable-vbmbeuhw/stream/2025-03-19T11:19:41.987"
          }
        ]
    }
}
{
    "level": "DEBUG",
    "message": "parsed",
    "timestamp": "2025-03-19T11:24:54.476Z",
    "service": "service_undefined",
    "sampling_rate": 0,
    "xray_trace_id": "1-67daa986-6d12de7ba0444d00eb00bf18",
    "parsed": {
        "Records": [
            {
                "eventID": "b8e6d30883a579b10278fe9f46b310e0",
                "eventName": "INSERT",
                "eventVersion": "1.1",
                "eventSource": "aws:dynamodb",
                "awsRegion": "eu-west-1",
                "eventSourceARN": "arn:aws:dynamodb:eu-west-1:123456789012:table/ddbstream-aamorosi-SomeTableTable-vbmbeuhw/stream/2025-03-19T11:19:41.987",
                "dynamodb": {
                    "NewImage": {
                        "id": "adadsad"
                    }
                }
            }
        ]
    }
}

and I can confirm that indeed, using the example in our docs makes the other fields under Records.[*].dynamodb disappear.

I will open a PR to create/export the schema you suggested. I also have noticed another minor issue with the /helpers/dynamodb export, which is missing type hints here, and can cause TypeScript issues under certain configurations.

[github-actions]

⚠️ COMMENT VISIBILITY WARNING ⚠️

This issue is now closed. Please be mindful that future comments are hard for our team to see.

If you need more assistance, please either tag a team member or open a new issue that references this one.

If you wish to keep having a conversation with other community members under this issue feel free to do so.