From d4378605b192740e4d82513aa8500e3e238bb57c Mon Sep 17 00:00:00 2001 From: Andrea Amorosi Date: Wed, 1 Nov 2023 02:06:45 +0100 Subject: [PATCH 1/2] docs(maintenance): add clarification about async decorators --- docs/core/logger.md | 3 ++- docs/core/metrics.md | 5 ++--- docs/core/tracer.md | 15 ++++++++++----- docs/utilities/idempotency.md | 7 +++++-- 4 files changed, 19 insertions(+), 11 deletions(-) diff --git a/docs/core/logger.md b/docs/core/logger.md index 1db08f0839..c23e06ece5 100644 --- a/docs/core/logger.md +++ b/docs/core/logger.md @@ -119,7 +119,8 @@ 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. + Powertools decorators can only be attached to async class methods and follow the experimetal decorators proposal implementation enabled via the `experimentalDecorators` compiler option in your `tsconfig.json`. If you want to inject + the context of a synchronous handler you can use the manual approach. ```typescript hl_lines="8" --8<-- "docs/snippets/logger/decorator.ts" diff --git a/docs/core/metrics.md b/docs/core/metrics.md index 925fa6d6cc..3e82c58898 100644 --- a/docs/core/metrics.md +++ b/docs/core/metrics.md @@ -212,7 +212,7 @@ 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. + Powertools decorators can only be attached to async class methods and follow the experimetal decorators proposal implementation enabled via the `experimentalDecorators` compiler option in your `tsconfig.json`. ```typescript hl_lines="12" --8<-- "docs/snippets/metrics/defaultDimensionsDecorator.ts" @@ -277,8 +277,7 @@ 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. + Powertools decorators can only be attached to async class methods and follow the experimetal decorators proposal implementation enabled via the `experimentalDecorators` compiler option in your `tsconfig.json`. 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..1bbb44f447 100644 --- a/docs/core/tracer.md +++ b/docs/core/tracer.md @@ -98,7 +98,8 @@ 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. + Powertools decorators can only be attached to async class methods and follow the experimetal decorators proposal implementation enabled via the `experimentalDecorators` compiler option in your `tsconfig.json`. If you want to trace + a synchronous handler method you can use the manual instrumentation 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" + !!! info + Powertools decorators can only be attached to async class methods and follow the experimetal decorators proposal implementation enabled via the `experimentalDecorators` compiler option in your `tsconfig.json`. If you want to trace + a function that is not a class method or that is not asynchronous, you can use the 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..9a77e4afc7 100644 --- a/docs/utilities/idempotency.md +++ b/docs/utilities/idempotency.md @@ -164,6 +164,9 @@ 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 + Powertools decorators can only be attached to async class methods and follow the experimetal decorators proposal implementation enabled via the `experimentalDecorators` compiler option in your `tsconfig.json`. + === "index.ts" ```typescript hl_lines="17" @@ -183,8 +186,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. From df0f2df50e346e73f4b957110c4012cab3ff65c4 Mon Sep 17 00:00:00 2001 From: Andrea Amorosi Date: Wed, 1 Nov 2023 02:31:12 +0100 Subject: [PATCH 2/2] docs(maintenance): add clarification about async decorators --- docs/core/logger.md | 6 +++--- docs/core/metrics.md | 10 ++++++---- docs/core/tracer.md | 12 ++++++------ docs/utilities/idempotency.md | 3 ++- 4 files changed, 17 insertions(+), 14 deletions(-) diff --git a/docs/core/logger.md b/docs/core/logger.md index c23e06ece5..1cc37a50ba 100644 --- a/docs/core/logger.md +++ b/docs/core/logger.md @@ -118,9 +118,9 @@ This functionality will include the following keys in your structured logs: === "Decorator" - !!! info - Powertools decorators can only be attached to async class methods and follow the experimetal decorators proposal implementation enabled via the `experimentalDecorators` compiler option in your `tsconfig.json`. If you want to inject - the context of a synchronous handler you can use the manual approach. + !!! 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 3e82c58898..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 async class methods and follow the experimetal decorators proposal implementation enabled via the `experimentalDecorators` compiler option in your `tsconfig.json`. + !!! 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,8 +277,9 @@ See below an example of how to automatically flush metrics with the Middy-compat #### Using the class decorator -!!! info - Powertools decorators can only be attached to async class methods and follow the experimetal decorators proposal implementation enabled via the `experimentalDecorators` compiler option in your `tsconfig.json`. +!!! 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 1bbb44f447..29f3f8a109 100644 --- a/docs/core/tracer.md +++ b/docs/core/tracer.md @@ -97,9 +97,9 @@ You can quickly start by importing the `Tracer` class, initialize it outside the === "Decorator" - !!! info - Powertools decorators can only be attached to async class methods and follow the experimetal decorators proposal implementation enabled via the `experimentalDecorators` compiler option in your `tsconfig.json`. If you want to trace - a synchronous handler method you can use the manual instrumentation instead. + !!! 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" @@ -157,9 +157,9 @@ You can trace other class methods using the `captureMethod` decorator or any arb === "Decorator" - !!! info - Powertools decorators can only be attached to async class methods and follow the experimetal decorators proposal implementation enabled via the `experimentalDecorators` compiler option in your `tsconfig.json`. If you want to trace - a function that is not a class method or that is not asynchronous, you can use the manual instrumentation instead. + !!! 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" diff --git a/docs/utilities/idempotency.md b/docs/utilities/idempotency.md index 9a77e4afc7..b1a5b009be 100644 --- a/docs/utilities/idempotency.md +++ b/docs/utilities/idempotency.md @@ -165,7 +165,8 @@ 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 - Powertools decorators can only be attached to async class methods and follow the experimetal decorators proposal implementation enabled via the `experimentalDecorators` compiler option in your `tsconfig.json`. + 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"