fix(electron-sdk): localstorage indexing (#1262)

This PR will fix the localstorage indexing by removing the previous
nested structure:
```
ldcache-{credential}
```

To:
```
ldcache
```

The new structure is more consistent with other SDKs by calculating the
storage index purely out of the context canonical keys.

This PR will also serialize the write to this cache so that multiple
instances of this SDK could exist.


<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes how all Electron SDK instances persist flag data by moving to
a shared `ldcache` file and introducing singleton/queued flush behavior;
this can affect cache isolation and persistence correctness across
clients. Risk is mitigated by added tests, but storage/indexing
regressions would impact offline/bootstrapped evaluations.
> 
> **Overview**
> Switches Electron SDK persistent flag/context caching from
per-credential files (e.g. `ldcache-{credentialHash}`) to a single
shared `ldcache` file via a singleton `ElectronStorage`, aligning cache
indexing purely with context-derived keys.
> 
> `ElectronStorage` now updates its in-memory cache first and
**serializes disk flushes** through a queued atomic-write mechanism;
initialization failures now surface as thrown errors (with cause) to the
platform wrapper, which logs and swallows storage failures.
> 
> Updates contract tests to reset the storage singleton between clients
and removes the `singleton` capability flag, and adds coverage for
`maxCachedContexts` eviction/disabled caching plus new
`ElectronPlatform` error-logging tests.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
81826d7. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->


<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/launchdarkly/js-core/pull/1262"
target="_blank">
  <picture>
<source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-open-in-devin-review-dark.svg?v=1">
<img
src="https://static.devin.ai/assets/gh-open-in-devin-review-light.svg?v=1"
alt="Open with Devin">
  </picture>
</a>
<!-- devin-review-badge-end -->

Author: joker23

packages/sdk/electron/__tests__/ElectronClient.mainProcess.test.ts

@@ -288,6 +288,101 @@ describe('given an initialized ElectronClient with enableIPC: false and polling'
   });
 });
 
+function makeMemoryStorage() {
+  const data = new Map<string, string>();
+  return {
+    get: jest.fn(async (key: string) => data.get(key) ?? null),
+    set: jest.fn(async (key: string, value: string) => {
+      data.set(key, value);
+    }),
+    clear: jest.fn(async (key: string) => {
+      data.delete(key);
+    }),
+    keys: () => Array.from(data.keys()),
+  };
+}
+
+describe('maxCachedContexts', () => {
+  it('evicts the oldest cached context when the limit is exceeded', async () => {
+    const storage = makeMemoryStorage();
+    const mockedFetch = mockFetch(JSON.stringify(remoteFlagsMockData), 200);
+    (ElectronPlatform as jest.Mock).mockReturnValue({
+      crypto: new ElectronCrypto(),
+      info: new ElectronInfo(),
+      requests: {
+        createEventSource: jest.fn(),
+        fetch: mockedFetch,
+        getEventSourceCapabilities: jest.fn(),
+      },
+      encoding: new ElectronEncoding(),
+      storage,
+    });
+
+    const client = createClient(clientSideId, DEFAULT_INITIAL_CONTEXT, {
+      initialConnectionMode: 'polling',
+      enableIPC: false,
+      diagnosticOptOut: true,
+      sendEvents: false,
+      maxCachedContexts: 1,
+    });
+    await client.start();
+
+    // After start, context A's flags are cached.
+    // Storage should contain: context index + context A data + context A freshness
+    const keysAfterStart = storage.keys();
+    const contextDataKeys = keysAfterStart.filter(
+      (k) => !k.includes('ContextIndex') && !k.includes('_freshness'),
+    );
+    expect(contextDataKeys).toHaveLength(1);
+
+    // Identify a second context — context A should be evicted (maxCachedContexts: 1)
+    await client.identify({ kind: 'user', key: 'context-b' });
+
+    const keysAfterIdentify = storage.keys();
+    const contextDataKeysAfter = keysAfterIdentify.filter(
+      (k) => !k.includes('ContextIndex') && !k.includes('_freshness'),
+    );
+    expect(contextDataKeysAfter).toHaveLength(1);
+
+    // The surviving key should be different from the first one (context B replaced context A)
+    expect(contextDataKeysAfter[0]).not.toEqual(contextDataKeys[0]);
+  });
+
+  it('does not cache flags when maxCachedContexts is 0', async () => {
+    const storage = makeMemoryStorage();
+    const mockedFetch = mockFetch(JSON.stringify(remoteFlagsMockData), 200);
+    (ElectronPlatform as jest.Mock).mockReturnValue({
+      crypto: new ElectronCrypto(),
+      info: new ElectronInfo(),
+      requests: {
+        createEventSource: jest.fn(),
+        fetch: mockedFetch,
+        getEventSourceCapabilities: jest.fn(),
+      },
+      encoding: new ElectronEncoding(),
+      storage,
+    });
+
+    const client = createClient(clientSideId, DEFAULT_INITIAL_CONTEXT, {
+      initialConnectionMode: 'polling',
+      enableIPC: false,
+      diagnosticOptOut: true,
+      sendEvents: false,
+      maxCachedContexts: 0,
+    });
+    await client.start();
+
+    // Flags should still evaluate correctly from the network response
+    expect(client.boolVariation('on-off-flag', false)).toBe(true);
+
+    // But no context data should be persisted to storage
+    const contextDataKeys = storage
+      .keys()
+      .filter((k) => !k.includes('ContextIndex') && !k.includes('_freshness'));
+    expect(contextDataKeys).toHaveLength(0);
+  });
+});
+
 describe('given an initialized ElectronClient with enableIPC: false and streaming', () => {
   const logger: LDLogger = {
     debug: jest.fn(),

packages/sdk/electron/__tests__/platform/ElectronPlatform.test.ts

@@ -0,0 +1,52 @@
+import type { LDLogger } from '@launchdarkly/js-client-sdk-common';
+
+import ElectronPlatform from '../../src/platform/ElectronPlatform';
+
+const failingStorage = {
+  get: jest.fn().mockRejectedValue(new Error('disk read failed')),
+  set: jest.fn().mockRejectedValue(new Error('disk write failed')),
+  clear: jest.fn().mockRejectedValue(new Error('disk clear failed')),
+};
+
+jest.mock('../../src/platform/ElectronStorage', () => ({
+  getElectronStorage: () => failingStorage,
+}));
+
+const logger: LDLogger = {
+  debug: jest.fn(),
+  info: jest.fn(),
+  warn: jest.fn(),
+  error: jest.fn(),
+};
+
+let platform: ElectronPlatform;
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  platform = new ElectronPlatform(logger, {});
+});
+
+it('logs error and returns null when storage get fails', async () => {
+  const result = await platform.storage!.get('some-key');
+
+  expect(result).toBeNull();
+  expect(logger.error).toHaveBeenCalledWith(
+    expect.stringContaining('Error getting key from storage: some-key'),
+  );
+});
+
+it('logs error and swallows when storage set fails', async () => {
+  await platform.storage!.set('some-key', 'some-value');
+
+  expect(logger.error).toHaveBeenCalledWith(
+    expect.stringContaining('Error setting key in storage: some-key'),
+  );
+});
+
+it('logs error and swallows when storage clear fails', async () => {
+  await platform.storage!.clear('some-key');
+
+  expect(logger.error).toHaveBeenCalledWith(
+    expect.stringContaining('Error clearing key from storage: some-key'),
+  );
+});