feat(js-client-sdk): add ability to customize storage impl (#1404)

This PR will enable browser sdk to take in a custom storage
implementation.

Additional details:
- added common implementation for client sdks to eventually to make this
feature common to all js client sdks
- custom storage implementations will be wrapped to ensure they don't
throw

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Optional API with safe wrapper; default persistence path is unchanged
when `storage` is not set.
> 
> **Overview**
> Adds an optional **`storage`** setting on the browser (and React
client) SDK so apps can plug in their own persistence instead of
**`window.localStorage`**, while keeping today’s default when the option
is omitted.
> 
> Shared client code introduces the **`LDStorage`** contract (`get` /
`set` / `clear`) and **`createSafeStorage`**, which adapts custom
implementations to the internal storage API: failures are logged, reads
return **`null`**, and writes are dropped so a bad implementation cannot
take down the host app. The browser client validates **`storage`**,
wraps it with **`createSafeStorage`**, and passes it into
**`BrowserPlatform`**, which uses the override when provided and
otherwise still chooses **`LocalStorage`** only when supported.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
a1f4117. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: joker23

packages/sdk/browser/__tests__/BrowserClient.storage.test.ts

@@ -0,0 +1,97 @@
+import { AutoEnvAttributes, LDLogger } from '@launchdarkly/js-client-sdk-common';
+
+import { makeClient } from '../src/BrowserClient';
+
+const mockPlatformConstructor = jest.fn();
+
+jest.mock('../src/platform/BrowserPlatform', () => ({
+  __esModule: true,
+  default: jest.fn().mockImplementation((logger, options, storage) => {
+    mockPlatformConstructor(logger, options, storage);
+    // eslint-disable-next-line global-require
+    const { makeBasicPlatform } = require('./BrowserClient.mocks');
+    const platform = makeBasicPlatform(options);
+    // Surface the storage the client wired in so we can assert on it, while
+    // keeping a working mock platform for the rest of construction.
+    if (storage) {
+      platform.storage = storage;
+    }
+    return platform;
+  }),
+}));
+
+let logger: LDLogger;
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  logger = { debug: jest.fn(), info: jest.fn(), warn: jest.fn(), error: jest.fn() };
+});
+
+function getWiredStorage() {
+  return mockPlatformConstructor.mock.calls[0][2];
+}
+
+it('wraps and passes a custom storage through to the platform', async () => {
+  const myStorage = {
+    get: jest.fn(async () => 'cached'),
+    set: jest.fn(async () => {}),
+    clear: jest.fn(async () => {}),
+  };
+
+  makeClient(
+    'client-side-id',
+    { key: 'user-key', kind: 'user' },
+    AutoEnvAttributes.Disabled,
+    { streaming: false, logger, diagnosticOptOut: true, storage: myStorage },
+  );
+
+  const wired = getWiredStorage();
+  expect(wired).toBeDefined();
+
+  // The wired storage delegates to the user's implementation.
+  await expect(wired.get('k')).resolves.toEqual('cached');
+  await wired.set('k', 'v');
+  await wired.clear('k');
+  expect(myStorage.get).toHaveBeenCalledWith('k');
+  expect(myStorage.set).toHaveBeenCalledWith('k', 'v');
+  expect(myStorage.clear).toHaveBeenCalledWith('k');
+  expect(logger.warn).not.toHaveBeenCalled();
+});
+
+it('does not pass a storage override when none is configured', () => {
+  makeClient(
+    'client-side-id',
+    { key: 'user-key', kind: 'user' },
+    AutoEnvAttributes.Disabled,
+    { streaming: false, logger, diagnosticOptOut: true },
+  );
+
+  expect(getWiredStorage()).toBeUndefined();
+});
+
+it('does not let a throwing custom storage escape the wrapper', async () => {
+  const throwingStorage = {
+    get: jest.fn(async () => {
+      throw new Error('boom');
+    }),
+    set: jest.fn(async () => {
+      throw new Error('boom');
+    }),
+    clear: jest.fn(async () => {
+      throw new Error('boom');
+    }),
+  };
+
+  makeClient(
+    'client-side-id',
+    { key: 'user-key', kind: 'user' },
+    AutoEnvAttributes.Disabled,
+    { streaming: false, logger, diagnosticOptOut: true, storage: throwingStorage },
+  );
+
+  const wired = getWiredStorage();
+  await expect(wired.get('k')).resolves.toBeNull();
+  await expect(wired.set('k', 'v')).resolves.toBeUndefined();
+  await expect(wired.clear('k')).resolves.toBeUndefined();
+  expect(logger.error).toHaveBeenCalledTimes(3);
+});

