docs(maintenance): add clarification about async decorators (#1778)

* docs(maintenance): add clarification about async decorators

* docs(maintenance): add clarification about async decorators

Author: dreamorosi

Diff for: docs/core/logger.md

@@ -118,8 +118,9 @@ This functionality will include the following keys in your structured logs:
 
 === "Decorator"
 
-    !!! info
-        Powertools decorators can only be attached to class methods and follow the experimetal decorators proposal implementation found in TypeScript 4.x. As such, you need to enable the `experimentalDecorators` compiler option in your `tsconfig.json` file to use them.
+    !!! 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 in a way that fits asynchronous methods. When decorating a synchronous method, the decorator replaces its implementation with an asynchronous 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<-- "docs/snippets/logger/decorator.ts"

Diff for: docs/core/metrics.md

@@ -211,8 +211,9 @@ You can add default dimensions to your metrics by passing them as parameters in
 
 === "with logMetrics decorator"
 
-    !!! info
-        Powertools decorators can only be attached to class methods and follow the experimetal decorators proposal implementation found in TypeScript 4.x. As such, you need to enable the `experimentalDecorators` compiler option in your `tsconfig.json` file to use them.
+    !!! 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 in a way that fits asynchronous methods. When decorating a synchronous method, the decorator replaces its implementation with an asynchronous 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<-- "docs/snippets/metrics/defaultDimensionsDecorator.ts"
@@ -276,9 +277,9 @@ See below an example of how to automatically flush metrics with the Middy-compat
 
 #### Using the class decorator
 
-!!! info
-    Decorators can only be attached to a class declaration, method, accessor, property, or parameter. Therefore, if you prefer to write your handler as a standard function rather than a Class method, check the [middleware](#using-a-middleware) or [manual](#manually) method sections instead.  
-    See the [official TypeScript documentation](https://www.typescriptlang.org/docs/handbook/decorators.html) for more details.
+!!! 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 in a way that fits asynchronous methods. When decorating a synchronous method, the decorator replaces its implementation with an asynchronous 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.
 
 The `logMetrics` decorator of the metrics utility can be used when your Lambda handler function is implemented as method of a Class.
 

Diff for: docs/core/tracer.md

@@ -97,8 +97,9 @@ You can quickly start by importing the `Tracer` class, initialize it outside the
 
 === "Decorator"
 
-    !!! info
-        Powertools decorators can only be attached to class methods and follow the experimetal decorators proposal implementation found in TypeScript 4.x. As such, you need to enable the `experimentalDecorators` compiler option in your `tsconfig.json` file to use them.
+    !!! 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 in a way that fits asynchronous methods. When decorating a synchronous method, the decorator replaces its implementation with an asynchronous 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 instead.
 
     ```typescript hl_lines="8"
     --8<-- "docs/snippets/tracer/decorator.ts"
@@ -152,10 +153,14 @@ When using the `captureLambdaHandler` decorator or middleware, Tracer performs t
 
 ### Methods
 
-You can trace other Class methods using the `captureMethod` decorator or any arbitrary function using manual instrumentation.
+You can trace other class methods using the `captureMethod` decorator or any arbitrary asynchronous function using manual instrumentation.
 
 === "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 in a way that fits asynchronous methods. When decorating a synchronous method, the decorator replaces its implementation with an asynchronous one causing the caller to have to `await` the now decorated method.
+        If this is not the desired behavior, you can use manual instrumentation instead.
+
     ```typescript hl_lines="8"
     --8<-- "docs/snippets/tracer/captureMethodDecorator.ts"
     ```
@@ -181,7 +186,7 @@ You can patch any AWS SDK clients by calling the `captureAWSv3Client` method:
 
 === "index.ts"
 
-    ```typescript hl_lines="5"
+    ```typescript hl_lines="6"
     --8<-- "docs/snippets/tracer/captureAWSv3.ts"
     ```
 
@@ -192,15 +197,15 @@ You can patch all AWS SDK v2 clients by calling the `captureAWS` method:
 
 === "index.ts"
 
-    ```typescript hl_lines="5"
+    ```typescript hl_lines="6"
     --8<-- "docs/snippets/tracer/captureAWSAll.ts"
     ```
 
 If you're looking to shave a few microseconds, or milliseconds depending on your function memory configuration, you can patch only specific AWS SDK v2 clients using `captureAWSClient`:
 
 === "index.ts"
 
-    ```typescript hl_lines="5"
+    ```typescript hl_lines="6"
     --8<-- "docs/snippets/tracer/captureAWS.ts"
     ```
 

Diff for: docs/utilities/idempotency.md

@@ -164,6 +164,10 @@ 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 in a way that fits asynchronous methods. When decorating a synchronous method, the decorator replaces its implementation with an asynchronous 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"
@@ -183,8 +187,8 @@ The configuration options for the `@idempotent` decorator are the same as the on
 ### MakeHandlerIdempotent Middy middleware
 
 !!! tip "A note about Middy"
-        Currently we support only Middy `v3.x` that you can install it by running `npm i @middy/core@~3`.
-        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"}.
+    Currently we support only Middy `v3.x` that you can install it by running `npm i @middy/core@~3`.
+    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](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.