feat(parser): add schema envelopes

[am29d]

Description of your changes

This PR introduces schema envelopes for popular events based and mirrors python coverage from Powertools python.

After initial class based implementation I reverted to functional implementation which simplifies the code and makes DX a bit cleaner. Here is an example how to use the envelopes:

import { z } from 'zod';
import { SQSEvent, Context } from 'aws-lambda';
import { sqsEnvelope } from '@aws-lambda-powertools/parser/envelopes/sqs';

const customSchema = z.object({
  name: z.string(),
  age: z.number().min(18).max(99),
});


export const handler = async (event: SQSEvent, context: Context) => {
  const message = sqsEnvelope(event, customSchema);
  // { name: 'Paul', age: 42 }
  // use parsed message for business logic
};

I have added zod-faker package to generate test events based on the test schema. This will also allow us to generate test events for the built-in schemas.

In addition, I had to rewrite the test event loader from utils to have a simpler usage with autocomplete.

The schema is types should be compatible the aws-lambda types package, but I'd like to create a dedicated issue for that to ensure there they match and that we have a mechanism to find and fix deviations in the future.

• API GW
• API GW v2
• CloudWatch
• DynamoDB
• EventBridge
• Kafka
• Kinesis
• Kinesis Firehose
• SNS
• SQS
• VPC lattice
• VPC lattice v2

Related issues, RFCs

Issue number: closes #1791

Checklist

• My changes meet the tenets criteria
• I have performed a self-review of my own code
• I have commented my code where necessary, particularly in areas that should be flagged with a TODO, or hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my change is effective and works
• The PR title follows the conventional commit semantics

Breaking change checklist

Is it a breaking change?: NO

• I have documented the migration process
• I have added, implemented necessary warnings (if it can live side by side)

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[sonarcloud]

Quality Gate passed

Kudos, no new issues were introduced!

0 New issues
0 Security Hotspots
No data about Coverage
0.0% Duplication on New Code

See analysis details on SonarCloud

[dreamorosi]

Thank you for the work on this PR, and sorry for the slow review.

My only comment, which I don't want to block the PR on, is that we could throw a custom error when parsing the body within the envelope rather than a generic Error.

I think that would make it easier to narrow down the exception handling similar to what we do in other utilities. However we can address this in a future PR if you prefer.