feat: Add new hybrid assignment cache implementation (#80)

* feat: Integrate new AssignmentCache API

* hybrid assignment cache

* better assertions

* fix import

* fix test

* clear localStorage before each test

* code review comments

* fix all the bugs

* instantiate and init assignment cache

* fix commentg

* write test

* bump dependency and fix imports

* use protected fields from super

Author: felipecsl

package.json

@@ -59,6 +59,6 @@
     "webpack-cli": "^4.10.0"
   },
   "dependencies": {
-    "@eppo/js-client-sdk-common": "3.2.2"
+    "@eppo/js-client-sdk-common": "3.3.1"
   }
 }

src/cache/assignment-cache-factory.spec.ts

@@ -0,0 +1,61 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import { assignmentCacheFactory } from './assignment-cache-factory';
+import HybridAssignmentCache from './hybrid-assignment-cache';
+
+import StorageArea = chrome.storage.StorageArea;
+
+describe('AssignmentCacheFactory', () => {
+  // TODO: Extract test-only function for this
+  const fakeStore: { [k: string]: string } = {};
+
+  const get = jest.fn((key?: string) => {
+    return new Promise((resolve) => {
+      if (!key) {
+        resolve(fakeStore);
+      } else {
+        resolve({ [key]: fakeStore[key] });
+      }
+    });
+  }) as jest.Mock;
+
+  const set = jest.fn((items: { [key: string]: string }) => {
+    return new Promise((resolve) => {
+      Object.assign(fakeStore, items);
+      resolve(undefined);
+    });
+  }) as jest.Mock;
+
+  const mockChromeStorage = { get, set } as unknown as StorageArea;
+
+  beforeEach(() => {
+    window.localStorage.clear();
+    Object.keys(fakeStore).forEach((key) => delete fakeStore[key]);
+  });
+
+  it('should create a hybrid cache if chrome storage is available', () => {
+    const cache = assignmentCacheFactory({
+      chromeStorage: mockChromeStorage,
+      storageKeySuffix: 'foo',
+    });
+    expect(cache).toBeInstanceOf(HybridAssignmentCache);
+    expect(Object.keys(fakeStore)).toHaveLength(0);
+    cache.set({ subjectKey: 'foo', flagKey: 'bar', allocationKey: 'baz', variationKey: 'qux' });
+    expect(Object.keys(fakeStore)).toHaveLength(1);
+  });
+
+  it('should create a hybrid cache if local storage is available', () => {
+    const cache = assignmentCacheFactory({
+      storageKeySuffix: 'foo',
+    });
+    expect(cache).toBeInstanceOf(HybridAssignmentCache);
+    expect(localStorage.length).toEqual(0);
+    cache.set({ subjectKey: 'foo', flagKey: 'bar', allocationKey: 'baz', variationKey: 'qux' });
+    // chrome storage is not being used
+    expect(Object.keys(fakeStore)).toHaveLength(0);
+    // local storage is being used
+    expect(localStorage.length).toEqual(1);
+  });
+});

src/cache/assignment-cache-factory.ts

@@ -0,0 +1,30 @@
+import { AssignmentCache } from '@eppo/js-client-sdk-common';
+
+import { hasWindowLocalStorage } from '../configuration-factory';
+
+import ChromeStorageAssignmentCache from './chrome-storage-assignment-cache';
+import HybridAssignmentCache from './hybrid-assignment-cache';
+import { LocalStorageAssignmentCache } from './local-storage-assignment-cache';
+import SimpleAssignmentCache from './simple-assignment-cache';
+
+export function assignmentCacheFactory({
+  chromeStorage,
+  storageKeySuffix,
+}: {
+  storageKeySuffix: string;
+  chromeStorage?: chrome.storage.StorageArea;
+}): AssignmentCache {
+  const hasLocalStorage = hasWindowLocalStorage();
+  const simpleCache = new SimpleAssignmentCache();
+  if (chromeStorage) {
+    const chromeStorageCache = new ChromeStorageAssignmentCache(chromeStorage);
+    return new HybridAssignmentCache(simpleCache, chromeStorageCache);
+  } else {
+    if (hasLocalStorage) {
+      const localStorageCache = new LocalStorageAssignmentCache(storageKeySuffix);
+      return new HybridAssignmentCache(simpleCache, localStorageCache);
+    } else {
+      return simpleCache;
+    }
+  }
+}

src/cache/chrome-storage-assignment-cache.ts

