fix: disable cache was not working (#1187)

**Requirements**

- [x] I have added test coverage for new or changed functionality
- [x] I have followed the repository's [pull request submission
guidelines](../blob/main/CONTRIBUTING.md#submitting-pull-requests)
- [x] I have validated my changes against all supported platform
versions

**Related issues**

sdk-2023

**Describe the solution you've provided**

- added an `disableCache` option
- fixed the overall cache pruning behavior

BEGIN_COMMIT_OVERRIDE
fix: Max cached context enforcement wasn't working for 0.
feat: Add explicit disableCache setting.
END_COMMIT_OVERRIDE

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes persistent flag caching behavior (read/write and eviction) and
introduces a new `disableCache` option, which can affect offline
fallback/initialization latency if misconfigured. Logic is covered by
new unit tests but touches core persistence paths.
> 
> **Overview**
> Fixes persistent flag caching so it can be **explicitly disabled** via
a new `disableCache` option (plumbed through `LDOptions` →
`Configuration` → `LDClientImpl` → `DefaultFlagManager` →
`FlagPersistence`) and validated in configuration parsing.
> 
> Updates `FlagPersistence` to skip all cache reads/writes when
`disableCache` is true or `maxCachedContexts <= 0`, while still
pruning/clearing previously cached entries and ensuring pruned contexts
(including equal-timestamp edge cases) are not re-written. Adds targeted
tests covering `maxCachedContexts=0`, `disableCache=true`, and pruning
behavior.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
431fce0. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/launchdarkly/js-core/pull/1187"
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/shared/sdk-client/__tests__/flag-manager/FlagManager.test.ts

@@ -25,6 +25,7 @@ describe('FlagManager override tests', () => {
       mockPlatform,
       TEST_SDK_KEY,
       TEST_MAX_CACHED_CONTEXTS,
+      false,
       mockLogger,
     );
   });

packages/shared/sdk-client/__tests__/flag-manager/FlagPersistence.test.ts

