improv(idempotency): expose record status & expiry config + make DynamoDB Client optional

[dreamorosi]

Description of your changes

As discussed in the linked issue this PR targets three areas of the Idempotency package. All the change aim at improving the DX for customers who decide to bring their own persistence layer, the documentation on how to actually write your own persistence layer will be addressed in a future PR.

DynamoDB Client

The DynamoDBPersistenceLayer relies on two AWS SDK modules: @aws-sdk/client-dynamodb and @aws-sdk/lib-dynamodb.

Before this PR the latter was listed as dependency while the other was only a development dependency. This mean that one was installed automatically upon installing the Idempotency utility while the other was to be installed manually by customers.

This PR marks both modules as devDependencies so that both must be installed explicitly by customers. This not only is in line with all other Powertools utilities, but also allows customers developing their own persistence layers to avoid installing an unnecessary dependency.

A third AWS SDK module (@aws-sdk/util-base64-node) is still listed as regular dependency, this is because the module is used to generate idempotency keys regardless of the persistence store used, so the module is considered as required.

This PR also introduces the concept of peerDependencies (learn more). This allows us to tell npm which versions of these optional dependencies the utility is compatible with. If customers try to install a version outside the range npm will emit a warning and exit the process.

IdempotencyRecordStatus as constant

The IdempotencyRecordStatus object is a map/dictionary of value that facilitate working with the states that an idempotency record can assume throughout its lifecycle:

const IdempotencyRecordStatus = {
  INPROGRESS: 'INPROGRESS',
  COMPLETED: 'COMPLETED',
  EXPIRED: 'EXPIRED',
} as const;

Before this PR the object was included as part of the types folder even though it's not a type. When building custom providers the dictionary must be imported, however doing so from an import like @aws-lambda-powertools/idempotency/types can be confusing.

This PR moves the object to the constants file and exposes it via the default export: @aws-lambda-powertools/idempotency. In doing so, the PR also modifies all the occurrences of imports throughout the package - this has caused the diff to include more files than expected.

getExpiresAfterSeconds() method

expiresAfterSeconds is a private property of the BasePersistenceLayer class. The value is configurable when initializing a new persistence layer and indicates the amount of time a record is kept around for idempotency - this is also known as ttl.

The class uses this value when creating a new IdempotencyRecord, this is fine for persistence stores like DynamoDB that use one of the items attributes as ttl key. Some other stores instead set the property either or both at the time of instantiating a new client or when writing an item.

In order to facilitate the former case, this PR exposes the property via a new getExpiresAfterSeconds() method that can be used by classes that extend the BasePersistenceLayer to get the value before seeing any record.

Related issues, RFCs

Issue number: #1678

Checklist

• My changes meet the tenets criteria
• I have performed a self-review of my own code
• I have commented my code where necessary, particularly in areas that should be flagged with a TODO, or hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my change is effective and works
• The PR title follows the conventional commit semantics

Breaking change checklist

Is it a breaking change?: NO

• I have documented the migration process
• I have added, implemented necessary warnings (if it can live side by side)

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[sonarqubecloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
0.0% Duplication