@@ -0,0 +1,33 @@
+import {
+  assignmentCacheKeyToString,
+  assignmentCacheValueToString,
+  AssignmentCacheEntry,
+} from '@eppo/js-client-sdk-common';
+
+import ChromeStorageAsyncMap from './chrome-storage-async-map';
+import { BulkReadAssignmentCache } from './hybrid-assignment-cache';
+
+export default class ChromeStorageAssignmentCache implements BulkReadAssignmentCache {
+  private readonly storage: ChromeStorageAsyncMap<string>;
+
+  constructor(chromeStorage: chrome.storage.StorageArea) {
+    this.storage = new ChromeStorageAsyncMap(chromeStorage);
+  }
+
+  set(entry: AssignmentCacheEntry): void {
+    // "fire-and-forget" - we intentionally don't wait for the promise to resolve
+    // noinspection JSIgnoredPromiseFromCall
+    this.storage.set(assignmentCacheKeyToString(entry), assignmentCacheValueToString(entry));
+  }
+
+  has(_: AssignmentCacheEntry): boolean {
+    throw new Error(
+      'This should never be called for ChromeStorageAssignmentCache, use getEntries() instead.',
+    );
+  }
+
+  async getEntries(): Promise<[string, string][]> {
+    const entries = await this.storage.entries();
+    return Object.entries(entries).map(([key, value]) => [key, value] as [string, string]);
+  }
+}

src/cache/chrome-storage-async-map.ts

@@ -0,0 +1,24 @@
+import { AsyncMap } from '@eppo/js-client-sdk-common';
+
+/** Chrome storage-backed {@link AsyncMap}. */
+export default class ChromeStorageAsyncMap<T> implements AsyncMap<string, T> {
+  constructor(private readonly storage: chrome.storage.StorageArea) {}
+
+  async has(key: string): Promise<boolean> {
+    const value = await this.get(key);
+    return !!value;
+  }
+
+  async get(key: string): Promise<T | undefined> {
+    const subset = await this.storage.get(key);
+    return subset?.[key] ?? undefined;
+  }
+
+  async entries(): Promise<{ [p: string]: T }> {
+    return await this.storage.get(null);
+  }
+
+  async set(key: string, value: T) {
+    await this.storage.set({ [key]: value });
+  }
+}

src/cache/hybrid-assignment-cache.spec.ts

@@ -0,0 +1,87 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import ChromeStorageAssignmentCache from './chrome-storage-assignment-cache';
+import HybridAssignmentCache from './hybrid-assignment-cache';
+import { LocalStorageAssignmentCache } from './local-storage-assignment-cache';
+
+import StorageArea = chrome.storage.StorageArea;
+
+describe('HybridStorageAssignmentCache', () => {
+  const fakeStore: Record<string, string> = {};
+
+  const get = jest.fn((key?: string) => {
+    return new Promise((resolve) => {
+      if (!key) {
+        resolve(fakeStore);
+      } else {
+        resolve({ [key]: fakeStore[key] });
+      }
+    });
+  }) as jest.Mock;
+
+  const set = jest.fn((items: { [key: string]: string }) => {
+    return new Promise((resolve) => {
+      Object.assign(fakeStore, items);
+      resolve(undefined);
+    });
+  }) as jest.Mock;
+
+  const mockChromeStorage = { get, set } as unknown as StorageArea;
+  const chromeStorageCache = new ChromeStorageAssignmentCache(mockChromeStorage);
+  const localStorageCache = new LocalStorageAssignmentCache('test');
+  const hybridCache = new HybridAssignmentCache(localStorageCache, chromeStorageCache);
+
+  beforeEach(() => {
+    window.localStorage.clear();
+  });
+
+  it('has should return false if cache is empty', async () => {
+    const cacheKey = {
+      subjectKey: 'subject-1',
+      flagKey: 'flag-1',
+      allocationKey: 'allocation-1',
+      variationKey: 'control',
+    };
+    await hybridCache.init();
+    expect(hybridCache.has(cacheKey)).toBeFalsy();
+  });
+
+  it('has should return true if cache key is present', async () => {
+    const cacheKey = {
+      subjectKey: 'subject-1',
+      flagKey: 'flag-1',
+      allocationKey: 'allocation-1',
+      variationKey: 'control',
+    };
+    await hybridCache.init();
+    expect(hybridCache.has(cacheKey)).toBeFalsy();
+    expect(localStorageCache.has(cacheKey)).toBeFalsy();
+    hybridCache.set(cacheKey);
+    expect(hybridCache.has(cacheKey)).toBeTruthy();
+    expect(localStorageCache.has(cacheKey)).toBeTruthy();
+  });
+
+  it('should populate localStorageCache from chromeStorageCache', async () => {
+    const key1 = {
+      subjectKey: 'subject-1',
+      flagKey: 'flag-1',
+      allocationKey: 'allocation-1',
+      variationKey: 'control',
+    };
+    const key2 = {
+      subjectKey: 'subject-2',
+      flagKey: 'flag-2',
+      allocationKey: 'allocation-2',
+      variationKey: 'control',
+    };
+    expect(localStorageCache.has(key1)).toBeFalsy();
+    chromeStorageCache.set(key1);
+    chromeStorageCache.set(key2);
+    await hybridCache.init();
+    expect(localStorageCache.has(key1)).toBeTruthy();
+    expect(localStorageCache.has(key2)).toBeTruthy();
+    expect(localStorageCache.has({ ...key1, allocationKey: 'foo' })).toBeFalsy();
+  });
+});

