Configurable cache behavior (#73)

* cache racing start in place

* additional test

* clean up debug logs

* cleanup from self-review of PR

* clean up annotations

* bump version of commons

* working to mirror android behavior

* local storage can expire too

* isolated hybrid store

* configuration factory uses update strategy

* failing test in place

* test passing

* minor comment changes from self-review of PR

* TODO for test as well

* test in place for useExpiredCache

* expired cache allowed

* composition over inheritance

* additional feedback from PR

Author: aarsilv

docs/js-client-sdk.eppojsclient.getboolassignment.md

@@ -7,7 +7,7 @@
 **Signature:**
 
 ```typescript
-getBoolAssignment(flagKey: string, subjectKey: string, subjectAttributes: Record<string, any>, defaultValue: boolean): boolean;
+getBoolAssignment(flagKey: string, subjectKey: string, subjectAttributes: Record<string, AttributeType>, defaultValue: boolean): boolean;
 ```
 
 ## Parameters
@@ -16,7 +16,7 @@ getBoolAssignment(flagKey: string, subjectKey: string, subjectAttributes: Record
 |  --- | --- | --- |
 |  flagKey | string |  |
 |  subjectKey | string |  |
-|  subjectAttributes | Record&lt;string, any&gt; |  |
+|  subjectAttributes | Record&lt;string, AttributeType&gt; |  |
 |  defaultValue | boolean |  |
 
 **Returns:**

docs/js-client-sdk.eppojsclient.getintegerassignment.md

@@ -7,7 +7,7 @@
 **Signature:**
 
 ```typescript
-getIntegerAssignment(flagKey: string, subjectKey: string, subjectAttributes: Record<string, any>, defaultValue: number): number;
+getIntegerAssignment(flagKey: string, subjectKey: string, subjectAttributes: Record<string, AttributeType>, defaultValue: number): number;
 ```
 
 ## Parameters
@@ -16,7 +16,7 @@ getIntegerAssignment(flagKey: string, subjectKey: string, subjectAttributes: Rec
 |  --- | --- | --- |
 |  flagKey | string |  |
 |  subjectKey | string |  |
-|  subjectAttributes | Record&lt;string, any&gt; |  |
+|  subjectAttributes | Record&lt;string, AttributeType&gt; |  |
 |  defaultValue | number |  |
 
 **Returns:**

docs/js-client-sdk.eppojsclient.getjsonassignment.md

@@ -7,7 +7,7 @@
 **Signature:**
 
 ```typescript
-getJSONAssignment(flagKey: string, subjectKey: string, subjectAttributes: Record<string, any>, defaultValue: object): object;
+getJSONAssignment(flagKey: string, subjectKey: string, subjectAttributes: Record<string, AttributeType>, defaultValue: object): object;
 ```
 
 ## Parameters
@@ -16,7 +16,7 @@ getJSONAssignment(flagKey: string, subjectKey: string, subjectAttributes: Record
 |  --- | --- | --- |
 |  flagKey | string |  |
 |  subjectKey | string |  |
-|  subjectAttributes | Record&lt;string, any&gt; |  |
+|  subjectAttributes | Record&lt;string, AttributeType&gt; |  |
 |  defaultValue | object |  |
 
 **Returns:**

docs/js-client-sdk.eppojsclient.getnumericassignment.md

@@ -7,7 +7,7 @@
 **Signature:**
 
 ```typescript
-getNumericAssignment(flagKey: string, subjectKey: string, subjectAttributes: Record<string, any>, defaultValue: number): number;
+getNumericAssignment(flagKey: string, subjectKey: string, subjectAttributes: Record<string, AttributeType>, defaultValue: number): number;
 ```
 
 ## Parameters
@@ -16,7 +16,7 @@ getNumericAssignment(flagKey: string, subjectKey: string, subjectAttributes: Rec
 |  --- | --- | --- |
 |  flagKey | string |  |
 |  subjectKey | string |  |
-|  subjectAttributes | Record&lt;string, any&gt; |  |
+|  subjectAttributes | Record&lt;string, AttributeType&gt; |  |
 |  defaultValue | number |  |
 
 **Returns:**

docs/js-client-sdk.eppojsclient.getstringassignment.md

@@ -7,7 +7,7 @@
 **Signature:**
 
 ```typescript
-getStringAssignment(flagKey: string, subjectKey: string, subjectAttributes: Record<string, any>, defaultValue: string): string;
+getStringAssignment(flagKey: string, subjectKey: string, subjectAttributes: Record<string, AttributeType>, defaultValue: string): string;
 ```
 
 ## Parameters
@@ -16,7 +16,7 @@ getStringAssignment(flagKey: string, subjectKey: string, subjectAttributes: Reco
 |  --- | --- | --- |
 |  flagKey | string |  |
 |  subjectKey | string |  |
-|  subjectAttributes | Record&lt;string, any&gt; |  |
+|  subjectAttributes | Record&lt;string, AttributeType&gt; |  |
 |  defaultValue | string |  |
 
 **Returns:**

js-client-sdk.api.md

@@ -6,40 +6,43 @@
 
 /// <reference types="chrome" />
 
+import { AttributeType } from '@eppo/js-client-sdk-common';
 import { EppoClient } from '@eppo/js-client-sdk-common';
 import { Flag } from '@eppo/js-client-sdk-common';
 import { IAssignmentEvent } from '@eppo/js-client-sdk-common';
 import { IAssignmentLogger } from '@eppo/js-client-sdk-common';
 import { IAsyncStore } from '@eppo/js-client-sdk-common';
 import { IEppoClient } from '@eppo/js-client-sdk-common';
 
-// @public (undocumented)
-export class ChromeStorageAsyncStore<T> implements IAsyncStore<T> {
-    constructor(storageArea: chrome.storage.StorageArea, cooldownSeconds?: number | undefined);
+// Warning: (ae-forgotten-export) The symbol "IStringStorageEngine" needs to be exported by the entry point index.d.ts
+//
+// @public
+export class ChromeStorageEngine implements IStringStorageEngine {
+    constructor(storageArea: chrome.storage.StorageArea);
     // (undocumented)
-    getEntries(): Promise<Record<string, T>>;
+    getContentsJsonString: () => Promise<string | null>;
     // (undocumented)
-    isExpired(): Promise<boolean>;
+    getMetaJsonString: () => Promise<string | null>;
     // (undocumented)
-    isInitialized(): boolean;
+    setContentsJsonString: (configurationJsonString: string) => Promise<void>;
     // (undocumented)
-    setEntries(entries: Record<string, T>): Promise<void>;
+    setMetaJsonString: (metaJsonString: string) => Promise<void>;
 }
 
 // @public
 export class EppoJSClient extends EppoClient {
-    // (undocumented)
-    getBoolAssignment(flagKey: string, subjectKey: string, subjectAttributes: Record<string, any>, defaultValue: boolean): boolean;
+    // @deprecated (undocumented)
+    getBoolAssignment(flagKey: string, subjectKey: string, subjectAttributes: Record<string, AttributeType>, defaultValue: boolean): boolean;
     // (undocumented)
     getBooleanAssignment(flagKey: string, subjectKey: string, subjectAttributes: Record<string, any>, defaultValue: boolean): boolean;
     // (undocumented)
-    getIntegerAssignment(flagKey: string, subjectKey: string, subjectAttributes: Record<string, any>, defaultValue: number): number;
+    getIntegerAssignment(flagKey: string, subjectKey: string, subjectAttributes: Record<string, AttributeType>, defaultValue: number): number;
     // (undocumented)
-    getJSONAssignment(flagKey: string, subjectKey: string, subjectAttributes: Record<string, any>, defaultValue: object): object;
+    getJSONAssignment(flagKey: string, subjectKey: string, subjectAttributes: Record<string, AttributeType>, defaultValue: object): object;
     // (undocumented)
-    getNumericAssignment(flagKey: string, subjectKey: string, subjectAttributes: Record<string, any>, defaultValue: number): number;
+    getNumericAssignment(flagKey: string, subjectKey: string, subjectAttributes: Record<string, AttributeType>, defaultValue: number): number;
     // (undocumented)
-    getStringAssignment(flagKey: string, subjectKey: string, subjectAttributes: Record<string, any>, defaultValue: string): string;
+    getStringAssignment(flagKey: string, subjectKey: string, subjectAttributes: Record<string, AttributeType>, defaultValue: string): string;
     // (undocumented)
     static initialized: boolean;
     // (undocumented)
@@ -60,6 +63,7 @@ export interface IClientConfig {
     apiKey: string;
     assignmentLogger: IAssignmentLogger;
     baseUrl?: string;
+    maxCacheAgeSeconds?: number;
     numInitialRequestRetries?: number;
     numPollRequestRetries?: number;
     persistentStore?: IAsyncStore<Flag>;
@@ -68,6 +72,9 @@ export interface IClientConfig {
     requestTimeoutMs?: number;
     skipInitialRequest?: boolean;
     throwOnFailedInitialization?: boolean;
+    // Warning: (ae-forgotten-export) The symbol "ServingStoreUpdateStrategy" needs to be exported by the entry point index.d.ts
+    updateOnFetch?: ServingStoreUpdateStrategy;
+    useExpiredCache?: boolean;
 }
 
 export { IEppoClient }

package.json

@@ -34,7 +34,6 @@
     "@microsoft/api-extractor": "^7.38.0",
     "@types/chrome": "^0.0.268",
     "@types/jest": "^29.5.11",
-    "@types/md5": "^2.3.2",
     "@typescript-eslint/eslint-plugin": "^5.13.0",
     "@typescript-eslint/parser": "^5.13.0",
     "eslint": "^8.17.0",

src/chrome-storage-engine.ts

@@ -0,0 +1,37 @@
+import { CONFIGURATION_KEY, META_KEY } from './storage-key-constants';
+import { IStringStorageEngine } from './string-valued.store';
+
+/**
+ * Chrome storage implementation of a string-valued store for storing a configuration and its metadata.
+ *
+ * This serializes the entire configuration object into a string and then stores it to a single key
+ * within the object for another single top-level key.
+ * Same with metadata about the store (e.g., when it was last updated).
+ */
+export class ChromeStorageEngine implements IStringStorageEngine {
+  private chromeStorageKey = 'eppo-sdk';
+
+  public constructor(private storageArea: chrome.storage.StorageArea) {}
+
+  public getContentsJsonString = async (): Promise<string | null> => {
+    const storage = await this.storageArea.get(this.chromeStorageKey);
+    return storage?.[CONFIGURATION_KEY] ?? null;
+  };
+
+  public getMetaJsonString = async (): Promise<string | null> => {
+    const storage = await this.storageArea.get(this.chromeStorageKey);
+    return storage?.[META_KEY] ?? null;
+  };
+
+  public setContentsJsonString = async (configurationJsonString: string): Promise<void> => {
+    await this.storageArea.set({
+      [CONFIGURATION_KEY]: configurationJsonString,
+    });
+  };
+
+  public setMetaJsonString = async (metaJsonString: string): Promise<void> => {
+    await this.storageArea.set({
+      [META_KEY]: metaJsonString,
+    });
+  };
+}

src/chrome.configuration-store.spec.ts renamed to src/chrome-storage.store.spec.ts

@@ -1,37 +1,24 @@
-import { ChromeStorageAsyncStore } from './chrome.configuration-store';
+import { IAsyncStore } from '@eppo/js-client-sdk-common';
 
-describe('ChromeStore', () => {
+import { ChromeStorageEngine } from './chrome-storage-engine';
+import { StringValuedAsyncStore } from './string-valued.store';
+
+import StorageArea = chrome.storage.StorageArea;
+
+describe('ChromeStorageStore', () => {
   const mockEntries: Record<string, string> = { key1: 'value1', key2: 'value2' };
-  let chromeStore: ChromeStorageAsyncStore<string>;
-  let extendedStorageLocal: chrome.storage.StorageArea;
+  const storageGetFake = jest.fn();
+  const chromeStorageEngine = new ChromeStorageEngine({
+    get: storageGetFake,
+    set: jest.fn(),
+  } as unknown as StorageArea);
+  let chromeStore: IAsyncStore<unknown>;
   let now: number;
 
   beforeEach(() => {
     now = Date.now();
-
     jest.useFakeTimers();
-
-    const get = jest.fn();
-    const set = jest.fn();
-    extendedStorageLocal = {
-      set,
-      get,
-      clear: jest.fn(),
-      remove: jest.fn(),
-      getBytesInUse: jest.fn(),
-      setAccessLevel: jest.fn(),
-      onChanged: {
-        addListener: jest.fn(),
-        removeListener: jest.fn(),
-        getRules: jest.fn(),
-        hasListener: jest.fn(),
-        removeRules: jest.fn(),
-        addRules: jest.fn(),
-        hasListeners: jest.fn(),
-      },
-    };
-
-    chromeStore = new ChromeStorageAsyncStore(extendedStorageLocal);
+    chromeStore = new StringValuedAsyncStore(chromeStorageEngine);
   });
 
   afterEach(() => {
@@ -40,14 +27,14 @@ describe('ChromeStore', () => {
   });
 
   it('is always expired without cooldown', async () => {
-    chromeStore = new ChromeStorageAsyncStore(extendedStorageLocal, undefined);
+    chromeStore = new StringValuedAsyncStore(chromeStorageEngine, undefined);
     expect(await chromeStore.isExpired()).toBe(true);
   });
 
   it('is not expired with cooldown', async () => {
-    chromeStore = new ChromeStorageAsyncStore(extendedStorageLocal, 10);
+    chromeStore = new StringValuedAsyncStore(chromeStorageEngine, 10);
 
-    (extendedStorageLocal.get as jest.Mock).mockImplementation(() => {
+    storageGetFake.mockImplementation(() => {
       return Promise.resolve({
         ['eppo-configuration']: JSON.stringify(mockEntries),
         ['eppo-configuration-meta']: JSON.stringify({
@@ -60,9 +47,9 @@ describe('ChromeStore', () => {
   });
 
   it('is expired after cooldown', async () => {
-    chromeStore = new ChromeStorageAsyncStore(extendedStorageLocal, 10);
+    chromeStore = new StringValuedAsyncStore(chromeStorageEngine, 10);
 
-    (extendedStorageLocal.get as jest.Mock).mockImplementation(() => {
+    storageGetFake.mockImplementation(() => {
       return Promise.resolve({
         ['eppo-configuration']: JSON.stringify(mockEntries),
         ['eppo-configuration-meta']: JSON.stringify({
@@ -86,7 +73,7 @@ describe('ChromeStore', () => {
   });
 
   it('should get entries', async () => {
-    (extendedStorageLocal.get as jest.Mock).mockImplementation(() => {
+    storageGetFake.mockImplementation(() => {
       return Promise.resolve({ ['eppo-configuration']: JSON.stringify(mockEntries) });
     });