chore: address feedback

Author: dreamorosi

docs/features/idempotency.md

@@ -162,13 +162,6 @@ The function this example has two arguments, note that while wrapping it with th
 
 You can also use the `@idempotent` decorator to make your Lambda handler idempotent, similar to the `makeIdempotent` function wrapper.
 
-!!! info
-    The class method decorators in this project follow the experimental implementation enabled via the [`experimentalDecorators` compiler option](https://www.typescriptlang.org/tsconfig#experimentalDecorators) in TypeScript.
-
-    Additionally, they are implemented to decorate async methods. When decorating a synchronous one, the decorator replaces its implementation with an async one causing the caller to have to `await` the now decorated method.
-
-    If this is not the desired behavior, you can use one of the other patterns to make your logic idempotent.
-
 === "index.ts"
 
     ```typescript hl_lines="17"
@@ -181,15 +174,8 @@ You can also use the `@idempotent` decorator to make your Lambda handler idempot
     --8<-- "examples/snippets/idempotency/types.ts"
     ```
 
-You can use the decorator on your Lambda handler or on any function that returns a response to make it idempotent. This is useful when you want to make a specific logic idempotent, for example when your Lambda handler performs multiple side effects and you only want to make a specific one idempotent.
-The configuration options for the `@idempotent` decorator are the same as the ones for the `makeIdempotent` function wrapper.
-
 ### MakeHandlerIdempotent Middy middleware
 
-!!! tip "A note about Middy"
-    We guarantee support for Middy.js `v4.x` through `v6.x` versions.
-    Check their docs to learn more about [Middy and its middleware stack](https://middy.js.org/docs/intro/getting-started){target="_blank"} as well as [best practices when working with Powertools](https://middy.js.org/docs/integrations/lambda-powertools#best-practices){target="_blank"}.
-
 If you are using [Middy.js](https://middy.js.org){target="_blank"} as your middleware engine, you can use the `makeHandlerIdempotent` middleware to make your Lambda handler idempotent.
 
 Similar to the `makeIdempotent` function wrapper, you can quickly make your Lambda handler idempotent by initializing the `DynamoDBPersistenceLayer` class and using it with the `makeHandlerIdempotent` middleware.

docs/features/logger.md

@@ -115,23 +115,12 @@ This functionality will include the following keys in your structured logs:
 
 === "Middy Middleware"
 
-    !!! tip "A note about Middy"
-        We guarantee support for Middy.js `v4.x` through `v6.x` versions.
-        Check their docs to learn more about [Middy and its middleware stack](https://middy.js.org/docs/intro/getting-started){target="_blank"} as well as [best practices when working with Powertools](https://middy.js.org/docs/integrations/lambda-powertools#best-practices){target="_blank"}.
-
     ```typescript hl_lines="2 14"
     --8<-- "examples/snippets/logger/middy.ts"
     ```
 
 === "Decorator"
 
-    !!! note
-        The class method decorators in this project follow the experimental implementation enabled via the [`experimentalDecorators` compiler option](https://www.typescriptlang.org/tsconfig#experimentalDecorators) in TypeScript.
-
-        Additionally, they are implemented to decorate async methods. When decorating a synchronous one, the decorator replaces its implementation with an async one causing the caller to have to `await` the now decorated method.
-
-        If this is not the desired behavior, you can call the `logger.injectLambdaContext()` method directly in your handler.
-
     ```typescript hl_lines="8"
     --8<-- "examples/snippets/logger/decorator.ts"
     ```

docs/features/metrics.md

@@ -201,10 +201,6 @@ You can add default dimensions to your metrics by passing them as parameters in
 
 === "Middy middleware"
 
-    !!! tip "A note about Middy"
-        We guarantee support for Middy.js `v4.x` through `v6.x` versions.
-        Check their docs to learn more about [Middy and its middleware stack](https://middy.js.org/docs/intro/getting-started){target="_blank"} as well as [best practices when working with Powertools](https://middy.js.org/docs/integrations/lambda-powertools#best-practices){target="_blank"}.
-
     ```typescript hl_lines="24-26"
     --8<-- "examples/snippets/metrics/defaultDimensionsMiddy.ts"
     ```
@@ -217,13 +213,6 @@ You can add default dimensions to your metrics by passing them as parameters in
 
 === "with logMetrics decorator"
 
-    !!! note
-        The class method decorators in this project follow the experimental implementation enabled via the [`experimentalDecorators` compiler option](https://www.typescriptlang.org/tsconfig#experimentalDecorators) in TypeScript.
-
-        Additionally, they are implemented to decorate async methods. When decorating a synchronous one, the decorator replaces its implementation with an async one causing the caller to have to `await` the now decorated method.
-
-        If this is not the desired behavior, you can use the `logMetrics` middleware instead.
-
     ```typescript hl_lines="12"
     --8<-- "examples/snippets/metrics/defaultDimensionsDecorator.ts"
     ```

docs/features/tracer.md

@@ -153,21 +153,12 @@ You can quickly start by importing the `Tracer` class, initialize it outside the
 
 === "Middy Middleware"
 
-    !!! tip "A note about Middy"
-        We guarantee support for Middy.js `v4.x` through `v6.x` versions.
-        Check their docs to learn more about [Middy and its middleware stack](https://middy.js.org/docs/intro/getting-started){target="_blank"} as well as [best practices when working with Powertools](https://middy.js.org/docs/integrations/lambda-powertools#best-practices){target="_blank"}.
-
     ```typescript hl_lines="2 15 17"
     --8<-- "examples/snippets/tracer/middy.ts"
     ```
 
 === "Decorator"
 
-    !!! note
-        The class method decorators in this project follow the experimental implementation enabled via the [`experimentalDecorators` compiler option](https://www.typescriptlang.org/tsconfig#experimentalDecorators) in TypeScript.
-
-        Additionally, they are implemented to decorate async methods. When decorating a synchronous one, the decorator replaces its implementation with an async one causing the caller to have to `await` the now decorated method.
-
     ```typescript hl_lines="8"
     --8<-- "examples/snippets/tracer/decorator.ts"
     ```
@@ -185,7 +176,7 @@ When using the `captureLambdaHandler` decorator or middleware, Tracer performs t
 * Handles the lifecycle of the subsegment
 * Creates a `ColdStart` annotation to easily filter traces that have had an initialization overhead
 * Creates a `Service` annotation to easily filter traces that have a specific service name
-* Captures any response, or full exceptions generated by the handler, and include them as tracing metadata
+* Captures any response, or full exceptions generated by the handler, and includes them as tracing metadata
 
 ### Annotations & Metadata
 

docs/features/validation.md

@@ -34,11 +34,6 @@ The `@validator` decorator is a class method decorator that you can use to valid
 
 If the validation fails, we will throw a `SchemaValidationError`.
 
-??? note "A note on class method decorators"
-    The class method decorators in this project follow the experimental implementation enabled via the [`experimentalDecorators` compiler option](https://www.typescriptlang.org/tsconfig#experimentalDecorators) in TypeScript. We will add support for the newer Stage 3 decorators proposal in the next major release.
-
-    All our decorators assume that the method they are decorating is an async method. This means that even when decorating a synchronous method, it will return a promise. If this is not the desired behavior, you can use one of the other patterns to validate your payloads.
-
 === "gettingStartedDecorator.ts"
 
     ```typescript hl_lines="1 11-14"

docs/getting-started/lambda-layers.md

@@ -11,7 +11,7 @@ You can add our layer both in the [AWS Lambda Console _(under `Layers`)_](https:
 
 ### Layer ARNs
 
-We publish the Lambda Layer for Powertools for AWS Lambda (TypeScript) in all commercial regions and AWS GovCloud (US) regions.
+We publish the Lambda Layer for Powertools for AWS Lambda in all commercial regions and AWS GovCloud (US) regions.
 
 ???+ tip "Spotted a missing region?"
 
@@ -89,6 +89,30 @@ Change `{aws::region}` to your AWS region, e.g. `eu-west-1`, and run the followi
 
 ```bash title="AWS CLI command to download Lambda Layer content"
 aws lambda get-layer-version-by-arn --arn arn:aws:lambda:{aws::region}:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24 --region {aws::region}
+
+# output
+{  
+    "Content": {,
+        "Location": "https://awslambda-eu-west-1-layers.s3.eu-west-1.amazonaws.com/...",
+        "CodeSha256": "gwGIE8w0JckdDeDCTX6FbWObb2uIDwgiaAq78gMWDyA=",
+        "CodeSize": 3548324
+    },
+    "LayerArn": "arn:aws:lambda:eu-west-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2",
+    "LayerVersionArn": "arn:aws:lambda:eu-west-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24",
+    "Description": "Powertools for AWS Lambda (TypeScript) version 2.18.0",
+    "CreatedDate": "2025-04-08T07:38:30.424+0000",
+    "Version": 24,
+    "CompatibleRuntimes": [
+        "nodejs18.x",
+        "nodejs20.x",
+        "nodejs22.x"
+    ],
+    "LicenseInfo": "MIT-0",
+    "CompatibleArchitectures": [
+        "arm64",
+        "x86_64"
+    ]
+}
 ```
 
 ### How to use with Infrastructure as Code
@@ -112,7 +136,7 @@ aws lambda get-layer-version-by-arn --arn arn:aws:lambda:{aws::region}:094274105
           `arn:aws:lambda:${Stack.of(this).region}:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24`
         );
         
-        new Function(this, 'Function', {
+        new NodejsFunction(this, 'Function', {
           runtime: Runtime.NODEJS_22_X,
           // Add the Layer to a Lambda function
           layers: [powertoolsLayer],
@@ -137,9 +161,9 @@ aws lambda get-layer-version-by-arn --arn arn:aws:lambda:{aws::region}:094274105
     });
     ```
 
-    Check the [documentation](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs.BundlingOptions.html#externalmodules) for more details.
+    Check the AWS CDK `NodeJsFunction` [documentation](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs.BundlingOptions.html#externalmodules) for more details.  
 
-    You can also use AWS SSM Parameter Store to dynamically add Powertools for AWS Lambda and resolve the Layer ARN from SSM Parameter Store in your code, allowing you to pin to `latest` or a specific Powertools for AWS Lambda version.
+    You can also use AWS SSM Parameter Store to dynamically resolve the Layer ARN from SSM Parameter Store and add the toolkit in your code, allowing you to pin to `latest` or a specific Powertools for AWS version.  
 
     ```typescript hl_lines="5 15-17"
     import { Stack } from 'aws-cdk-lib';
@@ -161,7 +185,7 @@ aws lambda get-layer-version-by-arn --arn arn:aws:lambda:{aws::region}:094274105
           })
         );
         
-        new Function(this, 'Function', {
+        new NodejsFunction(this, 'Function', {
           runtime: Runtime.NODEJS_22_X,
           // Add the Layer to a Lambda function
           layers: [powertoolsLayer],

docs/getting-started/navigating-the-toolkit.md

@@ -1,21 +1,19 @@
 ---
 title: Typescript Settings
-description: Configuration settings for using Powertools with TypeScript
+description: Configuration settings for using with TypeScript
 ---
 
 <!-- markdownlint-disable MD043 -->
 
 While you can use the toolkit with JavaScript, using TypeScript is recommended.
 
-The toolkit is written in TypeScript, and the type definitions are included in the package. This means you can take advantage of TypeScript's static typing and other features when using it.
-
-We officially support TypeScript 5.0 and later, and our development is done using the latest version of TypeScript. We recommend using the latest version of TypeScript to take advantage of the latest features and improvements.
+The toolkit is written in TypeScript with bundled type definitions. We officially support TypeScript 5.0+ and recommend using the latest version to benefit from all features and improvements.
 
 ## TypeScript Configuration
 
-The toolkit should work with most TypeScript configurations. The only requirement is that `experimentalDecorators` is set to `true` if you are using class method decorators. This is because we only support the legacy decorator proposal for now. We will support the new decorator proposal in the next major version of Powertools for AWS Lambda (TypeScript).
+If you use class method decorators, you must set `experimentalDecorators: true` in your tsconfig.json. This is because we currently support only the legacy decorator syntax. Support for the new decorator syntax will come in our next major release.  
 
-If you are looking for a starting point, the following `tsconfig.json` file is a good place to start. It includes the recommended settings along with some modern TypeScript features.
+The following `tsconfig.json` file is a good place to start and includes the recommended settings along with some modern TypeScript features.
 
 ```json
 {

docs/getting-started/typescript-settings.md

@@ -0,0 +1,49 @@
+---
+title: Usage patterns
+description: Getting to know the Powertools for AWS Lambda toolkit
+---
+
+<!-- markdownlint-disable MD043 -->
+
+Powertools for AWS Lambda (TypeScript) is a collection of utilities designed to help you build serverless applications on AWS.
+
+The toolkit is modular, so you can pick and choose the utilities you need for your application, but also combine them for a complete solution for your serverless applications.  
+
+## Patterns
+
+Many of the utilities provided can be used with different patterns, depending on your preferences and the structure of your code.
+
+### Class Method Decorator
+
+If you prefer writing your business logic using Object-Oriented Programming (OOP) and TypeScript Classes, the Class Method decorator pattern is a good fit. This approach lets you decorate class methods with Powertools utilities, applying their functionality with minimal code changes.
+
+This pattern works well when you want to integrate Powertools for AWS into an existing codebase without significant refactoring and with no additional runtime dependencies.
+
+!!! note
+    This approach relies on TypeScript's experimental decorator feature, see [TypeScript Settings](./typescript-settings.md) for more information.
+
+```ts
+---8<-- "examples/snippets/getting-started/patterns-decorator.ts"
+```
+
+All our decorators assume that the method they are decorating is asynchronous. This means that even when decorating a synchronous method, they will return a promise. If this is not the desired behavior, you can use one of the other patterns.
+
+### Middy.js Middleware
+
+If your existing codebase relies on the [Middy.js](https://middy.js.org/docs/) middleware engine, you can use the Powertools for AWS Lambda (TypeScript) middleware to integrate with your existing code. This approach is similar to the Class Method decorator pattern but uses the Middy.js middleware engine to apply Powertools utilities.
+
+!!! note
+    We guarantee support for Middy.js `v4.x` through `v6.x` versions.
+    Check Middy.js docs to learn more about [best practices](https://middy.js.org/docs/integrations/lambda-powertools#best-practices){target="_blank"} when working with Powertools for AWS middlewares.
+
+```ts
+---8<-- "examples/snippets/getting-started/patterns-middyjs.ts"
+```
+
+### Functional Approach
+
+If you prefer a more functional programming style, you can use the Powertools for AWS Lambda (TypeScript) utilities directly in your code without decorators or middleware. This approach is more verbose but provides the most control over how the utilities are applied.
+
+```ts
+---8<-- "examples/snippets/getting-started/patterns-functional.ts"
+```

docs/getting-started/usage-patterns.md

@@ -18,6 +18,8 @@ You can use Powertools for AWS Lambda in both TypeScript and JavaScript code bas
 
     Adopt one, a few, or all industry practices. **Progressively**.
 
+    [:octicons-arrow-right-24: All features](./features/index.md)
+
 - :heart:{ .lg .middle } __Support this project__
 
     ---