Skip to content

Releases: aws-powertools/powertools-lambda-typescript

v2.3.0

27 Jun 15:10
@github-actions github-actions
v2.3.0
b1cd636
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.3.0

Summary

This release improves Logger with (1) a more consistent handling of additional keys, and (2) a new method to reset keys. It also brings improvements to Parser with (1) more accurate API Gateway built-in schemas, and (2) better API reference.

We also fixed a bug with log sampling in Logger, and with the Idempotency decorator not preserving class scope.

🌟 ⭐ Thank you to @shdq for the work on the Logger improvements.

Working with additional keys in Logger

Docs

We have streamlined the experience for adding, removing, and resetting additional keys in Logger.

Temporary keys

Docs

You can add temporary keys to all future log messages via the appendKeys() method. This is helpful to contextualize log messages emitted within a specific function.

logger-append-keys

We have also added a new resetKeys() method to easily remove any temporary keys you have added, this is useful when you add multiple custom keys conditionally or when you emit canonical or wide logs.

logger-reset-keys

Persistent keys

Docs

You can now also persist keys across Lambda invocations by using the persistentKeys constructor option or the appendPersistentKeys() method.

These keys will now persist even if you call the resetKeys() method.

A common use case is to set keys about your environment or application version, so that you can easily filter logs in CloudWatch Logs.

logger-persistent-keys

The following properties and methods are now marked as deprecated and will be removed in the next major release:

  • persistentLogAttributes constructor option is replaced by persistentKeys
  • addPersistentLogAttributes() and setPersistentLogAttributes() methods are replaced by appendPersistentKeys()
  • removePersistentLogAttributes() method is replaced by removePersistentKeys()

New API Gateway built-in schemas in Parser

Docs

You can now use more accurate schemas for a fine grained validation and parsing, as well as improved type hinting, and code completion support.

API Gateway REST APIs:

  • [New] APIGatewayRequestAuthorizerEventSchema for request parameter-based Lambda authorizer (REQUEST authorizer)
  • [New] APIGatewayTokenAuthorizerEventSchema for token-based Lambda authorizer (TOKEN authorizer)
  • [Updated] APIGatewayProxyEventSchema for Lambda proxy integration

API Gateway HTTP APIs:

  • [New] APIGatewayRequestAuthorizerEventV2Schema for Lambda authorizer
  • [Updated] APIGatewayProxyEventV2Schema for Lambda proxy integration

parser-new-schemas

Improved API reference docs for Parser

Docs

You can now get details on built-in schemas and envelopes both within our online documentation (i.e. APIGatewayProxyEventSchema) and by hovering definitions without leaving your IDE.

Screenshot 2024-06-27 at 16 43 41

