This utility is currently released as beta developer preview and is intended strictly for feedback and testing purposes and not for production workloads.. The version and all future versions tagged with the -beta suffix should be treated as not stable. Up until before the General Availability release we might introduce significant breaking changes and improvements in response to customers feedback. |
Powertools for AWS Lambda (TypeScript) is a developer toolkit to implement Serverless best practices and increase developer velocity.
You can use the package in both TypeScript and JavaScript code bases.
- Intro
- Key features
- Usage
- Contribute
- Roadmap
- Connect
- How to support Powertools for AWS Lambda (TypeScript)?
- Credits
- License
This package provides a utility to implement idempotency in your Lambda functions. You can either use it to wrap a function, or as Middy middleware to make your AWS Lambda handler idempotent.
The current implementation provides a persistence layer for Amazon DynamoDB, which offers a variety of configuration options. You can also bring your own persistence layer by extending the BasePersistenceLayer class.
- Prevent Lambda handler from executing more than once on the same event payload during a time window
- Ensure Lambda handler returns the same result when called with the same payload
- Select a subset of the event as the idempotency key using JMESPath expressions
- Set a time window in which records with the same payload should be considered duplicates
- Expires in-progress executions if the Lambda function times out halfway through
To get started, install the library by running:
npm install @aws-lambda-powertools/idempotencyNext, review the IAM permissions attached to your AWS Lambda function and make sure you allow the actions detailed in the documentation of the utility.
You can make any function idempotent, and safe to retry, by wrapping it using the makeFunctionIdempotent higher-order function.
The function wrapper takes a reference to the function to be made idempotent as first argument, and an object with options as second argument.
import { makeFunctionIdempotent } 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<void> => {
// your code goes here here
};
export const handler = async (
event: SQSEvent,
_context: Context
): Promise<void> => {
for (const record of event.Records) {
await makeFunctionIdempotent(processingFunction, {
dataKeywordArgument: 'transactionId',
persistenceStore,
});
}
};Note that we are specifying a dataKeywordArgument option, this tells the Idempotency utility which field(s) will be used as idempotency key.
Check the docs for more examples.
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.
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<void> => {
// your code goes here here
}
).use(
makeHandlerIdempotent({
config,
persistenceStore,
})
);Check the docs for more examples.
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.
If you are interested in contributing to this project, please refer to our Contributing Guidelines.
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.
- Powertools for AWS Lambda on Discord:
#typescript- Invite link - Email: [email protected]
Knowing which companies are using this library is important to help prioritize the project internally. If your company is using Powertools for AWS Lambda (TypeScript), you can request to have your name and logo added to the README file by raising a Support Powertools for AWS Lambda (TypeScript) (become a reference) issue.
The following companies, among others, use Powertools:
Share what you did with Powertools for AWS Lambda (TypeScript) 💞💞. Blog post, workshops, presentation, sample apps and others. Check out what the community has already shared about Powertools for AWS Lambda (TypeScript) here.
This helps us understand who uses Powertools for AWS Lambda (TypeScript) in a non-intrusive way, and helps us gain future investments for other Powertools for AWS Lambda languages. When using Layers, you can add Powertools as a dev dependency (or as part of your virtual env) to not impact the development process.
Credits for the Lambda Powertools for AWS Lambda (TypeScript) idea go to DAZN and their DAZN Lambda Powertools.
This library is licensed under the MIT-0 License. See the LICENSE file.