fix: FDv2 Only -- Adjust the behavior of initialization when only cache initializers are available. (#1304)

The main goal of this is to attach meta-data to cache initializer
factories to allow for making some additional runtime decisions with
regard to initialization.

In doing so I am changing the factory types from functions into an
interface. Which will make this kind of change easier in the future. So
the majority of actual change is from that adjustment.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Touches FDv2 data-source orchestration and factory typings; mistakes
could change initialization resolution/rejection and status reporting
(especially offline/cache-only scenarios). Scope is contained to FDv2
pipeline and is covered by expanded tests.
> 
> **Overview**
> **FDv2 initialization now treats cache-only configurations as valid
even on cache miss.** `FDv2DataSource` detects when *all* initializers
are cache-marked and there are no synchronizers, and in that case
resolves initialization (optionally asserting `VALID`) instead of
rejecting with “all sources exhausted”; it also avoids overwriting
previously-reported error status and guards against `close()` races
during the exhaustion path.
> 
> **Factory types were refactored from function types to `{ create(...)
}` interfaces** (`InitializerFactory` adds optional `isCache`),
requiring updates across `SourceManager`, `SourceFactoryProvider`,
`FDv2DataManagerBase` (FDv1 fallback factory), and tests;
`createCacheInitializerFactory` now returns an `isCache`-marked factory.
CI package-size threshold was bumped from `38000` to `39000`.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
1104dc5. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: kinyoklion

.github/workflows/sdk-client.yml

@@ -32,4 +32,4 @@ jobs:
           target_file: 'packages/shared/sdk-client/dist/esm/index.mjs'
           package_name: '@launchdarkly/js-client-sdk-common'
           pr_number: ${{ github.event.number }}
-          size_limit: 38000
+          size_limit: 39000

packages/shared/sdk-client/__tests__/datasource/FDv2DataManagerBase.test.ts

@@ -93,8 +93,10 @@ function makeFlagManager() {
 
 function makeSourceFactoryProvider() {
   return {
-    createInitializerFactory: jest.fn((_entry: any) => jest.fn()),
-    createSynchronizerSlot: jest.fn((_entry: any) => createSynchronizerSlot(jest.fn())),
+    createInitializerFactory: jest.fn((entry: any) =>
+      entry?.type === 'cache' ? { create: jest.fn(), isCache: true } : { create: jest.fn() },
+    ),
+    createSynchronizerSlot: jest.fn((_entry: any) => createSynchronizerSlot({ create: jest.fn() })),
   };
 }
 
@@ -983,7 +985,7 @@ it('uses per-mode fdv1Fallback pollInterval from MODE_TABLE for background mode'
   const dsConfig = capturedDataSourceConfigs[0];
   const fdv1Slot = dsConfig.synchronizerSlots[dsConfig.synchronizerSlots.length - 1];
   // Invoke the factory to trigger createFDv1PollingSynchronizer.
-  fdv1Slot.factory(() => undefined);
+  fdv1Slot.factory.create(() => undefined);
 
   // The FDv1 fallback synchronizer should use background's default (3600s = 3600000ms).
   expect(createFDv1PollingSynchronizer).toHaveBeenCalledWith(
@@ -1022,6 +1024,25 @@ it('resolves identify immediately when initial mode has no sources', async () =>
   manager.close();
 });
 
+it('builds offline mode with a cache-marked initializer factory and no synchronizers', async () => {
+  // Verifies that the offline mode passes an isCache-marked factory to the
+  // data source. FDv2DataSource is responsible for recognizing this
+  // cache-only configuration and completing initialization on a cache miss.
+  const manager = createFDv2DataManagerBase(makeBaseConfig({ foregroundMode: 'offline' }));
+
+  const { resolve, reject } = await identifyManager(manager);
+
+  expect(resolve).toHaveBeenCalledTimes(1);
+  expect(reject).not.toHaveBeenCalled();
+
+  const dsConfig = capturedDataSourceConfigs[0];
+  expect(dsConfig.synchronizerSlots).toEqual([]);
+  expect(dsConfig.initializerFactories).toHaveLength(1);
+  expect(dsConfig.initializerFactories[0].isCache).toBe(true);
+
+  manager.close();
+});
+
 it('does not identify after close', async () => {
   const manager = createFDv2DataManagerBase(makeBaseConfig());
   manager.close();

packages/shared/sdk-client/__tests__/datasource/SourceFactoryProvider.test.ts

@@ -109,7 +109,7 @@ beforeEach(() => {
   });
   mockCreateStreamingInitializer.mockReturnValue({ close: jest.fn() });
   mockCreateStreamingSynchronizer.mockReturnValue({ close: jest.fn() });
-  mockCreateCacheInitializerFactory.mockReturnValue(jest.fn());
+  mockCreateCacheInitializerFactory.mockReturnValue({ create: jest.fn(), isCache: true });
   mockMakeFDv2Requestor.mockReturnValue({ poll: jest.fn() });
 });
 
@@ -124,7 +124,7 @@ it('creates a PollingInitializer for a polling initializer entry', () => {
 
   expect(factory).toBeDefined();
   const selectorGetter = () => 'some-selector';
-  factory!(selectorGetter);
+  factory!.create(selectorGetter);
   expect(mockCreatePollingInitializer).toHaveBeenCalledWith(
     ctx.requestor,
     ctx.logger,
@@ -141,7 +141,7 @@ it('creates a StreamingInitializer for a streaming initializer entry', () => {
 
   expect(factory).toBeDefined();
   const selectorGetter = () => 'some-selector';
-  factory!(selectorGetter);
+  factory!.create(selectorGetter);
   expect(mockCreateStreamingBase).toHaveBeenCalledWith(
     expect.objectContaining({
       requests: ctx.requests,
@@ -169,6 +169,7 @@ it('creates a CacheInitializer for a cache initializer entry', () => {
     logger: ctx.logger,
   });
   expect(factory).toBe(mockCreateCacheInitializerFactory.mock.results[0].value);
+  expect(factory!.isCache).toBe(true);
 });
 
 it('returns undefined for an unknown initializer entry type', () => {
@@ -196,7 +197,7 @@ it('creates a PollingSynchronizer slot for a polling synchronizer entry', () =>
   // Invoke the factory that was passed to createSynchronizerSlot
   const factoryArg = mockCreateSynchronizerSlot.mock.calls[0][0];
   const selectorGetter = () => 'sel';
-  factoryArg(selectorGetter);
+  factoryArg.create(selectorGetter);
   expect(mockCreatePollingSynchronizer).toHaveBeenCalledWith(
     ctx.requestor,
     ctx.logger,
@@ -218,7 +219,7 @@ it('creates a StreamingSynchronizer slot for a streaming synchronizer entry', ()
   // Invoke the factory that was passed to createSynchronizerSlot
   const factoryArg = mockCreateSynchronizerSlot.mock.calls[0][0];
   const selectorGetter = () => 'sel';
-  factoryArg(selectorGetter);
+  factoryArg.create(selectorGetter);
   expect(mockCreateStreamingBase).toHaveBeenCalledWith(
     expect.objectContaining({
       requests: ctx.requests,
@@ -255,7 +256,7 @@ it('creates a new requestor when polling entry has endpoint overrides', () => {
   expect(factory).toBeDefined();
 
   const selectorGetter = () => undefined;
-  factory!(selectorGetter);
+  factory!.create(selectorGetter);
 
   expect(mockMakeFDv2Requestor).toHaveBeenCalledWith(
     ctx.plainContextString,
@@ -288,7 +289,7 @@ it('uses per-entry pollInterval override for polling synchronizer', () => {
 
   const factoryArg = mockCreateSynchronizerSlot.mock.calls[0][0];
   const selectorGetter = () => undefined;
-  factoryArg(selectorGetter);
+  factoryArg.create(selectorGetter);
 
   expect(mockCreatePollingSynchronizer).toHaveBeenCalledWith(
     ctx.requestor,
@@ -307,7 +308,7 @@ it('uses per-entry initialReconnectDelay override for streaming initializer', ()
 
   const factory = provider.createInitializerFactory(entry, ctx);
   expect(factory).toBeDefined();
-  factory!(() => undefined);
+  factory!.create(() => undefined);
 
   expect(mockCreateStreamingBase).toHaveBeenCalledWith(
     expect.objectContaining({
@@ -328,7 +329,7 @@ it('ping handler uses the factory selector getter, not a stale reference', () =>
 
   let currentSelector: string | undefined = 'selector-v1';
   const selectorGetter = () => currentSelector;
-  factory!(selectorGetter);
+  factory!.create(selectorGetter);
 
   // Extract the pingHandler from the createStreamingBase call
   const streamingBaseArgs = mockCreateStreamingBase.mock.calls[0][0];
@@ -352,7 +353,7 @@ it('ping handler uses per-entry endpoint-overridden requestor', () => {
 
   const factory = provider.createInitializerFactory(entry, ctx);
   expect(factory).toBeDefined();
-  factory!(() => undefined);
+  factory!.create(() => undefined);
 
   // Extract the pingHandler from the createStreamingBase call
   const streamingBaseArgs = mockCreateStreamingBase.mock.calls[0][0];

packages/shared/sdk-client/__tests__/datasource/fdv2/CacheInitializer.test.ts

@@ -39,7 +39,7 @@ function createInitializer(
     context,
     logger,
   });
-  return factory(noSelector);
+  return factory.create(noSelector);
 }
 
 describe('CacheInitializer', () => {
@@ -51,6 +51,16 @@ describe('CacheInitializer', () => {
     context = Context.fromLDContext({ kind: 'user', key: 'test-user' });
   });
 
+  it('returns a factory marked as a cache initializer', () => {
+    const factory = createCacheInitializerFactory({
+      storage: makeMemoryStorage(),
+      crypto,
+      environmentNamespace: TEST_NAMESPACE,
+      context,
+    });
+    expect(factory.isCache).toBe(true);
+  });
+
   it('returns a changeSet with cached flags when cache is present', async () => {
     const storage = makeMemoryStorage();
     const flags: Flags = {
@@ -234,7 +244,7 @@ describe('CacheInitializer', () => {
       context,
     });
 
-    const initializer = factory(selectorGetter);
+    const initializer = factory.create(selectorGetter);
     const result = await initializer.run();
 
     expect(result.type).toBe('changeSet');