docs(maintenance): update examples to v2

[dreamorosi]

Description of your changes

Note

While the number of files changed is high, more than half of these files were deleted. Additionally, I would suggest reviewers to focus on the following paths examples/app/functions/*, examples/app/cdk/*, examples/app/template.yml which are the most important ones, all other changes are mainly config/and references.

This PR updates the example application in the repository to a new structure and adopts v2 of our toolkit.

Before this PR we had two folders under the examples directory, one for SAM (examples/sam) and one for CDK (examples/cdk). Besides the configuration files, and the way the template is defined, the code of the two examples was identical (as copy-pasted).

This required us to make double effort every time we wanted to make a change, so for this reason I am removing one of the two directories and renaming the other to simply examples/app.

This new directory contains the source code of the samples under examples/app/functions and the templates to deploy it both via CDK (examples/app/cdk/*) and SAM (examples/app/template.yml). The README file has been edited to highlight to readers that they can choose one method or the other to deploy the sample but that in either case the end result will be roughly the same.

Besides the changes above, the sample itself has been overhauled to include all utilities and also to showcase different usage patterns and techniques that customers building Lambda functions with TypeScript together with Powertools can draw from.

The main component of the sample remains a REST API with three endpoints:

• POST / -> functions/put-item.ts - write an item to the table
• GET / -> functions/get-all-items.ts - scan the first page of the items table
• GET /[item-id] -> functions/get-by-id.ts - get a specific item from the table

Each one of the three functions above uses one of the instrumentation techniques that we support: manual instrumentation, Middy.js middlewares, and TypeScript Class Decorators. The functions are mostly the same as they were before this PR except for changes related to improving Powertools usage to make it closer to real world usage and following best practices.

Of these functions, the first one (write an item to the table) has been made idempotent, and specifically the "put item" operation now is safe to retry. This was done by adopting the Idempotency utility.

Also in this same function we demonstrate the Parameters utility together with top-level await to fetch the name of the idempotency table from SSM. This is not strictly necessary as the table name could've been passed as environment variable, but customers in a real world use case would not necessarily have the idempotency table in the same stack as the function and also it's a way to showcase the utility.

In addition to the changes above, I have also enabled the stream on the items table and added a new function used to process it. This function uses the Batch Processing utility and demonstrates how to use the logger and tracer on the record handler function.

Of the four functions, two are bundled as CJS and two as ESM. Between both the CJS and ESM pairs, one function uses our Lambda Layers and another bundles its dependencies. This addresses all the usage patterns that we currently supports and gives us a platform to quickly baseline our code manually.

Each one of the functions applies optimized build configurations based on their format (i.e. minify, sources, main fields, tree-shaking, etc.), and the codebase is written using the recent TypeScript features like hash aliases as well as module structure that encourages tree shaking.

Both the CDK and SAM templates have now extensive comments that explain the purpose of each component in the stack.

All references to the uuid API that were present in the previous version of the sample were removed.

Related issues, RFCs

Issue number: #1103

Checklist

• My changes meet the tenets criteria
• I have performed a self-review of my own code
• I have commented my code where necessary, particularly in areas that should be flagged with a TODO, or hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my change is effective and works
• The PR title follows the conventional commit semantics

Breaking change checklist

Is it a breaking change?: NO

• I have documented the migration process
• I have added, implemented necessary warnings (if it can live side by side)

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[hjgraca]

Great work!

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
No data about Coverage
0.0% Duplication on New Code

See analysis details on SonarCloud