packages/sdk/browser/__tests__/options.test.ts

@@ -1,6 +1,6 @@
 import { jest } from '@jest/globals';
 
-import { LDLogger } from '@launchdarkly/js-client-sdk-common';
+import { LDLogger, LDStorage } from '@launchdarkly/js-client-sdk-common';
 
 import validateBrowserOptions, { filterToBaseOptionsWithDefaults } from '../src/options';
 
@@ -16,10 +16,23 @@ beforeEach(() => {
 });
 
 it('logs no warnings when all configuration is valid', () => {
+  const storage: LDStorage = {
+    get(_key: string): Promise<string | null> {
+      throw new Error('Function not implemented.');
+    },
+    set(_key: string, _value: string): Promise<void> {
+      throw new Error('Function not implemented.');
+    },
+    clear(_key: string): Promise<void> {
+      throw new Error('Function not implemented.');
+    },
+  };
+
   validateBrowserOptions(
     {
       fetchGoals: true,
       eventUrlTransformer: (url: string) => url,
+      storage,
     },
     logger,
   );

packages/sdk/browser/__tests__/platform/BrowserPlatform.test.ts

@@ -0,0 +1,63 @@
+import { LDLogger, Storage } from '@launchdarkly/js-client-sdk-common';
+
+import BrowserPlatform from '../../src/platform/BrowserPlatform';
+import LocalStorage, { isLocalStorageSupported } from '../../src/platform/LocalStorage';
+
+jest.mock('../../src/platform/LocalStorage', () => {
+  const actual = jest.requireActual('../../src/platform/LocalStorage');
+  return {
+    __esModule: true,
+    default: jest.fn(),
+    isLocalStorageSupported: jest.fn(() => true),
+    getAllStorageKeys: actual.getAllStorageKeys,
+  };
+});
+
+const mockLocalStorage = LocalStorage as jest.MockedClass<typeof LocalStorage>;
+const mockIsSupported = isLocalStorageSupported as jest.MockedFunction<typeof isLocalStorageSupported>;
+
+let logger: LDLogger;
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  mockIsSupported.mockReturnValue(true);
+  logger = { debug: jest.fn(), info: jest.fn(), warn: jest.fn(), error: jest.fn() };
+});
+
+function makeCustomStorage(): Storage {
+  return { get: jest.fn(), set: jest.fn(), clear: jest.fn() };
+}
+
+it('uses the provided storage override and does not construct LocalStorage', () => {
+  const custom = makeCustomStorage();
+  const platform = new BrowserPlatform(logger, {}, custom);
+
+  expect(platform.storage).toBe(custom);
+  expect(mockLocalStorage).not.toHaveBeenCalled();
+});
+
+it('falls back to LocalStorage when no override is provided and localStorage is supported', () => {
+  const platform = new BrowserPlatform(logger, {});
+
+  expect(mockLocalStorage).toHaveBeenCalledTimes(1);
+  expect(platform.storage).toBe(mockLocalStorage.mock.instances[0]);
+});
+
+it('has no storage when no override is provided and localStorage is unsupported', () => {
+  mockIsSupported.mockReturnValue(false);
+
+  const platform = new BrowserPlatform(logger, {});
+
+  expect(platform.storage).toBeUndefined();
+  expect(mockLocalStorage).not.toHaveBeenCalled();
+});
+
+it('uses the provided storage override even when localStorage is unsupported', () => {
+  mockIsSupported.mockReturnValue(false);
+  const custom = makeCustomStorage();
+
+  const platform = new BrowserPlatform(logger, {}, custom);
+
+  expect(platform.storage).toBe(custom);
+  expect(mockLocalStorage).not.toHaveBeenCalled();
+});

packages/sdk/browser/src/BrowserClient.ts

