feat: FDv2 types, refined validators, and DataManager interface (#1207)

This is the first of several PRs to integrate the changes from the
testing FDv2 branch.

## Summary
- Add `InitializerEntry`/`SynchronizerEntry` type aliases for type-safe
mode definitions
- Refine `protocolHandler` validation to use `isNullish` for
version/target fields (allows `0`)
- Add `connectionModes` config option to `LDClientDataSystemOptions`
- Split validator arrays so synchronizers reject `cache` entries
- Extend `DataManager` interface with optional `setForcedStreaming`,
`setAutomaticStreamingState`, `setFlushCallback` methods
- Export `MODE_TABLE` and `createDataSourceStatusManager` from
sdk-client index

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Medium risk due to public API surface changes (new `connectionModes`
option, new exported types/exports, and `DataManager` interface
extensions) plus adjusted FDv2 protocol validation that could affect
event processing in edge cases (e.g., version `0`).
> 
> **Overview**
> Adds a `connectionModes` override to `LDClientDataSystemOptions`, plus
new `InitializerEntry`/`SynchronizerEntry` types so mode definitions can
*type/validate* initializers vs synchronizers differently (notably
disallowing `cache` in `synchronizers`), with accompanying validator
updates and tests.
> 
> Refines FDv2 `protocolHandler` validation to treat `0` as valid for
`target`/`version`/`state` via `isNullish`, and adds warning logs when
ignoring malformed or out-of-sequence events.
> 
> Extends the `DataManager` interface with optional streaming/lifecycle
hooks (`setForcedStreaming`, `setAutomaticStreamingState`,
`setFlushCallback`) and updates public exports (including `MODE_TABLE`
and `createDataSourceStatusManager`), plus a doc fix for `flag-eval`
kind naming.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
e315ed6. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: kinyoklion

packages/shared/common/src/internal/fdv2/protocolHandler.ts

@@ -1,4 +1,5 @@
 import { LDLogger } from '../../api';
+import { isNullish } from '../../validators';
 import {
   DeleteObject,
   FDv2Event,
@@ -111,7 +112,10 @@ export function createProtocolHandler(
   }
 
   function processIntentNone(intent: PayloadIntent): ProtocolAction {
-    if (!intent.id || !intent.target) {
+    if (!intent.id || isNullish(intent.target)) {
+      logger?.warn(
+        `Ignoring 'none' intent with missing fields: id=${intent.id}, target=${intent.target}`,
+      );
       return ACTION_NONE;
     }
 
@@ -164,14 +168,15 @@ export function createProtocolHandler(
   }
 
   function processPutObject(data: PutObject): ProtocolAction {
-    if (
-      protocolState === 'inactive' ||
-      !tempId ||
-      !data.kind ||
-      !data.key ||
-      !data.version ||
-      !data.object
-    ) {
+    if (protocolState === 'inactive' || !tempId) {
+      logger?.warn('Received put-object before server-intent was established. Ignoring.');
+      return ACTION_NONE;
+    }
+
+    if (!data.kind || !data.key || isNullish(data.version) || !data.object) {
+      logger?.warn(
+        `Ignoring put-object with missing fields: kind=${data.kind}, key=${data.key}, version=${data.version}`,
+      );
       return ACTION_NONE;
     }
 
@@ -191,7 +196,15 @@ export function createProtocolHandler(
   }
 
   function processDeleteObject(data: DeleteObject): ProtocolAction {
-    if (protocolState === 'inactive' || !tempId || !data.kind || !data.key || !data.version) {
+    if (protocolState === 'inactive' || !tempId) {
+      logger?.warn('Received delete-object before server-intent was established. Ignoring.');
+      return ACTION_NONE;
+    }
+
+    if (!data.kind || !data.key || isNullish(data.version)) {
+      logger?.warn(
+        `Ignoring delete-object with missing fields: kind=${data.kind}, key=${data.key}, version=${data.version}`,
+      );
       return ACTION_NONE;
     }
 
@@ -214,7 +227,10 @@ export function createProtocolHandler(
       };
     }
 
-    if (!tempId || data.state === null || data.state === undefined || !data.version) {
+    if (!tempId || isNullish(data.state) || isNullish(data.version)) {
+      logger?.warn(
+        `Ignoring payload-transferred with missing fields: state=${data.state}, version=${data.version}`,
+      );
       resetAll();
       return ACTION_NONE;
     }

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

@@ -257,6 +257,44 @@ describe('given entries with invalid type field', () => {
   });
 });
 
+describe('given cache entries in synchronizers', () => {
+  it('discards a cache entry from synchronizers and warns', () => {
+    const result = validateModeDefinition(
+      { initializers: [], synchronizers: [{ type: 'cache' }] },
+      'testMode',
+      logger,
+    );
+
+    expect(result.synchronizers).toEqual([]);
+    expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('got cache'));
+  });
+
+  it('keeps valid synchronizer entries and discards cache', () => {
+    const result = validateModeDefinition(
+      {
+        initializers: [],
+        synchronizers: [{ type: 'polling' }, { type: 'cache' }, { type: 'streaming' }],
+      },
+      'testMode',
+      logger,
+    );
+
+    expect(result.synchronizers).toEqual([{ type: 'polling' }, { type: 'streaming' }]);
+    expect(logger.warn).toHaveBeenCalledTimes(1);
+  });
+
+  it('allows cache as an initializer', () => {
+    const result = validateModeDefinition(
+      { initializers: [{ type: 'cache' }], synchronizers: [] },
+      'testMode',
+      logger,
+    );
+
+    expect(result.initializers).toEqual([{ type: 'cache' }]);
+    expect(logger.warn).not.toHaveBeenCalled();
+  });
+});
+
 describe('given polling entries with invalid config', () => {
   it('drops pollInterval when it is a string and warns', () => {
     const result = validateModeDefinition(

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

@@ -53,6 +53,33 @@ export interface DataManager {
    * Closes the data manager. Any active connections are closed.
    */
   close(): void;
+
+  /**
+   * Force streaming on or off. When `true`, the data manager should
+   * maintain a streaming connection. When `false`, streaming is disabled.
+   * When `undefined`, the forced state is cleared and automatic behavior
+   * takes over.
+   *
+   * Optional — only browser data managers implement this.
+   */
+  setForcedStreaming?(streaming?: boolean): void;
+
+  /**
+   * Update the automatic streaming state based on whether change listeners
+   * are registered. When `true` and forced streaming is not set, the data
+   * manager should activate streaming.
+   *
+   * Optional — only browser data managers implement this.
+   */
+  setAutomaticStreamingState?(streaming: boolean): void;
+
+  /**
+   * Set a callback to flush pending analytics events. Called immediately
+   * (not debounced) when the lifecycle transitions to background.
+   *
+   * Optional — only FDv2 data managers implement this.
+   */
+  setFlushCallback?(callback: () => void): void;
 }
 
 /**

packages/shared/sdk-client/src/api/datasource/DataSourceEntry.ts

@@ -14,6 +14,7 @@ export interface EndpointConfig {
 
 /**
  * Configuration for a cache data source entry.
+ * Cache is only valid as an initializer (not a synchronizer).
  */
 export interface CacheDataSourceEntry {
   readonly type: 'cache';
@@ -45,6 +46,21 @@ export interface StreamingDataSourceEntry {
   readonly endpoints?: EndpointConfig;
 }
 
+/**
+ * An entry in the initializers list of a mode definition. Initializers
+ * can be cache, polling, or streaming sources.
+ */
+export type InitializerEntry =
+  | CacheDataSourceEntry
+  | PollingDataSourceEntry
+  | StreamingDataSourceEntry;
+
+/**
+ * An entry in the synchronizers list of a mode definition. Synchronizers
+ * can be polling or streaming sources (not cache).
+ */
+export type SynchronizerEntry = PollingDataSourceEntry | StreamingDataSourceEntry;
+
 /**
  * A data source entry in a mode table. Each entry identifies a data source type
  * and carries type-specific configuration overrides.

packages/shared/sdk-client/src/api/datasource/LDClientDataSystemOptions.ts

@@ -1,4 +1,5 @@
 import FDv2ConnectionMode from './FDv2ConnectionMode';
+import { ModeDefinition } from './ModeDefinition';
 
 // When FDv2 becomes the default, this should be integrated into the
 // main LDOptions interface (api/LDOptions.ts).
@@ -48,8 +49,27 @@ export interface LDClientDataSystemOptions {
    */
   automaticModeSwitching?: boolean | AutomaticModeSwitchingConfig;
 
-  // Req 5.3.5 TBD — custom named modes reserved for future use.
-  // customModes?: Record<string, { initializers: ..., synchronizers: ... }>;
+  /**
+   * Override the data source pipeline for specific connection modes.
+   *
+   * Each key is a connection mode name (`'streaming'`, `'polling'`, `'offline'`,
+   * `'one-shot'`, `'background'`). The value defines the initializers and
+   * synchronizers for that mode, replacing the built-in defaults.
+   *
+   * Only the modes you specify are overridden — unspecified modes retain
+   * their built-in definitions.
+   *
+   * @example
+   * ```
+   * connectionModes: {
+   *   streaming: {
+   *     initializers: [{ type: 'polling' }],
+   *     synchronizers: [{ type: 'streaming' }],
+   *   },
+   * }
+   * ```
+   */
+  connectionModes?: Partial<Record<FDv2ConnectionMode, ModeDefinition>>;
 }
 
 /**

packages/shared/sdk-client/src/api/datasource/ModeDefinition.ts

@@ -1,4 +1,4 @@
-import { DataSourceEntry } from './DataSourceEntry';
+import { InitializerEntry, SynchronizerEntry } from './DataSourceEntry';
 
 /**
  * Defines the data pipeline for a connection mode: which data sources
@@ -10,13 +10,13 @@ export interface ModeDefinition {
    * Sources are tried in order; the first that successfully provides a full
    * data set transitions the SDK out of the initialization phase.
    */
-  readonly initializers: ReadonlyArray<DataSourceEntry>;
+  readonly initializers: ReadonlyArray<InitializerEntry>;
 
   /**
    * Ordered list of data sources for ongoing synchronization after
    * initialization completes. Sources are in priority order with automatic
    * failover to the next source if the primary fails.
    * An empty array means no synchronization occurs (e.g., offline, one-shot).
    */
-  readonly synchronizers: ReadonlyArray<DataSourceEntry>;
+  readonly synchronizers: ReadonlyArray<SynchronizerEntry>;
 }

packages/shared/sdk-client/src/api/datasource/index.ts

@@ -4,6 +4,8 @@ export type {
   CacheDataSourceEntry,
   PollingDataSourceEntry,
   StreamingDataSourceEntry,
+  InitializerEntry,
+  SynchronizerEntry,
   DataSourceEntry,
 } from './DataSourceEntry';
 export type { ModeDefinition } from './ModeDefinition';

packages/shared/sdk-client/src/datasource/ConnectionModeConfig.ts

@@ -42,15 +42,20 @@ const streamingEntryValidators = {
   endpoints: validatorOf(endpointValidators),
 };
 
-const dataSourceEntryArrayValidator = arrayOf('type', {
+const initializerEntryArrayValidator = arrayOf('type', {
   cache: cacheEntryValidators,
   polling: pollingEntryValidators,
   streaming: streamingEntryValidators,
 });
 
+const synchronizerEntryArrayValidator = arrayOf('type', {
+  polling: pollingEntryValidators,
+  streaming: streamingEntryValidators,
+});
+
 const modeDefinitionValidators = {
-  initializers: dataSourceEntryArrayValidator,
-  synchronizers: dataSourceEntryArrayValidator,
+  initializers: initializerEntryArrayValidator,
+  synchronizers: synchronizerEntryArrayValidator,
 };
 
 const MODE_DEFINITION_DEFAULTS: Record<string, unknown> = {

packages/shared/sdk-client/src/datasource/LDClientDataSystemOptions.ts

@@ -2,7 +2,7 @@ import { TypeValidators } from '@launchdarkly/js-sdk-common';
 
 import type { PlatformDataSystemDefaults } from '../api/datasource';
 import { anyOf, validatorOf } from '../configuration/validateOptions';
-import { connectionModeValidator } from './ConnectionModeConfig';
+import { connectionModesValidator, connectionModeValidator } from './ConnectionModeConfig';
 
 const modeSwitchingValidators = {
   lifecycle: TypeValidators.Boolean,
@@ -13,6 +13,7 @@ const dataSystemValidators = {
   initialConnectionMode: connectionModeValidator,
   backgroundConnectionMode: connectionModeValidator,
   automaticModeSwitching: anyOf(TypeValidators.Boolean, validatorOf(modeSwitchingValidators)),
+  connectionModes: connectionModesValidator,
 };
 
 /**

packages/shared/sdk-client/src/datasource/fdv2/FDv2DataSource.ts

@@ -208,6 +208,10 @@ export function createFDv2DataSource(config: FDv2DataSourceConfig): FDv2DataSour
         recoveryTimeoutMs,
       );
 
+      if (conditions.promise) {
+        logger?.debug('Fallback condition active for current synchronizer.');
+      }
+
       // try/finally ensures conditions are closed on all code paths.
       let synchronizerRunning = true;
       try {