or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cache-persistence.mdconfiguration.mddecorator.mddynamodb-persistence.mderrors.mdfunction-wrapper.mdindex.mdmiddleware.mdtypes.md
tile.json

tessl/npm-aws-lambda-powertools--idempotency

Idempotency utility for AWS Lambda functions that prevents duplicate executions by tracking request payloads in DynamoDB or cache stores, with support for function wrappers, decorators, and Middy middleware.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@aws-lambda-powertools/idempotency@2.29.x

To install, run

npx @tessl/cli install tessl/npm-aws-lambda-powertools--idempotency@2.29.0

index.mddocs/

AWS Lambda Powertools Idempotency

The idempotency package provides utilities to make AWS Lambda functions and arbitrary functions idempotent and safe to retry. It prevents duplicate executions by tracking request payloads in persistence stores like DynamoDB or Redis/Valkey.

Package Information

  • Package Name: @aws-lambda-powertools/idempotency
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @aws-lambda-powertools/idempotency @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb

Core Imports

import { makeIdempotent, idempotent, IdempotencyConfig } from '@aws-lambda-powertools/idempotency';
import { DynamoDBPersistenceLayer } from '@aws-lambda-powertools/idempotency/dynamodb';
import { CachePersistenceLayer } from '@aws-lambda-powertools/idempotency/cache';
import { makeHandlerIdempotent } from '@aws-lambda-powertools/idempotency/middleware';

For CommonJS:

const { makeIdempotent, idempotent, IdempotencyConfig } = require('@aws-lambda-powertools/idempotency');
const { DynamoDBPersistenceLayer } = require('@aws-lambda-powertools/idempotency/dynamodb');
const { CachePersistenceLayer } = require('@aws-lambda-powertools/idempotency/cache');
const { makeHandlerIdempotent } = require('@aws-lambda-powertools/idempotency/middleware');

Basic Usage

import { makeIdempotent } from '@aws-lambda-powertools/idempotency';
import { DynamoDBPersistenceLayer } from '@aws-lambda-powertools/idempotency/dynamodb';
import type { Context, APIGatewayProxyEvent } from 'aws-lambda';

// Create a persistence store
const persistenceStore = new DynamoDBPersistenceLayer({
  tableName: 'idempotencyTable',
});

// Make your Lambda handler idempotent
const myHandler = async (
  event: APIGatewayProxyEvent,
  context: Context
): Promise<{ statusCode: number; body: string }> => {
  // Your business logic here
  return {
    statusCode: 200,
    body: JSON.stringify({ message: 'Success' }),
  };
};

export const handler = makeIdempotent(myHandler, { persistenceStore });

Architecture

The idempotency package is built around several key components:

  • Integration Patterns: Three ways to add idempotency - function wrappers (makeIdempotent), decorators (@idempotent), and Middy middleware (makeHandlerIdempotent)
  • Persistence Layers: Pluggable storage backends including DynamoDB and Redis/Valkey cache stores, with a base class for custom implementations
  • Configuration System: IdempotencyConfig class for fine-tuning behavior including JMESPath expressions, caching, expiry, and validation
  • Record Management: IdempotencyRecord class tracks execution state (INPROGRESS, COMPLETED, EXPIRED) with automatic expiry handling
  • Error Handling: Comprehensive error types for different failure scenarios including concurrent execution, missing keys, and validation failures

Capabilities

Function Wrapper

Make any function idempotent using the makeIdempotent higher-order function. Works with Lambda handlers and arbitrary functions.

function makeIdempotent<Func extends AnyFunction>(
  fn: Func,
  options: ItempotentFunctionOptions<Parameters<Func>>
): (...args: Parameters<Func>) => ReturnType<Func>;

type ItempotentFunctionOptions<T extends Array<any>> = T[1] extends Context
  ? IdempotencyLambdaHandlerOptions
  : IdempotencyLambdaHandlerOptions & {
      dataIndexArgument?: number;
    };

interface IdempotencyLambdaHandlerOptions {
  persistenceStore: BasePersistenceLayer;
  config?: IdempotencyConfig;
  keyPrefix?: string;
}

Function Wrapper

Decorator

Use the @idempotent decorator to make class methods idempotent. Ideal for TypeScript class-based Lambda handlers.

function idempotent(
  options: ItempotentFunctionOptions<Parameters<AnyFunction>>
): (
  target: unknown,
  propertyKey: string,
  descriptor: PropertyDescriptor
) => PropertyDescriptor;

Decorator

Middy Middleware

