docs(idempotency): write utility docs (#1592)

* docs: base docs

* wip

* chore: added paths to snippets tsconfig

* chore: added page to docs menu

* docs(idempotency): utility docs

* highlights

* chore: remove CDK mention

Author: dreamorosi

Diff for: .gitignore

@@ -33,6 +33,7 @@ coverage
 
 # Python virtual environments (for running mkdocs locally)
 venv
+.venv
 
 # Static documentation site generated by Mkdocs
 site

Diff for: docs/snippets/idempotency/customizePersistenceLayer.ts

@@ -0,0 +1,35 @@
+import { makeHandlerIdempotent } from '@aws-lambda-powertools/idempotency/middleware';
+import { DynamoDBPersistenceLayer } from '@aws-lambda-powertools/idempotency/dynamodb';
+import middy from '@middy/core';
+import type { Context } from 'aws-lambda';
+import type { Request, Response } from './types';
+
+const persistenceStore = new DynamoDBPersistenceLayer({
+  tableName: 'idempotencyTableName',
+  keyAttr: 'idempotencyKey',
+  expiryAttr: 'expiresAt',
+  inProgressExpiryAttr: 'inProgressExpiresAt',
+  statusAttr: 'currentStatus',
+  dataAttr: 'resultData',
+  validationKeyAttr: 'validationKey',
+});
+
+export const handler = middy(
+  async (_event: Request, _context: Context): Promise<Response> => {
+    try {
+      // ... create payment
+
+      return {
+        paymentId: '1234567890',
+        message: 'success',
+        statusCode: 200,
+      };
+    } catch (error) {
+      throw new Error('Error creating payment');
+    }
+  }
+).use(
+  makeHandlerIdempotent({
+    persistenceStore,
+  })
+);

Diff for: docs/snippets/idempotency/makeHandlerIdempotent.ts

@@ -0,0 +1,40 @@
+import { randomUUID } from 'node:crypto';
+import { makeHandlerIdempotent } from '@aws-lambda-powertools/idempotency/middleware';
+import { DynamoDBPersistenceLayer } from '@aws-lambda-powertools/idempotency/dynamodb';
+import middy from '@middy/core';
+import type { Context } from 'aws-lambda';
+import type { Request, Response, SubscriptionResult } from './types';
+
+const persistenceStore = new DynamoDBPersistenceLayer({
+  tableName: 'idempotencyTableName',
+});
+
+const createSubscriptionPayment = async (
+  event: Request
+): Promise<SubscriptionResult> => {
+  // ... create payment
+  return {
+    id: randomUUID(),
+    productId: event.productId,
+  };
+};
+
+export const handler = middy(
+  async (event: Request, _context: Context): Promise<Response> => {
+    try {
+      const payment = await createSubscriptionPayment(event);
+
+      return {
+        paymentId: payment.id,
+        message: 'success',
+        statusCode: 200,
+      };
+    } catch (error) {
+      throw new Error('Error creating payment');
+    }
+  }
+).use(
+  makeHandlerIdempotent({
+    persistenceStore,
+  })
+);

Diff for: docs/snippets/idempotency/makeIdempotentAnyFunction.ts

@@ -0,0 +1,59 @@
+import { randomUUID } from 'node:crypto';
+import {
+  makeIdempotent,
+  IdempotencyConfig,
+} from '@aws-lambda-powertools/idempotency';
+import { DynamoDBPersistenceLayer } from '@aws-lambda-powertools/idempotency/dynamodb';
+import type { Context } from 'aws-lambda';
+import type { Request, Response, SubscriptionResult } from './types';
+
+const persistenceStore = new DynamoDBPersistenceLayer({
+  tableName: 'idempotencyTableName',
+});
+const config = new IdempotencyConfig({});
+
+const reportSubscriptionMetrics = async (
+  _transactionId: string,
+  _user: string
+): Promise<void> => {
+  // ... send notification
+};
+
+const createSubscriptionPayment = makeIdempotent(
+  async (
+    transactionId: string,
+    event: Request
+  ): Promise<SubscriptionResult> => {
+    // ... create payment
+    return {
+      id: transactionId,
+      productId: event.productId,
+    };
+  },
+  {
+    persistenceStore,
+    dataIndexArgument: 1,
+    config,
+  }
+);
+
+export const handler = async (
+  event: Request,
+  context: Context
+): Promise<Response> => {
+  config.registerLambdaContext(context);
+  try {
+    const transactionId = randomUUID();
+    const payment = await createSubscriptionPayment(transactionId, event);
+
+    await reportSubscriptionMetrics(transactionId, event.user);
+
+    return {
+      paymentId: payment.id,
+      message: 'success',
+      statusCode: 200,
+    };
+  } catch (error) {
+    throw new Error('Error creating payment');
+  }
+};

Diff for: docs/snippets/idempotency/makeIdempotentBase.ts

@@ -0,0 +1,38 @@
+import { randomUUID } from 'node:crypto';
+import { makeIdempotent } from '@aws-lambda-powertools/idempotency';
+import { DynamoDBPersistenceLayer } from '@aws-lambda-powertools/idempotency/dynamodb';
+import type { Context } from 'aws-lambda';
+import type { Request, Response, SubscriptionResult } from './types';
+
+const persistenceStore = new DynamoDBPersistenceLayer({
+  tableName: 'idempotencyTableName',
+});
+
+const createSubscriptionPayment = async (
+  event: Request
+): Promise<SubscriptionResult> => {
+  // ... create payment
+  return {
+    id: randomUUID(),
+    productId: event.productId,
+  };
+};
+
+export const handler = makeIdempotent(
+  async (event: Request, _context: Context): Promise<Response> => {
+    try {
+      const payment = await createSubscriptionPayment(event);
+
+      return {
+        paymentId: payment.id,
+        message: 'success',
+        statusCode: 200,
+      };
+    } catch (error) {
+      throw new Error('Error creating payment');
+    }
+  },
+  {
+    persistenceStore,
+  }
+);

Diff for: docs/snippets/idempotency/makeIdempotentJmes.ts

@@ -0,0 +1,51 @@
+import { randomUUID } from 'node:crypto';
+import {
+  makeIdempotent,
+  IdempotencyConfig,
+} from '@aws-lambda-powertools/idempotency';
+import { DynamoDBPersistenceLayer } from '@aws-lambda-powertools/idempotency/dynamodb';
+import type { Context } from 'aws-lambda';
+import type { Request, Response, SubscriptionResult } from './types';
+
+const persistenceStore = new DynamoDBPersistenceLayer({
+  tableName: 'idempotencyTableName',
+});
+
+const createSubscriptionPayment = async (
+  user: string,
+  productId: string
+): Promise<SubscriptionResult> => {
+  // ... create payment
+  return {
+    id: randomUUID(),
+    productId: productId,
+  };
+};
+
+// Extract the idempotency key from the request headers
+const config = new IdempotencyConfig({
+  eventKeyJmesPath: 'headers."X-Idempotency-Key"',
+});
+
+export const handler = makeIdempotent(
+  async (event: Request, _context: Context): Promise<Response> => {
+    try {
+      const payment = await createSubscriptionPayment(
+        event.user,
+        event.productId
+      );
+
+      return {
+        paymentId: payment.id,
+        message: 'success',
+        statusCode: 200,
+      };
+    } catch (error) {
+      throw new Error('Error creating payment');
+    }
+  },
+  {
+    persistenceStore,
+    config,
+  }
+);

Diff for: docs/snippets/idempotency/makeIdempotentLambdaContext.ts

@@ -0,0 +1,51 @@
+import { randomUUID } from 'node:crypto';
+import {
+  makeIdempotent,
+  IdempotencyConfig,
+} from '@aws-lambda-powertools/idempotency';
+import { DynamoDBPersistenceLayer } from '@aws-lambda-powertools/idempotency/dynamodb';
+import type { Context } from 'aws-lambda';
+import type { Request, Response, SubscriptionResult } from './types';
+
+const persistenceStore = new DynamoDBPersistenceLayer({
+  tableName: 'idempotencyTableName',
+});
+const config = new IdempotencyConfig({});
+
+const createSubscriptionPayment = makeIdempotent(
+  async (
+    transactionId: string,
+    event: Request
+  ): Promise<SubscriptionResult> => {
+    // ... create payment
+    return {
+      id: transactionId,
+      productId: event.productId,
+    };
+  },
+  {
+    persistenceStore,
+    dataIndexArgument: 1,
+    config,
+  }
+);
+
+export const handler = async (
+  event: Request,
+  context: Context
+): Promise<Response> => {
+  // Register the Lambda context to the IdempotencyConfig instance
+  config.registerLambdaContext(context);
+  try {
+    const transactionId = randomUUID();
+    const payment = await createSubscriptionPayment(transactionId, event);
+
+    return {
+      paymentId: payment.id,
+      message: 'success',
+      statusCode: 200,
+    };
+  } catch (error) {
+    throw new Error('Error creating payment');
+  }
+};

Diff for: docs/snippets/idempotency/requiredIdempotencyKey.ts

@@ -0,0 +1,20 @@
+import {
+  IdempotencyConfig,
+  makeIdempotent,
+} from '@aws-lambda-powertools/idempotency';
+import { DynamoDBPersistenceLayer } from '@aws-lambda-powertools/idempotency/dynamodb';
+
+const persistenceStore = new DynamoDBPersistenceLayer({
+  tableName: 'IdempotencyTable',
+});
+
+// Requires "user"."uid" and "orderId" to be present
+const config = new IdempotencyConfig({
+  eventKeyJmesPath: '[user.uid, orderId]',
+  throwOnNoIdempotencyKey: true,
+});
+
+export const handler = makeIdempotent((_event: unknown) => ({}), {
+  persistenceStore,
+  config,
+});

Diff for: docs/snippets/idempotency/types.ts

@@ -0,0 +1,15 @@
+type Request = {
+  user: string;
+  productId: string;
+};
+
+type Response = {
+  [key: string]: unknown;
+};
+
+type SubscriptionResult = {
+  id: string;
+  productId: string;
+};
+
+export { Request, Response, SubscriptionResult };

Diff for: docs/snippets/idempotency/workingWithCompositeKey.ts

@@ -0,0 +1,30 @@
+import { makeHandlerIdempotent } from '@aws-lambda-powertools/idempotency/middleware';
+import { DynamoDBPersistenceLayer } from '@aws-lambda-powertools/idempotency/dynamodb';
+import middy from '@middy/core';
+import type { Context } from 'aws-lambda';
+import type { Request, Response } from './types';
+
+const persistenceStore = new DynamoDBPersistenceLayer({
+  tableName: 'idempotencyTableName',
+  sortKeyAttr: 'sort_key',
+});
+
+export const handler = middy(
+  async (_event: Request, _context: Context): Promise<Response> => {
+    try {
+      // ... create payment
+
+      return {
+        paymentId: '12345',
+        message: 'success',
+        statusCode: 200,
+      };
+    } catch (error) {
+      throw new Error('Error creating payment');
+    }
+  }
+).use(
+  makeHandlerIdempotent({
+    persistenceStore,
+  })
+);

Diff for: docs/snippets/idempotency/workingWithCustomClient.ts

@@ -0,0 +1,32 @@
+import { makeIdempotent } from '@aws-lambda-powertools/idempotency';
+import { DynamoDBPersistenceLayer } from '@aws-lambda-powertools/idempotency/dynamodb';
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import type { Context } from 'aws-lambda';
+import type { Request, Response } from './types';
+
+const customDynamoDBClient = new DynamoDBClient({
+  endpoint: 'http://localhost:8000',
+});
+const persistenceStore = new DynamoDBPersistenceLayer({
+  tableName: 'idempotencyTableName',
+  awsSdkV3Client: customDynamoDBClient,
+});
+
+export const handler = makeIdempotent(
+  async (_event: Request, _context: Context): Promise<Response> => {
+    try {
+      // ... create payment
+
+      return {
+        paymentId: '12345',
+        message: 'success',
+        statusCode: 200,
+      };
+    } catch (error) {
+      throw new Error('Error creating payment');
+    }
+  },
+  {
+    persistenceStore,
+  }
+);