Skip to content

Releases: aws-powertools/powertools-lambda-typescript

v2.25.1

14 Aug 10:44
@github-actions github-actions
v2.25.1
1e609f1
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.
Compare
Choose a tag to compare
v2.25.1 Latest
Latest

Summary

This is a patch release that addresses an issue with the logger and the idempotency package introduced in v2.25.0 that could potentially affect users’ tests in some circumstances. This does not affect any production workloads.

Furthermore, it also fixes an issue with the tracer package which caused a deprecation warning when @tracer.captureLambdaHandler() was used.

We recommend updating to this version if you're currently using v2.25.0, especially if you're experiencing any test-related issues.

⭐ Congratulations @MaxOpperman, @BeckettFrey for their first PRs merged in the project 🎉

Changes

  • ci: bump version-n-release GitHub Action and modify input values (#4330) by @dreamorosi
  • improv(idempotency): Prevent error when AWS_LAMBDA_FUNCTION_NAME is not passed in the Idempotency Persistence Layer (#4327) by @sdangol
  • improv(logger): resolve issue when no logger region is set (#4319) by @MaxOpperman
  • improv(ci): Skip Layer version checks for the Gamma environment (#4321) by @sdangol
  • refactor: idempotency env service to functions 4246 (#4314) by @BeckettFrey
  • fix(tracer): pass args of decorated method as they are (#4312) by @dreamorosi

📜 Documentation updates

🔧 Maintenance

This release was made possible by the following contributors:

@BeckettFrey, @MaxOpperman, @dependabot[bot], @dreamorosi, @github-actions[bot], @sdangol, @svozza, dependabot[bot] and github-actions[bot]

Contributors

dreamorosi, svozza, and 4 other contributors
Assets 2
Loading

v2.25.0

12 Aug 14:31
@github-actions github-actions
v2.25.0
deab7fc
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.
Compare
Choose a tag to compare
v2.25.0

Summary

We have discontinued support for Node.js 18 with this release. All users are strongly encouraged to upgrade to Node.js 20 or later to ensure continued compatibility and security updates.

The parse function is now exported from the Parser package. This addition enables manual parsing in scenarios such as validating query string parameters, offering more flexibility in data handling and validation.

We’ve also fixed a bug with the Zod schema for the Cognito Trigger Event in the parser.

Furthermore, we have been working on the improvements in the overall code quality and maintainability of the codebase.

⭐ Congratulations @dwrth, @bdellegrazie, @jaimellamasi for their first PRs merged in the project 🎉

Parse Function

Docs

import { parse } from '@aws-lambda-powertools/parser';

export const handler = async (event: APIGatewayEvent) => {
  try {
    const querySchema = z.object({
      id: z.string()
    });
    const params = parse(event.queryStringParameters, undefined, querySchema);
  } catch(error) {
    console.error("Failed to parse the query string parameters");
  }
}

Before this release, it was only possible to use the parser through middleware or a decorator.
To use the parse function, simply pass the payload to be parsed, the envelope (if required), the schema, and the optional safe parse flag.

Changes

  • feat(event-handler): add event handler registry (#4307) by @svozza
  • feat(event-handler): add error classes for http errors (#4299) by @svozza
  • feat(parser): Exported the parse function from the parser (#4300) by @sdangol
  • feat(event-handler): implement route matching & resolution system for rest handler (#4297) by @svozza
  • refactor(idempotency): fix code quality issues (#4298) by @dwrth
  • improv(deps): Decrease the update schedule of aws-cdk and aws-sdk-v3 group in dependabot (#4290) by @sdangol
  • refactor(commons): fix code quality issues (#4292) by @dwrth
  • refactor(jmespath): fix code quality issues (#4286) by @dwrth
  • refactor(batch): improve code quality in test handlers (#4281) by @dwrth
  • refactor(logger): replace EnvironmentVariablesService class with helper functions (#4251) by @jaimellamasi
  • test(event-handler): coverage 100% for AppSync GraphQL (#4261) by @dreamorosi
  • refactor(kafka): improve tests & error handling (#4262) by @dreamorosi
  • refactor(tracer): fix code quality issues (#4264) by @dwrth
  • fix(parser): cognito schema preferredRole may be null (#4259) by @bdellegrazie
  • ci: update version-n-changelog action & input (#4258) by @dreamorosi
  • feat(event-handler): add support for AppSync GraphQL batch resolvers (#4218) by @arnabrahman

📜 Documentation updates

🔧 Maintenance

Read more

Contributors

bdellegrazie, dreamorosi, and 6 other contributors
Loading

v2.24.1

29 Jul 14:32
@github-actions github-actions
v2.24.1
fc26144
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.
Compare
Choose a tag to compare
v2.24.1

Summary

In this release we have improved runtime validations in the Metrics utility, ensuring that invalid metrics are not sent to CloudWatch and avoiding data loss.

Furthermore, we now only support Zod 4.x. Using Zod 3.x with the Parser utility will result in a build-time error.

⭐ Congratulations @JonkaSusaki and @uttam282005 for their first PRs merged in the project 🎉

Metrics Runtime Validations

Docs

Before this release, if you published invalid metrics they could fail silently, leading to data loss. Now Lambda will throw an error if the following constraints do not hold:

  • Metric Name: Validated according to CloudWatch constraints
  • Metric Value: Validated for numeric values
  • Metric Unit: Validated for allowed units
  • Metric Resolution: Validated for allowed resolutions
  • Dimension Name: Both Dimension name and value are validated for non empty, non-null values.

Changes

  • fix(metrics): revert changes when raise warning with overridden default dimensions (#4226) by @svozza
  • fix(metrics): emit warning when default dimensions are overwritten (#4222) by @uttam282005
  • refactor(event-handler): replace EnvironmentVariablesService class with helper functions in Event Handler (#4225) by @JonkaSusaki
  • ci: fix version output interpolation in make-version workflow (#4220) by @dreamorosi
  • ci: set version number correctly when versioning (#4219) by @dreamorosi
  • feat(event-handler): add route management system for ApiGw event handler (#4211) by @svozza
  • ci: update make-release.yml workflow to use latest upstream (#4215) by @dreamorosi
  • ci: remove local create-pr action (#4213) by @dreamorosi
  • improv(maintenance): Removed some unused assignments and added missing error handling (#4208) by @sdangol
  • ci: remove lerna version (#4201) by @dreamorosi
  • refactor(ci): Updated the publish command in the CI to use npm publish instead of lerna publish (#4195) by @sdangol
  • refactor(metrics): replace EnvironmentVariablesService with cached #envConfig (#4188) by @uttam282005
  • improv(metrics): Added runtime validations for the metrics utility functions (#4181) by @sdangol
  • refactor(parameters): replace EnvironmentVariablesService class with helper functions in Parameters (#4168) by @JonkaSusaki

🌟New features and non-breaking changes

📜 Documentation updates

🔧 Maintenance

This release was made possible by the following contributors:

@JonkaSusaki, @dependabot[bot], @dreamorosi, @github-actions[bot], @sdangol, @svozza, @uttam282005, dependabot[bot] and github-actions[bot]

Contributors

dreamorosi, svozza, and 4 other contributors
Loading

v2.24.0

15 Jul 17:35
@github-actions github-actions
v2.24.0
501dc17
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.
Compare
Choose a tag to compare
v2.24.0

Summary

We’ve listened to your feedback and starting from this release of Parser we support only Zod v4 for all our built-in schemas and envelopes. Additionally the utility got a power up and it now supports schemas written using Standard Schema 🔥.

We’ve also fixed a bug in Tracer that prevented requests made via proxies to be traced correctly and another bug in Metrics that caused dimension sets to be added correctly to the metrics data object..

🌟 Congratulations to @chetan9518, @sdangol, and @matteofigus for their first PRs merged in the project 🎉

Using Parser with Standard Schema

Docs

You can now use schemas written using Valibot or other Standard Schema-compatible parsing library to parse incoming events using the parser Middy.js middleware or TypeScript class method decorator. This is useful if your codebase is already relying on one of these libraries or you want to have full control over the bundle size.

Note that our built-in schemas and envelopes are still defined only using Zod. If you would like us to support other libraries like Valibot please open an issue and we will consider it based on the community's feedback.

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

import { Logger } from '@aws-lambda-powertools/logger';
import { parser } from '@aws-lambda-powertools/parser/middleware';
import middy from '@middy/core';
import {
  array,
  number,
  object,
  optional,
  pipe,
  string,
  toMinValue,
} from 'valibot';

const logger = new Logger();

const orderSchema = object({
  id: pipe(number(), toMinValue(0)),
  description: string(),
  items: array(
    object({
      id: pipe(number(), toMinValue(0)),
      quantity: pipe(number(), toMinValue(1)),
      description: string(),
    })
  ),
  optionalField: optional(string()),
});

export const handler = middy()
  .use(parser({ schema: orderSchema }))
  .handler(async (event): Promise<void> => {
    for (const item of event.items) {
      logger.info('Processing item', { item });
    }
  });

Tracing requests using a proxy

Docs

You can now correctly trace outbound requests made via proxies. Tracer will detect the CONNECT request made to the proxy and intelligently exclude it from the trace data, leaving only the segment for the main request to avoid creating noise in your traces.

import { Tracer } from "@aws-lambda-powertools/tracer";
import { getSecret } from "@aws-lambda-powertools/parameters/secrets";
import { captureLambdaHandler } from "@aws-lambda-powertools/tracer/middleware";
import middy from "@middy/core";
import { ProxyAgent } from "undici";

const tracer = new Tracer({
  serviceName: "tracerproxy",
});
const client = new ProxyAgent({
  uri: "http://proxy:8080",
  token: await getSecret('/dev/proxy-token'),
});

export const handler = middy()
  .use(captureLambdaHandler(tracer))
  .handler(async () => {
    try {
      const res = await fetch("https://foo.com", {
        dispatcher: client,
        signal: AbortSignal.timeout(2000),
      });
      console.debug("Response status:", res.status);
      if (!res.ok) {
        throw new Error(`HTTP error! status: ${res.status}`);
      }
    } catch (error) {
      console.error("Error fetching URL:", error);
      if (error instanceof HttpError) {
        return {
          statusCode: error.code,
        };
      }
      return {
        statusCode: 500,
      };
    }

    return {
      statusCode: 200,
    };
});

Adding dimension sets to metrics

Docs

You can create separate dimension sets for your metrics using the addDimensions() method. This allows you to group metrics by different dimension combinations.

Starting from this release, when you use this method, we’ll create a new dimension set rather than adding to the existing dimensions - the previous behavior was incorrect and didn’t allow you to track the same metric across different dimension combinations.

import { Metrics, MetricUnit } from '@aws-lambda-powertools/metrics';

const metrics = new Metrics({
  namespace: 'serverlessAirline',
  serviceName: 'orders',
});

export const handler = async (
  _event: unknown,
  _context: unknown
): Promise<void> => {
  // Add a single dimension
  metrics.addDimension('environment', 'prod');

  // Add a new dimension set
  metrics.addDimensions({
    dimension1: '1',
    dimension2: '2',
  });

  // Add another dimension set
  metrics.addDimensions({
    region: 'us-east-1',
    category: 'books',
  });

  // Add metrics
  metrics.addMetric('successfulBooking', MetricUnit.Count, 1);
  metrics.publishStoredMetrics();
};

Changes

  • fix(parser): Removed the nullable type from the md5OfMessageAttributes in SqsRecordSchema (#4165) by @sdangol
  • chore(parser): remove deprecated parser type (#4154) by @dreamorosi
  • refactor(metrics): optimize addDimensions method to avoid O(n²) complexity (#4156) by @dreamorosi
  • chore: fix typo in partitioned layers workflow (#4126) by @dreamorosi

🌟New features and non-breaking changes

📜 Documentation updates

🐛 Bug and hot fixes

🔧 Maintenance

  • chore: bump to 2.24.0 (#4172) by @dreamorosi
  • chore(deps): bump @types/node from 24.0.12 to 24.0.13 (#4167) by @dependabot[bot]
  • chore(deps): bump esbuild from 0.25.5 to 0.25.6 (#4166) by @dependabot[bot]
  • feat(parser): support Standard Schema and upgrade to Zod v4 (#4164) by @dreamorosi
  • chore(deps-dev): bump @redis/client from 5.5.6 to 5.6.0 (#4162) by @dependabot[bot]
  • chore(deps): bump the aws-sdk-v3 group across 1 directory with 9 updates (#4159) by @dependabot[bot]
  • chore(deps): bump vscode/devcontainers/javascript-node from 0d29e5f to eac37fb in /.devcontainer (#4161) by @dependabot[bot]
  • chore(deps-dev): bump zod from 3.25.67 to 3.25.76 (#4158) by @dependabot[bot]
  • chore(deps): bump @types/node from 24.0.10 to 24.0.12 (#4157) by @dependabot[bot]
  • refactor(tracer): replace class-based env access with functional helpers (#4146) by @chetan9518
  • chore(deps): bump aws-cdk-lib from 2.203.1 to 2.204.0 in the aws-cdk group across 1 directory (#4143) by @dependabot[bot]
  • chore(deps-dev): bump @biomejs/biome from 1.9.4 to 2.1.0 (#4147) by @dependabot[bot]
  • chore: bump biome formatter to next major & reformat (#4145) by @dreamorosi
  • chore(deps): bump the aws-cdk group across 1 directory with 2 updates (#4129) by @dependabot[bot]
  • chore(deps): bump @types/node from 24.0.8 to 24.0.10 (#4119) by @dependabot[bot]
  • chore(deps): bump the aws-cdk group across 1 directory with 3 updates (#4118) by @dependabot[bot]
  • chore(deps-dev): bump @aws-sdk/client-cloudwatch from 3.840.0 to 3.841.0 in the aws-sdk-v3 group across 1 directory (#4117) by @[dependabot[bot]](http...
Read more

Contributors

matteofigus, dreamorosi, and 3 other contributors
Loading

v2.23.0

03 Jul 18:48
@github-actions github-actions
v2.23.0
b8e6d93
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.
Compare
Choose a tag to compare
v2.23.0

Summary

We're excited to announce a new resolver for AppSync GraphQL APIs in the Event Handler utility. It simplifies routing and processing of events in AWS Lambda functions by allowing you to define resolvers for specific GraphQL types and fields.

We’ve also fixed two bugs in Logger: 1/ one causing timestamps to be incorrectly formatted when using non-UTC timezone and around midnight, and 2/ another causing temporary keys to not be properly cleared when using the injectLambdaContext() Middy.js middleware.

Finally, starting from this release we're publishing our Lambda layers in the AWS China Beijing Region operated by Sinnet.

🌟 A huge thank you to @arnabrahman for the amazing work on the AppSync GraphQL resolver 🎉

Working AppSync GraphQL APIs

Key Features

  • Route events based on GraphQL type and field keys
  • Automatically parse API arguments to function parameters
  • Handle GraphQL responses and errors in the expected format

To get started install the Event Handler utility by running:

npm install @aws-lambda-powertools/event-handler

Registering a resolver

Docs

You can register functions to match GraphQL types and fields with one of three methods:

  • onQuery() - Register a function to handle a GraphQL Query type.
  • onMutation() - Register a function to handle a GraphQL Mutation type.
  • resolver() - Register a function to handle a GraphQL type and field.

Your resolvers receive the parsed arguments from the GraphQL request as their first parameter. We will take care of parsing the response or catching errors and returning them in the expected format.

You can register a resolver for a Query type, you can use the onQuery() method. This method allows you to define a function that will be invoked when a GraphQL Query is made.

import { AppSyncGraphQLResolver } from '@aws-lambda-powertools/event-handler/appsync-graphql';
import { Logger } from '@aws-lambda-powertools/logger';
import type { Context } from 'aws-lambda';

const logger = new Logger({
  serviceName: 'TodoManager',
});
const app = new AppSyncGraphQLResolver({ logger });

app.onQuery<{ id: string }>('getTodo', async ({ id }) => {
  logger.debug('Resolving todo', { id });
  // Simulate fetching a todo from a database or external service
  return {
    id,
    title: 'Todo Title',
    completed: false,
  };
});

export const handler = async (event: unknown, context: Context) =>
  app.resolve(event, context);

Use the onMutation() method to process GraphQL mutations:.

import {
  AppSyncGraphQLResolver,
  makeId,
} from '@aws-lambda-powertools/event-handler/appsync-graphql';
import { Logger } from '@aws-lambda-powertools/logger';
import type { Context } from 'aws-lambda';

const logger = new Logger({
  serviceName: 'TodoManager',
});
const app = new AppSyncGraphQLResolver({ logger });

app.onMutation<{ title: string }>('createTodo', async ({ title }) => {
  logger.debug('Creating todo', { title });
  const todoId = makeId();
  // Simulate creating a todo in a database or external service
  return {
    id: todoId,
    title,
    completed: false,
  };
});

export const handler = async (event: unknown, context: Context) =>
  app.resolve(event, context);

When you want to have more control over the type and field, you can use the resolver() method. This method allows you to register a function for a specific GraphQL type and field including custom types.

import { AppSyncGraphQLResolver } from '@aws-lambda-powertools/event-handler/appsync-graphql';
import { Logger } from '@aws-lambda-powertools/logger';
import type { Context } from 'aws-lambda';

const logger = new Logger({
  serviceName: 'TodoManager',
});
const app = new AppSyncGraphQLResolver({ logger });

app.resolver(
  async () => {
    logger.debug('Resolving todos');
    // Simulate fetching a todo from a database or external service
    return [
      {
        id: 'todo-id',
        title: 'Todo Title',
        completed: false,
      },
      {
        id: 'todo-id-2',
        title: 'Todo Title 2',
        completed: true,
      },
    ];
  },
  {
    fieldName: 'listTodos',
    typeName: 'Query',
  }
);

export const handler = async (event: unknown, context: Context) =>
  app.resolve(event, context);

The resolver includes helper functions for working with AppSync scalar values (basic data types like String, Int, Boolean). These helpers simplify data type conversion and validation when processing GraphQL requests. To learn more check out the documentation page.

Lambda Layers in AWS China (Beijing) Region

Docs

Powertools for AWS Lambda (TypeScript) layers are now available in the AWS China Beijing Region operated by Sinnet.

Region Location ARN
cn-north-1 Beijing arn:aws-aws-cn:lambda:cn-north-1:498634801083:layer:AWSLambdaPowertoolsTypeScriptV2:30

You can use the AWS CLI to inspect the contents of the layer and read its metadata:

aws lambda get-layer-version-by-arn --arn arn:aws-aws-cn:lambda:cn-north-1:498634801083:layer:AWSLambdaPowertoolsTypeScriptV2:30 --region cn-north-1

Changes

📜 Documentation updates

🔧 Maintenance

  • chore(deps): bump @types/node from 24.0.8 to 24.0.10 (#4119) by @dependabot[bot]
  • chore(deps): bump the aws-cdk group across 1 directory with 3 updates (#4118) by @dependabot[bot]
  • chore(deps-dev): bump @aws-sdk/client-cloudwatch from 3.840.0 to 3.841.0 in the aws-sdk-v3 group across 1 directory (#4117) by @dependabot[bot]
  • docs(event-handler): add AppSync GraphQL docs page (#4120) by @dreamorosi
  • feat(event-handler): support onQuery and onMutation handlers (#4111) by @dreamorosi
  • chore(deps): bump @types/node from 24.0.7 to 24.0.8 (#4107) by @dependabot[bot]
  • chore(deps): bump the aws-sdk-v3 group across 1 directory with 9 updates (#4106) by @dependabot[bot]
  • chore(deps): bump mkdocs-material from 9.6.14 to 9.6.15 in /docs (#4104) by @dependabot[bot]
  • chore(deps): bump squidfunk/mkdocs-material from eb04b60 to 0bfdba4 in /docs (#4105) by @dependabot[bot]
  • chore(deps): bump the aws-cdk group across 1 directory with 2 updates (#4108) by @dependabot[bot]
  • chore(deps): bump @types/node from 24.0.4 to 24.0.7 (#4099) by @dependabot[bot]
  • chore(deps-dev): bump typedoc from 0.28.5 to 0.28.6 in the typescript group across 1 directory (#4090) by @dependabot[bot]
  • chore(deps): bump the aws-sdk-v3 group across 1 directory with 9 updates (#4098) by @dependabot[bot]
  • chore(deps): bump github/codeql-action from 3.29.0 to ...
Read more

Contributors

sthulb, leandrodamascena, and 2 other contributors
Loading

v2.22.0

20 Jun 17:43
@github-actions github-actions
v2.22.0
7f8619f
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.
Compare
Choose a tag to compare
v2.22.0

Summary

We're excited to announce the Kafka Consumer utility, which transparently handles message deserialization, provides an intuitive developer experience, and integrates seamlessly with the rest of the Powertools for AWS Lambda ecosystem.

Key features

  • Automatic deserialization of Kafka messages (JSON, Avro, and Protocol Buffers)
  • Simplified event record handling with intuitive interface
  • Support for key and value deserialization
  • Support for Standard Schema output parsing (e.g., Zod, Valibot, ArkType)
  • Support for Event Source Mapping (ESM) with and without Schema Registry integration
  • Out of the box error handling for deserialization issues

Getting Started

To get started, depending on the schema types you want to use, install the library and the corresponding libraries:

  • JSON schemas npm install @aws-lambda-powertools/kafka
  • Avro schemas npm install @aws-lambda-powertools/kafka avro-js
  • Protocol Buffer schemas npm install @aws-lambda-powertools/kafka protobufjs

Additionally, if you want to use output parsing with Standard Schema, you can install any of the supported libraries, for example: Zod, Valibot, or ArkType.

Processing Kafka events

Docs

You can use Kafka consumer utility to transform raw Kafka events into an intuitive format for processing.

The kafkaConsumer function can deserialize both keys and values independently based on your schema configuration. This flexibility allows you to work with different data formats in the same message.

Working with Avro:

carbon-4

Working with Protocol Buffers:

carbon-4

Working with JSON messages

carbon-5

Additional parsing

Docs

You can parse deserialized data using your preferred parsing library. This can help you integrate Kafka data with your domain schemas and application architecture, providing type hints, runtime parsing and validation, and advanced data transformations.

The example below uses Zod to create schemas, but you can use any Standard Schema-compatible library:

carbon-4

Error handling

Docs

You can handle errors when processing Kafka messages to ensure your application maintains resilience and provides clear diagnostic information.

We lazily decode fields like value, key, and headers only when accessed. This allows you to handle deserialization errors at the point of access rather than when the record is first processed.

carbon-5

To learn more about the launch, read the blog post published alongside the release.

🐛 Bug and hot fixes

  • fix(event-handler): fix decorated scope in appsync events (#3974) by @dreamorosi

Changes

🌟New features and non-breaking changes

  • feat(layers): add parameterised layer deployment and verification (#4033) by @sthulb

📜 Documentation updates

🔧 Maintenance

Read more

Contributors

sthulb, am29d, and dreamorosi
Loading

v2.21.0

03 Jun 15:03
@github-actions github-actions
v2.21.0
d3e4184
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.
Compare
Choose a tag to compare
v2.21.0

Summary

This release introduces a new BedrockAgentFunctionResolver to Event Handler that simplifies connecting AWS Lambda functions to Amazon Bedrock Agents. This feature eliminates the need to write boilerplate code for parsing requests and formatting responses, allowing you to focus on your agent's business logic.

⭐ A big thank you to @VatsalGoel3 and @svozza for their contributions to this release and to Instil for becoming a public customer reference!

Creating Amazon Bedrock Agents

Docs

You can now use the new BedrockAgentFunctionResolver to register tools and handle requests in your Lambda functions. The resolver will automatically parse the request, route it to the appropriate function, and return a well-formed response that includes the tool's output and any existing session attributes.

carbon

By default, errors are handled gracefully and returned to the agent with error type and message information, allowing the conversation to continue. This is useful when you want to let the LLM handle errors and reduce boilerplate error-handling code.

If you need more control over error scenarios, you can use BedrockFunctionResponse to customize the response and determine if the conversation should continue:

carbon

You can also use the BedrockFunctionResponse when you want to enrich the response with session attributes or knowledge base configurations, or when you want the agent to re-prompt the user to provide additional information.

carbon-2

Changes

🌟New features and non-breaking changes

  • feat(event-handler): add Amazon Bedrock Agents Functions Resolver (#3957) by @svozza
  • feat(commons): environment variable helpers (#3945) by @dreamorosi

📜 Documentation updates

🐛 Bug and hot fixes

  • fix(parameters): preserve original stack trace on transform failures … (#3982) by @VatsalGoel3

🔧 Maintenance

This release was made possible by the following contributors:

@VatsalGoel3, @dreamorosi, @hjgraca, and @svozza

Contributors

hjgraca, dreamorosi, and 2 other contributors
Loading

v2.20.0

20 May 08:35
@github-actions github-actions
v2.20.0
23aa1d9
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.
Compare
Choose a tag to compare
v2.20.0

Summary

This release enhances Idempotency to support Valkey- and Redis OSS-compatible databases as a persistence layer. We’ve also added new schemas for AppSync Events APIs and updated existing ones for Amazon DynamoDB and Amazon Kinesis streams.

⭐ A big thank you to @arnabrahman for working on the Idempotency feature, and @kiitosu for their contributions!

Using cache databases with Idempotency

Docs

You can now use Valkey- and Redis OSS-compatible databases as a persistence layer for your applications with the Idempotency utility. This allows you to leverage managed services like ElastiCache Serverless, which can scale to hundreds of millions of operations per second with microsecond latency.

To get started, install the latest version of Idempotency along with a cache client:

npm i @aws-lambda-powertools/idempotency @valkey/valkey-glide

Configure the client and pass it to the new CachePersistenceLayer class:

carbon-4

Pass the new persistence layer to any of the Idempotency methods, for example:

carbon-4

If you are currently using Idempotency with Amazon DynamoDB, you can use the new CachePersistenceLayer as a drop-in replacement in your functions.

New and Improved Parser Schemas

Docs

We’ve added two new schemas for AppSync Events APIs and updated two existing ones for Amazon DynamoDB and Amazon Kinesis streams:

Schema Name Description
🆕 AppSyncEventsPublishSchema New schema to parse PUBLISH operation
🆕 AppSyncEventsSubscribeSchema New schema to parse SUBSCRIBE operation
DynamoDBStreamSchema Added window, state, isFinalInvokeForWindow, isWindowTerminatedEarly, and eventSourceArn fields
KinesisDataStreamSchema Added window, state, isFinalInvokeForWindow, isWindowTerminatedEarly, and eventSourceArn fields

Changes

🌟New features and non-breaking changes

  • feat(parser): add support for tumbling windows in Kinesis and DynamoDB events (#3931) by @kiitosu
  • feat(idempotency): support for Redis as idempotency backend (#3896) by @arnabrahman
  • feat(parser): add schemas for AppSync Events (#3907) by @dreamorosi

🌟 Minor Changes

  • refactor(event-handler): mark identity field as unknown in event (#3922) by @dreamorosi

📜 Documentation updates

🔧 Maintenance

Read more

Contributors

kiitosu, dreamorosi, and arnabrahman
Loading

v2.19.1

06 May 10:39
@github-actions github-actions
v2.19.1
2f5704c
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.
Compare
Choose a tag to compare
v2.19.1

Summary

In this release we’ve enhanced Logger to format error stack traces for easier reading in non-production environments.

We also fixed a bug in the Event Handler AppSyncEventResolver that caused subscription events to be rejected incorrectly. The fix requires no changes on your part besides updating to the latest version.

⭐ A big thank you to Ours Privacy for becoming a public customer reference, and @ConnorKirk for their contributions!

Changes

Pretty print stack trace in dev mode

Docs

You can now pretty print error stack traces when dev mode is enabled via the POWERTOOLS_DEV environment variable. This makes it easier to troubleshoot issues during development.

carbon-4

🌟 Minor Changes

  • improv(logger): Format the stack trace as an array of strings in dev mode (#3852) by @ConnorKirk

📜 Documentation updates

🐛 Bug and hot fixes

  • fix(event-handler): ignore return type from onSubscribe handler (#3888) by @dreamorosi

🔧 Maintenance

This release was made possible by the following contributors:

@ConnorKirk and @dreamorosi

Contributors

dreamorosi and ConnorKirk
Loading

v2.19.0

24 Apr 21:29
@github-actions github-actions
v2.19.0
53f0e40
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.
Compare
Choose a tag to compare
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.

carbon

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:

carbon-2

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.

carbon-3

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

🌟New features and non-breaking changes

📜 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]

Contributors

jorovipe97, dreamorosi, and 2 other contributors
Loading