Releases: aws-powertools/powertools-lambda-typescript
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
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:
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.
Batch Processing
Skip processing failed group id messages of SQS FIFO queues on error
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.
Parser (beta)
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
- improv(idempotency): handle functions with no return value (#2521) by @dreamorosi
- improv(tracer): remove require in tracer provider (#2557) by @dreamorosi
📜 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
to96abcbb
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
to8a87f05
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
to5358893
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
to48d1914
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
- fix(idempotency): deep sort payload during hashing (#2570) by @arnabrahman
- fix(parser): handle API Gateway Test UI sourceIp (#2531) by @dreamorosi
🔧 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
tocad3951
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...
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
- chore(deps): bump squidfunk/mkdocs-material from
11d7ec0
to8ef47d7
in /docs (#2516) by @dependabot - chore(deps-dev): bump tsx from 4.9.3 to 4.10.2 (#2510) by @dependabot
- chore(deps): bump mkdocs-material from 9.5.21 to 9.5.22 in /docs (#2515) by @dependabot
- chore(deps): bump the aws-sdk group with 11 updates (#2509) 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): bump @types/node from 20.12.10 to 20.12.11 (#2497) by @dependabot
- chore(docs): miscellaneous updates and clarifications on docs (#2494) by @dreamorosi
- 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): bump @types/node from 20.12.9 to 20.12.10 (#2491) by @dependabot
- docs(maintenance): add link to new and official workshop (#2488) by @dreamorosi
- chore(deps): bump squidfunk/mkdocs-material from
98c9809
to11d7ec0
in /docs (#2476) by @dependabot - chore(deps): bump mkdocs-material from 9.5.20 to 9.5.21 in /docs (#2477) by @dependabot
- chore(deps-dev): bump tsx from 4.9.0 to 4.9.3 (#2480) by @dependabot
- chore(deps): bump @types/node from 20.12.8 to 20.12.9 (#2482) by @dependabot
- chore(deps): bump jinja2 from 3.1.3 to 3.1.4 in /docs (#2483) by @dependabot
- chore(deps): bump the aws-sdk group with 9 updates (#2478) by @dependabot
- chore(deps-dev): bump tsx from 4.8.2 to 4.9.0 (#2473) by @dependabot
- chore(deps): bump @types/node from 20.12.7 to 20.12.8 (#2474) by @dependabot
- chore(deps-dev): bump tsx from 4.7.3 to 4.8.2 (#2462) by @dependabot
- chore(deps): bump the aws-cdk group across 1 directory with 2 updates (#2471) by @dependabot
- chore(deps): bump the aws-sdk group across 1 directory with 9 updates (#2469) by @dependabot
- chore(deps): bump the aws-sdk group across 1 directory with 9 updates (#2468) by @dependabot
- chore(deps): bump the aws-sdk group with 9 updates (#2448) by @dependabot
- chore(deps): bump mkdocs-material from 9.5.19 to 9.5.20 in /docs (#2450) by @dependabot
- chore(deps): bump squidfunk/mkdocs-material from
e309089
to98c9809
in /docs (#2451) by @dependabot - chore(deps): bump squidfunk/mkdocs-material from
521644b
toe309089
in /docs (#2438) by @dependabot - chore(deps-dev): bump tsx from 4.7.2 to 4.7.3 (#2444) by @dependabot
- chore(deps): bump the aws-sdk group with 9 updates (#2446) by @dependabot
- chore(deps): bump the aws-cdk group with 2 updates (#2442) by @dependabot
- chore(docs): move code snippets under examples (#2436) by @dreamorosi
- chore(deps): bump mkdocs-material from 9.5.18 to 9.5.19 in /docs (#2437) by @dependabot
- chore(maintenance): add markdownlint (#2434) by @dreamorosi
- chore(deps-dev): bump aws-sdk from 2.1604.0 to 2.1605.0 (#2432) by @dependabot
- chore(deps-dev): bump aws-sdk from 2.1602.0 to 2.1604.0 (#2423) by @dependabot
- docs(maintenance): april updates (#2417) by @heitorlessa
- chore(deps-dev): bump aws-sdk from 2.1601.0 to 2.1602.0 (#2402) by @dependabot
- chore(deps): bump the aws-cdk group with 2 updates (#2401) by @dependabot
- chore(deps-dev): bump zod from 3.22.4 to 3.22.5 (#2403) by @dependabot
- chore(deps-dev): bump aws-sdk from 2.1599.0 to 2.1601.0 (#2393) by @dependabot
- chore(deps): bump the aws-sdk group with 9 updates (#2386) by @dependabot
🐛 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
tobbd5e0f
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 (...
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
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
- Define data schema as Zod schema, then parse, validate and extract only what you want
- Built-in schemas and envelopes to unwrap and validate popular AWS event sources payloads
- Extend and customize envelopes to fit your needs
- Safe parsing option to avoid throwing errors and custom error handling
- Available as a Middy.js middleware, TypeScript class method decorator, and standalone function
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
- feat(idempotency): add custom JMESPath functions (#2364) by @dreamorosi
- docs(parser): add utility readme (#2360) by @dreamorosi
🌟 Minor Changes
- refactor(jmespath): rename jmespath parsing options type (#2367) by @dreamorosi
📜 Documentation updates
- chore(deps-dev): bump aws-sdk from 2.1599.0 to 2.1601.0 (#2393) by @dependabot
- chore(deps): bump the aws-sdk group with 9 updates (#2386) by @dependabot
- test(maintenance): add ESM output to e2e test (#2370) by @dreamorosi
- chore(deps): bump mkdocs-material from 9.5.17 to 9.5.18 in /docs (#2371) by @dependabot
- chore(deps): bump squidfunk/mkdocs-material from
6b124e1
to521644b
in /docs (#2373) by @dependabot - refactor(jmespath): rename jmespath parsing options type (#2367) by @dreamorosi
- feat(idempotency): add custom JMESPath functions (#2364) by @dreamorosi
- chore(deps-dev): bump aws-sdk from 2.1598.0 to 2.1599.0 (#2365) by @dependabot
- docs(parser): add utility readme (#2360) by @dreamorosi
- chore(deps): bump the aws-sdk group with 9 updates (#2358) by @dependabot
- chore(deps-dev): bump aws-sdk from 2.1597.0 to 2.1598.0 (#2359) by @dependabot
- chore(deps): bump idna from 3.6 to 3.7 in /docs (#2357) by @dependabot
- chore(deps): bump the aws-cdk group with 2 updates (#2354) by @dependabot
- chore(deps-dev): bump aws-sdk from 2.1596.0 to 2.1597.0 (#2355) by @dependabot
- chore(deps): bump typescript from 5.4.4 to 5.4.5 (#2356) by @dependabot
- chore(deps): bump the aws-sdk group with 9 updates (#2349) by @dependabot
- chore(deps): bump the aws-cdk group with 2 updates (#2350) by @dependabot
- chore(deps-dev): bump aws-sdk from 2.1595.0 to 2.1596.0 (#2351) by @dependabot
- chore(deps): bump @types/node from 20.12.6 to 20.12.7 (#2352) by @dependabot
🐛 Bug and hot fixes
- fix(jmespath): refactor custom function int...
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:
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
- feat(tracer): instrument fetch requests (#2293) by @dreamorosi
- feat(jmespath): add parser component (#2266) by @dreamorosi
- feat(jmespath): add tree interpreter (#2265) by @dreamorosi
- feat(jmespath): add powertools functions (#2264) by @dreamorosi
- feat(jmespath): add built in functions (#2259) by @dreamorosi
- feat(jmespath): add lexer component (#2214) by @dreamorosi
- feat(jmespath): add abstract syntax tree definition (#2213) by @dreamorosi
- feat(jmespath): add Expression and utils (#2212) by @dreamorosi
🌟 Minor Changes
📜 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...
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
- feat(logger): improve regex in stack trace parsing (#2194) by @karthikeyanjp
- feat(commons): add fromBase64 helper function (#2190) by @dreamorosi
- feat(jmespath): add base types and errors (#2192) by @dreamorosi
🌟 Minor Changes
- improv(commons): expand type utils functions (#2189) by @dreamorosi
📜 Documentation updates
- chore(deps): bump the aws-sdk group with 2 updates (#2237) by @dependabot
- chore(deps-dev): bump aws-sdk from 2.1576.0 to 2.1578.0 (#2236) by @dependabot
- chore(deps): bump the aws-sdk group with 9 updates (#2227) by @dependabot
- docs(maintenance): update v1 and v2 status (#2226) by @dreamorosi
- chore(deps-dev): bump aws-sdk from 2.1575.0 to 2.1576.0 (#2222) by @dependabot
- chore(deps-dev): bump the aws-sdk group with 1 update (#2221) by @dependabot
- chore(deps-dev): bump aws-sdk from 2.1574.0 to 2.1575.0 (#2219) by @dependabot
- chore(deps-dev): bump aws-sdk from 2.1568.0 to 2.1574.0 (#2201) by @dependabot
- chore(deps): bump the aws-sdk group with 10 updates (#2180) by @dependabot
- chore(docs): fix typo in tracer.md (#2178) by @miguel-martinr
- chore(docs): add
ContextExamples
to upgrade guide (#2197) by @am29d - chore(deps-dev): bump the aws-sdk group with 3 updates (#2172) by @dependabot
- chore(deps): bump mkdocs-material from 9.5.12 to 9.5.13 in /docs (#2171) by @dependabot
- chore(deps): bump mkdocs-material from 9.5.11 to 9.5.12 in /docs (#2153) by @dependabot
- chore(deps): bump the aws-sdk group with 9 updates (#2154) by @dependabot
- chore(deps): bump squidfunk/mkdocs-material from
7be068b
to3678304
in /docs (#2169) by @dependabot
🐛 Bug and hot fixes
- fix(layers): add
createRequire
banner in esm (#2232) by @dreamorosi - fix(idempotency): transform private class fields (#2233) by @dreamorosi
🔧 Maintenance
- chore(deps): bump the aws-cdk group with 2 updates (#2238) by @dependabot
- chore(deps): bump the aws-sdk group with 2 updates (#2237) by @dependabot
- chore(deps): bump esbuild from 0.20.1 to 0.20.2 (#2239) by @dependabot
- chore(deps-dev): bump aws-sdk from 2.1576.0 to 2.1578.0 (#2236) by @dependabot
- chore(deps-dev): bump @types/node from 20.11.26 to 20.11.28 (#2235) by @dependabot
- chore(deps-dev): bump follow-redirects from 1.15.5 to 1.15.6 (#2234) by @dependabot
- chore(deps): bump the aws-sdk group with 9 updates (#2227) by @dependabot
- chore(deps-dev): bump aws-sdk from 2.1575.0 to 2.1576.0 (#2222) by @dependabot
- chore(deps-dev): bump the aws-sdk group with 1 update (#2221) by @dependabot
- chore(deps-dev): bump @types/node from 20.11.25 to 20.11.26 (#2218) by @dependabot
- chore(deps-dev): bump aws-sdk from 2.1574.0 to 2.1575.0 (#2219) by @dependabot
- chore(deps): bump the aws-cdk group with 2 updates (#2216) by @dependabot
- improv(commons): expand type utils functions (#2189) by @dreamorosi
- chore(deps): bump the aws-cdk group with 2 updates (#2202) by @dependabot
- feat(commons): add fromBase64 helper function (#2190) by @dreamorosi
- chore(deps-dev): bump typescript from 5.3.3 to 5.4.2 (#2176) by @dependabot
- chore(deps-dev): bump typedoc from 0.25.11 to 0.25.12 (#2203) by @dependabot
- chore(deps): bump aws-xray-sdk-core from 3.5.3 to 3.5.4 (#2183) by @dependabot
- chore(deps-dev): bump aws-sdk from 2.1568.0 to 2.1574.0 (#2201) by @dependabot
- chore(deps-dev): bump @types/node from 20.11.24 to 20.11.25 (#2182) by @dependabot
- chore(deps): bump the aws-sdk group with 10 updates (#2180) by @dependabot
- chore(jmespath): add package to workspace (#2185) by @dreamorosi
- chore(deps-dev): bump @types/aws-lambda from 8.10.134 to 8.10.136 (#2175) by @dependabot
- chore(deps): bump the aws-cdk group with 2 updates (#2173) by @dependabot
- chore(deps-dev): bump the aws-sdk group with 3 updates (#2172) by @dependabot
- chore(deps-dev): bump typedoc from 0.25.8 to 0.25.11 (#2174) by @dependabot
- chore(deps-dev): bump eslint from 8.56.0 to 8.57.0 (#2150) by @dependabot
- chore(deps): bump the aws-sdk group with 9 updates (#2154) by @dependabot
- chore(deps-dev): bump @types/node from 20.11.22 to 20.11.24 (#2155) by @dependabot
- chore(deps): bump vscode/devcontainers/javascript-node from
7a20ece
to4dbf8b6
in /.devcontainer (#2168) by @dependabot
This release was made possible by the following contributors:
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
- fix(tracer): modify
aws-xray-sdk-core
import for js (#2164) by @dreamorosi
This release was made possible by the following contributors:
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
- chore(docs): mark
docs/snippets
package as private (#2161) by @dreamorosi
This release was made possible by the following contributors:
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...
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
- chore(ci): create one layer artifact per region & merge (#2095) by @dreamorosi
- chore(ci): bump version to 1.18.1 (#2113) by @dreamorosi
- chore(maintenance): add core team to code owners (#2099) by @dreamorosi
- chore(deps): bump the aws-sdk group with 9 updates (#2087) by @dependabot
- chore(deps-dev): bump husky from 9.0.10 to 9.0.11 (#2069) by @dependabot
- chore(deps-dev): bump socks & ip-address (#2065) by @dreamorosi
- chore(deps-dev): bump @types/node from 20.11.16 to 20.11.17 (#2057) by @dependabot
- chore(deps-dev): bump aws-sdk from 2.1549.0 to 2.1557.0 (#2063) by @dependabot
- chore(deps-dev): bump typedoc from 0.25.7 to 0.25.8 (#2056) by @dependabot
- chore(deps): bump the aws-cdk group with 2 updates (#2054) by @dependabot
- chore(deps): bump the aws-sdk group with 9 updates (#2061) by @dependabot
- chore(deps-dev): bump lerna from 8.0.2 to 8.1.2 (#2038) by @dependabot
- chore(deps-dev): bump @typescript-eslint/parser from 6.19.1 to 6.21.0 (#2025) by @dependabot
- chore(deps): bump the aws-sdk group with 9 updates (#2037) by @dependabot
- chore(deps-dev): bump husky from 9.0.6 to 9.0.10 (#2039) by @dependabot
- chore(deps-dev): bump prettier from 3.2.4 to 3.2.5 (#2040) by @dependabot
- chore(deps-dev): bump @typescript-eslint/eslint-plugin from 6.19.1 to 6.21.0 (#2024) by @dependabot
- chore(deps-dev): bump @types/jest from 29.5.11 to 29.5.12 (#2019) by @dependabot
- chore(deps-dev): bump @types/aws-lambda from 8.10.131 to 8.10.133 (#2018) by @dependabot
- chore(deps-dev): bump lint-staged from 15.2.0 to 15.2.2 (#2026) by @dependabot
- chore(deps): bump vscode/devcontainers/javascript-node from
ff7fcaf
to7a20ece
in /.devcontainer (#2035) by @dependabot - chore(deps): bump the aws-sdk group with 9 updates (#2011) by @dependabot
- chore(deps-dev): bump @types/node from 20.11.7 to 20.11.16 (#2010) by @dependabot
- chore(deps): bump esbuild from 0.19.12 to 0.20.0 (#1988) by @dependabot
- chore(deps): bump the aws-cdk group with 2 updates (#2008) by @dependabot
- chore(deps-dev): bump aws-sdk from 2.1544.0 to 2.1549.0 (#2009) by @dependabot
- chore(deps-dev): bump axios from 1.6.6 to 1.6.7 (#1976) by @dependabot
- chore(deps-dev): bump husky from 9.0.5 to 9.0.6 (#1975) by @dependabot
- chore(deps-dev): bump aws-sdk from 2.1543.0 to 2.1544.0 (#1977) by @dependabot
- chore(deps-dev): bump @types/node from 20.11.6 to 20.11.7 (#1974) by @dependabot
- chore(deps-dev): bump husky from 9.0.3 to 9.0.5 (#1971) by @dependabot
- chore(deps): bump the aws-cdk group with 2 updates (#1972) by @dependabot
- chore(deps-dev): bump axios from 1.6.5 to 1.6.6 (#1964) by @dependabot
- chore(deps-dev): bump @types/node from 20.11.5 to 20.11.6 (#1963) by @dependabot
- chore(deps-dev): bump husky from 8.0.3 to 9.0.3 (#1962) by @dependabot
This release was made possible by the following contributors:
@am29d, @dreamorosi, @heitorlessa, @hjgraca, and @kevin-secrist
v1.18.0
Summary
This minor release introduces improvements around how the Idempotency utility handles conditional writes when used with DynamoDB as persistence layer. Additionally the release fixes an issue with expired AppConfig session tokens that affected long lived execution environments.
Idempotency: DynamoDB storage optimization
The Idempotency utility uses conditional writes to persist the idempotency state of a request. A failed conditional write signals to the utility that the request payload being processed has already been tried or is currently being processed.
Previously, condition check errors in single write operations did not return a copy of the item in the event of a condition check error. A separate read request was necessary to get the item and investigate the cause of the error.
Now that AWS introduced the ability to return a copy of the item as it was during the write attempt the Idempotency utility simplifies and lowers the cost of handling retries by removing the need to perform a separate read operation to retrieve the idempotency record of the request already processed.
Note that this feature requires you to use version v3.363.0 of the @aws-sdk/client-dynamodb
or newer together with @aws-lambda-powertools/idempotency
.
Parameters: AppConfig Session Token handling
When retrieving a configuration from AppConfig the Parameters utility retrieves a session token that can be used to retrieve the next value within 24 hours. Prior to this release the utility mistakenly assumed that the execution environment would be recycled before that time due to the Lambda timeout of 15 minutes.
For those customers who use provisioned concurrency or use the Parameters utility outside of Lambda however this was an issue as it caused the utility to fail retrieving new configurations from AppConfig due to an expired token. Starting from this release the utility keeps track of the token expiration timestamp and retrieves a new one before attempting to call AppConfig if the token has already expired.
Acknowledgements
Congrats to @daschaa, @tolutheo, and @yamatatsu for getting their first PR merged 🎉
Changes
- chore(maintenance): add overwrite to artifact arn in layer pipeline (#1970) by @dreamorosi
- chore(maintenance): group CDK cli with other CDK dependencies (#1968) by @dreamorosi
- chore(maintenance): add environment scope to npm token (#1957) by @dreamorosi
- chore(maintenance): fine tune dependabot config (#1935) by @dreamorosi
- chore(ci): add aws-sdk group and ignore middy upgrades in examples (#1893) by @am29d
- chore(ci): allow deps-dev for semantic PR (#1861) by @am29d
- chore(ci): allow dependabot PRs (#1860) by @heitorlessa
- chore(ci): [StepSecurity] Apply security best practices (#1839) by @step-security-bot
- chore(internal): broken link in boring-cyborg app (#1807) by @daschaa
- chore(ci): Update log retention for layers (#1809) by @sthulb
- chore(ci): Update permissions in workflows (#1810) by @sthulb
- chore(ci): sets base permissions on all workflows (#1801) by @sthulb
🌟New features and non-breaking changes
📜 Documentation updates
- chore(docs): bump layer version to 28 in docs (#1969) by @am29d
- chore(docs): add link to performance tuning demo (#1960) by @dreamorosi
- chore(layers): add ca-west-1 (#1836) by @am29d
- feat(idempotency): leverage new dynamodB Failed conditional writes behavior (#1779) by @tolutheo
- docs: fix typos (#1834) by @am29d
- docs: fix some typos (#1824) by @yamatatsu
- docs: fix deps and build (#1830) by @am29d
- chore(maintenance): add
--require-hashes
flag to pip installs (#1827) by @dreamorosi - chore(docs): add AppYourself reference customer (#1826) by @dreamorosi
- docs(logger): remove logEvent from required settings (#1821) by @am29d
- chore(docs): fix layer version in CDK example (#1805) by @daschaa
🐛 Bug and hot fixes
- fix(parameters): refresh AppConfig session token after 24 hrs (#1916) by @dreamorosi
🔧 Maintenance
- chore(deps-dev): bump husky from 9.0.3 to 9.0.5 (#1971) by @dependabot
- chore(deps): bump the aws-cdk group with 2 updates (#1972) by @dependabot
- chore(deps-dev): bump axios from 1.6.5 to 1.6.6 (#1964) by @dependabot
- chore(deps-dev): bump @types/node from 20.11.5 to 20.11.6 (#1963) by @dependabot
- chore(deps-dev): bump husky from 8.0.3 to 9.0.3 (#1962) by @dependabot
- chore(docs): add link to performance tuning demo (#1960) by @dreamorosi
- chore(deps): bump the aws-sdk group with 9 updates (#1959) by @dependabot
- chore(deps-dev): bump aws-sdk from 2.1540.0 to 2.1543.0 (#1958) by @dependabot
- chore(deps-dev): bump @typescript-eslint/eslint-plugin from 6.19.0 to 6.19.1 (#1948) by @dependabot
- chore(deps-dev): bump @typescript-eslint/parser from 6.19.0 to 6.19.1 (#1946) by @dependabot
- chore(deps): bump esbuild from 0.19.11 to 0.19.12 (#1952) by @dependabot
- chore(deps-dev): bump ts-jest from 29.1.1 to 29.1.2 (#1943) by @dependabot
- chore(deps-dev): bump aws-sdk from 2.1538.0 to 2.1540.0 (#1944) by @dependabot
- chore(deps): bump the aws-sdk group with 9 updates (#1940) by @dependabot
- chore(deps): bump the aws-cdk group with 1 update (#1936) by @dependabot
- chore(deps): bump the aws-sdk group with 4 updates (#1937) by @dependabot
- chore(deps): bump aws-cdk from 2.121.1 to 2.122.0 (#1938) by @dependabot
- chore(deps-dev): bump aws-sdk from 2.1537.0 to 2.1538.0 (#1933) by @dependabot
- chore(deps-dev): bump aws-sdk from 2.1536.0 to 2.1537.0 (#1926) by @dependabot
- chore(deps-dev): bump prettier from 3.2.2 to 3.2.4 (#1927) by @dependabot
- chore(deps-dev): bump @types/node from 20.11.4 to 20.11.5 (#1928) by @dependabot
- chore(deps-dev): bump lerna from 7.4.2 to 8.0.2 (#1923) by @dependabot
- chore(maintenance): fix install command for .devcontainer setup (#1924) by @am29d
- chore(deps-dev): bump @types/node from 20.11.2 to 20.11.4 (#1920) by @dependabot
- chore(deps): fix dependencies and dependabot config (#1917) by @dreamorosi
- chore(deps-dev): bump typedoc-plugin-missing-exports from 2.1.0 to 2.2.0 (#1911) by @dependabot
- chore(deps-dev): bump @types/lodash.merge from 4.6.7 to 4.6.9 (#1902) by @dependabot
- chore(deps-dev): bump @types/node from 20.11.0 to 20.11.2 (#1912) by @dependabot
- chore(deps-dev): bump @types/aws-lambda from 8.10.129 to 8.10.131 (#1901) by @dependabot
- chore(deps): bump vscode/devcontainers/javascript-node from
b01b5db
toff7fcaf
in /.devcontainer (#1892) by @dependabot - chore(deps-dev): bump aws-sdk-client-mock-jest from 3.0.0 to 3.0.1 (#1897) by @dependabot
- chore(deps-dev): bump eslint-config-prettier from 9.0.0 to 9.1.0 (#1872) by @dependabot
- chore(deps-dev): bump @types/node from 20.10.7 to 20.11.0 in /examples/cdk (#1885) by @dependabot
- chore(deps-dev): bump @types/node from 20.10.7 to 20.11.0 in /examples/sam (#1890) by @dependabot
- chore(deps-dev): bump @typescript-eslint/parser from 6.12.0 to 6.18.1 (#1896) by @dependabot
- chore(deps-dev): bump eslint-import-resolver-typescript from 3.6.0 to 3.6.1 (#1874) by @dependabot
- chore(deps-dev): bump follow-redirects from 1.15.2 to 1.15.4 (#1842) by @dependabot
- chore(deps): bump esbuild from 0.19.3 to 0.19.11 (#1868) by @dependabot
- chore(deps-dev): bump typedoc from 0.25.1 to 0.25.7 (#1869) by @dependabot
- chore(deps): bump vscode/devcontainers/javascript-node from
a20adf8
tob01b5db
in /.devcontainer (#1840) by @dependabot - chore(deps-dev): bump @aws-sdk/client-cloudwatch from 3.438.0 to 3.485.0 (#1857) by @dependabot
- chore(deps-dev): bump @types/promise-retry from 1.1.3 to 1.1.6 (#1866) by @dependabot
- chore(ci): Dependabot fine tuning (#1862) by @am29d
- chore(deps): bump constructs from 10.2.70 to 10.3.0 (#1846) by @dependabot
- chore(deps-dev): bump @types/node from 20.6.1 to 20.10.7 in /examples/cdk (#1851) by @dependabot
- chore(deps-dev): bump @types/node from 20.6.1 to 20.10.7 in /examples/sam (#1853) by @dependabot
- chore(deps): bump aws-cdk from 2.107.0 to 2.118.0 (#1854) by @dependabot
- chore(deps): bump aws-cdk-lib from 2.107.0 to 2.118.0 (#1856) by @dependabot
- docs: fix typos (#1834) by @am29d
- docs: fix some typos (#1824) by @yamatatsu
- chore(docs): add AppYourself reference customer (#1826) by @dreamorosi
This release was made possible by the following contributors:
@am29d, @daschaa, @dreamorosi, @heitorlessa, @sthulb, @tolutheo, and @yamatatsu