The idempotency package for the Powertools for AWS Lambda (TypeScript) library. It provides options to make your Lambda functions idempotent and safe to retry.
npm install @aws-lambda-powertools/idempotency
BasePersistenceLayer class.
sh
npm i @aws-lambda-powertools/idempotency @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
`
Next, review the IAM permissions attached to your AWS Lambda function and make sure you allow
the actions detailed
in the documentation of the utility.
$3
You can make any function idempotent, and safe to retry, by wrapping it using the makeIdempotent higher-order
function.
The makeIdempotent function takes a reference to the function to be made idempotent as first argument, and an object
with options as second argument.
When you wrap your Lambda handler function, the utility uses the content of the event parameter to handle the
idempotency logic.
`ts
import {makeIdempotent} from '@aws-lambda-powertools/idempotency';
import {DynamoDBPersistenceLayer} from '@aws-lambda-powertools/idempotency/dynamodb';
import type {Context, APIGatewayProxyEvent} from 'aws-lambda';
const persistenceStore = new DynamoDBPersistenceLayer({
tableName: 'idempotencyTableName',
});
const myHandler = async (
event: APIGatewayProxyEvent,
_context: Context
): Promise => {
// your code goes here here
};
export const handler = makeIdempotent(myHandler, {
persistenceStore,
});
`
You can also use the makeIdempotent function to wrap any other arbitrary function, not just Lambda handlers.
`ts
import {makeIdempotent} from '@aws-lambda-powertools/idempotency';
import {DynamoDBPersistenceLayer} from '@aws-lambda-powertools/idempotency/dynamodb';
import type {Context, SQSEvent, SQSRecord} from 'aws-lambda';
const persistenceStore = new DynamoDBPersistenceLayer({
tableName: 'idempotencyTableName',
});
const processingFunction = async (payload: SQSRecord): Promise => {
// your code goes here here
};
const processIdempotently = makeIdempotent(processingFunction, {
persistenceStore,
});
export const handler = async (
event: SQSEvent,
_context: Context
): Promise => {
for (const record of event.Records) {
await processIdempotently(record);
}
};
`
If your function has multiple arguments, you can use the dataIndexArgument option to specify which argument should be
used as the idempotency key.
`ts
import {makeIdempotent} from '@aws-lambda-powertools/idempotency';
import {DynamoDBPersistenceLayer} from '@aws-lambda-powertools/idempotency/dynamodb';
import type {Context, SQSEvent, SQSRecord} from 'aws-lambda';
const persistenceStore = new DynamoDBPersistenceLayer({
tableName: 'idempotencyTableName',
});
const processingFunction = async (payload: SQSRecord, customerId: string): Promise => {
// your code goes here here
};
const processIdempotently = makeIdempotent(processingFunction, {
persistenceStore,
// this tells the utility to use the second argument ( customerId) as the idempotency key
dataIndexArgument: 1,
});
export const handler = async (
event: SQSEvent,
_context: Context
): Promise => {
for (const record of event.Records) {
await processIdempotently(record, 'customer-123');
}
};
`
Note that you can also specify a JMESPath expression in the Idempotency config object to select a subset of the event
payload as the idempotency key. This is useful when dealing with payloads that contain timestamps or request ids.
`ts
import {makeIdempotent, IdempotencyConfig} from '@aws-lambda-powertools/idempotency';
import {DynamoDBPersistenceLayer} from '@aws-lambda-powertools/idempotency/dynamodb';
import type {Context, APIGatewayProxyEvent} from 'aws-lambda';
const persistenceStore = new DynamoDBPersistenceLayer({
tableName: 'idempotencyTableName',
});
const myHandler = async (
event: APIGatewayProxyEvent,
_context: Context
): Promise => {
// your code goes here here
};
export const handler = makeIdempotent(myHandler, {
persistenceStore,
config: new IdempotencyConfig({
eventKeyJmespath: 'requestContext.identity.user',
}),
});
`
Additionally, you can also use one of
the JMESPath built-in functions
like powertools_json() to decode keys and use parts of the payload as the idempotency key.
`ts
import {makeIdempotent, IdempotencyConfig} from '@aws-lambda-powertools/idempotency';
import {DynamoDBPersistenceLayer} from '@aws-lambda-powertools/idempotency/dynamodb';
import type {Context, APIGatewayProxyEvent} from 'aws-lambda';
const persistenceStore = new DynamoDBPersistenceLayer({
tableName: 'idempotencyTableName',
});
const myHandler = async (
event: APIGatewayProxyEvent,
_context: Context
): Promise => {
// your code goes here here
};
export const handler = makeIdempotent(myHandler, {
persistenceStore,
config: new IdempotencyConfig({
eventKeyJmespath: 'powertools_json(body).["user", "productId"]',
}),
});
`
Check the docs for more examples.
$3
You can make any function idempotent, and safe to retry, by decorating it using the @idempotent decorator.
`ts
import {idempotent} from '@aws-lambda-powertools/idempotency';
import {LambdaInterface} from '@aws-lambda-powertools/commons';
import {DynamoDBPersistenceLayer} from '@aws-lambda-powertools/idempotency/dynamodb';
import type {Context, APIGatewayProxyEvent} from 'aws-lambda';
const persistenceStore = new DynamoDBPersistenceLayer({
tableName: 'idempotencyTableName',
});
class MyHandler extends LambdaInterface {
@idempotent({persistenceStore: dynamoDBPersistenceLayer})
public async handler(
event: APIGatewayProxyEvent,
context: Context
): Promise {
// your code goes here here
}
}
const handlerClass = new MyHandler();
export const handler = handlerClass.handler.bind(handlerClass);
`
Using the same decorator, you can also make any other arbitrary method idempotent.
`ts
import {idempotent} from '@aws-lambda-powertools/idempotency';
import {LambdaInterface} from '@aws-lambda-powertools/commons';
import {DynamoDBPersistenceLayer} from '@aws-lambda-powertools/idempotency/dynamodb';
import type {Context} from 'aws-lambda';
const persistenceStore = new DynamoDBPersistenceLayer({
tableName: 'idempotencyTableName',
});
class MyHandler extends LambdaInterface {
public async handler(
event: unknown,
context: Context
): Promise {
for (const record of event.Records) {
await this.processIdempotently(record);
}
}
@idempotent({persistenceStore: dynamoDBPersistenceLayer})
private async process(record: unknown): Promise {
// process each code idempotently
}
}
const handlerClass = new MyHandler();
export const handler = handlerClass.handler.bind(handlerClass);
`
The decorator configuration options are identical with the ones of the makeIdempotent function. Check
the docs for more examples.
$3
If instead you use Middy, you can use the makeHandlerIdempotent middleware. When using the middleware your Lambda
handler becomes idempotent.
By default, the Idempotency utility will use the full event payload to create an hash and determine if a request is
idempotent, and therefore it should not be retried.
When dealing with a more elaborate payload, where parts of the payload always change you should use
the IdempotencyConfig object to instruct the utility to only use a portion of your payload. This is useful when
dealing with payloads that contain timestamps or request ids.
`ts
import {IdempotencyConfig} from '@aws-lambda-powertools/idempotency';
import {makeHandlerIdempotent} from '@aws-lambda-powertools/idempotency/middleware';
import {DynamoDBPersistenceLayer} from '@aws-lambda-powertools/idempotency/dynamodb';
import middy from '@middy/core';
import type {Context, APIGatewayProxyEvent} from 'aws-lambda';
const persistenceStore = new DynamoDBPersistenceLayer({
tableName: 'idempotencyTableName',
});
const config = new IdempotencyConfig({
hashFunction: 'md5',
useLocalCache: false,
expiresAfterSeconds: 3600,
throwOnNoIdempotencyKey: false,
eventKeyJmesPath: 'headers.idempotency-key',
});
export const handler = middy(
async (_event: APIGatewayProxyEvent, _context: Context): Promise => {
// your code goes here here
}
).use(
makeHandlerIdempotent({
config,
persistenceStore,
})
);
`
Check the docs for more examples.
$3
You can use a DynamoDB Table to store the idempotency information. This enables you to keep track of the hash key,
payload, status for progress, expiration, and much more.
You can customize most of the configuration options of the table, i.e the names of the attributes.
See
the API documentation
for more details.
Contribute
If you are interested in contributing to this project, please refer to our Contributing Guidelines.
Roadmap
The roadmap of Powertools for AWS Lambda (TypeScript) is driven by customers’ demand.
Help us prioritize upcoming functionalities or utilities by upvoting existing RFCs and feature requests, or creating new ones, in this GitHub repository.
Connect
- Powertools for AWS Lambda on Discord: #typescript` - Invite link