Changes

  • chore(deps): bump zgosalvez/github-actions-ensure-sha-pinned-actions from 3.0.7 to 3.0.9 (#2664) by @dependabot
  • chore(deps): bump github/codeql-action from 3.25.9 to 3.25.10 (#2656) by @dependabot
  • chore(deps): bump actions/checkout from 4.1.6 to 4.1.7 (#2650) by @dependabot
  • chore(deps): bump github/codeql-action from 3.25.8 to 3.25.9 (#2651) by @dependabot

🌟New features and non-breaking changes

📜 Documentation updates

🐛 Bug and hot fixes

🔧 Maintenance

This release was made possible by the following contributors:

@am29d, @dreamorosi, and @shdq

Contributors

shdq, am29d, and 2 other contributors
Loading

v2.2.0

13 Jun 14:10
@github-actions github-actions
v2.2.0
b35f9f1
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.2.0

Summary

This release improves 1/ Idempotency now handles payloads with out-of-order keys and functions with no return value, and 2/ Batch Processing can optionally continue processing messages with different group IDs for SQS FIFO queues.

🌟 ⭐ Special thanks to our contributors @daschaa and @arnabrahman - thank you for your work on this release!

Idempotency

Docs

Deep sort payload

⚠️ Previously processed transactions with out-of-order keys might lose idempotency guarantees

We now sort payloads before creating an idempotency key. Before, we were serializing them with the keys in the order they were provided.

In use cases where the client can send out-of-order payloads like REST APIs, browser clients, and proxies this could have caused the request to not be idempotent.

For example, the following two payloads would have resulted in two different hashes before this release:

carbon-3

Make functions idempotent with no return value

You can now make your function idempotent even if it returns no value. This is useful when your want to trigger AWS Step Functions workflow, or fire-and-forget other services or APIs. Before, Idempotency required an explicit return value and would have failed if not provided.

carbon-2

Batch Processing

Skip processing failed group id messages of SQS FIFO queues on error

Docs

You have now a new flag skipGroupOnError to return the messages from a failed group ID back to SQS and continue processing messages from subsequent group IDs. Previously, Batch stopped processing upon any failure regardless of the message group ID.

carbon-4

Parser (beta)

Docs

Fix sourceIp validation for APIGatewayProxyEvent for Management Console

APIGatewayProxyEvent is now compatible with the test payload from Amazon API Gateway Console. When testing an endpoint from the AWS Console, API Gateway sends a mock source IP value, test-invoke-source-ip, causing the validation to fail. The Parser utility now includes an override to handle this edge case.

Changes

  • test(idempotency): fix integration tests (#2622) by @dreamorosi
  • chore(deps): bump zgosalvez/github-actions-ensure-sha-pinned-actions from 3.0.6 to 3.0.7 (#2628) by @dependabot
  • chore(deps): bump actions/dependency-review-action from 4.3.2 to 4.3.3 (#2614) by @dependabot
  • chore(deps): bump github/codeql-action from 3.25.7 to 3.25.8 (#2610) by @dependabot
  • chore(deps): bump zgosalvez/github-actions-ensure-sha-pinned-actions from 3.0.5 to 3.0.6 (#2599) by @dependabot
  • chore(deps): bump github/codeql-action from 3.25.6 to 3.25.7 (#2593) by @dependabot
  • chore(idempotency): expiration timestamp rounded to the nearest second (#2574) by @arnabrahman
  • chore(deps): bump github/codeql-action from 3.25.5 to 3.25.6 (#2565) by @dependabot
  • chore(deps): bump actions/checkout from 4.1.5 to 4.1.6 (#2548) by @dependabot
  • chore(ci): Adopt multi directory config for dependabot (#2532) by @daschaa
  • chore(parameters): Use AppConfig L2 constructs for integration tests (#2524) by @daschaa

🌟New features and non-breaking changes

  • feat(batch): add option to continue processing other group IDs on failure in SqsFifoPartialProcessor (#2590) by @arnabrahman
  • fix(idempotency): deep sort payload during hashing (#2570) by @arnabrahman

🌟 Minor Changes

📜 Documentation updates

  • chore(deps): bump the aws-sdk group across 1 directory with 9 updates (#2644) by @dependabot
  • docs(tracer): add ESM instructions to tracer usage docs (#2630) by @dreamorosi
  • chore(deps): bump the aws-cdk group across 1 directory with 2 updates (#2626) by @dependabot
  • chore(deps): bump the aws-sdk group across 1 directory with 9 updates (#2619) by @dependabot
  • chore(deps-dev): bump tsx from 4.13.2 to 4.15.1 (#2629) by @dependabot
  • chore(deps): bump squidfunk/mkdocs-material from 8a87f05 to 96abcbb in /docs (#2615) by @dependabot
  • chore(deps-dev): bump tsx from 4.12.0 to 4.13.2 (#2620) by @dependabot
  • chore(deps-dev): bump tsx from 4.11.2 to 4.12.0 (#2612) by @dependabot
  • chore(deps): bump mkdocs-material from 9.5.25 to 9.5.26 in /docs (#2616) by @dependabot
  • chore(deps): bump @types/node from 20.14.1 to 20.14.2 (#2608) by @dependabot
  • chore(deps): bump the aws-sdk group across 1 directory with 9 updates (#2606) by @dependabot
  • chore(deps): bump @types/node from 20.14.0 to 20.14.1 (#2603) by @dependabot
  • feat(batch): add option to continue processing other group IDs on failure in SqsFifoPartialProcessor (#2590) by @arnabrahman
  • chore(deps): bump @types/node from 20.12.13 to 20.14.0 (#2601) by @dependabot
  • chore(deps): bump the aws-sdk group across 1 directory with 11 updates (#2598) by @dependabot
  • chore(deps): bump the aws-sdk group across 1 directory with 9 updates (#2591) by @dependabot
  • chore(deps): bump @types/node from 20.12.12 to 20.12.13 (#2595) by @dependabot
  • chore(deps): bump ts-jest from 29.1.3 to 29.1.4 (#2586) by @dependabot
  • chore(deps): bump esbuild from 0.21.3 to 0.21.4 (#2583) by @dependabot
  • chore(deps): bump the aws-cdk group across 1 directory with 2 updates (#2578) by @dependabot
  • chore(deps): bump squidfunk/mkdocs-material from 5358893 to 8a87f05 in /docs (#2584) by @dependabot
  • chore(deps): bump mkdocs-material from 9.5.24 to 9.5.25 in /docs (#2585) by @dependabot
  • chore(deps-dev): bump tsx from 4.10.5 to 4.11.0 (#2575) by @dependabot
  • docs(batch): review API docs & README (#2562) by @dreamorosi
  • chore(deps): bump requests from 2.31.0 to 2.32.0 in /docs (#2563) by @dependabot
  • chore(deps): bump ts-jest from 29.1.2 to 29.1.3 (#2567) by @dependabot
  • chore(deps): bump squidfunk/mkdocs-material from 48d1914 to 5358893 in /docs (#2553) by @dependabot
  • chore(deps): bump mkdocs-material from 9.5.23 to 9.5.24 in /docs (#2554) by @dependabot
  • chore(deps): bump @types/aws-lambda from 8.10.137 to 8.10.138 (#2545) by @dependabot
  • chore(deps-dev): bump tsx from 4.10.3 to 4.10.5 (#2549) by @dependabot
  • chore(deps): bump the aws-cdk group across 1 directory with 2 updates (#2544) by @dependabot
  • chore(deps): bump esbuild from 0.21.2 to 0.21.3 (#2537) by @dependabot
  • chore(deps): bump squidfunk/mkdocs-material from 8ef47d7 to 48d1914 in /docs (#2533) by @dependabot
  • chore(deps): bump mkdocs-material from 9.5.22 to 9.5.23 in /docs (#2534) by @dependabot
  • chore(deps): bump the aws-cdk group across 1 directory with 2 updates (#2536) by @dependabot
  • chore(deps-dev): bump tsx from 4.10.2 to 4.10.3 (#2538) by @dependabot
  • chore(deps): bump @types/node from 20.12.11 to 20.12.12 (#2529) by @dependabot
  • chore(deps): bump esbuild from 0.21.1 to 0.21.2 (#2512) by @dependabot

🐛 Bug and hot fixes

🔧 Maintenance

  • chore(deps-dev): pin lerna to 8.1.2 (#2646) by @dreamorosi
  • chore(deps): bump the aws-sdk group across 1 directory with 9 updates (#2644) by @dependabot
  • chore(deps-dev): bump aws-sdk from 2.1637.0 to 2.1639.0 (#2638) by @dependabot
  • chore(deps-dev): bump prettier from 3.3.1 to 3.3.2 (#2633) by @dependabot
  • chore(deps): bump aws-xray-sdk-core from 3.6.0 to 3.9.0 (#2631) by @dependabot
  • chore(deps): bump the aws-cdk group across 1 directory with 2 updates (#2626) by @dependabot
  • chore(deps-dev): bump aws-sdk from 2.1636.0 to 2.1637.0 (#2627) by @dependabot
  • chore(deps): bump the aws-sdk group across 1 directory with 9 updates (#2619) by @dependabot
  • chore(deps-dev): bump tsx from 4.13.2 to 4.15.1 (#2629) by @dependabot
  • chore(deps-dev): bump aws-sdk from 2.1634.0 to 2.1636.0 (#2617) by @dependabot
  • chore(deps-dev): bump tsx from 4.12.0 to 4.13.2 (#2620) by @dependabot
  • chore(deps-dev): bump tsx from 4.11.2 to 4.12.0 (#2612) by @dependabot
  • chore(deps-dev): bump aws-sdk from 2.1633.0 to 2.1634.0 (#2609) by @dependabot
  • chore(deps): bump @types/node from 20.14.1 to 20.14.2 (#2608) by @dependabot
  • chore(deps-dev): bump prettier from 3.3.0 to 3.3.1 (#2607) by @dependabot
  • chore(deps): bump the aws-sdk group across 1 directory with 9 updates (#2606) by @dependabot
  • chore(deps-dev): bump aws-sdk from 2.1632.0 to 2.1633.0 (#2604) by @dependabot
  • chore(deps): bump @types/node from 20.14.0 to 20.14.1 (#2603) by @dependabot
  • chore(deps): bump @types/node from 20.12.13 to 20.14.0 (#2601) by @dependabot
  • chore(deps): bump the aws-sdk group across 1 directory with 11 updates (#2598) by @dependabot
  • chore(deps): bump vscode/devcontainers/javascript-node from bbd5e0f to cad3951 in /.devcontainer (#2592) by @dependabot
  • chore(deps): bump the aws-sdk group across 1 directory with 9 updates (#2591) by @dependabot
  • chore(deps-dev): bump aws-sdk from 2.1628.0 to 2.1631.0 (#2596) by @dependabot
  • chore(deps): bump @types/node from 20.12.12 to 20.12.13 (#2595) by @dependabot
  • chore(deps): bump ts-jest from 29.1.3 to 29.1.4 (#2586) by @dependabot
  • chore(deps): bump esbuild from 0.21.3 to 0.2...
Read more

Contributors

dreamorosi, arnabrahman, and 2 other contributors
Loading

v2.1.1

14 May 16:23
@github-actions github-actions
v2.1.1
cc10139
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.1.1

Summary

This patch release brings bug fixes to the Parser and a deprecation notice to the Tracer utility.

Parser

In response to customer reports we have applied a number of fixes on some of the built-in schemas for the Parser utility.

Specifically, the queryStringParameters, multiValueQueryStringParameters, and body fields in the APIGatewayProxyEventSchema have been converted to .nullable() to account for them being set to null in some types of requests.

Likewise, the etag field in the S3EventNotificationEventBridgeDetailSchema has been made .optional() since it's not included when an object being deleted on S3 sends a notification via Amazon EventBridge.

Finally, the principalOrgId and cognitoIdentity fields in the APIGatewayProxyEventV2Schema have been converted to .nullish().

We want to thank everyone who has taken the time to test the first beta for the Parser utility and especially those who have also reported issues they might have encountered. Thank you for making Powertools for AWS Lambda better for everyone!

Tracer

In March 2024, AWS announced that AWS SDK for JavaScript v2 will reach end-of-support in September 8, 2025. In response to this announcement, and to align with the warnings already being emitted by the AWS SDK, with this release we are marking the captureAWS and captureAWSClient methods as deprecated.

This announcement does not impact the methods and you are free to continue using them. The deprecation tag serves only as a gentle nudge to consider a migration to the newer AWS SDK for JavaScript v3 which can be instrumented via the captureAWSv3Client.

The two methods we are marking as deprecated today will be removed in the next major release, which as of today has no planned date.

Acknowledgements

Congratulations to @blytheaw for getting their first PR merged 🎉 and thanks also to @arnabrahman for another successful contribution 🙏!

Workshop

For those of you wanting to get a deeper introduction to Powertools for AWS Lambda, you can now try our official self-paced workshop titled “Accelerate your serverless journey with Powertools for AWS Lambda”.

Miscellaneous

We are happy to also share that we have restarted working on the RFC process for the upcoming Event Handler utility. Last week we have published a first decision log on our direction in terms of routing implementation where we have decided to move forward with a new implementation rather than taking a 3rd party library as dependency. The next step will be to finalize the main RFC for how the API and Developer Experience (DX) for the utility will look like.

In parallel, we have started refreshing the API docs for the utilities starting with the Commons utility, which is mainly used internally by other utilities. The goal for this workstream is to standardize the docstrings and contextual documentation so that you can have more details on what different public APIs do.

Changes

  • chore(deps): bump ossf/scorecard-action from 2.3.1 to 2.3.3 (#2506) by @dependabot
  • chore(deps): bump github/codeql-action from 3.25.4 to 3.25.5 (#2514) by @dependabot
  • chore(tracer): mark captureAWS & captureAWSClient functions as deprecated (#2508) by @arnabrahman
  • chore(deps): bump github/codeql-action from 3.25.3 to 3.25.4 (#2495) by @dependabot
  • chore(deps): bump actions/checkout from 4.1.4 to 4.1.5 (#2489) by @dependabot
  • chore(docs): fix update layer arn for cdk (#2487) by @am29d
  • chore(deps): bump zgosalvez/github-actions-ensure-sha-pinned-actions from 3.0.4 to 3.0.5 (#2475) by @dependabot
  • chore(deps): bump actions/dependency-review-action from 4.2.5 to 4.3.2 (#2460) by @dependabot
  • chore(deps): bump actions/download-artifact from 4.1.6 to 4.1.7 (#2439) by @dependabot
  • chore(deps): bump actions/checkout from 4.1.3 to 4.1.4 (#2440) by @dependabot
  • chore(deps): bump github/codeql-action from 3.25.2 to 3.25.3 (#2445) by @dependabot
  • chore(deps): bump github/codeql-action from 3.25.1 to 3.25.2 (#2425) by @dependabot
  • chore(deps): bump actions/upload-artifact from 4.3.2 to 4.3.3 (#2426) by @dependabot
  • chore(deps): bump actions/download-artifact from 4.1.5 to 4.1.6 (#2424) by @dependabot
  • chore(maintenance): update labels in automation (#2419) by @dreamorosi
  • chore(deps): bump actions/checkout from 4.1.2 to 4.1.3 (#2412) by @dependabot
  • chore(deps): bump actions/download-artifact from 4.1.4 to 4.1.5 (#2404) by @dependabot
  • chore(deps): bump actions/upload-artifact from 4.3.1 to 4.3.2 (#2405) by @dependabot
  • chore(deps): bump github/codeql-action from 3.25.0 to 3.25.1 (#2385) by @dependabot

📜 Documentation updates

🐛 Bug and hot fixes

  • fix(parser): set APIGatewayProxyEventSchema body and query string keys to be nullable (#2465) by @blytheaw
  • fix(parser): lambda function url cognitoIdentity and principalOrgId nullable (#2430) by @am29d
  • fix(parser): set etag optional for delete object notifications (#2429) by @am29d

🔧 Maintenance

  • chore(deps-dev): bump tsx from 4.9.3 to 4.10.2 (#2510) by @dependabot
  • chore(deps): bump the aws-sdk group with 11 updates (#2509) by @dependabot
  • chore(deps-dev): bump lerna from 8.1.2 to 8.1.3 (#2513) by @dependabot
  • chore(deps-dev): bump aws-sdk from 2.1616.0 to 2.1617.0 (#2507) by @dependabot
  • chore(deps-dev): bump zod from 3.23.6 to 3.23.8 (#2504) by @dependabot
  • chore(deps): bump the aws-sdk group with 9 updates (#2502) by @dependabot
  • chore(deps): bump the aws-cdk group with 2 updates (#2503) by @dependabot
  • chore(deps-dev): bump aws-sdk from 2.1614.0 to 2.1616.0 (#2501) by @dependabot
  • chore(deps): bump vscode/devcontainers/javascript-node from ec1e123 to bbd5e0f in /.devcontainer (#2496) by @dependabot
  • chore(deps): bump @types/node from 20.12.10 to 20.12.11 (#2497) by @dependabot
  • chore(deps): bump esbuild from 0.21.0 to 0.21.1 (#2500) by @dependabot
  • chore(deps): bump esbuild from 0.20.2 to 0.21.0 (#2490) by @dependabot
  • chore(deps-dev): bump aws-sdk from 2.1613.0 to 2.1614.0 (#2492) by @dependabot
  • chore(deps): bump @types/node from 20.12.9 to 20.12.10 (#2491) by @dependabot
  • chore(deps-dev): bump tsx from 4.9.0 to 4.9.3 (#2480) by @dependabot
  • chore(deps-dev): bump aws-sdk from 2.1612.0 to 2.1613.0 (#2481) by @dependabot
  • chore(deps): bump @types/node from 20.12.8 to 20.12.9 (...
Read more

Contributors

am29d, heitorlessa, and 4 other contributors
Loading

v2.1.0

18 Apr 09:27
@github-actions github-actions
v2.1.0
8b1a9ad
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.1.0

Summary

This release marks the first beta release of the new Parser utility 🎉 and adds custom JMESPath functions to the Idempotency utility.

Parser

⚠️ WARNING: Do not use this utility in production just yet! ⚠️
This AWS Lambda Powertools for TypeScript utility is currently released as beta developer preview and is intended strictly for feedback and testing purposes only. This version is not stable, and significant breaking changes might incur before the GA release.

We are excited to announce the first public beta for the Parser utility, which brings data validation and parsing using Zod, a TypeScript-first schema declaration library.

Key features

To get started install the utility together with Zod 3.x:

npm i @aws-lambda-powertools/parser zod@~3

Next, define your schema that models your event, for example:

import { z } from 'zod';

const orderSchema = z.object({
  id: z.number().positive(),
  description: z.string(),
  items: z.array(
    z.object({
      id: z.number().positive(),
      quantity: z.number(),
      description: z.string(),
    })
  ),
  optionalField: z.string().optional(),
});

The utility comes with built-in schemas for many AWS events (API GW, ALB, SQS, SNS, EventBridge, Kafka, Kinesis, and more) that you can use or extended with your own payloads. For example, when working with events coming from Amazon EventBridge you can provide a custom schema for the detail field:

import type { Context } from 'aws-lambda';
import type { LambdaInterface } from '@aws-lambda-powertools/commons/types';
import { parser } from '@aws-lambda-powertools/parser';
import { z } from 'zod';
import { EventBridgeSchema } from '@aws-lambda-powertools/parser/schemas';

const orderEventSchema = EventBridgeSchema.extend({
  detail: orderSchema, 
});

type OrderEvent = z.infer<typeof orderEventSchema>;

class Lambda implements LambdaInterface {
  @parser({ schema: orderEventSchema }) 
  public async handler(event: OrderEvent, _context: Context): Promise<void> {
    for (const item of event.detail.items) {
      // process OrderItem
    }
  }
}

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

If you are interested only in your custom part of the payload, the utility provides a collection of built-in envelopes that you can use together your schema.

Using envelopes, the utility will validate and parse the entire event and return only your custom part of the payload within the envelope rather than the entire object:

import { parser } from '@aws-lambda-powertools/parser/middleware';
import { z } from 'zod';
import middy from '@middy/core';
import { EventBridgeEnvelope } from '@aws-lambda-powertools/parser/envelopes';

type Order = z.infer<typeof orderSchema>;

const lambdaHandler = async (
  event: Order
): Promise<void> => {
  for (const item of event.items) {
    // item is parsed as { id: number, quanityt: number, description: string }
  }
};

export const handler = middy(lambdaHandler).use(
  parser({ schema: orderSchema, envelope: EventBridgeEnvelope })
);

You can also use built-in schemas and envelopes manually, without middyjs or decorator:

import type { Context } from 'aws-lambda';
import { z } from 'zod';
import { EventBridgeEnvelope } from '@aws-lambda-powertools/parser/envelopes';
import { EventBridgeSchema } from '@aws-lambda-powertools/parser/schemas';
import type { EventBridgeEvent } from '@aws-lambda-powertools/parser/types';

type Order = z.infer<typeof orderSchema>;

export const handler = async (
  event: EventBridgeEvent,
  _context: Context
): Promise<void> => {
  const parsedEvent = EventBridgeSchema.parse(event); 
  // parsed as event bridge event but detail is still unknown
  const order: Order = EventBridgeEnvelope.parse(event, orderSchema); 
  // parsed as event bridge event and detail as orderSchema
};

As mentioned, the utility is published as a beta and thus its API, schemas, and envelopes might change. We however encourage you to give it a try and provide feedback over the next couple of weeks so that we can hash out any issue before we can consider it production ready.

Idempotency

Starting from this release you can use the custom functions from the JMESPath utility when specifying a JMESPath expression to select the idempotency key from payloads.

This is especially useful when working with events that contain encoded data such as Amazon API Gateway or Amazon SQS among others.

import { makeIdempotent, IdempotencyConfig } from '@aws-lambda-powertools/idempotency';
import { DynamoDBPersistenceLayer } from '@aws-lambda-powertools/idempotency/dynamodb';
import type { APIGatewayProxyEvent } from 'aws-lambda';

const persistenceStore = new DynamoDBPersistenceLayer({
  tableName: 'idempotencyTableName',
});

export const handler = makeIdempotent(async (event: APIGatewayProxyEvent) => {
  // handler code goes here
}, {
  persistenceStore,
  config: new IdempotencyConfig({
    eventKeyJmespath: 'powertools_json(body).["user", "productId"]',
  }),
});

The feature is possible thanks to the integration with the @aws-lambda-powertools/jmespath utility that we launched in the previous release and that replaces the existing jmespath library dependency.

Changes

  • chore(deps): bump github/codeql-action from 3.25.0 to 3.25.1 (#2385) by @dependabot
  • chore(ci): fetch entire history for lerna versioning (#2391) by @am29d
  • chore(deps): bump github/codeql-action from 3.24.10 to 3.25.0 (#2363) by @dependabot
  • chore(parser): add DeadLetterQueueSourceArn attribute (#2362) by @am29d

🌟New features and non-breaking changes

🌟 Minor Changes

  • refactor(jmespath): rename jmespath parsing options type (#2367) by @dreamorosi

📜 Documentation updates

🐛 Bug and hot fixes

  • fix(jmespath): refactor custom function int...
Read more

Contributors

am29d, dreamorosi, and dependabot
Loading

v2.0.4

10 Apr 16:11
@github-actions github-actions
v2.0.4
3f296d2
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.0.4

Summary

This release introduces a new Powertools utility to work with JMESPath, adds the ability to trace requests made via the fetch module for Tracer, and brings bug fixes and improvements for the Logger and Idempotency utilities.

JMESPath

We're excited to release the JMESPath utility, a fully spec compliant high-level library to parse and extract data from JSON objects using JMESPath expressions.

Usage

To get started, install the library by running:

npm i @aws-lambda-powertools/jmespath

At its core, the library provides a utility function to extract data from a JSON object using a JMESPath expression.

import { search } from '@aws-lambda-powertools/jmespath';
import { Logger } from '@aws-lambda-powertools/logger';

const logger = new Logger();

type MyEvent = {
  foo: {
    bar: string;
  };
}

export const handler = async (event: MyEvent): Promise<void> => {
  const result = search(event, 'foo.bar');
  logger.info(result); // "baz"
};

In some cases however, you may want to extract data from an envelope. The library provides a utility function to help you work with envelopes and extract data from them.

import { extractDataFromEnvelope } from '@aws-lambda-powertools/jmespath/envelopes';

type MyEvent = {
  body: string; // "{\"customerId\":\"dd4649e6-2484-4993-acb8-0f9123103394\"}"
  deeplyNested: Array<{ someData: number[] }>;
};

type MessageBody = {
  customerId: string;
};

export const handler = async (event: MyEvent): Promise<unknown> => {
  const payload = extractDataFromEnvelope<MessageBody>(
    event,
    'powertools_json(body)'
  );
  const { customerId } = payload; // now deserialized

  // also works for fetching and flattening deeply nested data
  const someData = extractDataFromEnvelope<number[]>(
    event,
    'deeplyNested[*].someData[]'
  );

  return {
    customerId,
    message: 'success',
    context: someData,
    statusCode: 200,
  };
};

The utility comes with a set of built-in envelopes to help you extract data from common event sources such as S3, SQS, SNS, and more:

import {
  extractDataFromEnvelope,
  SQS,
} from '@aws-lambda-powertools/jmespath/envelopes';
import { Logger } from '@aws-lambda-powertools/logger';
import type { SQSEvent } from 'aws-lambda';

const logger = new Logger();

type MessageBody = {
  customerId: string;
};

export const handler = async (event: SQSEvent): Promise<void> => {
  const records = extractDataFromEnvelope<Array<MessageBody>>(event, SQS);
  for (const record of records) {
    // records is now a list containing the deserialized body of each message
    const { customerId } = record;
    logger.appendKeys({ customerId });
  }
};

Finally, in addition to supporting all the built-in JMESPath functions present in the specification, the utility provides custom functions to help you work with more complex data structures. For example, you can use the powertools_json function to parse a JSON string, or the powertools_base64 function to decode a base64-encoded string:

import { extractDataFromEnvelope } from '@aws-lambda-powertools/jmespath/envelopes';
import { Logger } from '@aws-lambda-powertools/logger';

const logger = new Logger();

export const handler = async (event: { payload: string }): Promise<void> => {
  const data = extractDataFromEnvelope<string>(
    event,
    'powertools_json(powertools_base64(payload))'
  );

  logger.info('Decoded payload', { data });
};

In future releases we will incorporate this utility as part of the Idempotency utility as well as other upcoming utilities.

Tracer

Starting from this release you can trace requests made using the fetch global module that is available in Lambda functions running on managed runtimes Node.js 18 or newer.

The feature is enabled by default and all requests are captured by default. For each request Tracer will generate a subsegment under the currently active segment and annotate it with informations about the request.

For example, the following code:

import { Tracer } from '@aws-lambda-powertools/tracer';
import { captureLambdaHandler } from '@aws-lambda-powertools/tracer/middleware';
import middy from '@middy/core';

const tracer = new Tracer({ serviceName: 'serverlessAirline' });

export const handler = middy(async () => {
  await fetch("http://httpbin.org/status/500");
}).use(captureLambdaHandler(tracer));

Will result in a segments timeline similar to this:

317722392-699f8ad8-3172-41d3-8ab7-58e7786767f6

As you can see, if the request has a 4xx or 5xx like in this case, the appropriate flag is automatically added to the subsegment so you can have complete visibility.

Just like with other requests made using http-based modules before, you can opt out of tracing requests made using fetch by setting either the captureHTTPsRequests constructor parameter or the POWERTOOLS_TRACER_CAPTURE_HTTPS_REQUESTS environment variable to false.

Idempotency

When using the Idempotency utility you can enable in-memory caching so that requests handled by the same Lambda execution environments can be processed without calling the persistence layer.

Prior to this release, some of the requests that caused a "cache hit" would be rejected as if another request was already in progress rather than returning the value from the cache. While this bug could have not caused data loss due to it happening exclusively when retrying an idempotent request, it could have caused an artificially high number of IdempotencyAlreadyInProgess errors.

This release fixes the logic for cache retrieval and ensures that when there's a "cache hit" the correct value is returned from the in-memory cache and its value is returned in the response.

Logger

When initialized the Logger utility performs a number of actions to configure the content of the logs, their format, and its overall behavior. Some of these setup activities can cause warning or debug logs to be emitted if certain conditions are met, for example: if the utility is initialized with a log level that is more verbose than the one set in Lambda's advanced logging controls.

In prior releases of v2 some of these warnings could cause runtime errors to be thrown due to the utility not being fully initialized at the time of emitting the logs. This release brings a new and improved initialization logic that buffers debug and warning logs and emits them only when the Logger instance is ready.

Additionally, the utility now uses template literals instead of the node:util module to format some of these warnings. This change was done to allow the utility to be compatible with LLRT (Low Latency Runtime), an experimental lightweight JavaScript runtime currently under development.

Acknowledgements

Special thanks to @NimmLor, @webdeveric, and @yamatatsu for contributing to this release 🎉

Changes

  • chore(deps): bump zgosalvez/github-actions-ensure-sha-pinned-actions from 3.0.3 to 3.0.4 (#2343) by @dependabot
  • chore(deps): bump github/codeql-action from 3.24.9 to 3.24.10 (#2331) by @dependabot
  • chore(ci): add monthly roadmap reminder central action (#2330) by @heitorlessa
  • chore(deps): bump actions/setup-python from 5.0.0 to 5.1.0 (#2288) by @dependabot
  • test(jmespath): 100% coverage and spec compliance (#2271) by @dreamorosi
  • chore(deps): bump actions/dependency-review-action from 4.2.4 to 4.2.5 (#2279) by @dependabot
  • chore(deps): bump actions/dependency-review-action from 4.2.3 to 4.2.4 (#2272) by @dependabot
  • chore(deps): bump github/codeql-action from 3.24.8 to 3.24.9 (#2267) by @dependabot
  • chore(deps): bump actions/dependency-review-action from 4.1.3 to 4.2.3 (#2260) by @dependabot
  • chore(deps): bump github/codeql-action from 3.24.7 to 3.24.8 (#2256) by @dependabot

🌟New features and non-breaking changes

🌟 Minor Changes

  • refactor(logger): use template literal instead of node:util format (#2283) by @NimmLor

📜 Documentation updates

  • chore(deps): bump @types/node from 20.12.5 to 20.12.6 (#2342) by @dependabot
  • chore(maintenance): update release flow diagram (#2322) by @dreamorosi
  • chore(docs): streamline docs homepage (#2328) by @dreamorosi
  • chore(deps-dev): bump aws-sdk from 2.1593.0 to 2.1595.0 (#2338) by @dependabot
  • chore(deps): bump @types/node from 20.12.4 to 20.12.5 (#2334) by @dependabot
  • chore(deps): bump the aws-cdk group with 2 updates (#2332) by @dependabot
  • chore(deps): bump the aws-sdk group with 9 updates (#2324) by @dependabot
  • chore(deps): bump @types/aws-lambda from 8.10.136 to 8.10.137 (#2325) by @dependabot
  • chore(deps): bump typescript from 5.4.3 to 5.4.4 (#2326) by @dependabot
  • chore(docs): update batch docs highlight & links (#2320) by @dreamorosi
  • chore(maintenance): document process to add a new region to layers (#2...
Read more

Contributors

webdeveric, am29d, and 5 other contributors
Loading

v2.0.3

15 Mar 16:57
@github-actions github-actions
v2.0.3
8138df1
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.0.3

Summary

This release brings a couple of bug fixes related to our new ESM builds as well as minor improvements in how Logger formats error stack traces.

Idempotency

Due to a misconfiguration in our build process some components of the Idempotency utility were not being transformed correctly when bundling our TypeScript source code to ESM-formatted JavaScript. This caused runtime errors when importing the ESM build of the utility.

With this release we have fixed the build process and resolved the issue so that the Idempotency utility can now be used with functions using ESM.

Layers

Since the v2 release we have started including ESM builds to our public Lambda Layers, however we failed to include a polyfill for the require keyword

Based on our tests the presence of this polyfill should not impact your code but only code paths evaluated as a result of importing Powertools utilities from the layer itself. If you encounter issues with this change please let us know by opening an issue.

Logger

As part of this release have improved the regular expression used to extract the file and line locations of an error from its stack trace. The change didn't result in any chance in the way errors are formatted, so you should not see any difference in your logs.

Acknowledgements

Special thanks to @karthikeyanjp and @miguel-martinr for their contributions as well as @AllyMurray for reporting the issue with bundling.

Changes

  • chore(deps): bump github/codeql-action from 3.24.6 to 3.24.7 (#2220) by @dependabot
  • chore(deps): bump actions/checkout from 4.1.1 to 4.1.2 (#2215) by @dependabot
  • chore(docs): remove missing README from typedoc for jmespath temporarily (#2200) by @am29d
  • chore(deps): bump actions/download-artifact from 4.1.3 to 4.1.4 (#2157) by @dependabot

🌟New features and non-breaking changes

🌟 Minor Changes

📜 Documentation updates

🐛 Bug and hot fixes

🔧 Maintenance

This release was made possible by the following contributors:

@am29d, @dreamorosi, @karthikeyanjp and @miguel-martinr

Contributors

am29d, dreamorosi, and 4 other contributors
Loading

v2.0.2

05 Mar 09:23
@github-actions github-actions
v2.0.2
047ad5c
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.0.2

Summary

This patch release fixes a bug affecting customers using Tracer in a JavaScript ESM environment.

Tracer

In v2.0.0 we launched ESM support and most of our focus went on customers using Powertools with TypeScript and bundlers (i.e. esbuild). This introduced a bug that prevented customers using plain JavaScript with ESM from successfully importing the utility.

This release changes the way that the AWS X-Ray SDK for Node.js is imported within the Tracer utility so that customers using ESM with JavaScript can import the utility correctly.

Special thanks to @webdeveric for reporting the issue and suggesting a fix.

Changes

🐛 Bug and hot fixes

This release was made possible by the following contributors:

@dreamorosi

Contributors

webdeveric and dreamorosi
Loading

v2.0.1

04 Mar 16:28
@dreamorosi dreamorosi
v2.0.1
303428a
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.0.1

Summary

This is a patch release we had to make to align the new Lambda Layer ARNs to the v2.0.0 major release.

The ARN for the new major version will use this format: arn:aws:lambda:{region}:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:1.

You can find a list of changes introduced with v2 in the v2.0.0 release notes.

Changes

This release was made possible by the following contributors:

@dreamorosi, @am29d

Contributors

am29d and dreamorosi
Loading

v2.0.0

04 Mar 16:25
@github-actions github-actions
v2.0.0
303428a
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.0.0

Summary

We are super happy to announce our next major version – v2.0.0 🎉🎉!

The most requested feature by customers was enabling ESM support. The ecosystem is gradually moving to ESM and today 1 in 5 of the popular packages on npm contains ESM. You can now take advantage of modern features like top-level await, and advanced techniques like tree shaking to benefit from smaller bundles.

Using CommonJS? We have your back! v2 supports both CommonJS and ESM, as we know the ecosystem is in a transition phase as we speak.

The second most requested feature was further Logger customizations. Extending logger to customize log attributes became easier – we now differentiate between standard and custom log attributes. Based on your feedback, we’ve also improved typing and made it more intuitive to decide what the final output should be.

We care deeply about minimizing breaking changes

Over the past few months, we carefully selected each breaking change to make, and crafted an extensive upgrade guide to ease your transition to v2. Please let us know whether we can make your upgrade process easier.

🌟 We couldn’t have done this without you 🌟

Thanks to everyone in the community for their patience and assistance as we've been working on this release. A special thanks to @antstanley, @erikayao93, and @shdq for their contributions to this milestone.

Note

The section below is an excerpt of what's available in the Upgrade guide

What’s New in v2

ESM Support

With support for ESM in v2, you can now use import instead of require syntax.

This is especially useful when you want to run asynchronous code during the initialization phase by using top-level await.

import { getSecret } from '@aws-lambda-powertools/parameters/secrets';

// This code will run during the initialization phase of your Lambda function
const myApiKey = await getSecret('my-api-key', { transform: 'json' });

export const handler = async (_event: unknown, _context: unknown) => {
    // ...
};

If you are unable to use ESM, you can still use the require syntax to import packages. We will continue to support it by shipping CommonJS alongside ESM.

When using a dependency or transitive dependency that doesn’t support ESM yet, you can still use ESM and polyfill the import during your bundling step.

For example, Tracer (@aws-lambda-powertools/tracer) relies on the AWS X-Ray SDK for Node.js which uses require.

Here’s an example of how to polyfill the require keyword using AWS CDK and esbuild:

import { Stack, type StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { NodejsFunction, OutputFormat } from 'aws-cdk-lib/aws-lambda-nodejs';
import { Runtime } from 'aws-cdk-lib/aws-lambda';

export class MyStack extends Stack {
  public constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const handler = new NodejsFunction(this, 'helloWorldFunction', {
      runtime: Runtime.NODEJS_20_X,
      handler: 'handler',
      entry: 'src/index.ts',
      bundling: {
        format: OutputFormat.ESM,
        banner: 
          "import { createRequire } from 'module';const require = createRequire(import.meta.url);", 
      },
    });
  }
}

Logger new features

Complete log format customization

In v1, the Logger utility exposed the standard structured keys to custom log formatters as a single argument and expected a plain object with keys and values for the log output:

import { LogFormatter } from '@aws-lambda-powertools/logger';
import {
  LogAttributes,
  UnformattedAttributes,
} from '@aws-lambda-powertools/logger/lib/types';

class MyCompanyLogFormatter extends LogFormatter {
  public formatAttributes(attributes: UnformattedAttributes): LogAttributes {
    return {
      message: attributes.message,
      service: attributes.serviceName,
      environment: attributes.environment,
      awsRegion: attributes.awsRegion,
      correlationIds: {
        awsRequestId: attributes.lambdaContext?.awsRequestId,
        xRayTraceId: attributes.xRayTraceId,
      },
      lambdaFunction: {
        name: attributes.lambdaContext?.functionName,
        arn: attributes.lambdaContext?.invokedFunctionArn,
        memoryLimitInMB: attributes.lambdaContext?.memoryLimitInMB,
        version: attributes.lambdaContext?.functionVersion,
        coldStart: attributes.lambdaContext?.coldStart,
      },
      logLevel: attributes.logLevel,
      timestamp: this.formatTimestamp(attributes.timestamp),
      logger: {
        sampleRateValue: attributes.sampleRateValue,
      },
    };
  }
}

export { MyCompanyLogFormatter };

In v2, you now have complete control over both standard (attributes) and custom keys (additionalLogAttributes) in the formatAttributes() method. Also, you now may return a LogItem object to increase type safety when defining the final log output.

import { LogFormatter, LogItem } from '@aws-lambda-powertools/logger';
import type { LogAttributes, UnformattedAttributes } from '@aws-lambda-powertools/logger/types';

class MyCompanyLogFormatter extends LogFormatter {
  public formatAttributes(
    attributes: UnformattedAttributes,
    additionalLogAttributes: LogAttributes  
  ): LogItem {  
    const baseAttributes = {
        message: attributes.message,
        service: attributes.serviceName,
        environment: attributes.environment,
        awsRegion: attributes.awsRegion,
        correlationIds: {
            awsRequestId: attributes.lambdaContext?.awsRequestId,
            xRayTraceId: attributes.xRayTraceId,
        },
        lambdaFunction: {
            name: attributes.lambdaContext?.functionName,
            arn: attributes.lambdaContext?.invokedFunctionArn,
            memoryLimitInMB: attributes.lambdaContext?.memoryLimitInMB,
            version: attributes.lambdaContext?.functionVersion,
            coldStart: attributes.lambdaContext?.coldStart,
        },
        logLevel: attributes.logLevel,
        timestamp: this.formatTimestamp(attributes.timestamp),
        logger: {
            sampleRateValue: attributes.sampleRateValue,
        },
    };

    // Create a new LogItem with the base attributes
    const logItem = new LogItem({ attributes: baseAttributes });

    // Merge additional attributes
    logItem.addAttributes(additionalLogAttributes); 

    return logItem;
  }
}

export { MyCompanyLogFormatter };

With this change you can tailor the format of your logs to your company’s standards and seamlessly integrate with third-party observability providers that require specific formats. This new modular LogFormatter will also allow us to add more features over the coming releases, so stay tuned!

Log sampling

In v1, log sampling implementation was inconsistent from other Powertools for AWS Lambda languages (Python, .NET, Java).

Logger sampleRateValue continues to determine the percentage of concurrent/cold start invocations that logs will be sampled, e.g. log level set to DEBUG.

However in v2, we changed slightly the implementation for consistency across languages:

Behavior v1 v2
Log Level Log level remains unchanged and any log statement is printed Log level changes to DEBUG
Log sampling indication No indication Debug message emitted during initialization indicates sampling is enabled

Scoped imports

In v2, we improved tree-shaking support to help you reduce your function bundle size. That is, only bundle what you use.

To help you import and bundle only code paths that you really need we’ve added support for subpath exports. This means that you can target certain modules based on their path.

For example, in v1 you could import Middy.js middlewares from the default export of a package (e.g. injectLambdaContext would be imported from @aws-lambda-powertools/logger).

import { Logger, injectLambdaContext } from '@aws-lambda-powertools/logger';
import { Tracer, captureLambdaHandler } from '@aws-lambda-powertools/tracer';
import { Metrics, logMetrics } from '@aws-lambda-powertools/metrics';

In v2, you can now import only the Middy.js middlewares from a dedicated path. This means if you don’t use Middy.js you will benefit from a smaller bundle size.

import { Logger } from '@aws-lambda-powertools/logger';
import { injectLambdaContext } from '@aws-lambda-powertools/logger/middleware';

import { Tracer } from '@aws-lambda-powertools/tracer';
import { captureLambdaHandler } from '@aws-lambda-powertools/tracer/middleware';

import { Metrics } from '@aws-lambda-powertools/metrics';
import { logMetrics } from '@aws-lambda-powertools/metrics/middleware';

Likewise, in v2 you can now directly import...

Read more

Contributors

hjgraca, shdq, and 5 other contributors
Loading

v1.18.1

20 Feb 19:12
@github-actions github-actions
v1.18.1
07ddeda
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
v1.18.1

Summary

This patch release fixes a regression in the Idempotency utility introduced in the previous release that prevented stored records to be validated when validation was enabled. We also have published our versioning and maintenance policy and the upgrade guide to our next major version.

Idempotency

When using the utility, you can use the payloadValidationJmesPath option, to provide a JMESPath expression to specify which part of the event body should be validated against previous idempotent invocations. Due to a bug we introduced in the last release, the validation was not applied when using the recent versions of the AWS SDK.

This release fixes the bug and restores the validation for all requests, regardless of AWS SDK version. Thanks to @kevin-secrist for identifying and reporting the issue!

Announcements

The next major version of Powertools for AWS Lambda (TypeScript) is launching soon. We have prepared an upgrade guide that we hope will help you get ready for the upgrade.

Additionally, we also have made public our versioning and maintenance policy. The document highlights our versioning strategy and we hope will give you more clarity on the project.

🌟New features and non-breaking changes

  • feat(idempotency): return existing record in IdempotencyValidationError (#2059) by @kevin-secrist

📜 Documentation updates

  • chore(docs): fix broken upgrade guide link in banner (#2091) by @dreamorosi
  • docs(maintenance): create upgrade guide from v1 to v2 (#1994) by @dreamorosi
  • chore(docs): add Alma Media to list of companies using Powertools (#2021) by @am29d
  • docs(maintenance): add versioning and maintenance policy (#1996) by @heitorlessa

🐛 Bug and hot fixes

  • fix(idempotency): validate idempotency record returned in conditional write (#2083) by @dreamorosi

🔧 Maintenance

This release was made possible by the following contributors:

@am29d, @dreamorosi, @heitorlessa, @hjgraca, and @kevin-secrist

Contributors

hjgraca, kevin-secrist, and 4 other contributors
Loading