src/cache/hybrid-assignment-cache.ts

@@ -0,0 +1,40 @@
+import { AssignmentCache, AssignmentCacheEntry } from '@eppo/js-client-sdk-common';
+
+/** An {@link AssignmentCache} that can write (set) multiple entries at once (in bulk). */
+export type BulkWriteAssignmentCache = AssignmentCache & {
+  /** Sets all entries in the cache to the provided array of [key, value] pairs. */
+  setEntries(entries: [string, string][]): void;
+};
+
+/** An {@link AssignmentCache} that can read (get) all entries at once. */
+export type BulkReadAssignmentCache = AssignmentCache & {
+  /** Returns all entries in the cache as an array of [key, value] pairs. */
+  getEntries(): Promise<[string, string][]>;
+};
+
+/**
+ * An {@link AssignmentCache} implementation that, upon `init`, reads from a persistent and async {@link BulkReadAssignmentCache}
+ * and writes to a synchronous {@link BulkWriteAssignmentCache} for serving the cache.
+ * */
+export default class HybridAssignmentCache implements AssignmentCache {
+  constructor(
+    private readonly servingStore: BulkWriteAssignmentCache,
+    private readonly persistentStore: BulkReadAssignmentCache,
+  ) {}
+
+  async init(): Promise<void> {
+    const entries = await this.persistentStore.getEntries();
+    if (entries) {
+      this.servingStore.setEntries(entries);
+    }
+  }
+
+  set(key: AssignmentCacheEntry): void {
+    this.servingStore.set(key);
+    this.persistentStore.set(key);
+  }
+
+  has(key: AssignmentCacheEntry): boolean {
+    return this.servingStore.has(key);
+  }
+}

src/local-storage-assignment-cache.spec.ts renamed to src/cache/local-storage-assignment-cache.spec.ts

@@ -8,23 +8,23 @@ describe('LocalStorageAssignmentCache', () => {
   it('typical behavior', () => {
     const cache = new LocalStorageAssignmentCache('test');
     expect(
-      cache.hasLoggedAssignment({
+      cache.has({
         subjectKey: 'subject-1',
         flagKey: 'flag-1',
         allocationKey: 'allocation-1',
         variationKey: 'control',
       }),
     ).toEqual(false);
 
-    cache.setLastLoggedAssignment({
+    cache.set({
       subjectKey: 'subject-1',
       flagKey: 'flag-1',
       allocationKey: 'allocation-1',
       variationKey: 'control',
     });
 
     expect(
-      cache.hasLoggedAssignment({
+      cache.has({
         subjectKey: 'subject-1',
         flagKey: 'flag-1',
         allocationKey: 'allocation-1',
@@ -33,15 +33,15 @@ describe('LocalStorageAssignmentCache', () => {
     ).toEqual(true); // this key has been logged
 
     // change variation
-    cache.setLastLoggedAssignment({
+    cache.set({
       subjectKey: 'subject-1',
       flagKey: 'flag-1',
       allocationKey: 'allocation-1',
       variationKey: 'variant',
     });
 
     expect(
-      cache.hasLoggedAssignment({
+      cache.has({
         subjectKey: 'subject-1',
         flagKey: 'flag-1',
         allocationKey: 'allocation-1',
@@ -62,53 +62,53 @@ describe('LocalStorageAssignmentCache', () => {
       allocationKey: 'allocation-1',
     };
 
-    cacheA.setLastLoggedAssignment({
+    cacheA.set({
       variationKey: 'variation-A',
       ...constantAssignmentProperties,
     });
 
     expect(
-      cacheA.hasLoggedAssignment({
+      cacheA.has({
         variationKey: 'variation-A',
         ...constantAssignmentProperties,
       }),
     ).toEqual(true);
 
     expect(
-      cacheB.hasLoggedAssignment({
+      cacheB.has({
         variationKey: 'variation-A',
         ...constantAssignmentProperties,
       }),
     ).toEqual(false);
 
-    cacheB.setLastLoggedAssignment({
+    cacheB.set({
       variationKey: 'variation-B',
       ...constantAssignmentProperties,
     });
 
     expect(
-      cacheA.hasLoggedAssignment({
+      cacheA.has({
         variationKey: 'variation-A',
         ...constantAssignmentProperties,
       }),
     ).toEqual(true);
 
     expect(
-      cacheB.hasLoggedAssignment({
+      cacheB.has({
         variationKey: 'variation-A',
         ...constantAssignmentProperties,
       }),
     ).toEqual(false);
 
     expect(
-      cacheA.hasLoggedAssignment({
+      cacheA.has({
         variationKey: 'variation-B',
         ...constantAssignmentProperties,
       }),
     ).toEqual(false);
 
     expect(
-      cacheB.hasLoggedAssignment({
+      cacheB.has({
         variationKey: 'variation-B',
         ...constantAssignmentProperties,
       }),