Merge branch 'main' into feat/metrics_custom_logger

Author: dreamorosi

docs/core/tracer.md

@@ -378,7 +378,7 @@ Tracer exposes a `getRootXrayTraceId()` method that allows you to retrieve the [
 
 ### Escape hatch mechanism
 
-You can use `tracer.provider` attribute to access all methods provided by the [AWS X-Ray SDK](https://docs.aws.amazon.com/xray-sdk-for-nodejs/latest/reference/AWSXRay.html).
+You can use `tracer.provider` attribute to access [a subset of the methods provided](https://docs.powertools.aws.dev/lambda/typescript/latest/api/classes/_aws_lambda_powertools_tracer.provider_ProviderService.ProviderService.html) by the [AWS X-Ray SDK](https://docs.aws.amazon.com/xray-sdk-for-nodejs/latest/reference/AWSXRay.html).
 
 This is useful when you need a feature available in X-Ray that is not available in the Tracer utility, for example [SQL queries tracing](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs-sqlclients.html), or [a custom logger](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs-configuration.html#xray-sdk-nodejs-configuration-logging).
 
@@ -388,6 +388,8 @@ This is useful when you need a feature available in X-Ray that is not available
     --8<-- "examples/snippets/tracer/escapeHatch.ts"
     ```
 
+If you need to access a method that is not available you can import it directly from the AWS X-Ray SDK for Node.js. Compatibility with the Tracer utility is not guaranteed.
+
 ## Testing your code
 
 Tracer is disabled by default when not running in the AWS Lambda environment - This means no code changes or environment variables to be set.

docs/utilities/idempotency.md

@@ -206,6 +206,8 @@ Similar to the `makeIdempotent` function wrapper, you can quickly make your Lamb
     --8<-- "examples/snippets/idempotency/types.ts:3:16"
     ```
 
+For the middleware to work, your Lambda function handler must return a value different from `undefined`. This is a [known limitation of the early return feature in Middy.js](https://github.com/middyjs/middy/issues/1236). If your use case requires early returns, you can use the `makeIdempotent` function wrapper instead.
+
 ### Choosing a payload subset for idempotency
 
 Use [`IdempotencyConfig`](#customizing-the-default-behavior) to instruct the idempotent decorator to only use a portion of your payload to verify whether a request is idempotent, and therefore it should not be retried. When dealing with a more elaborate payload, where parts of the payload always change, you should use the **`eventKeyJmesPath`** parameter.

examples/app/package.json

@@ -30,8 +30,8 @@
   "devDependencies": {
     "@types/aws-lambda": "^8.10.145",
     "@types/node": "22.5.4",
-    "aws-cdk": "^2.157.0",
-    "aws-cdk-lib": "^2.157.0",
+    "aws-cdk": "^2.158.0",
+    "aws-cdk-lib": "^2.158.0",
     "constructs": "^10.3.0",
     "source-map-support": "^0.5.21",
     "tsx": "^4.19.0",

layers/package.json

@@ -36,8 +36,8 @@
     "source-map-support": "^0.5.21"
   },
   "dependencies": {
-    "aws-cdk": "^2.157.0",
-    "aws-cdk-lib": "^2.157.0",
+    "aws-cdk": "^2.158.0",
+    "aws-cdk-lib": "^2.158.0",
     "esbuild": "^0.23.1"
   }
 }

package-lock.json

@@ -50,11 +50,11 @@
   },
   "homepage": "https://github.com/aws-powertools/powertools-lambda-typescript#readme",
   "devDependencies": {
-    "@biomejs/biome": "^1.8.3",
+    "@biomejs/biome": "^1.9.0",
     "@types/aws-lambda": "^8.10.145",
     "@types/jest": "^29.5.12",
     "@types/node": "^22.5.4",
-    "@vitest/coverage-v8": "^2.0.5",
+    "@vitest/coverage-v8": "^2.1.0",
     "husky": "^9.1.6",
     "jest": "^29.7.0",
     "jest-runner-groups": "^2.2.0",

package.json

@@ -1,18 +1,18 @@
-import { IdempotencyHandler } from '../IdempotencyHandler.js';
-import { IdempotencyConfig } from '../IdempotencyConfig.js';
 import {
-  cleanupMiddlewares,
   IDEMPOTENCY_KEY,
+  cleanupMiddlewares,
 } from '@aws-lambda-powertools/commons';
 import type {
-  AnyFunction,
-  IdempotencyLambdaHandlerOptions,
-} from '../types/IdempotencyOptions.js';
-import type {
+  JSONValue,
   MiddlewareLikeObj,
   MiddyLikeRequest,
-  JSONValue,
 } from '@aws-lambda-powertools/commons/types';
+import { IdempotencyConfig } from '../IdempotencyConfig.js';
+import { IdempotencyHandler } from '../IdempotencyHandler.js';
+import type {
+  AnyFunction,
+  IdempotencyLambdaHandlerOptions,
+} from '../types/IdempotencyOptions.js';
 
 /**
  * @internal
@@ -90,6 +90,11 @@ const shouldSkipIdempotency = (request: MiddyLikeRequest): boolean => {
  * ).use(makeHandlerIdempotent({ persistenceStore: dynamoDBPersistenceLayer }));
  * ```
  *
+ * For the middleware to work, your Lambda function handler must return a value different from `undefined`.
+ * This is a [known limitation of the early return feature in Middy.js](https://github.com/middyjs/middy/issues/1236).
+ *
+ * If your use case requires early returns, you can use the {@link index.makeIdempotent | makeIdempotent()} function wrapper instead.
+ *
  * @param options - Options for the idempotency middleware
  */
 const makeHandlerIdempotent = (