RFC: Powertools for AWS (TypeScript) v2

[dreamorosi]

Is this related to an existing feature request or issue?

No response

Which Powertools for AWS Lambda (TypeScript) utility does this relate to?

Other

Summary

As already indicated in the public roadmap, in the coming months we will be releasing a new major version.

This will allow us to both introduce new features as well as quality of life improvements that might require breaking changes or otherwise special attention.

Use case

The next major release will have two goals:

• Introduce new features that require breaking changes
• Improve the three existing core utilities with practices that we have learned but haven't applied to avoid changes

The two areas that will definitely require breaking changes are:

• ES Modules support (#521): adding this will require changes in the way we bundle & export modules, for this reason we will classify as breaking change even though the imports and interface might remain equivalent
• Improving Logger (#1261, #1136, #1500, TBC): there are a series of changes that we want to make to improve Logger and make it more powerful and extensible. To do so we will have to refactor the internals of the utility which might impact some advanced users in a breaking way.

In addition to the above we are also going to take the opportunity to improve other areas of the codebase. Some of these changes might also require breaking changes. For each one of them we are committed to consider the tradeoffs and keep this issue updated as we investigate.

Proposal

All the work for this release will happen in a separate branch feat/v2, this will allow us to publish alpha releases to the npm registry independently from the main version (1.x). This will allow customers to get early access to the new features and optionally start applying the required changes or simply give feedback on the new items.

Quick summary

Item	Issue	Status	Code change required	Notes
ES Modules support	#521	✅
Drop Node.js 14 support	#1686	✅
Tracer capture sync methods	#1204	❌		no demand
Logger format all attributes	#1261	✅	Yes
Logger observability providers	#1500	✅
Logger widen arguments types	#1777	❌		more feedback needed
Tracer captureLambdaHandler higher order function	#1833	❌		more feedback needed
Logger sampling - dynamically change to debug	#1136	✅	Yes
Logger exotic types - support Set and Map	#1649	❌		closed in favor of #1776
JMESPath functions	#1298	🚧
Remove createTracer & createLogger helpers	#1721	✅	Yes
Remove events and context samples from commons	#1354	✅	tests only
Support arm64 Lambda Layer	#1374	✅
Isolate imports for middleware in core utilities	#1759	✅	Yes
Revisit types & interfaces for Logger	#1729	✅	Yes
Revisit types & interfaces for Metrics	#1731	✅	Yes
Revisit types & interfaces for Tracer	#1730	✅	Yes
Create upgrade guide in docs	#1983	🚧
Create automation for next pre-releases	#1717	✅
Create automation to publish v2 docs under next	#1718	✅
Experiment with tslib runtime helpers	#1674	❌		see issue for more info

Legend for Status column:

• ✅ Completed
• 🚧 Work in Progress
• ❌ Canceled / rescheduled to future release
• 🗓Backlog

Out of scope

The following items will not be part of this milestone:

• Correlation ID support #129
• New utilities (i.e. Validation, Parser, Event Handler)[^1]

[^1]: We will continue working on feature parity in parallel, but their release is not tied to this milestone.

Potential challenges

Nothing is perfect and the plan laid out above is somewhat ambitious, for this reason if some unforeseen blocker comes up we might decide to reprioritize and exclude some issues from the milestone.

Dependencies and Integrations

No response

Alternative solutions

No response

Acknowledgment

• [x] This feature request meets Powertools for AWS Lambda (TypeScript) Tenets
• [ ] Should this be considered in other Powertools for AWS Lambda languages? i.e. Python, Java, and .NET

Future readers

Please react with 👍 and your use case to help us understand customer demand.

[buggy]

I haven't spent nearly enough time looking at decorators but are there any compatibility issues we should be looking at? TypeScript 5.0 added support for the stage 3 proposal and my basic understanding is that this replaced the earlier experimental implemenatation.

[dreamorosi]

I haven't spent nearly enough time looking at decorators but are there any compatibility issues we should be looking at? TypeScript 5.0 added support for the stage 3 proposal and my basic understanding is that this replaced the earlier experimental implemenatation.

If you are already using Powertools' decorators, moving to TS 5.x while using the same compilerOptions that you were using before, namely "experimentalDecorators": true, won't require any change.

As you mentioned TS 5.x introduced a new implementation of the feature which brings changes in the decorators signature. In order to opt-in into the feature you have to remove or turn off experimentalDecorators in your configs. If you keep the setting on TypeScript will continue using the pre-5.x version/implementation.

From our side, we have evaluated moving to the new signature/implementation, however we have decided not to follow through for the time being because esbuild, which is extensively used in both CDK and SAM as well as our repo, doesn't support the new implementation.

For this reason, we have moved the project to 5.x (this is already merged in main and available in the last two releases) and kept the experimentalDecorators setting enabled. The PR where I introduced the change has a more detailed explanation of what I mentioned above: https://github.com/aws-powertools/powertools-lambda-typescript/pull/1672#issue-1892910420

[antstanley]

Any thoughts on publishing the in progress work on v2 under a beta tag on NPM? Good way to get broader feedback on the enhancements.

[antstanley]

Oh wait.. I see #1719 has been merged, but I don't see it published on npm https://www.npmjs.com/package/@aws-lambda-powertools/logger?activeTab=versions

That PR was merged to main, which means feat/v2 doesn't have the workflows, where they kinda need to be...

[dreamorosi]

Hey @antstanley, in order to trigger the workflow using the dispatch event, the file must be on the default branch, which for us is main.

From the docs:

To trigger the workflow_dispatch event, your workflow must be in the default branch

Once there, we can select a branch on which to run it, which in this case will be feat/v2 (see screenshot below): .

We don't publish nightly builds to npm, so it's expected that you don't see the new version published yet.

I'm planning on running a few more tests tomorrow and as soon as the integration tests are passing I'll run the workflow and publish the first alpha of the v2 line under the next tag.

As soon as it's done I'll report back here, and likely also on other channels.

[dreamorosi]

Hi everyone, we have finally published the first alpha release for this new version 🎉

The packages are available on npm under the next tag, meaning that you can download them by running: npm i @aws-lambda-powertools/<PACKAGE_NAME>@next.

If you try any of them and find anything that doesn't work or it's not clear, please let us know by opening an issue.

Tomorrow I'll also post some release notes to detail all the changes.

[dreamorosi]

We are happy to share that we are planning on publishing v2 under the latest tag next week!

We have also created an upgrade guide that lists all the changes required to use the new version: https://docs.powertools.aws.dev/lambda/typescript/latest/upgrade/

[github-actions[bot]]

⚠️ COMMENT VISIBILITY WARNING ⚠️

This issue is now closed. Please be mindful that future comments are hard for our team to see.

If you need more assistance, please either tag a team member or open a new issue that references this one.

If you wish to keep having a conversation with other community members under this issue feel free to do so.

[github-actions[bot]]

This is now released under v2.0.0 version!