feat: Simplify AssignmentCache interface (#83)

* feat: Simplify AssignmentCache interface

* cleanup

* reverting these unrelated changes

* minor cleanup

Author: felipecsl

package.json

@@ -43,6 +43,7 @@
   "devDependencies": {
     "@types/jest": "^29.5.11",
     "@types/js-base64": "^3.3.1",
+    "@types/lodash": "^4.17.5",
     "@types/md5": "^2.3.2",
     "@types/semver": "^7.5.6",
     "@typescript-eslint/eslint-plugin": "^5.13.0",
@@ -55,6 +56,7 @@
     "eslint-plugin-promise": "^6.0.0",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
+    "lodash": "^4.17.21",
     "prettier": "^2.7.1",
     "terser-webpack-plugin": "^5.3.3",
     "testdouble": "^3.20.1",

src/assignment-cache.ts

@@ -0,0 +1,81 @@
+import { getMD5Hash } from '../obfuscation';
+
+import { LRUCache } from './lru-cache';
+
+export type AssignmentCacheKey = {
+  subjectKey: string;
+  flagKey: string;
+  allocationKey: string;
+  variationKey: string;
+};
+
+export interface AsyncMap<K, V> {
+  get(key: K): Promise<V | undefined>;
+  set(key: K, value: V): Promise<void>;
+  has(key: K): Promise<boolean>;
+}
+
+export interface AssignmentCache {
+  set(key: AssignmentCacheKey): void;
+  has(key: AssignmentCacheKey): boolean;
+}
+
+export abstract class AssignmentCacheImpl<T extends Map<string, string>>
+  implements AssignmentCache
+{
+  // key -> variation value hash
+  protected constructor(protected readonly delegate: T) {}
+
+  has(key: AssignmentCacheKey): boolean {
+    const isPresent = this.delegate.has(this.toCacheKeyString(key));
+    if (!isPresent) {
+      // no cache key present
+      return false;
+    }
+
+    // the subject has been assigned to a different variation
+    // than was previously logged.
+    // in this case we need to log the assignment again.
+    const cachedValue = this.get(key);
+    return cachedValue === getMD5Hash(key.variationKey);
+  }
+
+  private get(key: AssignmentCacheKey): string | undefined {
+    return this.delegate.get(this.toCacheKeyString(key));
+  }
+
+  set(key: AssignmentCacheKey): void {
+    this.delegate.set(this.toCacheKeyString(key), getMD5Hash(key.variationKey));
+  }
+
+  private toCacheKeyString({ subjectKey, flagKey, allocationKey }: AssignmentCacheKey): string {
+    return [`subject:${subjectKey}`, `flag:${flagKey}`, `allocation:${allocationKey}`].join(';');
+  }
+}
+
+/**
+ * A cache that never expires.
+ *
+ * The primary use case is for client-side SDKs, where the cache is only used
+ * for a single user.
+ */
+export class NonExpiringInMemoryAssignmentCache extends AssignmentCacheImpl<Map<string, string>> {
+  constructor() {
+    super(new Map<string, string>());
+  }
+}
+
+/**
+ * A cache that uses the LRU algorithm to evict the least recently used items.
+ *
+ * It is used to limit the size of the cache.
+ *
+ * The primary use case is for server-side SDKs, where the cache is shared across
+ * multiple users. In this case, the cache size should be set to the maximum number
+ * of users that can be active at the same time.
+ */
+export class LRUInMemoryAssignmentCache extends AssignmentCacheImpl<LRUCache> {
+  constructor(maxSize: number) {
+    super(new LRUCache(maxSize));
+  }
+}

src/cache/assignment-cache.ts

@@ -6,21 +6,52 @@
  * The cache is implemented as a Map, which is a built-in JavaScript object.
  * The Map object holds key-value pairs and remembers the order of key-value pairs as they were inserted.
  */
-export class LRUCache {
-  private capacity: number;
-  private cache: Map<string, string>;
+export class LRUCache implements Map<string, string> {
+  private readonly cache = new Map<string, string>();
+  [Symbol.toStringTag]: string;
 
-  constructor(capacity: number) {
-    this.capacity = capacity;
-    this.cache = new Map<string, string>();
+  constructor(private readonly capacity: number) {}
+
+  [Symbol.iterator](): IterableIterator<[string, string]> {
+    return this.cache[Symbol.iterator]();
+  }
+
+  forEach(
+    callbackFn: (value: string, key: string, map: Map<string, string>) => void,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    thisArg?: any,
+  ): void {
+    this.cache.forEach(callbackFn, thisArg);
+  }
+
+  readonly size: number = this.cache.size;
+
+  entries(): IterableIterator<[string, string]> {
+    return this.cache.entries();
+  }
+
+  clear() {
+    this.cache.clear();
+  }
+
+  delete(key: string): boolean {
+    return this.cache.delete(key);
+  }
+
+  keys(): IterableIterator<string> {
+    return this.cache.keys();
+  }
+
+  values(): IterableIterator<string> {
+    return this.cache.values();
   }
 
   has(key: string): boolean {
     return this.cache.has(key);
   }
 
   get(key: string): string | undefined {
-    if (!this.cache.has(key)) {
+    if (!this.has(key)) {
       return undefined;
     }
 
@@ -32,16 +63,16 @@ export class LRUCache {
       // This is crucial for maintaining the correct order of elements in the cache,
       // which directly impacts which item is considered the least recently used (LRU) and
       // thus eligible for eviction when the cache reaches its capacity.
-      this.cache.delete(key);
+      this.delete(key);
       this.cache.set(key, value);
     }
 
     return value;
   }
 
-  set(key: string, value: string): void {
+  set(key: string, value: string): this {
     if (this.capacity === 0) {
-      return;
+      return this;
     }
 
     if (this.cache.has(key)) {
@@ -52,9 +83,10 @@ export class LRUCache {
       // Therefore, the first key represents the oldest entry, which is the least recently used item in our cache.
       // We use Map.prototype.keys().next().value to obtain this oldest key and then delete it from the cache.
       const oldestKey = this.cache.keys().next().value;
-      this.cache.delete(oldestKey);
+      this.delete(oldestKey);
     }
 
     this.cache.set(key, value);
+    return this;
   }
 }

src/lru-cache.spec.ts renamed to src/cache/lru-cache.spec.ts

@@ -1,3 +1,4 @@
+import { times } from 'lodash';
 import * as td from 'testdouble';
 
 import {
@@ -165,19 +166,17 @@ describe('EppoClient E2E test', () => {
       client.getStringAssignment(flagKey, 'subject-to-be-logged', {}, 'default-value');
       client.setLogger(mockLogger);
       expect(td.explain(mockLogger.logAssignment).callCount).toEqual(1);
-
       client.setLogger(mockLogger);
       expect(td.explain(mockLogger.logAssignment).callCount).toEqual(1);
     });
 
     it('Does not invoke logger for events that exceed queue size', () => {
       const mockLogger = td.object<IAssignmentLogger>();
-
       const client = new EppoClient(storage);
 
-      for (let i = 0; i < MAX_EVENT_QUEUE_SIZE + 100; i++) {
-        client.getStringAssignment(flagKey, `subject-to-be-logged-${i}`, {}, 'default-value');
-      }
+      times(MAX_EVENT_QUEUE_SIZE + 100, (i) =>
+        client.getStringAssignment(flagKey, `subject-to-be-logged-${i}`, {}, 'default-value'),
+      );
       client.setLogger(mockLogger);
       expect(td.explain(mockLogger.logAssignment).callCount).toEqual(MAX_EVENT_QUEUE_SIZE);
     });
@@ -364,7 +363,7 @@ describe('EppoClient E2E test', () => {
       client.setLogger(mockLogger);
     });
 
-    it('logs duplicate assignments without an assignment cache', () => {
+    it('logs duplicate assignments without an assignment cache', async () => {
       client.disableAssignmentCache();
 
       client.getStringAssignment(flagKey, 'subject-10', {}, 'default');
@@ -374,12 +373,10 @@ describe('EppoClient E2E test', () => {
       expect(td.explain(mockLogger.logAssignment).callCount).toEqual(2);
     });
 
-    it('does not log duplicate assignments', () => {
+    it('does not log duplicate assignments', async () => {
       client.useNonExpiringInMemoryAssignmentCache();
-
       client.getStringAssignment(flagKey, 'subject-10', {}, 'default');
       client.getStringAssignment(flagKey, 'subject-10', {}, 'default');
-
       // call count should be 1 because the second call is a cache hit and not logged.
       expect(td.explain(mockLogger.logAssignment).callCount).toEqual(1);
     });
@@ -415,8 +412,8 @@ describe('EppoClient E2E test', () => {
       expect(td.explain(mockLogger.logAssignment).callCount).toEqual(2);
     });
 
-    it('logs for each unique flag', () => {
-      storage.setEntries({
+    it('logs for each unique flag', async () => {
+      await storage.setEntries({
         [flagKey]: mockFlag,
         'flag-2': {
           ...mockFlag,