From a1a2022131e892c6f0e790e62ed0fdc3ff70b45c Mon Sep 17 00:00:00 2001
From: Andrea Amorosi <dreamorosi@gmail.com>
Date: Mon, 17 Feb 2025 11:28:19 +0100
Subject: [PATCH] docs(idempotency): document keyPrefix feature

---
 docs/utilities/idempotency.md                 | 25 +++++++++++++++
 .../idempotency/customKeyPrefixDecorator.ts   | 31 +++++++++++++++++++
 .../idempotency/customKeyPrefixFnWrapper.ts   | 27 ++++++++++++++++
 .../idempotency/customKeyPrefixMiddleware.ts  | 29 +++++++++++++++++
 4 files changed, 112 insertions(+)
 create mode 100644 examples/snippets/idempotency/customKeyPrefixDecorator.ts
 create mode 100644 examples/snippets/idempotency/customKeyPrefixFnWrapper.ts
 create mode 100644 examples/snippets/idempotency/customKeyPrefixMiddleware.ts

diff --git a/docs/utilities/idempotency.md b/docs/utilities/idempotency.md
index 878f06042c..fde149ebbb 100644
--- a/docs/utilities/idempotency.md
+++ b/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 --git a/examples/snippets/idempotency/customKeyPrefixDecorator.ts b/examples/snippets/idempotency/customKeyPrefixDecorator.ts
new file mode 100644
index 0000000000..407e328ade
--- /dev/null
+++ b/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 --git a/examples/snippets/idempotency/customKeyPrefixFnWrapper.ts b/examples/snippets/idempotency/customKeyPrefixFnWrapper.ts
new file mode 100644
index 0000000000..0395ff3e9f
--- /dev/null
+++ b/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 --git a/examples/snippets/idempotency/customKeyPrefixMiddleware.ts b/examples/snippets/idempotency/customKeyPrefixMiddleware.ts
new file mode 100644
index 0000000000..9505ec75ea
--- /dev/null
+++ b/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');
+    }
+  });