@@ -7,6 +7,7 @@ import {
   Configuration,
   createDefaultSourceFactoryProvider,
   createFDv2DataManagerBase,
+  createSafeStorage,
   FDv2ConnectionMode,
   FlagManager,
   Hook,
@@ -71,9 +72,12 @@ class BrowserClientImpl extends LDClientImpl {
     // TODO: Use the already-configured baseUri from the SDK config. SDK-560
     const baseUrl = options.baseUri ?? 'https://clientsdk.launchdarkly.com';
 
-    const platform = overridePlatform ?? new BrowserPlatform(logger, options);
     // Only the browser-specific options are in validatedBrowserOptions.
     const validatedBrowserOptions = validateBrowserOptions(options, logger);
+    const safeStorage = validatedBrowserOptions.storage
+      ? createSafeStorage(validatedBrowserOptions.storage, logger)
+      : undefined;
+    const platform = overridePlatform ?? new BrowserPlatform(logger, options, safeStorage);
     // The base options are in baseOptionsWithDefaults.
     const baseOptionsWithDefaults = filterToBaseOptionsWithDefaults({ ...options, logger });
     const { eventUrlTransformer } = validatedBrowserOptions;

packages/sdk/browser/src/common.ts

@@ -31,6 +31,7 @@ export type {
   LDInspection,
   LDLogger,
   LDLogLevel,
+  LDStorage,
   LDMultiKindContext,
   LDSingleKindContext,
   TrackSeriesContext,

packages/sdk/browser/src/options.ts

@@ -2,6 +2,7 @@ import {
   LDClientDataSystemOptions,
   LDLogger,
   LDOptions as LDOptionsBase,
+  LDStorage,
   ManualModeSwitching,
   OptionMessages,
   TypeValidator,
@@ -96,6 +97,23 @@ export interface BrowserOptions extends Omit<LDOptionsBase, 'initialConnectionMo
    * A list of plugins to be used with the SDK.
    */
   plugins?: LDPlugin[];
+
+  /**
+   * Custom storage implementation.
+   *
+   * Storage is used for caching flag values for a context as well as persisting
+   * generated identifiers.
+   *
+   * By default the browser SDK uses `window.localStorage`.
+   *
+   * @remarks
+   * If there is an issue with the storage implementation, then generated keys
+   * and context caches may not be persisted. This will cause the SDK to generate
+   * new keys and context caches on every startup. Implementations should not
+   * throw; if one does, the SDK logs the error and degrades gracefully rather
+   * than crashing the application.
+   */
+  storage?: LDStorage;
 }
 
 export interface ValidatedOptions {
@@ -104,20 +122,23 @@ export interface ValidatedOptions {
   streaming?: boolean;
   automaticBackgroundHandling?: boolean;
   plugins: LDPlugin[];
+  storage?: LDStorage;
 }
 
 const optDefaults = {
   fetchGoals: true,
   eventUrlTransformer: (url: string) => url,
   streaming: undefined,
   plugins: [],
+  storage: undefined,
 };
 
 const validators: { [Property in keyof BrowserOptions]: TypeValidator | undefined } = {
   fetchGoals: TypeValidators.Boolean,
   eventUrlTransformer: TypeValidators.Function,
   streaming: TypeValidators.Boolean,
   plugins: TypeValidators.createTypeArray('LDPlugin', {}),
+  storage: TypeValidators.Object,
 };
 
 function withBrowserDefaults(opts: BrowserOptions): BrowserOptions {

packages/sdk/browser/src/platform/BrowserPlatform.ts

@@ -23,10 +23,8 @@ export default class BrowserPlatform implements Platform {
   requests: Requests = new BrowserRequests();
   storage?: Storage;
 
-  constructor(logger: LDLogger, options: BrowserOptions) {
-    if (isLocalStorageSupported()) {
-      this.storage = new LocalStorage(logger);
-    }
+  constructor(logger: LDLogger, options: BrowserOptions, storage?: Storage) {
+    this.storage = storage ?? (isLocalStorageSupported() ? new LocalStorage(logger) : undefined);
     this.info = new BrowserInfo(options);
   }
 }

packages/sdk/react/__tests__/client/LDReactClientOptions.storage.test.ts

@@ -0,0 +1,14 @@
+import type { LDStorage } from '../../src/client';
+import type { LDReactClientOptions } from '../../src/client/LDOptions';
+
+it('accepts a custom storage override on the react client options', () => {
+  const storage: LDStorage = {
+    get: async () => null,
+    set: async () => {},
+    clear: async () => {},
+  };
+
+  const options: LDReactClientOptions = { storage };
+
+  expect(options.storage).toBe(storage);
+});