feat!: version 2, the ESM update

.github/actions/cached-node-modules/action.yml

@@ -4,6 +4,9 @@ inputs:
   nodeVersion: # id of input
     description: 'Node.js version to use in the cache key'
     default: '20'
+  build:
+    description: 'Whether to build the packages or not'
+    default: 'true'
 outputs:
   cache-hit:
     description: "Whether the cache was hit or not"
@@ -17,7 +20,7 @@ runs:
       shell: bash
     - name: Cache node modules
       id: cache-node-modules
-      uses: actions/cache@69d9d449aced6a2ede0bc19182fadc3a0a42d2b0 # v3.2.6
+      uses: actions/cache@13aacd865c20de90d75de3b17ebe84f7a17d57d2 # v4.0.0
       with:
         path: '**/node_modules'
         # Use the combo between node version, name, and SHA-256 hash of the lock file as cache key so that
@@ -29,8 +32,8 @@ runs:
       run: npm ci
       shell: bash
     - name: Build packages
-      # Regardless of whether the cache was hit or not, we need to build the packages.
-      #
+      # Regardless of whether the cache was hit or not, we need to build the packages, unless the caller says otherwise
+      if: inputs.build == 'true'
       # We build the shared package first, then the others in parallel to speed up the process
       # even though we could just run `npm run build` in the root folder and build them in
       # sequence, but still in the correct order.

.github/scripts/release_patch_package_json.js

@@ -44,6 +44,7 @@ const betaPackages = [];
       types,
       files,
       private,
+      type,
     } = pkgJson;
 
     let version = originalVersion;
@@ -71,6 +72,7 @@ const betaPackages = [];
       main,
       types,
       files,
+      type,
     };
 
     // Not all utilities have these fields, so only add them if they exist to avoid

.github/workflows/make-version.yml

@@ -30,9 +30,13 @@ jobs:
         uses: ./.github/actions/cached-node-modules
       - name: Version
         id: bump-version
+        run: npx lerna version --conventional-commits --no-git-tag-version --no-push --no-commit-hooks --yes
+      - name: Update user agent version
         run: |
-          npx lerna version --conventional-commits --no-git-tag-version --no-push --no-commit-hooks --yes
-          git add .
+          VERSION=$(cat lerna.json | jq .version -r)
+          echo -e "// this file is auto generated, do not modify\nexport const VERSION = '$VERSION';" > packages/commons/src/version.ts
+      - name: Stage changes
+        run: git add .
       - name: Set release version
         id: set-release-version
         run: |

.gitignore

@@ -50,4 +50,4 @@ tmp
 
 # TS build files
 tsconfig.tsbuildinfo
-.tsbuildinfo
+.tsbuildinfo

MAINTAINERS.md

@@ -1,2 +1,2 @@
 > [!IMPORTANT]
-> Maintainers' playbook moved: https://docs.powertools.aws.dev/lambda/typescript/latest/maintainers/
+> Maintainers' playbook moved: https://docs.powertools.aws.dev/lambda/typescript/latest/maintainers/

docs/core/logger.md

@@ -45,11 +45,11 @@ The library has three optional settings, which can be set via environment variab
 
 These settings will be used across all logs emitted:
 
