v2.19.0

Summary

We are excited to announce a new integration for Event Handler to work with AWS AppSync Events APIs. This utility provides a structured way to handle AppSync real-time events through dedicated handler methods, automatic routing, and flexible configuration options.

We have also improved the experience for customers who are using the log buffering feature in Logger with AWS Lambda’s Advanced Logging Controls (ALC) enabled by emitting a log when the ALC log level is less verbose than the log level in the buffering configuration, which prevents data loss.

⭐ A big thank you to @jorovipe97 and @ConnorKirk for their contributions to this release!

New Event Handler for AppSync Events

Docs

The new AppSyncEventsResolver is designed to streamline working with AWS AppSync real-time APIs by:

• Handling publish and subscribe events with dedicated handler methods
• Routing events automatically based on namespace and channel patterns
• Supporting wildcard patterns for catch-all handlers
• Controlling event aggregation for batch processing
• Implementing graceful error handling

Handling publish events

You can register handlers for publish events using the onPublish method and specifying a pattern for the namespace and channels. This is useful when you want to modify payload content, persist the message in a database, or apply business logic and conditionally filter messages out.

Handling subscribe events

You can use the onSubscribe() method to process subscription requests before allowing clients to connect to specific channels. This enables authorization checks and subscription filtering based on client context or payload attributes, as well as subscription tracking, for example:

Working with aggregated processing

You can use the aggregate parameter when registering an onPublish handler to process multiple events together as a batch. This is useful when you need to optimize database operations, or want to have full control over how the messages are processed.

AppSyncEventsResolver FAQs

Q: Can I handle different types of events from the same channel?
A: Yes, you can register different handlers for publish and subscribe events on the same channel.
Q: How does handler precedence work with wildcard patterns?
A: More specific patterns take precedence over wildcards. For example, /default/channel1 will be chosen over /default/, which will be chosen over /.
Q: What happens when an exception occurs in my handler?
A: With individual processing (aka aggregate disabled), the utility catches exceptions and includes them in the response for the specific event while still processing other events. You can also explicitly raise an UnauthorizedException exception to reject the entire request.
Q: Does the order of async event processing matter?
A: No, AppSync Events doesn't guarantee delivery order. As long as each response includes the original event ID, AppSync processes them correctly regardless of order. Because of this, when aggregate is disabled, we call your handlers all at once.
Q: Can I process multiple events as a batch?
A: Yes, enable aggregate when registering an onPublish handler to receive all matching events as a batch. When doing so, you're responsible implementing the logic to process them and return a list of corresponding items.

Changes

