Merge main into lr/ls-less - resolved conflicts in package.json and local-storage-engine.ts

typotter · typotter · commit b17b5f50a14d · 2025-08-20T13:32:16.000-06:00
diff --git a/src/isolatable-hybrid.store.spec.ts b/src/isolatable-hybrid.store.spec.ts
@@ -2,6 +2,7 @@ import {
   IsolatableHybridConfigurationStore,
   ServingStoreUpdateStrategy,
 } from './isolatable-hybrid.store';
+import { StorageFullUnableToWrite } from './string-valued.store';
 
 describe('IsolatableHybridConfigurationStore', () => {
   const syncStoreMock = {
@@ -130,4 +131,49 @@ describe('IsolatableHybridConfigurationStore', () => {
       });
     },
   );
+
+  describe('StorageFullUnableToWrite exception handling', () => {
+    const store = new IsolatableHybridConfigurationStore(syncStoreMock, asyncStoreMock, 'always');
+
+    beforeEach(() => {
+      jest.resetAllMocks();
+    });
+
+    it('should continue operating even when async store fails with StorageFullUnableToWrite', async () => {
+      const entries = { key1: 'value1' };
+      asyncStoreMock.isInitialized.mockReturnValue(true);
+      asyncStoreMock.isExpired.mockReturnValue(true);
+      asyncStoreMock.setEntries.mockRejectedValue(new StorageFullUnableToWrite());
+      syncStoreMock.setEntries.mockResolvedValue(undefined);
+      syncStoreMock.getKeys.mockReturnValue([]);
+
+      // Should not throw - be resilient to async store failures
+      await expect(store.setEntries(entries)).resolves.not.toThrow();
+
+      // Sync store should still be updated for resilience
+      expect(syncStoreMock.setEntries).toHaveBeenCalledWith(entries);
+    });
+
+    it('should handle StorageFullUnableToWrite during initialization', async () => {
+      asyncStoreMock.isInitialized.mockReturnValue(false);
+      asyncStoreMock.setEntries.mockRejectedValue(new StorageFullUnableToWrite());
+
+      await expect(store.init()).resolves.not.toThrow();
+    });
+
+    it('should handle async store failures gracefully', async () => {
+      const entries = { key1: 'value1' };
+      asyncStoreMock.isInitialized.mockReturnValue(true);
+      asyncStoreMock.isExpired.mockReturnValue(true);
+      asyncStoreMock.setEntries.mockRejectedValue(new StorageFullUnableToWrite());
+      syncStoreMock.setEntries.mockResolvedValue(undefined);
+      syncStoreMock.getKeys.mockReturnValue([]);
+
+      // Should not throw even if async store fails
+      await expect(store.setEntries(entries)).resolves.not.toThrow();
+
+      expect(asyncStoreMock.setEntries).toHaveBeenCalledWith(entries);
+      expect(syncStoreMock.setEntries).toHaveBeenCalledWith(entries);
+    });
+  });
 });
diff --git a/src/isolatable-hybrid.store.ts b/src/isolatable-hybrid.store.ts
@@ -1,4 +1,9 @@
-import { HybridConfigurationStore, IAsyncStore, ISyncStore } from '@eppo/js-client-sdk-common';
+import {
+  applicationLogger,
+  HybridConfigurationStore,
+  IAsyncStore,
+  ISyncStore,
+} from '@eppo/js-client-sdk-common';
 
 export type ServingStoreUpdateStrategy = 'always' | 'expired' | 'empty';
 
