feat(idempotency): support for Valkey- and Redis OSS-compatible cache (#3896)

Co-authored-by: Andrea Amorosi <dreamorosi@gmail.com>
Co-authored-by: Leandro Damascena <lcdama@amazon.pt>

Author: 3 people

package-lock.json

@@ -52,6 +52,14 @@
       "import": "./lib/esm/types/DynamoDBPersistence.js",
       "require": "./lib/cjs/types/DynamoDBPersistence.js"
     },
+    "./cache": {
+      "import": "./lib/esm/persistence/CachePersistenceLayer.js",
+      "require": "./lib/cjs/persistence/CachePersistenceLayer.js"
+    },
+    "./cache/types": {
+      "import": "./lib/esm/types/CachePersistence.js",
+      "require": "./lib/cjs/types/CachePersistence.js"
+    },
     "./middleware": {
       "import": "./lib/esm/middleware/makeHandlerIdempotent.js",
       "require": "./lib/cjs/middleware/makeHandlerIdempotent.js"
@@ -75,6 +83,14 @@
         "lib/cjs/types/DynamoDBPersistence.d.ts",
         "lib/esm/types/DynamoDBPersistence.d.ts"
       ],
+      "cache": [
+        "lib/cjs/persistence/CachePersistenceLayer.d.ts",
+        "lib/esm/persistence/CachePersistenceLayer.d.ts"
+      ],
+      "cache/types": [
+        "lib/cjs/types/CachePersistence.d.ts",
+        "lib/esm/types/CachePersistence.d.ts"
+      ],
       "middleware": [
         "lib/cjs/middleware/makeHandlerIdempotent.d.ts",
         "lib/esm/middleware/makeHandlerIdempotent.d.ts"
@@ -104,7 +120,9 @@
   "peerDependencies": {
     "@aws-sdk/client-dynamodb": ">=3.x",
     "@aws-sdk/lib-dynamodb": ">=3.x",
-    "@middy/core": "4.x || 5.x || 6.x"
+    "@middy/core": "4.x || 5.x || 6.x",
+    "@redis/client": "^5.0.1",
+    "@valkey/valkey-glide": "^1.3.4"
   },
   "peerDependenciesMeta": {
     "@aws-sdk/client-dynamodb": {
@@ -115,6 +133,12 @@
     },
     "@middy/core": {
       "optional": true
+    },
+    "@redis/client": {
+      "optional": true
+    },
+    "@valkey/valkey-glide": {
+      "optional": true
     }
   },
   "keywords": [

packages/idempotency/package.json

@@ -1,3 +1,4 @@
+import type { BasePersistenceAttributes } from './types/BasePersistenceLayer.js';
 /**
  * Number of times to retry a request in case of `IdempotencyInconsistentStateError`
  *
@@ -20,4 +21,22 @@ const IdempotencyRecordStatus = {
   EXPIRED: 'EXPIRED',
 } as const;
 
-export { IdempotencyRecordStatus, MAX_RETRIES };
+/**
+ * Base persistence attribute key names for persistence layers
+ */
+const PERSISTENCE_ATTRIBUTE_KEY_MAPPINGS: Record<
+  keyof Required<BasePersistenceAttributes>,
+  string
+> = {
+  statusAttr: 'status',
+  expiryAttr: 'expiration',
+  inProgressExpiryAttr: 'in_progress_expiration',
+  dataAttr: 'data',
+  validationKeyAttr: 'validation',
+} as const;
+
+export {
+  IdempotencyRecordStatus,
+  MAX_RETRIES,
+  PERSISTENCE_ATTRIBUTE_KEY_MAPPINGS,
+};

packages/idempotency/src/constants.ts

@@ -113,6 +113,16 @@ class IdempotencyKeyError extends IdempotencyUnknownError {
   }
 }
 
+/**
+ * Error with the persistence layer's consistency, needs to be removed
+ */
+class IdempotencyPersistenceConsistencyError extends IdempotencyUnknownError {
+  public constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'IdempotencyPersistenceConsistencyError';
+  }
+}
+
 export {
   IdempotencyUnknownError,
   IdempotencyItemAlreadyExistsError,
@@ -122,5 +132,6 @@ export {
   IdempotencyValidationError,
   IdempotencyInconsistentStateError,
   IdempotencyPersistenceLayerError,
+  IdempotencyPersistenceConsistencyError,
   IdempotencyKeyError,
 };

packages/idempotency/src/errors.ts

@@ -12,4 +12,7 @@ export {
 export { IdempotencyConfig } from './IdempotencyConfig.js';
 export { makeIdempotent } from './makeIdempotent.js';
 export { idempotent } from './idempotencyDecorator.js';
-export { IdempotencyRecordStatus } from './constants.js';
+export {
+  IdempotencyRecordStatus,
+  PERSISTENCE_ATTRIBUTE_KEY_MAPPINGS,
+} from './constants.js';

packages/idempotency/src/index.ts

@@ -30,7 +30,7 @@ abstract class BasePersistenceLayer implements BasePersistenceLayerInterface {
   // envVarsService is always initialized in the constructor
   private envVarsService!: EnvironmentVariablesService;
   private eventKeyJmesPath?: string;
-  private expiresAfterSeconds: number = 60 * 60; // 1 hour default
+  protected expiresAfterSeconds: number = 60 * 60; // 1 hour default
   private hashFunction = 'md5';
   private payloadValidationEnabled = false;
   private throwOnNoIdempotencyKey = false;