From fab61101c5a8b658a723f4f65ad8160f5a6ccc08 Mon Sep 17 00:00:00 2001 From: Andrea Amorosi Date: Thu, 2 Nov 2023 17:03:46 +0100 Subject: [PATCH] docs(maintenance): add clarification about async decorators (#1778) * docs(maintenance): add clarification about async decorators * docs(maintenance): add clarification about async decorators --- docs/core/logger.md | 5 +++-- docs/core/metrics.md | 11 ++++++----- docs/core/tracer.md | 17 +++++++++++------ docs/utilities/idempotency.md | 8 ++++++-- 4 files changed, 26 insertions(+), 15 deletions(-) diff --git a/docs/core/logger.md b/docs/core/logger.md index 1db08f0839..1cc37a50ba 100644 --- a/docs/core/logger.md +++ b/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 --git a/docs/core/metrics.md b/docs/core/metrics.md index 925fa6d6cc..a3804b742d 100644 --- a/docs/core/metrics.md +++ b/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 --git a/docs/core/tracer.md b/docs/core/tracer.md index c8dab4003c..29f3f8a109 100644 --- a/docs/core/tracer.md +++ b/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,7 +197,7 @@ 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" ``` @@ -200,7 +205,7 @@ If you're looking to shave a few microseconds, or milliseconds depending on your === "index.ts" - ```typescript hl_lines="5" + ```typescript hl_lines="6" --8<-- "docs/snippets/tracer/captureAWS.ts" ``` diff --git a/docs/utilities/idempotency.md b/docs/utilities/idempotency.md index dc58487016..b1a5b009be 100644 --- a/docs/utilities/idempotency.md +++ b/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.