-| Setting                | Description                                                                                                      | Environment variable            | Default Value       | Allowed Values                                         | Example Value       | Constructor parameter |
-| ---------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------- | ------------------------------------------------------ | ------------------- | --------------------- |
-| **Service name**       | Sets the name of service of which the Lambda function is part of, that will be present across all log statements | `POWERTOOLS_SERVICE_NAME`       | `service_undefined` | Any string                                             | `serverlessAirline` | `serviceName`         |
-| **Logging level**      | Sets how verbose Logger should be, from the most verbose to the least verbose (no logs)                          | `POWERTOOLS_LOG_LEVEL`          | `INFO`              | `DEBUG`, `INFO`, `WARN`, `ERROR`, `CRITICAL`, `SILENT` | `ERROR`             | `logLevel`            |
-| **Sample rate**        | Probability that a Lambda invocation will print all the log items regardless of the log level setting           | `POWERTOOLS_LOGGER_SAMPLE_RATE` | `0`                 | `0.0` to `1.0`                                         | `0.1`               | `sampleRateValue`     |
+| Setting           | Description                                                                                                      | Environment variable            | Default Value       | Allowed Values                                         | Example Value       | Constructor parameter |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------- | ------------------------------------------------------ | ------------------- | --------------------- |
+| **Service name**  | Sets the name of service of which the Lambda function is part of, that will be present across all log statements | `POWERTOOLS_SERVICE_NAME`       | `service_undefined` | Any string                                             | `serverlessAirline` | `serviceName`         |
+| **Logging level** | Sets how verbose Logger should be, from the most verbose to the least verbose (no logs)                          | `POWERTOOLS_LOG_LEVEL`          | `INFO`              | `DEBUG`, `INFO`, `WARN`, `ERROR`, `CRITICAL`, `SILENT` | `ERROR`             | `logLevel`            |
+| **Sample rate**   | Probability that a Lambda invocation will print all the log items regardless of the log level setting            | `POWERTOOLS_LOGGER_SAMPLE_RATE` | `0`                 | `0.0` to `1.0`                                         | `0.1`               | `sampleRateValue`     |
 
 See all environment variables in the [Environment variables](../index.md/#environment-variables) section.
 Check API docs to learn more about [Logger constructor options](https://docs.powertools.aws.dev/lambda/typescript/latest/api/types/_aws_lambda_powertools_logger.types.ConstructorOptions.html){target="_blank"}.
@@ -110,10 +110,10 @@ This functionality will include the following keys in your structured logs:
 === "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`.
+        We guarantee support only for Middy.js `v4.x`, that you can install it by running `npm i @middy/core@~4`.
         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="1 13"
+    ```typescript hl_lines="2 14"
     --8<-- "docs/snippets/logger/middy.ts"
     ```
 
@@ -131,7 +131,7 @@ This functionality will include the following keys in your structured logs:
 
 === "Manual"
 
-    ```typescript hl_lines="6"
+    ```typescript hl_lines="10"
     --8<-- "docs/snippets/logger/manual.ts"
     ```
 
@@ -163,7 +163,7 @@ When debugging in non-production environments, you can instruct Logger to log th
 
 === "Middy Middleware"
 
-    ```typescript hl_lines="10"
+    ```typescript hl_lines="15"
     --8<-- "docs/snippets/logger/eventMiddy.ts"
     ```
 
@@ -236,7 +236,7 @@ If you want to make sure that persistent attributes added **inside the handler f
 
 === "Middy Middleware"
 
-    ```typescript hl_lines="30"
+    ```typescript hl_lines="31"
     --8<-- "docs/snippets/logger/clearStateMiddy.ts"
     ```
 
@@ -509,23 +509,21 @@ The `createChild` method allows you to create a child instance of the Logger, wh
     }
     ```
 
-### Sampling logs
+### Sampling debug logs
 
-Use sampling when you want to print all the log items generated in your code, based on a **percentage of your concurrent/cold start invocations**.
+Use sampling when you want to dynamically change your log level to **DEBUG** based on a **percentage of your concurrent/cold start invocations**.
 
-You can do that by setting a "sample rate", a float value ranging from `0.0` (0%) to `1` (100%), by using a `POWERTOOLS_LOGGER_SAMPLE_RATE` env var or passing the `sampleRateValue` parameter in the Logger constructor.
-This number represents the probability that a Lambda invocation will print all the log items regardless of the log level setting.
-
-For example, by setting the "sample rate" to `0.5`, roughly 50% of your lambda invocations will print all the log items, including the `debug` ones.
+You can use values ranging from `0` to `1` (100%) when setting the `sampleRateValue` constructor option or `POWERTOOLS_LOGGER_SAMPLE_RATE` env var.
 
 !!! tip "When is this useful?"
-    In production, to avoid log data pollution and reduce CloudWatch costs, developers are encouraged to use the logger with `logLevel` equal to `ERROR` or `WARN`.
-    This means that only errors or warnings will be printed.
+    Let's imagine a sudden spike increase in concurrency triggered a transient issue downstream. When looking into the logs you might not have enough information, and while you can adjust log levels it might not happen again.
 
-    However, it might still be useful to print all the logs (including debug ones) of a very small percentage of invocations to have a better understanding of the behaviour of your code in production even when there are no errors.
-
-    **Sampling decision happens at the Logger initialization**. This means sampling may happen significantly more or less than depending on your traffic patterns, for example a steady low number of invocations and thus few cold starts.
-    If you want to reset the sampling decision and refresh it for each invocation, you can call the `logger.refreshSampleRateCalculation()` method at the beginning or end of your handler.
+    This feature takes into account transient issues where additional debugging information can be useful.
+
+Sampling decision happens at the Logger initialization. This means sampling may happen significantly more or less than depending on your traffic patterns, for example a steady low number of invocations and thus few cold starts.
+
+!!! note
+    Open a [feature request](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?assignees=&labels=type%2Ffeature-request%2Ctriage&projects=aws-powertools%2F7&template=feature_request.yml&title=Feature+request%3A+TITLE) if you want Logger to calculate sampling for every invocation
 
 === "handler.ts"
 
@@ -639,7 +637,7 @@ You can customize the structure (keys and values) of your log items by passing a
 
 === "handler.ts"
 
-    ```typescript hl_lines="2 5"
+    ```typescript hl_lines="2 6"
     --8<-- "docs/snippets/logger/bringYourOwnFormatterHandler.ts"
     ```
 
@@ -700,9 +698,6 @@ This is a Jest sample that provides the minimum information necessary for Logger
     --8<-- "docs/snippets/logger/unitTesting.ts"
     ```
 
-!!! tip
-    If you don't want to declare your own dummy Lambda Context, you can use [`ContextExamples.helloworldContext`](https://github.com/aws-powertools/powertools-lambda-typescript/blob/main/packages/commons/src/samples/resources/contexts/hello-world.ts#L3-L16) from [`@aws-lambda-powertools/commons`](https://www.npmjs.com/package/@aws-lambda-powertools/commons).
-
 ### Suppress logs with Jest
 
 When unit testing your code with [Jest](https://jestjs.io) you can use the `POWERTOOLS_DEV` environment variable in conjunction with the Jest `--silent` CLI option to suppress logs from Logger.

docs/core/metrics.md

@@ -49,7 +49,7 @@ npm install @aws-lambda-powertools/metrics
 
 !!! warning "Caution"
 
-    Using the Lambda [Advanced Logging Controls](...docs link) feature requires you to update your version of Powertools for AWS Lambda (TypeScript) to at least v1.15.0 to ensure metrics are reported correctly to Amazon CloudWatch Metrics.
+    Using the Lambda [Advanced Logging Controls](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-cloudwatchlogs.html#monitoring-cloudwatchlogs-advanced) feature requires you to update your version of Powertools for AWS Lambda (TypeScript) to at least v1.15.0 to ensure metrics are reported correctly to Amazon CloudWatch Metrics.
 
 ### Usage
 
@@ -253,7 +253,7 @@ See below an example of how to automatically flush metrics with the Middy-compat
 
 === "handler.ts"
 
-    ```typescript hl_lines="20"
+    ```typescript hl_lines="2 17"
     --8<-- "docs/snippets/metrics/middy.ts"
     ```
 
@@ -368,7 +368,7 @@ You can optionally capture cold start metrics with the `logMetrics` middleware o
 
 === "Middy Middleware"
 
-    ```typescript hl_lines="21"
+    ```typescript hl_lines="18"
     --8<-- "docs/snippets/metrics/captureColdStartMetricMiddy.ts"
     ```
 
@@ -398,7 +398,7 @@ You can add high-cardinality data as part of your Metrics log with the `addMetad
 
 === "handler.ts"
 
-    ```typescript hl_lines="18"
+    ```typescript hl_lines="15"
     --8<-- "docs/snippets/metrics/addMetadata.ts"
     ```
 

docs/core/tracer.md

@@ -88,10 +88,10 @@ You can quickly start by importing the `Tracer` class, initialize it outside the
 === "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`.
+        We guarantee support only for Middy.js `v4.x`, that you can install it by running `npm i @middy/core@~4`.
         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="1 14 16"
+    ```typescript hl_lines="2 15 17"
     --8<-- "docs/snippets/tracer/middy.ts"
     ```
 
@@ -197,7 +197,7 @@ You can patch all AWS SDK v2 clients by calling the `captureAWS` method:
 
 === "index.ts"
 
-    ```typescript hl_lines="6"
+    ```typescript hl_lines="7"
     --8<-- "docs/snippets/tracer/captureAWSAll.ts"
     ```
 
@@ -284,7 +284,7 @@ Alternatively, use the `captureResponse: false` option in both `tracer.captureLa
 
 === "middy.ts"
 
-    ```typescript hl_lines="17"
+    ```typescript hl_lines="18"
     --8<-- "docs/snippets/tracer/disableCaptureResponseMiddy.ts"
     ```