feat(idempotency): add support for custom key prefix

[shdq]

Summary

This allows users to define a custom static idempotency key prefix, making it easier to refactor or group functions under the same idempotency key space

Changes

This PR introduces support for customizing the idempotency key prefix in the makeIdempotent function and makeHandlerIdempotent for middleware. Previously, the key prefix was hardcoded based on the function’s location, limiting flexibility.

All three usage of lambda are covered:

• makeIdempotent function
• decorator @idempotent
• middy middleware

Examples:

const persistenceStore = new DynamoDBPersistenceLayer({
  tableName: 'idempotencyTableName',
});

const processPayment = makeIdempotent(
  async (paymentProps) => {
    // ... process your payload

    return {
      message: 'success',
      statusCode: 200,
    };
  },
  {
    persistenceStore,
    keyPrefix: 'some_custom_value', // <-- new parameter
  }
);

export const handler = async (event) => {
  // ... do something with the event
  return processPayment({
    customerId: event.customerId,
    amount: event.amount
  });
};

// OR


const config = new IdempotencyConfig({});

class MyLambda implements LambdaInterface {
  @idempotent({
    persistenceStore,
    config,
    keyPrefix: 'some_custom_value', // <-- new parameter
   })
  public async handler(_event, _context) {
    // ... process your event
    return {
      message: 'success',
      statusCode: 200,
    };
  }
}

const defaultLambda = new MyLambda();
export const handler = defaultLambda.handler.bind(defaultLambda);

// OR

export const handler = middy(
  async (event) => {
    // ... process your event
).use(
  makeHandlerIdempotent({
    persistenceStore,
    keyPrefix: 'some_custom_value', // <-- new parameter
  })
);

Issue number: closes #3515

---

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.

[dreamorosi]

Hi @shdq, hope you're doing well!

I wanted to ask if you need any help with this. If things got busy on your end it's perfectly fine, perhaps I could push a couple commits to your branch and get the PR merged next week.

[shdq]

Hey Andrea

The changes brought by this PR with the custom prefix added to:

• middleware (makeHandlerIdempotent)
• wrapper fn (makeIdempotent)
• tests for config, persistent store, wrapper/middy

If we need to cover any extra cases let me know.

Everything seems ready except for the documentation. Where should I add the docs?

I want to finalize it and merge the PR next week, so let's work closer on this one. Don't hesitate to reach out on Discord, it would be faster.

Have a great weekend!

[dreamorosi]

Thank you for the updates @shdq, I have checked out the branch locally, built the package, and tested it in a side project and could verify that everything works as expected.

I have left a couple comments on the tests, they're all minor and only around test naming for better consistency/clarity.

In terms of documentation, I would add a new section before or after this one. If you think there's a better order I'm open for suggestions, but overall I'd keep it under "Advanced".

When it comes to content, you can copy and adapt the one from the Python docs, which is here. Feel free to simplify the code sample to focus it on the new feature.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
6.8% Duplication on New Code

See analysis details on SonarQube Cloud

[dreamorosi]

Thank you for addressing my comments, I'll open a new PR to add the docs separately.