Bug: Zod 3 support listed by parser package

[ben-eb]

Expected Behavior

parser library should not list Zod 3 as a compatible peer:

powertools-lambda-typescript/packages/parser/package.json

Line 208 in 7757cf0

"zod": "^3.25.0 || ^4.0.0"

Current Behavior

Zod 3 is listed as a compatible peer dependency, but it is not (as envelopes now use Zod 4 exclusive functions)

Code snippet

Not specific to any code sample, the problem is in the version range specified by package.json

Steps to Reproduce

• Install Zod 3 and parser dependency;
• Try to use a schema and note the type incompatibilities. I noticed this when using types for SNS;

Possible Solution

Remove Zod 3 from peer version range

Powertools for AWS Lambda (TypeScript) version

latest

AWS Lambda function runtime

22.x

Packaging format used

npm

Execution logs

[boring-cyborg]

Thanks for opening your first issue here! We'll come back to you as soon as we can.
In the meantime, check out the #typescript channel on our Powertools for AWS Lambda Discord: Invite link

[ben-eb]

Additionally, the website documents Zod 3 compatibility - https://docs.powertools.aws.dev/lambda/typescript/latest/utilities/parser/#getting-started

[dreamorosi]

Hi @ben-eb, thanks for opening this issue.

The project lists peer dependencies according to Zod's own best practices described here and here:

Regarding the docs, unsure how/why that URL works, but the page you're looking for should be this (notice end of the URL): https://docs.powertools.aws.dev/lambda/typescript/latest/features/parser/

Will investigate why that page works, as it's outdated and shouldn't be published.

[ben-eb]

I think Zod's own documentation is correct here, but 2.24.0 breaks compatibility. Here is a minimal reproduction:

import { SnsSchema } from "@aws-lambda-powertools/parser/schemas/sns";
import { z } from "zod";

const schema = z.object({
  operation: z.enum(["create", "update"]),
});

function parse(event: unknown) {
  const parsedEvent = SnsSchema.parse(event);

  return parsedEvent.Records.map((record) => {
    return {
      // @ts-ignore Below line errors using latest parser library
      message: schema.parse(JSON.parse(record.Sns.Message)),
      attributes: record.Sns.MessageAttributes,
    };
  });
}

const event = {
  Records: [
    {
      EventVersion: "1.0",
      EventSubscriptionArn: "arn:aws:sns:EXAMPLE",
      EventSource: "aws:sns",
      Sns: {
        SignatureVersion: "1",
        Timestamp: "1970-01-01T00:00:00.000Z",
        Signature: "EXAMPLE",
        SigningCertUrl: "https://www.example.com",
        MessageId: "95df01b4-ee98-5cb9-9903-4c221d41eb5e",
        Message: JSON.stringify({ operation: "create" }),
        MessageAttributes: {
          Test: {
            Type: "String",
            Value: "TestString",
          },
          TestBinary: {
            Type: "Binary",
            Value: "TestBinary",
          },
        },
        Type: "Notification",
        UnsubscribeUrl: "https://www.example.com",
        TopicArn: "arn:aws:sns:EXAMPLE",
        Subject: "TestInvoke",
      },
    },
  ],
};

console.log(parse(event));

Output:

◎ tsc && node dist/index.js
file:///Users/me/projects/powertools-issue/node_modules/@aws-lambda-powertools/parser/lib/esm/schemas/sns.js:12
    UnsubscribeUrl: z.url(),
                      ^

TypeError: z.url is not a function
    at file:///Users/me/projects/powertools-issue/node_modules/@aws-lambda-powertools/parser/lib/esm/schemas/sns.js:12:23
    at ModuleJob.run (node:internal/modules/esm/module_job:271:25)
    at async onImport.tracePromise.__proto__ (node:internal/modules/esm/loader:547:26)
    at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:116:5)

Node.js v22.13.0

Whereas in 2.23.0 we get the following output:

[
  {
    message: { operation: 'create' },
    attributes: { Test: [Object], TestBinary: [Object] }
  }
]

[dreamorosi]

I understand this might've caused friction on your side. Yes, 2.24.0 introduces a non-backwards compatible - this is in line with our 3P dependency versioning policy published here.

Prior to making the change we had a request for comment issue open for over a month (here) where we asked for feedback on how to proceed in regards to this migration. Everyone who engaged was supportive of moving straight to v4.

Once we made the release last week, we also called this out in the release notes, mentioning this:

If you are using Zod v3 and need more time to migrate, you can continue using Parser v2.23.0 as long as needed.

With this in mind, I think you have 2 options:

• don't upgrade Zod to 3.25.0 and stay on Parser 2.23.0
• upgrade Zod to >3.24.0 and upgrade Parser to 2.24.0