Integrate idempotency with Middy middleware framework for Lambda handlers.

function makeHandlerIdempotent(
  options: IdempotencyLambdaHandlerOptions
): MiddlewareLikeObj;

interface MiddlewareLikeObj {
  before: (request: MiddyLikeRequest) => unknown;
  after: (request: MiddyLikeRequest) => Promise<void>;
  onError: (request: MiddyLikeRequest) => Promise<void>;
}

Middy Middleware

DynamoDB Persistence

Store idempotency records in Amazon DynamoDB with extensive configuration options for table attributes and behavior.

class DynamoDBPersistenceLayer extends BasePersistenceLayer {
  constructor(config: DynamoDBPersistenceOptions);
}

interface DynamoDBPersistenceOptions {
  tableName: string;
  keyAttr?: string;
  sortKeyAttr?: string;
  staticPkValue?: string;
  statusAttr?: string;
  expiryAttr?: string;
  inProgressExpiryAttr?: string;
  dataAttr?: string;
  validationKeyAttr?: string;
  awsSdkV3Client?: DynamoDBClient;
  clientConfig?: DynamoDBClientConfig;
}

DynamoDB Persistence

Cache Persistence

Store idempotency records in Redis or Valkey cache stores for high-performance scenarios.

class CachePersistenceLayer extends BasePersistenceLayer {
  constructor(options: CachePersistenceOptions);
}

interface CachePersistenceOptions extends BasePersistenceAttributes {
  client: CacheClient;
}

interface CacheClient {
  get(name: string): Promise<CacheValue | null>;
  set(name: CacheValue, value: unknown, options?: unknown): Promise<CacheValue | null>;
  del(keys: string[]): Promise<number>;
}

Cache Persistence

Configuration

Customize idempotency behavior with the IdempotencyConfig class, including JMESPath expressions, caching, expiry, hash functions, and payload validation.

class IdempotencyConfig {
  constructor(config: IdempotencyConfigOptions);

  public eventKeyJmesPath: string;
  public expiresAfterSeconds: number;
  public hashFunction: string;
  public jmesPathOptions: JMESPathParsingOptions;
  public lambdaContext?: Context;
  public maxLocalCacheSize: number;
  public payloadValidationJmesPath?: string;
  public throwOnNoIdempotencyKey: boolean;
  public responseHook?: ResponseHook;
  public useLocalCache: boolean;

  public isEnabled(): boolean;
  public registerLambdaContext(context: Context): void;
}

interface IdempotencyConfigOptions {
  eventKeyJmesPath?: string;
  payloadValidationJmesPath?: string;
  jmesPathOptions?: Functions;
  throwOnNoIdempotencyKey?: boolean;
  expiresAfterSeconds?: number;
  useLocalCache?: boolean;
  maxLocalCacheSize?: number;
  hashFunction?: string;
  lambdaContext?: Context;
  responseHook?: ResponseHook;
}

Configuration

Error Classes

Comprehensive error types for handling different idempotency failure scenarios.

class IdempotencyUnknownError extends Error {}
class IdempotencyItemAlreadyExistsError extends IdempotencyUnknownError {
  public existingRecord?: IdempotencyRecord;
}
class IdempotencyItemNotFoundError extends IdempotencyUnknownError {}
class IdempotencyAlreadyInProgressError extends IdempotencyUnknownError {
  public existingRecord?: IdempotencyRecord;
}
class IdempotencyInvalidStatusError extends IdempotencyUnknownError {}
class IdempotencyValidationError extends IdempotencyUnknownError {
  public existingRecord?: IdempotencyRecord;
}
class IdempotencyInconsistentStateError extends IdempotencyUnknownError {}
class IdempotencyPersistenceLayerError extends IdempotencyUnknownError {}
class IdempotencyKeyError extends IdempotencyUnknownError {}

Note: IdempotencyPersistenceConsistencyError is used internally by the cache persistence layer but is not exported from the main package.

Error Classes

Types

Core type definitions for idempotency options, persistence configuration, and record management.

Type Definitions

Constants

const IdempotencyRecordStatus: {
  readonly INPROGRESS: "INPROGRESS";
  readonly COMPLETED: "COMPLETED";
  readonly EXPIRED: "EXPIRED";
};

const PERSISTENCE_ATTRIBUTE_KEY_MAPPINGS: {
  readonly statusAttr: "status";
  readonly expiryAttr: "expiration";
  readonly inProgressExpiryAttr: "in_progress_expiration";
  readonly dataAttr: "data";
  readonly validationKeyAttr: "validation";
};