feat: Add experimental FDv2 configuration (unused) (#1169)

Add `dataSystem` option to LDOptions for FDv2 data system configuration.
The field is marked @internal and stripped from public type declarations
via stripInternal. When present, ConfigurationImpl deep-validates it
using dataSystemValidators with platform-specific defaults passed via
LDClientInternalOptions.dataSystemDefaults.

- Browser SDK passes BROWSER_DATA_SYSTEM_DEFAULTS
- React Native SDK passes MOBILE_DATA_SYSTEM_DEFAULTS
- No behavioral changes — the configuration is accepted and validated
but not yet wired to any data manager selection logic

SDK-1935

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Touches shared configuration validation logic (new nested-default
handling and validator generation), which could subtly affect option
parsing across SDKs, though the feature is gated behind an
internal/experimental option and is not yet wired to runtime behavior.
> 
> **Overview**
> Introduces an *experimental, `@internal`* `dataSystem` option on
`LDOptions` to carry FDv2 data-system configuration, and adds deep
validation for it when platform `dataSystemDefaults` are supplied.
> 
> Browser and React Native clients now pass platform-specific defaults
(`BROWSER_DATA_SYSTEM_DEFAULTS`, `MOBILE_DATA_SYSTEM_DEFAULTS`) via
`LDClientInternalOptions`, and the shared config layer switches from a
static validator map to `createValidators()` plus an enhanced
`validatorOf()` that can apply built-in defaults for nested objects.
Tests were added to ensure `dataSystem` is not stripped from base
options and is validated/merged (including warning/fallback behavior for
invalid shapes/values).
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
fa111d5. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: kinyoklion

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

@@ -90,3 +90,19 @@ it('does not override common config flushInterval if it is set', () => {
   const result = filterToBaseOptionsWithDefaults(opts);
   expect(result.flushInterval).toEqual(15);
 });
+
+it('passes dataSystem through to base options without stripping', () => {
+  const opts = {
+    dataSystem: { initialConnectionMode: 'polling' },
+  } as any;
+  const result = filterToBaseOptionsWithDefaults(opts);
+  expect((result as any).dataSystem).toEqual({ initialConnectionMode: 'polling' });
+});
+
+it('passes an empty dataSystem through to base options', () => {
+  const opts = {
+    dataSystem: {},
+  } as any;
+  const result = filterToBaseOptionsWithDefaults(opts);
+  expect((result as any).dataSystem).toEqual({});
+});

packages/sdk/browser/src/BrowserClient.ts

@@ -1,6 +1,7 @@
 import {
   AutoEnvAttributes,
   BasicLogger,
+  BROWSER_DATA_SYSTEM_DEFAULTS,
   browserFdv1Endpoints,
   Configuration,
   FlagManager,
@@ -110,6 +111,7 @@ class BrowserClientImpl extends LDClientImpl {
         includeAuthorizationHeader: false,
         highTimeoutThreshold: 5,
         userAgentHeaderName: 'x-launchdarkly-user-agent',
+        dataSystemDefaults: BROWSER_DATA_SYSTEM_DEFAULTS,
         trackEventModifier: (event: internal.InputCustomEvent) =>
           new internal.InputCustomEvent(
             event.context,

packages/sdk/react-native/src/ReactNativeLDClient.ts

@@ -11,6 +11,7 @@ import {
   LDEmitter,
   LDHeaders,
   LDPluginEnvironmentMetadata,
+  MOBILE_DATA_SYSTEM_DEFAULTS,
   mobileFdv1Endpoints,
 } from '@launchdarkly/js-client-sdk-common';
 
@@ -65,6 +66,7 @@ export default class ReactNativeLDClient extends LDClientImpl {
       getImplementationHooks: (_environmentMetadata: LDPluginEnvironmentMetadata) =>
         internal.safeGetHooks(logger, _environmentMetadata, validatedRnOptions.plugins),
       credentialType: 'mobileKey',
+      dataSystemDefaults: MOBILE_DATA_SYSTEM_DEFAULTS,
     };
 
     const platform = createPlatform(logger, options, validatedRnOptions.storage);

packages/shared/sdk-client/__tests__/configuration/Configuration.test.ts

@@ -178,3 +178,149 @@ it('does not wrap already safe loggers', () => {
   const config = new ConfigurationImpl({ logger });
   expect(config.logger).toBe(logger);
 });
+
+describe('dataSystem validation', () => {
+  it('does not set dataSystem when not provided', () => {
+    const config = new ConfigurationImpl(
+      {},
+      {
+        getImplementationHooks: () => [],
+        credentialType: 'clientSideId',
+        dataSystemDefaults: {
+          initialConnectionMode: 'one-shot',
+          automaticModeSwitching: false,
+        },
+      },
+    );
+    expect(config.dataSystem).toBeUndefined();
+  });
+
+  it('validates dataSystem with platform defaults when provided as empty object', () => {
+    const config = new ConfigurationImpl(
+      // @ts-ignore dataSystem is @internal
+      { dataSystem: {} },
+      {
+        getImplementationHooks: () => [],
+        credentialType: 'clientSideId',
+        dataSystemDefaults: {
+          initialConnectionMode: 'one-shot',
+          automaticModeSwitching: false,
+        },
+      },
+    );
+    expect(config.dataSystem).toBeDefined();
+    expect(config.dataSystem!.initialConnectionMode).toBe('one-shot');
+    expect(config.dataSystem!.automaticModeSwitching).toBe(false);
+  });
+
+  it('validates dataSystem with user overrides applied over platform defaults', () => {
+    const config = new ConfigurationImpl(
+      // @ts-ignore dataSystem is @internal
+      { dataSystem: { initialConnectionMode: 'polling' } },
+      {
+        getImplementationHooks: () => [],
+        credentialType: 'mobileKey',
+        dataSystemDefaults: {
+          initialConnectionMode: 'streaming',
+          backgroundConnectionMode: 'background',
+          automaticModeSwitching: true,
+        },
+      },
+    );
+    expect(config.dataSystem).toBeDefined();
+    expect(config.dataSystem!.initialConnectionMode).toBe('polling');
+    expect(config.dataSystem!.backgroundConnectionMode).toBe('background');
+    expect(config.dataSystem!.automaticModeSwitching).toBe(true);
+  });
+
+  it('warns and falls back to default for invalid dataSystem sub-fields', () => {
+    console.error = jest.fn();
+    const config = new ConfigurationImpl(
+      // @ts-ignore dataSystem is @internal
+      { dataSystem: { initialConnectionMode: 'turbo' } },
+      {
+        getImplementationHooks: () => [],
+        credentialType: 'clientSideId',
+        dataSystemDefaults: {
+          initialConnectionMode: 'one-shot',
+          automaticModeSwitching: false,
+        },
+      },
+    );
+    expect(config.dataSystem).toBeDefined();
+    expect(config.dataSystem!.initialConnectionMode).toBe('one-shot');
+    expect(console.error).toHaveBeenCalledWith(
+      expect.stringContaining('dataSystem.initialConnectionMode'),
+    );
+  });
+
+  it('does not deep-validate dataSystem when dataSystemDefaults is not provided', () => {
+    const config = new ConfigurationImpl(
+      // @ts-ignore dataSystem is @internal
+      { dataSystem: { initialConnectionMode: 'polling' } },
+      {
+        getImplementationHooks: () => [],
+        credentialType: 'clientSideId',
+      },
+    );
+    // Without defaults, deep validation is skipped — raw object from basic validator
+    expect(config.dataSystem).toBeDefined();
+  });
+
+  it('warns and ignores dataSystem when set to a non-object value', () => {
+    console.error = jest.fn();
+    const config = new ConfigurationImpl(
+      // @ts-ignore dataSystem is @internal
+      { dataSystem: 'streaming' },
+      {
+        getImplementationHooks: () => [],
+        credentialType: 'clientSideId',
+        dataSystemDefaults: {
+          initialConnectionMode: 'one-shot',
+          automaticModeSwitching: false,
+        },
+      },
+    );
+    expect(config.dataSystem).toBeUndefined();
+    expect(console.error).toHaveBeenCalledWith(expect.stringContaining('dataSystem'));
+  });
+
+  it('validates automaticModeSwitching as a granular config object', () => {
+    const config = new ConfigurationImpl(
+      // @ts-ignore dataSystem is @internal
+      { dataSystem: { automaticModeSwitching: { lifecycle: true, network: false } } },
+      {
+        getImplementationHooks: () => [],
+        credentialType: 'mobileKey',
+        dataSystemDefaults: {
+          initialConnectionMode: 'streaming',
+          automaticModeSwitching: true,
+        },
+      },
+    );
+    expect(config.dataSystem).toBeDefined();
+    expect(config.dataSystem!.automaticModeSwitching).toEqual({
+      lifecycle: true,
+      network: false,
+    });
+  });
+
+  it('does not set other config fields when dataSystem defaults are provided', () => {
+    const config = new ConfigurationImpl(
+      {},
+      {
+        getImplementationHooks: () => [],
+        credentialType: 'clientSideId',
+        dataSystemDefaults: {
+          initialConnectionMode: 'one-shot',
+          automaticModeSwitching: false,
+        },
+      },
+    );
+    // dataSystem defaults should not leak into the config when dataSystem is not provided
+    expect(config.dataSystem).toBeUndefined();
+    // Other fields should retain their normal defaults
+    expect(config.sendEvents).toBe(true);
+    expect(config.capacity).toBe(100);
+  });
+});

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

@@ -1,5 +1,6 @@
 import type { LDLogger } from '@launchdarkly/js-sdk-common';
 
+import { LDClientDataSystemOptions } from './datasource/LDClientDataSystemOptions';
 import { Hook } from './integrations/Hooks';
 import { LDInspection } from './LDInspection';
 
@@ -279,4 +280,19 @@ export interface LDOptions {
    * @defaultValue false.
    */
   cleanOldPersistentData?: boolean;
+
+  /**
+   * @internal
+   *
+   * WARNING: This option is EXPERIMENTAL and UNSUPPORTED. It is subject to
+   * change or removal without notice. Do not use in production applications.
+   * Using this option may result in unexpected behavior, data loss, or
+   * breaking changes in future SDK versions. LaunchDarkly does not provide
+   * support for configurations using this option.
+   *
+   * Configuration for the FDv2 data system. When present, the SDK uses
+   * the FDv2 protocol for flag delivery instead of the default FDv1
+   * protocol.
+   */
+  dataSystem?: LDClientDataSystemOptions;
 }

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

@@ -10,9 +10,13 @@ import {
 } from '@launchdarkly/js-sdk-common';
 
 import { Hook, type LDOptions } from '../api';
+import type {
+  LDClientDataSystemOptions,
+  PlatformDataSystemDefaults,
+} from '../api/datasource/LDClientDataSystemOptions';
 import { LDInspection } from '../api/LDInspection';
 import validateOptions from './validateOptions';
-import validators from './validators';
+import createValidators from './validators';
 
 const DEFAULT_POLLING_INTERVAL: number = 60 * 5;
 
@@ -21,6 +25,7 @@ export interface LDClientInternalOptions extends internal.LDInternalOptions {
   getImplementationHooks: (environmentMetadata: LDPluginEnvironmentMetadata) => Hook[];
   credentialType: 'clientSideId' | 'mobileKey';
   getLegacyStorageKeys?: () => string[];
+  dataSystemDefaults?: PlatformDataSystemDefaults;
 }
 
 export interface Configuration {
@@ -59,6 +64,7 @@ export interface Configuration {
   readonly inspectors: LDInspection[];
   readonly credentialType: 'clientSideId' | 'mobileKey';
   readonly getImplementationHooks: (environmentMetadata: LDPluginEnvironmentMetadata) => Hook[];
+  readonly dataSystem?: LDClientDataSystemOptions;
 }
 
 const DEFAULT_POLLING: string = 'https://clientsdk.launchdarkly.com';
@@ -138,6 +144,7 @@ export default class ConfigurationImpl implements Configuration {
   public readonly getImplementationHooks: (
     environmentMetadata: LDPluginEnvironmentMetadata,
   ) => Hook[];
+  public readonly dataSystem?: LDClientDataSystemOptions;
 
   // Allow indexing Configuration by a string
   [index: string]: any;
@@ -150,6 +157,9 @@ export default class ConfigurationImpl implements Configuration {
     },
   ) {
     this.logger = ensureSafeLogger(pristineOptions.logger);
+    const validators = createValidators({
+      dataSystemDefaults: internalOptions.dataSystemDefaults,
+    });
     const validated = validateOptions(
       pristineOptions as Record<string, unknown>,
       validators,

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

@@ -111,7 +111,10 @@ export default function validateOptions(
  * `validateOptions` will recursively validate the nested object's properties.
  * Defaults for nested fields are passed through from the parent.
  */
-export function validatorOf(validators: Record<string, TypeValidator>): CompoundValidator {
+export function validatorOf(
+  validators: Record<string, TypeValidator>,
+  builtInDefaults?: Record<string, unknown>,
+): CompoundValidator {
   return {
     is: (u: unknown) => TypeValidators.Object.is(u),
     getType: () => 'object',
@@ -120,9 +123,9 @@ export function validatorOf(validators: Record<string, TypeValidator>): Compound
         logger?.warn(OptionMessages.wrongOptionType(name, 'object', typeof value));
         return undefined;
       }
-      const nestedDefaults = TypeValidators.Object.is(defaults)
-        ? (defaults as Record<string, unknown>)
-        : {};
+      const nestedDefaults =
+        builtInDefaults ??
+        (TypeValidators.Object.is(defaults) ? (defaults as Record<string, unknown>) : {});
       const nested = validateOptions(
         value as Record<string, unknown>,
         validators,

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

@@ -1,40 +1,54 @@
-// eslint-disable-next-line max-classes-per-file
 import { TypeValidator, TypeValidators } from '@launchdarkly/js-sdk-common';
 
 import { type LDOptions } from '../api';
-
-const validators: Record<keyof LDOptions, TypeValidator> = {
-  logger: TypeValidators.Object,
-  maxCachedContexts: TypeValidators.numberWithMin(0),
-
-  baseUri: TypeValidators.String,
-  streamUri: TypeValidators.String,
-  eventsUri: TypeValidators.String,
-
-  capacity: TypeValidators.numberWithMin(1),
-  diagnosticRecordingInterval: TypeValidators.numberWithMin(2),
-  flushInterval: TypeValidators.numberWithMin(2),
-  streamInitialReconnectDelay: TypeValidators.numberWithMin(0),
-
-  allAttributesPrivate: TypeValidators.Boolean,
-  debug: TypeValidators.Boolean,
-  diagnosticOptOut: TypeValidators.Boolean,
-  withReasons: TypeValidators.Boolean,
-  sendEvents: TypeValidators.Boolean,
-
-  pollInterval: TypeValidators.numberWithMin(30),
-
-  useReport: TypeValidators.Boolean,
-
-  privateAttributes: TypeValidators.StringArray,
-
-  applicationInfo: TypeValidators.Object,
-  wrapperName: TypeValidators.String,
-  wrapperVersion: TypeValidators.String,
-  payloadFilterKey: TypeValidators.stringMatchingRegex(/^[a-zA-Z0-9](\w|\.|-)*$/),
-  hooks: TypeValidators.createTypeArray('Hook[]', {}),
-  inspectors: TypeValidators.createTypeArray('LDInspection', {}),
-  cleanOldPersistentData: TypeValidators.Boolean,
-};
-
-export default validators;
+import type { PlatformDataSystemDefaults } from '../api/datasource/LDClientDataSystemOptions';
+import { dataSystemValidators } from '../datasource/LDClientDataSystemOptions';
+import { validatorOf } from './validateOptions';
+
+export interface ValidatorOptions {
+  dataSystemDefaults?: PlatformDataSystemDefaults;
+}
+
+export default function createValidators(
+  options?: ValidatorOptions,
+): Record<keyof LDOptions, TypeValidator> {
+  return {
+    logger: TypeValidators.Object,
+    maxCachedContexts: TypeValidators.numberWithMin(0),
+
+    baseUri: TypeValidators.String,
+    streamUri: TypeValidators.String,
+    eventsUri: TypeValidators.String,
+
+    capacity: TypeValidators.numberWithMin(1),
+    diagnosticRecordingInterval: TypeValidators.numberWithMin(2),
+    flushInterval: TypeValidators.numberWithMin(2),
+    streamInitialReconnectDelay: TypeValidators.numberWithMin(0),
+
+    allAttributesPrivate: TypeValidators.Boolean,
+    debug: TypeValidators.Boolean,
+    diagnosticOptOut: TypeValidators.Boolean,
+    withReasons: TypeValidators.Boolean,
+    sendEvents: TypeValidators.Boolean,
+
+    pollInterval: TypeValidators.numberWithMin(30),
+
+    useReport: TypeValidators.Boolean,
+
+    privateAttributes: TypeValidators.StringArray,
+
+    applicationInfo: TypeValidators.Object,
+    wrapperName: TypeValidators.String,
+    wrapperVersion: TypeValidators.String,
+    payloadFilterKey: TypeValidators.stringMatchingRegex(/^[a-zA-Z0-9](\w|\.|-)*$/),
+    hooks: TypeValidators.createTypeArray('Hook[]', {}),
+    inspectors: TypeValidators.createTypeArray('LDInspection', {}),
+    cleanOldPersistentData: TypeValidators.Boolean,
+    dataSystem: options?.dataSystemDefaults
+      ? validatorOf(
+          dataSystemValidators,
+          options.dataSystemDefaults as unknown as Record<string, unknown>,
+        )
+      : TypeValidators.Object,
+  };
+}