• chore: update cdk output dir (#3854) by @dreamorosi

🌟New features and non-breaking changes

• feat(event-handler): AppSync Events resolver (#3858) by @dreamorosi

📜 Documentation updates

• feat(event-handler): AppSync Events resolver (#3858) by @dreamorosi
• docs: Update metrics docs to mention correct POWERTOOLS_METRICS_DISABLED variable name. (#3848) by @jorovipe97
• chore(deps): bump the aws-cdk group across 1 directory with 3 updates (#3838) by @dependabot[bot]
• chore(deps): bump squidfunk/mkdocs-material from sha256:23b69789b1dd836c53ea25b32f62ef8e1a23366037acd07c90959a219fd1f285 to sha256:95f2ff42251979c043d6cb5b1c82e6ae8189e57e02105813dd1ce124021a418b in /docs (#3840) by @dependabot[bot]
• chore(deps): bump mkdocs-material from 9.6.11 to 9.6.12 in /docs (#3842) by @dependabot[bot]
• chore(deps): bump @aws-sdk/lib-dynamodb from 3.788.0 to 3.789.0 in the aws-sdk-v3 group across 1 directory (#3835) by @dependabot[bot]
• docs: fix copy-me button (#3836) by @dreamorosi
• docs: add getting started section (#3818) by @dreamorosi
• chore(deps): bump the aws-cdk group across 1 directory with 2 updates (#3833) by @dependabot[bot]
• chore(deps): bump @types/node from 22.14.0 to 22.14.1 (#3831) by @dependabot[bot]
• chore(deps): bump the aws-sdk-v3 group across 1 directory with 9 updates (#3826) by @dependabot[bot]
• chore(deps): bump @types/aws-lambda from 8.10.148 to 8.10.149 (#3824) by @dependabot[bot]
• chore(deps): bump aws-cdk-lib from 2.188.0 to 2.189.0 (#3820) by @dependabot[bot]
• chore(deps): bump the typescript group across 1 directory with 2 updates (#3810) by @dependabot[bot]

🐛 Bug and hot fixes

• fix(parser): Make Kafka key property optional (#3855) by @ConnorKirk
• fix(logger): warn customers when the ALC log level is less verbose than log buffer (#3834) by @ConnorKirk
• fix(logger): warn only once on ALC log level mismatch (#3816) by @dreamorosi

🔧 Maintenance

• feat(event-handler): AppSync Events resolver (#3858) by @dreamorosi
• chore(deps-dev): bump typedoc from 0.28.2 to 0.28.3 in the typescript group across 1 directory (#3844) by @dependabot[bot]
• chore(deps-dev): bump the vitest group across 1 directory with 2 updates (#3845) by @dependabot[bot]
• chore(deps-dev): bump zod from 3.24.2 to 3.24.3 (#3839) by @dependabot[bot]
• chore(deps): bump the aws-cdk group across 1 directory with 3 updates (#3838) by @dependabot[bot]
• chore(deps): bump squidfunk/mkdocs-material from sha256:23b69789b1dd836c53ea25b32f62ef8e1a23366037acd07c90959a219fd1f285 to sha256:95f2ff42251979c043d6cb5b1c82e6ae8189e57e02105813dd1ce124021a418b in /docs (#3840) by @dependabot[bot]
• chore(deps): bump mkdocs-material from 9.6.11 to 9.6.12 in /docs (#3842) by @dependabot[bot]
• chore(deps): bump @aws-sdk/lib-dynamodb from 3.788.0 to 3.789.0 in the aws-sdk-v3 group across 1 directory (#3835) by @dependabot[bot]
• chore(deps): bump the aws-cdk group across 1 directory with 2 updates (#3833) by @dependabot[bot]
• chore(deps-dev): bump typedoc-plugin-zod from 1.4.0 to 1.4.1 in the typescript group across 1 directory (#3829) by @dependabot[bot]
• chore(deps-dev): bump lint-staged from 15.5.0 to 15.5.1 (#3830) by @dependabot[bot]
• chore(deps): bump @types/node from 22.14.0 to 22.14.1 (#3831) by @dependabot[bot]
• chore(deps): bump actions/setup-node from 4.3.0 to 4.4.0 (#3828) by @dependabot[bot]
• chore(deps): bump github/codeql-action from 3.28.14 to 3.28.15 (#3817) by @dependabot[bot]
• chore(deps): bump the aws-sdk-v3 group across 1 directory with 9 updates (#3826) by @dependabot[bot]
• chore(deps): bump @types/aws-lambda from 8.10.148 to 8.10.149 (#3824) by @dependabot[bot]
• chore(deps): bump vite from 6.2.5 to 6.2.6 (#3827) by @dependabot[bot]
• chore(deps): bump aws-cdk-lib from 2.188.0 to 2.189.0 (#3820) by @dependabot[bot]
• chore(deps): bump vscode/devcontainers/javascript-node from be11ae6 to ee45bc4 in /.devcontainer (#3819) by @dependabot[bot]
• chore(deps): bump the typescript group across 1 directory with 2 updates (#3810) by @dependabot[bot]
• chore(deps): bump github/codeql-action from 3.28.13 to 3.28.14 (#3811) by @dependabot[bot]
• chore(deps): bump vscode/devcontainers/javascript-node from 78fda8c to be11ae6 in /.devcontainer (#3812) by @dependabot[bot]

This release was made possible by the following contributors:

@ConnorKirk, @dependabot[bot], @dreamorosi, @github-actions[bot], @jorovipe97, dependabot[bot] and github-actions[bot]