feat: add IndexedDB storage engine as alternative to localStorage

docs/js-client-sdk.iclientconfig.md

@@ -206,6 +206,25 @@ boolean
 _(Optional)_ Whether initialization will be considered successfully complete if expired cache values are loaded. If false, initialization will always wait for a fetch if cached values are expired. (default: false)
 
 
+</td></tr>
+<tr><td>
+
+[useIndexedDB?](./js-client-sdk.iclientconfig.useindexeddb.md)
+
+
+</td><td>
+
+
+</td><td>
+
+boolean
+
+
+</td><td>
+
+_(Optional)_ Use IndexedDB for storing flag configurations and assignment cache instead of localStorage. IndexedDB provides significantly larger storage capacity (gigabytes, browser-dependent) compared to localStorage (\~5-10MB). Data is stored as native JavaScript objects using IndexedDB's structured clone algorithm for efficient storage and retrieval. (default: false)
+
+
 </td></tr>
 </tbody></table>
 

docs/js-client-sdk.iclientconfig.useindexeddb.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@eppo/js-client-sdk](./js-client-sdk.md) &gt; [IClientConfig](./js-client-sdk.iclientconfig.md) &gt; [useIndexedDB](./js-client-sdk.iclientconfig.useindexeddb.md)
+
+## IClientConfig.useIndexedDB property
+
+Use IndexedDB for storing flag configurations and assignment cache instead of localStorage. IndexedDB provides significantly larger storage capacity (gigabytes, browser-dependent) compared to localStorage (\~5-10MB). Data is stored as native JavaScript objects using IndexedDB's structured clone algorithm for efficient storage and retrieval. (default: false)
+
+**Signature:**
+
+```typescript
+useIndexedDB?: boolean;
+```

docs/js-client-sdk.iprecomputedclientconfig.md

@@ -90,6 +90,25 @@ IPrecompute
 </td><td>
 
 
+</td></tr>
+<tr><td>
+
+[useIndexedDB?](./js-client-sdk.iprecomputedclientconfig.useindexeddb.md)
+
+
+</td><td>
+
+
+</td><td>
+
+boolean
+
+
+</td><td>
+
+_(Optional)_ Use IndexedDB for storing flag configurations and assignment cache instead of localStorage. IndexedDB provides significantly larger storage capacity (gigabytes, browser-dependent) compared to localStorage (\~5-10MB). Data is stored as native JavaScript objects using IndexedDB's structured clone algorithm for efficient storage and retrieval. (default: false)
+
+
 </td></tr>
 </tbody></table>
 

docs/js-client-sdk.iprecomputedclientconfig.useindexeddb.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@eppo/js-client-sdk](./js-client-sdk.md) &gt; [IPrecomputedClientConfig](./js-client-sdk.iprecomputedclientconfig.md) &gt; [useIndexedDB](./js-client-sdk.iprecomputedclientconfig.useindexeddb.md)
+
+## IPrecomputedClientConfig.useIndexedDB property
+
+Use IndexedDB for storing flag configurations and assignment cache instead of localStorage. IndexedDB provides significantly larger storage capacity (gigabytes, browser-dependent) compared to localStorage (\~5-10MB). Data is stored as native JavaScript objects using IndexedDB's structured clone algorithm for efficient storage and retrieval. (default: false)
+
+**Signature:**
+
+```typescript
+useIndexedDB?: boolean;
+```

js-client-sdk.api.md

@@ -163,6 +163,7 @@ export interface IClientConfig extends IBaseRequestConfig {
     // Warning: (ae-forgotten-export) The symbol "ServingStoreUpdateStrategy" needs to be exported by the entry point index.d.ts
     updateOnFetch?: ServingStoreUpdateStrategy;
     useExpiredCache?: boolean;
+    useIndexedDB?: boolean;
 }
 
 // @public
