docs(idempotency): document keyPrefix feature (#3611)

Author: dreamorosi

Diff for: docs/utilities/idempotency.md

@@ -695,6 +695,31 @@ This means that we will raise **`IdempotencyKeyError`** if the evaluation of **`
     --8<-- "examples/snippets/idempotency/samples/workingWIthIdempotencyRequiredKeyError.json"
     ```
 
+### Customizing the idempotency key prefix
+
+!!! warning
+    Changing the idempotency key generation will invalidate existing idempotency records
+
+You can use the `keyPrefix` parameter in any of the idempotency configurations to define a custom prefix for your idempotency key. This allows you to decouple the idempotency key from the function name, which is especially useful during application refactorings.
+
+=== "Using a custom prefix with function wrapper"
+
+    ```typescript hl_lines="25"
+    --8<-- "examples/snippets/idempotency/customKeyPrefixFnWrapper.ts"
+    ```
+
+=== "Using a custom prefix with decorator"
+
+    ```typescript hl_lines="13"
+    --8<-- "examples/snippets/idempotency/customKeyPrefixDecorator.ts"
+    ```
+
+=== "Using a custom prefix with Middy.js middleware"
+
+    ```typescript hl_lines="14"
+    --8<-- "examples/snippets/idempotency/customKeyPrefixMiddleware.ts"
+    ```
+
 ### Batch integration
 
 You can easily integrate with [Batch](batch.md) utility by using idempotency wrapper around your processing function.

Diff for: examples/snippets/idempotency/customKeyPrefixDecorator.ts

@@ -0,0 +1,31 @@
+import { randomUUID } from 'node:crypto';
+import { idempotent } from '@aws-lambda-powertools/idempotency';
+import { DynamoDBPersistenceLayer } from '@aws-lambda-powertools/idempotency/dynamodb';
+import type { Context } from 'aws-lambda';
+
+const persistenceStore = new DynamoDBPersistenceLayer({
+  tableName: 'idempotencyTableName',
+});
+
+class Lambda {
+  @idempotent({
+    persistenceStore,
+    keyPrefix: 'createSubscriptionPayment',
+  })
+  async handler(event: unknown, context: Context) {
+    try {
+      // ... create payment
+
+      return {
+        paymentId: randomUUID(),
+        message: 'success',
+        statusCode: 200,
+      };
+    } catch (error) {
+      throw new Error('Error creating payment');
+    }
+  }
+}
+
+const lambda = new Lambda();
+export const handler = lambda.handler.bind(lambda);

Diff for: examples/snippets/idempotency/customKeyPrefixFnWrapper.ts

@@ -0,0 +1,27 @@
+import { randomUUID } from 'node:crypto';
+import { makeIdempotent } from '@aws-lambda-powertools/idempotency';
+import { DynamoDBPersistenceLayer } from '@aws-lambda-powertools/idempotency/dynamodb';
+
+const persistenceStore = new DynamoDBPersistenceLayer({
+  tableName: 'idempotencyTableName',
+});
+
+export const handler = makeIdempotent(
+  async () => {
+    try {
+      // ... create payment
+
+      return {
+        paymentId: randomUUID(),
+        message: 'success',
+        statusCode: 200,
+      };
+    } catch (error) {
+      throw new Error('Error creating payment');
+    }
+  },
+  {
+    persistenceStore,
+    keyPrefix: 'createSubscriptionPayment',
+  }
+);

Diff for: examples/snippets/idempotency/customKeyPrefixMiddleware.ts

@@ -0,0 +1,29 @@
+import { randomUUID } from 'node:crypto';
+import { DynamoDBPersistenceLayer } from '@aws-lambda-powertools/idempotency/dynamodb';
+import { makeHandlerIdempotent } from '@aws-lambda-powertools/idempotency/middleware';
+import middy from '@middy/core';
+
+const persistenceStore = new DynamoDBPersistenceLayer({
+  tableName: 'idempotencyTableName',
+});
+
+export const handler = middy()
+  .use(
+    makeHandlerIdempotent({
+      persistenceStore,
+      keyPrefix: 'createSubscriptionPayment',
+    })
+  )
+  .handler(async () => {
+    try {
+      // ... create payment
+
+      return {
+        paymentId: randomUUID(),
+        message: 'success',
+        statusCode: 200,
+      };
+    } catch (error) {
+      throw new Error('Error creating payment');
+    }
+  });