docs(idempotency): utility docs

Author: dreamorosi

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,
+  })
+);

docs/snippets/idempotency/disablingUtility.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,
+  })
+);

docs/snippets/idempotency/jestMockDynamoDB.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');
+  }
+};

docs/snippets/idempotency/localDynamoDB.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,
+  }
+);

docs/snippets/idempotency/makeFunctionIdempotentBase.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,
+  }
+);

docs/snippets/idempotency/makeHandlerIdempotent.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');
+  }
+};