@@ -198,6 +199,7 @@ export interface IPrecomputedClientConfig extends IBaseRequestConfig {
     //
     // (undocumented)
     precompute: IPrecompute;
+    useIndexedDB?: boolean;
 }
 
 // @public

src/cache/assignment-cache-factory.ts

@@ -1,18 +1,21 @@
 import { AssignmentCache } from '@eppo/js-client-sdk-common';
 
-import { hasWindowLocalStorage } from '../configuration-factory';
+import { hasIndexedDB, hasWindowLocalStorage } from '../configuration-factory';
 
 import ChromeStorageAssignmentCache from './chrome-storage-assignment-cache';
 import HybridAssignmentCache from './hybrid-assignment-cache';
+import { IndexedDBAssignmentCache } from './indexed-db-assignment-cache';
 import { LocalStorageAssignmentCache } from './local-storage-assignment-cache';
 import SimpleAssignmentCache from './simple-assignment-cache';
 
 export function assignmentCacheFactory({
   forceMemoryOnly = false,
+  useIndexedDB = false,
   chromeStorage,
   storageKeySuffix,
 }: {
   forceMemoryOnly?: boolean;
+  useIndexedDB?: boolean;
   storageKeySuffix: string;
   chromeStorage?: chrome.storage.StorageArea;
 }): AssignmentCache {
@@ -22,15 +25,18 @@ export function assignmentCacheFactory({
     return simpleCache;
   }
 
+  // Priority order: Chrome storage > IndexedDB (if opted in) > localStorage > memory-only
   if (chromeStorage) {
     const chromeStorageCache = new ChromeStorageAssignmentCache(chromeStorage);
     return new HybridAssignmentCache(simpleCache, chromeStorageCache);
+  } else if (useIndexedDB && hasIndexedDB()) {
+    // IndexedDB is available and user has opted in
+    const indexedDBCache = new IndexedDBAssignmentCache(storageKeySuffix);
+    return new HybridAssignmentCache(simpleCache, indexedDBCache);
+  } else if (hasWindowLocalStorage()) {
+    const localStorageCache = new LocalStorageAssignmentCache(storageKeySuffix);
+    return new HybridAssignmentCache(simpleCache, localStorageCache);
   } else {
-    if (hasWindowLocalStorage()) {
-      const localStorageCache = new LocalStorageAssignmentCache(storageKeySuffix);
-      return new HybridAssignmentCache(simpleCache, localStorageCache);
-    } else {
-      return simpleCache;
-    }
+    return simpleCache;
   }
 }

src/cache/indexed-db-assignment-cache.ts

@@ -0,0 +1,39 @@
+import { AbstractAssignmentCache } from '@eppo/js-client-sdk-common';
+
+import { BulkReadAssignmentCache, BulkWriteAssignmentCache } from './hybrid-assignment-cache';
+import { IndexedDBAssignmentShim } from './indexed-db-assignment-shim';
+
+/**
+ * IndexedDB-backed assignment cache.
+ *
+ * Provides persistent storage for assignment results with larger capacity than localStorage.
+ * Stores assignments as a blob in IndexedDB for efficient storage and retrieval.
+ */
+export class IndexedDBAssignmentCache
+  extends AbstractAssignmentCache<IndexedDBAssignmentShim>
+  implements BulkReadAssignmentCache, BulkWriteAssignmentCache
+{
+  constructor(storageKeySuffix: string) {
+    super(new IndexedDBAssignmentShim(storageKeySuffix));
+  }
+
+  setEntries(entries: [string, string][]): void {
+    entries.forEach(([key, value]) => {
+      if (key && value) {
+        this.delegate.set(key, value);
+      }
+    });
+  }
+
+  async getEntries(): Promise<[string, string][]> {
+    return Array.from(this.entries());
+  }
+
+  /**
+   * Initialize the cache by loading from IndexedDB.
+   * This should be called during SDK initialization.
+   */
+  async init(): Promise<void> {
+    await this.delegate.init();
+  }
+}