Skip to content

Releases: aws-powertools/powertools-lambda-typescript

v2.26.1

15 Sep 12:44
@github-actions github-actions
v2.26.1
0855525
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.26.1 Latest
Latest

Summary

This patch release addresses a regression with the Batch Processing utility introduced in v2.26.0 that caused a bundling error due to an internal dependency not being declared in the package.json.

This bug affects only those who are using Batch Processing without other Powertools for AWS utilities and who have already upgraded to v2.26.0 which was released on 12/09/2025.

We recommend updating to the latest version to avoid the issue.

⭐ Congratulations to @Grmiade for identifying this issue and fixing it with their first PR merged in the project 🎉

Changes

  • chore(ci): update layer ARN on documentation (#4471) by @sdangol

📜 Documentation updates

  • chore(ci): update layer ARN on documentation (#4488) by @sdangol
  • chore(deps): bump the aws-cdk group across 1 directory with 3 updates (#4443) by @dependabot[bot]
  • docs(batch): added documentation for the parser integration feature in batch processor (#4435) by @sdangol

🔧 Maintenance

This release was made possible by the following contributors:

@Grmiade, @dependabot[bot], @github-actions[bot], @sdangol, dependabot[bot] and github-actions[bot]

Contributors

Grmiade, sdangol, and dependabot
Assets 2
Loading

v2.26.0

12 Sep 11:26
@github-actions github-actions
v2.26.0
ddb52e3
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.26.0

Summary

We're excited to announce support for API Gateway REST APIs in the Event Handler utility. This simplifies routing and processing of events in AWS Lambda functions by allowing you to define specific handlers that corresponds to routes in your REST APIs with minimal boilerplate code.

We have also integrated the Parser utility with Batch Processing, enabling automatic validation of payloads from SQS, Kinesis and DynamoDB streams.

Furthermore, we have added support for custom error handlers to the AppSync GraphQL event handler resolver, with automatic marshalling of errors to the expected AppSync format and logging built-in.

⭐ Congratulations @dcabib for their first PR merged in the project and to @arnabrahman for their continued contributions to AppSync event handler 🎉

Working with API Gateway REST APIs

Key Features

  • Lightweight routing to reduce boilerplate code for API Gateway REST APIs
  • Built-in middleware engine for executing custom logic when processing requests and responses
  • Supports micro function (one or a few routes) and monolithic functions (all routes)

To get started install the Event Handler utility by running:

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

Docs

Registering a route

You can register routes to match HTTP verbs and specific paths. Each HTTP verb corresponds to a method on the REST handler Router class and the path is the first argument of that method

When a request is received, the event handler will automatically convert the event into a Request object and give you access to the current request context, including this request object, the raw event, a Response object, and the lambda context.

import { Router } from '@aws-lambda-powertools/event-handler/experimental-rest';
import type { Context, APIGatewayProxyEvent } from 'aws-lambda';

const app = new Router();

app.get('/ping', async (_, {request: Request, res: Response, context: Context, event: APIGatewayProxyEvent}) => {
  return { message: 'pong' };
});

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

We also support dynamic routes in the format path/:identifer, where the :identifier will be extracted as a named parameter and passed to your route handler.

import { Router } from '@aws-lambda-powertools/event-handler/experimental-rest';
import type { Context } from 'aws-lambda/handler';

const logger = new Logger({});

const app = new Router({ logger });

app.get('/todos/:todoId', async ({ todoId }) => {
  const todo = await getTodoById(todoId);
  return { todo };
});

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

Autoserialization

For your convenience, when you return a JavaScript object from your route handler, we automatically return an appropriate API Gateway response object by doing the following:

  • Auto-serialize the response to JSON and trim whitespace
  • Include the response under the appropriate equivalent of a body
  • Set the Content-Type header to application/json
  • Set the HTTP status code to 200 (OK)
import { Router } from '@aws-lambda-powertools/event-handler/experimental-rest';
import type { Context } from 'aws-lambda/handler';

const logger = new Logger({});

const app = new Router({ logger });

app.get('/todos/:todoId', async ({ todoId }) => {
  const todo = await getTodoById(todoId);
  return { todo };
});

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

/**
This returns:

{
  statusCode: 200,
  headers: {
    'Content-Type': 'application/json'
  },
  body: '{"todo\":"an-id"}',
  isBase64Encoded": false
}
**/

Error Handling

You can use errorHandler function to gracefully handle exceptions. This works by passing an error constructor and an error handler function to the error registration method,

Event handler comes with a number of error classes such as BadRequest, InternalServerError and so on. Using these will ensure the correct HTTP code is returned. You can also extend the base error class to create your custom errors.

import { Router, BadRequestError } from '@aws-lambda-powertools/event-handler/experimental-rest';
import type { Context } from 'aws-lambda/handler';

const logger = new Logger({});

const app = new Router({ logger });

app.errorHandler(BadRequestError, async (error: BadRequestError) => {
  return {
    error: 'Validation Error',
    message: `Error: ${error.message}`,
  }
});

app.get('/todos/:todoId', async ({ todoId }) => {
  if(todoId == null) throw BadRequestError('todoId cannot be null');
  const todo = await getTodoById(todoId);
  return { todo };
});

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

/**
This returns:

{
  statusCode: 400,
  headers: {
    'Content-Type': 'application/json'
  },
  body: '{"error":"Validation Error","message":"Error: todoId cannot be null"}'
  isBase64Encoded": false
}
**/

Note that unhandled errors will be caught in the Router and converted to an HTTP 500 error response.

Decorators

You can also use decorators for registering route and error handlers.

import { Router } from '@aws-lambda-powertools/event-handler/experimental-rest';
import { Logger } from '@aws-lambda-powertools/logger';
import type { Context } from 'aws-lambda/handler';

const logger = new Logger({});
const app = new Router({ logger });

class Lambda {
  @app.errorHandler(BadRequestError)
  public async handleBadRequest(error: BadRequestError) {
    return {
      error: 'Validation Error',
      message: `Error: ${error.message}`,
    };
  } 
   
  @app.get('/todos/:todoId')
  public async getTodos({ todoId }: { todoId: string }) {
    const todo = await getTodoById(todoId);
    return { todo };
  }

  public async handler(event: unknown, context: Context) {
    return app.resolve(event, context, { scope: this });
  }
}

const lambda = new Lambda();
export const handler = lambda.handler.bind(lambda);

Middleware

Use middleware when you need to run custom logic before or after your route handler executes. Every middleware is simply a function that receives the following arguments:

  • params Route parameters extracted from the URL path
  • reqCtx Request context containing the event, Lambda context, request, and response objects
  • next A function to pass control to the next middleware in the chain

Middleware can be applied on specific routes, globally on all routes, or a combination of both.

Middleware execution follows an onion pattern where global middleware runs first in pre-processing, then route-specific middleware. After the handler executes, the order reverses for post-processing.

import { Router } from '@aws-lambda-powertools/event-handler/experimental-rest';
import type { Middleware } from '@aws-lambda-powertools/event-handler/types';
import type { Context } from 'aws-lambda';

const app = new Router();

// Global middleware - executes first in pre-processing, last in post-processing
app.use(async (params, reqCtx, next) => {
  reqCtx.res.headers.set('x-pre-processed-by', 'global-middleware');
  await next();
  reqCtx.res.headers.set('x-post-processed-by', 'global-middleware');
});

// Route-specific middleware - executes second in pre-processing, first in post-processing
const routeMiddleware: Middleware = async (params, reqCtx, next) => {
  // ...
};

app.get('/todos', async () => {
  const todos = await getAllTodos();
  return { todos };
});

// route specific middleware
app.post('/todos', [routeMiddleware], async (params, reqCtx) => {
  // ...
});

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

Parser Integration with Batch Processing

The Batch Processing utility now supports integration with the Parser utility, enabling automatic validation and transformation of batch records before processing. You can use built in transformers: json , base64 , and unmarshall to transform your schemas into common data formats. It is compatible with SQS, Kinesis Data Streams and DynamDB Streams. You can either use a complete schema or even just an inner schema for the parsing.

Example

import {
  BatchProcessor,
  EventType,
  processPartialResponse,
} from '@aws-lambda-powertools/batch';
import { parser } from '@aws-lambda-powertools/batch/parser';
import type { SQSHandler, SQSRecord } from 'aws-lambda';
import { z } from 'zod';

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

const processor = new BatchProcessor(EventType.SQS, {
  parser,
  innerSchema: customSchema,
  transformer: 'json',
});

const recordHandler = async ({
  body: { name, age },
}: SQSRecord & { body: z.infer<typeof customSchema> }) => {
  // this is safe to use because it's parsed
};

export const handler: SQSHandler = async (event, context) =>
  processPartialResponse(event, recordHandler, processor, {
    context,
  });

Error Handling with AppSync GraphQL

We've also added error handling capabilities to the AppSync GraphQL resolver. You can register your custom error handlers for specific error classes using app.exceptionHandler(ErrorClass, handler) . All errors are automatically formatted for AppSync compatibility and include logging for better observability, making it easier to build GraphQL APIs with proper error ...

Read more

Contributors

svozza, arnabrahman, and 3 other contributors
Loading

v2.25.2

26 Aug 18:31
@github-actions github-actions
v2.25.2
90c1ed3
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.2

Summary

In this release, the setDefaultDimensions method in the Metrics utility now emits a warning if an existing default dimension is over-written, making it consistent with addDimension and addDimensions methods:

⭐ Congratulations to @kawaaaa, and @shrivarshapoojari for their first PRs merged in the project 🎉

Changes

  • improv(ci): Inherited the secrets for update ssm workflow (#4388) by @sdangol
  • feat(event-handler): add resolution logic to base router (#4349) by @svozza
  • improv(ci): Fixed the Make Release workflow permission issue (#4385) by @sdangol
  • chore(commons): concatenate PT UA to AWS_SDK_UA_APP_ID when one is set (#4374) by @dreamorosi
  • improv(ci): Moved the secrets expanded in the run block to env variables (#4370) by @sdangol
  • improv(ci): removed the secret inheritance and replaced with the needed secrets (#4364) by @sdangol
  • improv(ci): Added comments in workflow files triggering Excessive Secret Exposure Alert (#4367) by @sdangol
  • improv(ci): Automate the layer version tracking during the Make Release workflow (#4355) by @sdangol
  • refactor(logger): use vitest env helpers in unit tests (#4360) by @dwrth
  • chore(parameters): fix SonarQube code quality issues and optimize imports (#4359) by @shrivarshapoojari
  • refactor(logger): mark private members as readonly and fix code quality issues (#4350) by @kawaaaas
  • ci: switch e2e env in run-e2e-tests workflow (#4347) by @dreamorosi
  • improv(metrics): emit warning when default dimensions are overwritten (#4287) by @uttam282005
  • improv: decorate methods without destructuring args (#4345) by @dreamorosi
  • feat(event-handler): add function to convert Lambda proxy event to web response object (#4343) by @svozza
  • fix(event-handler): pass event, context and request objects into handler (#4329) by @svozza
  • ci: add Kiro & other LLM fodlers to gitignore (#4333) by @dreamorosi

📜 Documentation updates

🔧 Maintenance

This release was made possible by the following contributors:

@dependabot[bot], @dreamorosi, @dwrth, @github-actions[bot], @kawaaaas, @sdangol, @shrivarshapoojari, @svozza, @uttam282005, dependabot[bot] and github-actions[bot]

Contributors

dreamorosi, svozza, and 7 other contributors
Loading

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

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