@@ -21,8 +26,12 @@ export class IsolatableHybridConfigurationStore<T> extends HybridConfigurationSt
   /** @Override */
   public async setEntries(entries: Record<string, T>): Promise<boolean> {
     if (this.persistentStore) {
-      // always update persistent store
-      await this.persistentStore.setEntries(entries);
+      try {
+        // always update persistent store
+        await this.persistentStore.setEntries(entries);
+      } catch (e) {
+        applicationLogger.warn(`Failed to setEntries on persistent store: ${e}`);
+      }
     }
 
     const persistentStoreIsExpired =
diff --git a/src/local-storage-engine.ts b/src/local-storage-engine.ts
@@ -1,7 +1,11 @@
 import * as LZString from 'lz-string';
 
 import { CONFIGURATION_KEY, META_KEY } from './storage-key-constants';
-import { IStringStorageEngine } from './string-valued.store';
+import {
+  IStringStorageEngine,
+  StorageFullUnableToWrite,
+  LocalStorageUnknownFailure,
+} from './string-valued.store';
 
 interface EppoGlobalMeta {
   migratedAt?: number;
@@ -52,15 +56,53 @@ export class LocalStorageEngine implements IStringStorageEngine {
     return this.localStorage.getItem(this.metaKey);
   };
 
+  /**
+   * @throws StorageFullUnableToWrite
+   * @throws LocalStorageUnknownFailure
+   */
   public setContentsJsonString = async (configurationJsonString: string): Promise<void> => {
     const compressed = LZString.compressToBase64(configurationJsonString);
-    this.localStorage.setItem(this.contentsKey, compressed);
+    this.safeWrite(this.contentsKey, compressed);
   };
 
+  /**
+   * @throws StorageFullUnableToWrite
+   * @throws LocalStorageUnknownFailure
+   */
   public setMetaJsonString = async (metaJsonString: string): Promise<void> => {
-    this.localStorage.setItem(this.metaKey, metaJsonString);
+    this.safeWrite(this.metaKey, metaJsonString);
   };
 
+  /**
+   * @throws StorageFullUnableToWrite
+   * @throws LocalStorageUnknownFailure
+   */
+  private safeWrite(key: string, value: string): void {
+    try {
+      this.localStorage.setItem(key, value);
+    } catch (error) {
+      if (error instanceof DOMException) {
+        // Check for quota exceeded error
+        if (error.code === DOMException.QUOTA_EXCEEDED_ERR || error.name === 'QuotaExceededError') {
+          try {
+            this.clear();
+            // Retry setting the item after clearing
+            this.localStorage.setItem(key, value);
+            return;
+          } catch {
+            throw new StorageFullUnableToWrite();
+          }
+        }
+      }
+      // For any other error, wrap it in our custom exception
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new LocalStorageUnknownFailure(
+        `Failed to write to localStorage: ${errorMessage}`,
+        error instanceof Error ? error : (error as Error),
+      );
+    }
+  }
+
   private ensureCompressionMigration(): void {
     const globalMeta = this.getGlobalMeta();
 
@@ -115,4 +157,21 @@ export class LocalStorageEngine implements IStringStorageEngine {
   private setGlobalMeta(meta: EppoGlobalMeta): void {
     this.localStorage.setItem(LocalStorageEngine.GLOBAL_META_KEY, JSON.stringify(meta));
   }
+
+  public clear(): void {
+    const keysToDelete: string[] = [];
+
+    // Collect all keys that start with 'eppo-configuration'
+    for (let i = 0; i < this.localStorage.length; i++) {
+      const key = this.localStorage.key(i);
+      if (key?.startsWith(CONFIGURATION_KEY)) {
+        keysToDelete.push(key);
+      }
+    }
+
+    // Delete collected keys
+    keysToDelete.forEach((key) => {
+      this.localStorage.removeItem(key);
+    });
+  }
 }
diff --git a/src/local-storage.store.spec.ts b/src/local-storage.store.spec.ts
@@ -3,7 +3,7 @@
  */
 
 import { LocalStorageEngine } from './local-storage-engine';
-import { StringValuedAsyncStore } from './string-valued.store';
+import { StringValuedAsyncStore, StorageFullUnableToWrite, LocalStorageUnknownFailure } from './string-valued.store';
 
 describe('LocalStorageStore', () => {
   // Note: window.localStorage is mocked for the node environment via the jsdom jest environment
@@ -80,4 +80,105 @@ describe('LocalStorageStore', () => {
     expect(await storeB.entries()).toEqual({ theKey: 'B' });
     expect(await storeB.isExpired()).toBe(false);
   });
+
+  describe('clear method', () => {
+    it('should clear all eppo-configuration keys', () => {
+      window.localStorage.setItem('eppo-configuration-test', 'value1');
+      window.localStorage.setItem('eppo-configuration-other', 'value2');
+      window.localStorage.setItem('other-key', 'value3');
+
+      localStorageEngine.clear();
+
+      expect(window.localStorage.getItem('eppo-configuration-test')).toBeNull();
+      expect(window.localStorage.getItem('eppo-configuration-other')).toBeNull();
+      expect(window.localStorage.getItem('other-key')).toBe('value3');
+    });
+
+    it('should handle empty storage', () => {
+      window.localStorage.clear();
+      expect(() => localStorageEngine.clear()).not.toThrow();
+    });
+  });
+
+  describe('StorageFullUnableToWrite exception handling', () => {
+    let mockLocalStorage: Storage;
+    let localStorageEngineWithMock: LocalStorageEngine;
+
+    beforeEach(() => {
+      mockLocalStorage = {
+        getItem: jest.fn(),
+        setItem: jest.fn(),
+        removeItem: jest.fn(),
+        clear: jest.fn(),
+        length: 0,
+        key: jest.fn(),
+      };
+      localStorageEngineWithMock = new LocalStorageEngine(mockLocalStorage, 'test');
+    });
+
+    it('should throw StorageFullUnableToWrite when setContentsJsonString fails after clear and retry', async () => {
+      const quotaError = new DOMException('QuotaExceededError', 'QuotaExceededError');
+      Object.defineProperty(quotaError, 'code', { value: DOMException.QUOTA_EXCEEDED_ERR });
+      
+      (mockLocalStorage.setItem as jest.Mock).mockImplementation(() => {
+        throw quotaError;
+      });
+      (mockLocalStorage.key as jest.Mock).mockReturnValue(null);
+      (mockLocalStorage.length as any) = 0;
+
+      await expect(
+        localStorageEngineWithMock.setContentsJsonString('test-config')
+      ).rejects.toThrow(StorageFullUnableToWrite);
+    });
+
+    it('should throw StorageFullUnableToWrite when setMetaJsonString fails after clear and retry', async () => {
+      const quotaError = new DOMException('QuotaExceededError', 'QuotaExceededError');
+      Object.defineProperty(quotaError, 'code', { value: DOMException.QUOTA_EXCEEDED_ERR });
+      
+      (mockLocalStorage.setItem as jest.Mock).mockImplementation(() => {
+        throw quotaError;
+      });
+      (mockLocalStorage.key as jest.Mock).mockReturnValue(null);
+      (mockLocalStorage.length as any) = 0;
+
+      await expect(
+        localStorageEngineWithMock.setMetaJsonString('test-meta')
+      ).rejects.toThrow(StorageFullUnableToWrite);
+    });
+
+    it('should succeed after clearing when retry works', async () => {
+      const quotaError = new DOMException('QuotaExceededError', 'QuotaExceededError');
+      Object.defineProperty(quotaError, 'code', { value: DOMException.QUOTA_EXCEEDED_ERR });
+      
+      let callCount = 0;
+      (mockLocalStorage.setItem as jest.Mock).mockImplementation(() => {
+        callCount++;
+        if (callCount === 1) {
+          throw quotaError;
+        }
+        // Second call succeeds
+      });
+      (mockLocalStorage.key as jest.Mock).mockReturnValue('eppo-configuration-old');
+      (mockLocalStorage.length as any) = 1;
+
+      await expect(
+        localStorageEngineWithMock.setContentsJsonString('test-config')
+      ).resolves.not.toThrow();
+      
+      expect(mockLocalStorage.removeItem).toHaveBeenCalledWith('eppo-configuration-old');
+      expect(mockLocalStorage.setItem).toHaveBeenCalledTimes(2);
+    });
+
+    it('should throw LocalStorageUnknownFailure for non-quota errors', async () => {
+      const otherError = new Error('Some other error');
+      (mockLocalStorage.setItem as jest.Mock).mockImplementation(() => {
+        throw otherError;
+      });
+
+      const error = await localStorageEngineWithMock.setContentsJsonString('test-config').catch(e => e);
+      expect(error).toBeInstanceOf(LocalStorageUnknownFailure);
+      expect(error.originalError).toBe(otherError);
+      expect(error.message).toContain('Some other error');
+    });
+  });
 });
diff --git a/src/string-valued.store.ts b/src/string-valued.store.ts
@@ -1,5 +1,22 @@
 import { IAsyncStore } from '@eppo/js-client-sdk-common';
 
+export class StorageFullUnableToWrite extends Error {
+  constructor(message = 'Storage is full and unable to write.') {
+    super(message);
+    this.name = 'StorageFullUnableToWrite';
+  }
+}
+
+export class LocalStorageUnknownFailure extends Error {
+  constructor(
+    message = 'Local storage operation failed for unknown reason.',
+    public originalError?: Error,
+  ) {
+    super(message);
+    this.name = 'LocalStorageUnknownFailure';
+  }
+}
+
 /**
  * Interface for a string-based storage engine which stores string contents as well as metadata
  * about those contents (e.g., when it was last updated)
@@ -49,6 +66,10 @@ export class StringValuedAsyncStore<T> implements IAsyncStore<T> {
     return contentsJsonString ? JSON.parse(contentsJsonString) : {};
   }
 
+  /**
+   * @param entries
+   * @throws StorageFullUnableToWrite
+   */
   public async setEntries(entries: Record<string, T>): Promise<void> {
     // String-based storage takes a dictionary of key-value string pairs,
     // so we write the entire configuration and meta to a single location for each.
diff --git a/yarn.lock b/yarn.lock