@@ -28,6 +28,7 @@ describe('FlagPersistence tests', () => {
       makeMockPlatform(makeMemoryStorage(), makeMockCrypto()),
       TEST_NAMESPACE,
       5,
+      false,
       flagStore,
       createFlagUpdater(flagStore, mockLogger),
       mockLogger,
@@ -45,6 +46,7 @@ describe('FlagPersistence tests', () => {
       makeMockPlatform(makeCorruptStorage(), makeMockCrypto()),
       TEST_NAMESPACE,
       5,
+      false,
       flagStore,
       createFlagUpdater(flagStore, mockLogger),
       mockLogger,
@@ -72,6 +74,7 @@ describe('FlagPersistence tests', () => {
       makeMockPlatform(makeMemoryStorage(), makeMockCrypto()),
       TEST_NAMESPACE,
       5,
+      false,
       flagStore,
       flagUpdater,
       mockLogger,
@@ -100,6 +103,7 @@ describe('FlagPersistence tests', () => {
       makeMockPlatform(memoryStorage, makeMockCrypto()),
       TEST_NAMESPACE,
       5,
+      false,
       flagStore,
       flagUpdater,
       mockLogger,
@@ -129,6 +133,7 @@ describe('FlagPersistence tests', () => {
       mockPlatform,
       TEST_NAMESPACE,
       5,
+      false,
       flagStore,
       flagUpdater,
       mockLogger,
@@ -165,6 +170,7 @@ describe('FlagPersistence tests', () => {
       mockPlatform,
       TEST_NAMESPACE,
       1,
+      false,
       flagStore,
       flagUpdater,
       mockLogger,
@@ -213,6 +219,7 @@ describe('FlagPersistence tests', () => {
       mockPlatform,
       TEST_NAMESPACE,
       1,
+      false,
       flagStore,
       flagUpdater,
       mockLogger,
@@ -244,6 +251,7 @@ describe('FlagPersistence tests', () => {
       mockPlatform,
       TEST_NAMESPACE,
       5,
+      false,
       flagStore,
       flagUpdater,
       mockLogger,
@@ -277,6 +285,7 @@ describe('FlagPersistence tests', () => {
       mockPlatform,
       TEST_NAMESPACE,
       5,
+      false,
       flagStore,
       flagUpdater,
       mockLogger,
@@ -305,6 +314,173 @@ describe('FlagPersistence tests', () => {
     expect(await memoryStorage.get(contextDataKey)).toContain('"version":2');
   });
 
+  it('does not write to storage when maxCachedContexts is 0', async () => {
+    const memoryStorage = makeMemoryStorage();
+    const mockPlatform = makeMockPlatform(memoryStorage, makeMockCrypto());
+    const flagStore = createDefaultFlagStore();
+    const mockLogger = makeMockLogger();
+    const flagUpdater = createFlagUpdater(flagStore, mockLogger);
+
+    const fpUnderTest = new FlagPersistence(
+      mockPlatform,
+      TEST_NAMESPACE,
+      0,
+      false,
+      flagStore,
+      flagUpdater,
+      mockLogger,
+    );
+
+    const context = Context.fromLDContext({ kind: 'org', key: 'TestyPizza' });
+    const flags = { flagA: { version: 1, flag: makeMockFlag() } };
+
+    await fpUnderTest.init(context, flags);
+
+    const contextDataKey = await namespaceForContextData(
+      mockPlatform.crypto,
+      TEST_NAMESPACE,
+      context,
+    );
+    expect(await memoryStorage.get(contextDataKey)).toBeNull();
+  });
+
+  it('clears previously cached data when maxCachedContexts is 0', async () => {
+    const memoryStorage = makeMemoryStorage();
+    const crypto = makeMockCrypto();
+    const mockPlatform = makeMockPlatform(memoryStorage, crypto);
+    const flagStore = createDefaultFlagStore();
+    const mockLogger = makeMockLogger();
+    const flagUpdater = createFlagUpdater(flagStore, mockLogger);
+
+    const contextA = Context.fromLDContext({ kind: 'org', key: 'TestyPizza' });
+    const storageKeyA = await namespaceForContextData(crypto, TEST_NAMESPACE, contextA);
+    const indexKey = await namespaceForContextIndex(TEST_NAMESPACE);
+
+    // Pre-populate storage as if a prior session had maxCachedContexts > 0
+    const indexJson = JSON.stringify({ index: [{ id: storageKeyA, timestamp: 1 }] });
+    await memoryStorage.set(indexKey, indexJson);
+    await memoryStorage.set(storageKeyA, JSON.stringify({ flagA: makeMockFlag() }));
+
+    const fpUnderTest = new FlagPersistence(
+      mockPlatform,
+      TEST_NAMESPACE,
+      0,
+      false,
+      flagStore,
+      flagUpdater,
+      mockLogger,
+    );
+
+    const flags = { flagA: { version: 1, flag: makeMockFlag() } };
+    await fpUnderTest.init(contextA, flags);
+
+    // Existing entry must have been evicted
+    expect(await memoryStorage.get(storageKeyA)).toBeNull();
+    // Index must be saved as empty
+    const savedIndex = JSON.parse((await memoryStorage.get(indexKey))!);
+    expect(savedIndex.index).toHaveLength(0);
+  });
+
+  it('does not load from storage when maxCachedContexts is 0', async () => {
+    const memoryStorage = makeMemoryStorage();
+    const mockPlatform = makeMockPlatform(memoryStorage, makeMockCrypto());
+    const flagStore = createDefaultFlagStore();
+    const mockLogger = makeMockLogger();
+    const flagUpdater = createFlagUpdater(flagStore, mockLogger);
+
+    // First write data to storage using a normal FlagPersistence
+    const writeFp = new FlagPersistence(
+      mockPlatform,
+      TEST_NAMESPACE,
+      5,
+      false,
+      flagStore,
+      flagUpdater,
+      mockLogger,
+    );
+    const context = Context.fromLDContext({ kind: 'org', key: 'TestyPizza' });
+    const flags = { flagA: { version: 1, flag: makeMockFlag() } };
+    await writeFp.init(context, flags);
+
+    // Now try to load with maxCachedContexts: 0
+    const fpUnderTest = new FlagPersistence(
+      mockPlatform,
+      TEST_NAMESPACE,
+      0,
+      false,
+      flagStore,
+      flagUpdater,
+      mockLogger,
+    );
+    const didLoad = await fpUnderTest.loadCached(context);
+    expect(didLoad).toEqual(false);
+  });
+
+  it('does not write to storage when disableCache is true', async () => {
+    const memoryStorage = makeMemoryStorage();
+    const mockPlatform = makeMockPlatform(memoryStorage, makeMockCrypto());
+    const flagStore = createDefaultFlagStore();
+    const mockLogger = makeMockLogger();
+    const flagUpdater = createFlagUpdater(flagStore, mockLogger);
+
+    const fpUnderTest = new FlagPersistence(
+      mockPlatform,
+      TEST_NAMESPACE,
+      5,
+      true,
+      flagStore,
+      flagUpdater,
+      mockLogger,
+    );
+
+    const context = Context.fromLDContext({ kind: 'org', key: 'TestyPizza' });
+    const flags = { flagA: { version: 1, flag: makeMockFlag() } };
+
+    await fpUnderTest.init(context, flags);
+
+    const contextDataKey = await namespaceForContextData(
+      mockPlatform.crypto,
+      TEST_NAMESPACE,
+      context,
+    );
+    expect(await memoryStorage.get(contextDataKey)).toBeNull();
+  });
+
+  it('does not load from storage when disableCache is true', async () => {
+    const memoryStorage = makeMemoryStorage();
+    const mockPlatform = makeMockPlatform(memoryStorage, makeMockCrypto());
+    const flagStore = createDefaultFlagStore();
+    const mockLogger = makeMockLogger();
+    const flagUpdater = createFlagUpdater(flagStore, mockLogger);
+
+    // First write data to storage using a normal FlagPersistence
+    const writeFp = new FlagPersistence(
+      mockPlatform,
+      TEST_NAMESPACE,
+      5,
+      false,
+      flagStore,
+      flagUpdater,
+      mockLogger,
+    );
+    const context = Context.fromLDContext({ kind: 'org', key: 'TestyPizza' });
+    const flags = { flagA: { version: 1, flag: makeMockFlag() } };
+    await writeFp.init(context, flags);
+
+    // Now try to load with disableCache: true
+    const fpUnderTest = new FlagPersistence(
+      mockPlatform,
+      TEST_NAMESPACE,
+      5,
+      true,
+      flagStore,
+      flagUpdater,
+      mockLogger,
+    );
+    const didLoad = await fpUnderTest.loadCached(context);
+    expect(didLoad).toEqual(false);
+  });
+
   test('upsert ignores inactive context', async () => {
     const memoryStorage = makeMemoryStorage();
     const mockPlatform = makeMockPlatform(memoryStorage, makeMockCrypto());
@@ -316,6 +492,7 @@ describe('FlagPersistence tests', () => {
       mockPlatform,
       TEST_NAMESPACE,
       5,
+      false,
       flagStore,
       flagUpdater,
       mockLogger,
@@ -350,6 +527,55 @@ describe('FlagPersistence tests', () => {
     expect(await memoryStorage.get(activeContextDataKey)).not.toBeNull();
     expect(await memoryStorage.get(inactiveContextDataKey)).toBeNull();
   });
+
+  it('does not write to storage when current context is pruned due to equal timestamps', async () => {
+    const memoryStorage = makeMemoryStorage();
+    const crypto = makeMockCrypto();
+    const mockPlatform = makeMockPlatform(memoryStorage, crypto);
+    const flagStore = createDefaultFlagStore();
+    const mockLogger = makeMockLogger();
+    const flagUpdater = createFlagUpdater(flagStore, mockLogger);
+
+    const contextA = Context.fromLDContext({ kind: 'org', key: 'TestyPizza' });
+    const contextB = Context.fromLDContext({ kind: 'user', key: 'TestyUser' });
+
+    const storageKeyA = await namespaceForContextData(crypto, TEST_NAMESPACE, contextA);
+    const storageKeyB = await namespaceForContextData(crypto, TEST_NAMESPACE, contextB);
+    const indexKey = await namespaceForContextIndex(TEST_NAMESPACE);
+
+    // Pre-populate storage: index with A before B (same timestamp t=1), and B's flag data
+    const indexJson = JSON.stringify({
+      index: [
+        { id: storageKeyA, timestamp: 1 },
+        { id: storageKeyB, timestamp: 1 },
+      ],
+    });
+    await memoryStorage.set(indexKey, indexJson);
+    await memoryStorage.set(storageKeyB, JSON.stringify({ flagB: makeMockFlag() }));
+
+    const fpUnderTest = new FlagPersistence(
+      mockPlatform,
+      TEST_NAMESPACE,
+      1,
+      false,
+      flagStore,
+      flagUpdater,
+      mockLogger,
+      () => 1,
+    );
+
+    const flags = { flagA: { version: 1, flag: makeMockFlag() } };
+    await fpUnderTest.init(contextA, flags);
+
+    // A was in the pruned list — must not be re-written to storage
+    expect(await memoryStorage.get(storageKeyA)).toBeNull();
+    // B was not pruned — its existing data should be untouched
+    expect(await memoryStorage.get(storageKeyB)).not.toBeNull();
+    // Index should contain only B
+    const savedIndex = JSON.parse((await memoryStorage.get(indexKey))!);
+    expect(savedIndex.index).toHaveLength(1);
+    expect(savedIndex.index[0].id).toBe(storageKeyB);
+  });
 });
 
 describe('FlagPersistence freshness', () => {
@@ -363,6 +589,7 @@ describe('FlagPersistence freshness', () => {
       makeMockPlatform(memoryStorage, crypto),
       TEST_NAMESPACE,
       5,
+      false,
       flagStore,
       createFlagUpdater(flagStore, mockLogger),
       mockLogger,

packages/shared/sdk-client/src/LDClientImpl.ts

@@ -129,6 +129,7 @@ export default class LDClientImpl implements LDClient, LDClientIdentifyResult {
       this.platform,
       sdkKey,
       this._config.maxCachedContexts,
+      this._config.disableCache ?? false,
       this._config.logger,
     );
     this._diagnosticsManager = createDiagnosticsManager(sdkKey, this._config, platform);

packages/shared/sdk-client/src/api/LDOptions.ts

@@ -295,4 +295,13 @@ export interface LDOptions {
    * protocol.
    */
   dataSystem?: LDClientDataSystemOptions;
+
+  /**
+   * Set to true to completely disable the persistent flag cache. When disabled,
+   * flags are never read from or written to local storage. This takes precedence
+   * over `maxCachedContexts`.
+   *
+   * @defaultValue false
+   */
+  disableCache?: boolean;
 }

packages/shared/sdk-client/src/configuration/Configuration.ts

@@ -31,6 +31,7 @@ export interface LDClientInternalOptions extends internal.LDInternalOptions {
 export interface Configuration {
   readonly logger: LDLogger;
   readonly maxCachedContexts: number;
+  readonly disableCache?: boolean;
   readonly capacity: number;
   readonly diagnosticRecordingInterval: number;
   readonly flushInterval: number;
@@ -93,6 +94,7 @@ export default class ConfigurationImpl implements Configuration {
   private readonly streamUri = DEFAULT_STREAM;
 
   public readonly maxCachedContexts = 5;
+  public readonly disableCache: boolean = false;
 
   public readonly capacity = 100;
   public readonly diagnosticRecordingInterval = 900;

packages/shared/sdk-client/src/configuration/validators.ts

@@ -37,6 +37,7 @@ export default function createValidators(
 
     privateAttributes: TypeValidators.StringArray,
 
+    disableCache: TypeValidators.Boolean,
     applicationInfo: TypeValidators.Object,
     wrapperName: TypeValidators.String,
     wrapperVersion: TypeValidators.String,