feat: FDv2DataManagerBase for mode switching and data source lifecycle by kinyoklion · Pull Request #1210 · launchdarkly/js-core

kinyoklion · 2026-03-19T22:35:54Z

Summary

Add FDv2DataManagerBase — shared data manager orchestrating FDv2 connection mode switching, state debouncing, and data source lifecycle
Implements DataManager interface with foreground/background mode support, forced/automatic streaming control, and flush callbacks
Includes FlagManager.applyChanges from feat: FlagManager.applyChanges for FDv2 full/partial/none semantics #1208 for full/partial/none flag update semantics

Stacked on #1209 and #1208.

Note

Medium Risk
Adds a new shared FDv2 data manager that controls connection-mode resolution and data source lifecycle, plus updates public dataSystem option shapes; mistakes here could affect SDK initialization, reconnection behavior, and flag freshness across platforms.

Overview
Introduces createFDv2DataManagerBase (and exported types) as a shared FDv2 orchestration layer that performs mode resolution/debouncing, manages FDv2DataSource creation/teardown across identifies and mode changes, tracks selector state, triggers a background flush callback, and optionally appends a blocked FDv1 polling fallback synchronizer.

Updates the public dataSystem configuration model by renaming initialConnectionMode to foregroundConnectionMode in platform defaults and by making automaticModeSwitching a discriminated union ({type:'automatic'} vs {type:'manual', initialConnectionMode}), with validator support via validatorOf(..., { is }); tests are updated and expanded accordingly, including a large new test suite for FDv2DataManagerBase.

^{Written by Cursor Bugbot for commit 0786b64. This will update automatically on new commits. Configure here.}

…xtensions Add InitializerEntry/SynchronizerEntry types for type-safe mode definitions, refine protocolHandler validation to use isNullish for version/target fields, add connectionModes config option, split validator arrays for initializers vs synchronizers, and extend DataManager with optional streaming/flush methods.

Add applyChanges method to FlagManager and FlagPersistence that handles full replacement, partial upsert, and no-change persistence in a single call, designed for the FDv2 data path.

Add SourceFactoryProvider that converts declarative InitializerEntry and SynchronizerEntry config into concrete initializer factories and synchronizer slots, with support for per-entry endpoint and interval overrides.

…data-manager-base

…cycle Add shared data manager that orchestrates FDv2 connection mode switching, state debouncing, streaming control, and data source lifecycle management. Implements the DataManager interface with support for foreground/background modes, forced/automatic streaming, and flush callbacks.

- Fix ping handler to use per-entry endpoint-overridden requestor and the factory's selector getter (sg) for fresh selectors on each ping - Extract duplicated streaming base config into shared buildStreamingBase helper - Restructure SourceFactoryContext to group polling/streaming config into nested objects (polling.paths, polling.intervalSeconds, streaming.paths, streaming.initialReconnectDelaySeconds) - Resolve merge conflict in FDv2DataSource (warn -> debug)

…a-manager-base

Adapt factory context construction to use nested polling/streaming config objects and remove selectorGetter from the context (now passed directly via factory sg parameter).

Account for new FDv2 SourceFactoryProvider and related code paths.

…a-manager-base

… checks Push applyChanges down through the flag manager layers so the FDv2 path no longer routes through FDv1's upsert (which has version checks and inactive-context guards). FlagStore.applyPartial inserts without version comparison, and FlagUpdater.applyChanges sets the active context directly and emits change events.

…data-manager-base

…er-apply-changes # Conflicts: # packages/shared/sdk-client/src/datasource/fdv2/FDv2DataSource.ts

…er-base # Conflicts: # packages/shared/sdk-client/src/index.ts

Account for new FDv2 applyChanges code in FlagUpdater/FlagStore that flows into the browser SDK bundle.

…data-manager-base

Replace FlagStore.applyPartial with FlagStore.applyChanges that handles full/partial/none, delegating to init for full. FlagUpdater.applyChanges now delegates storage to FlagStore.applyChanges and only handles change event computation.

…data-manager-base

…er-base

github-actions · 2026-03-21T00:11:27Z

@launchdarkly/js-sdk-common size report
This is the brotli compressed size of the ESM build.
Compressed size: 25661 bytes
Compressed size limit: 29000
Uncompressed size: 126143 bytes

github-actions · 2026-03-21T00:11:45Z

@launchdarkly/js-client-sdk size report
This is the brotli compressed size of the ESM build.
Compressed size: 25214 bytes
Compressed size limit: 34000
Uncompressed size: 87656 bytes

github-actions · 2026-03-21T00:11:50Z

@launchdarkly/browser size report
This is the brotli compressed size of the ESM build.
Compressed size: 173123 bytes
Compressed size limit: 200000
Uncompressed size: 804784 bytes

github-actions · 2026-03-21T00:11:51Z

@launchdarkly/js-client-sdk-common size report
This is the brotli compressed size of the ESM build.
Compressed size: 36644 bytes
Compressed size limit: 38000
Uncompressed size: 201227 bytes

…onnectionMode - Remove initialConnectionMode from LDClientDataSystemOptions - Add ManualModeSwitching interface (type: 'manual' + initialConnectionMode) - Add type: 'automatic' discriminant to AutomaticModeSwitchingConfig - Rename PlatformDataSystemDefaults.initialConnectionMode to foregroundConnectionMode - Update validators to accept boolean | automatic config | manual config - Update all tests for new shape

kinyoklion · 2026-03-23T22:46:03Z

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

        credentialType: 'clientSideId',
        dataSystemDefaults: {
-          initialConnectionMode: 'one-shot',
+          foregroundConnectionMode: 'one-shot',


This is now the platform specific default, and not the same thing as the initial connection mode.

The config field represents the configured foreground mode, not just the initial one. Internally aliased to configuredForegroundMode to avoid collision with the mutable foregroundMode state variable.

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

Clear the selector when an FDv1 synchronizer delivers a payload without state, preventing stale selectors from being sent on subsequent requests.

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

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

…e leak If close() is called while namespaceForEnvironment is pending, identify would resume and create a data source and debounce manager that would never be cleaned up. Add a guard after the await to bail out early.

Update automaticModeSwitching docs to reference AutomaticModeSwitchingConfig and ManualModeSwitching types instead of re-declaring the shape inline. Add discriminant docs and cross-references to related types.

…n table Replace setRequestedMode and setForegroundMode with setConnectionMode that sets an explicit connection mode override. When set, it bypasses the entire transition table (network, lifecycle, streaming logic). Pass undefined to clear and return to automatic behavior. Priority hierarchy: 1. connectionModeOverride (setConnectionMode) 2. Transition table with foreground mode from: a. forcedStreaming b. automaticStreaming c. configuredForegroundMode

…ction The synchronous flag updates and change events are the critical path. The returned promise is only for async cache persistence — intentionally not awaited so the data source pipeline isn't blocked by storage I/O.

Add optional is parameter to validatorOf so anyOf can discriminate between object shapes by checking a type field. Split mode switching validators into separate automatic and manual variants with type-based is predicates.

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

cursor · 2026-03-25T18:21:28Z

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

+  NetworkState,
+  PendingState,
+  ReconciliationCallback,
+} from './datasource/StateDebounceManager';


LifecycleState missing from StateDebounceManager re-exports

Low Severity

NetworkState is re-exported from StateDebounceManager but its sibling type LifecycleState is not, even though both are used symmetrically in the exported FDv2DataManagerControl interface (setNetworkState and setLifecycleState). While LifecycleState is available from the api/datasource export path, the asymmetry in the StateDebounceManager export block is confusing for consumers looking at these related types side-by-side.

devin-ai-integration

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 5 additional findings.

## Summary - Conditionally use `FDv2DataManagerBase` when `dataSystem` config is present, falling back to `BrowserDataManager` for FDv1 - Derive foreground mode from `ManualModeSwitching.initialConnectionMode` or browser platform default - Use optional chaining for `setForcedStreaming`/`setAutomaticStreamingState`/`setFlushCallback` via the `DataManager` interface methods - Update `combined-browser.yml` bundle size limit for FDv2 code paths Stacked on #1210.  --- > [!NOTE] > **Medium Risk** > Introduces a conditional switch between FDv1 and FDv2 data paths in `BrowserClient`, which can affect endpoint selection and streaming behavior. Risk is mitigated by fallback to FDv1 when `dataSystem` is unset and added tests covering routing/validation behavior. > > **Overview** > **BrowserClient now conditionally uses FDv2**: when `configuration.dataSystem` is present, it instantiates `createFDv2DataManagerBase` (using `BROWSER_TRANSITION_TABLE`, `MODE_TABLE`, and FDv2 query params), otherwise it continues using the existing `BrowserDataManager`/FDv1 endpoints. > > **Streaming/flush integration is generalized** by calling `setForcedStreaming`, `setAutomaticStreamingState`, and `setFlushCallback` via optional chaining so the same client logic works across FDv1/FDv2 managers; explicit `streaming: false` is forwarded to prevent FDv2 auto-promotion. > > Adds `resolveForegroundMode` to derive FDv2 foreground mode from `ManualModeSwitching.initialConnectionMode` (or platform defaults), exports it from `sdk-client`, and extends browser tests to assert FDv1 vs FDv2 endpoint selection and that invalid `dataSystem` sub-options warn but still enable FDv2. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 04afb4e. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup>

kinyoklion added 11 commits March 19, 2026 15:11

feat: add FlagManager.applyChanges for FDv2 full/partial/none semantics

a4d5ad0

Add applyChanges method to FlagManager and FlagPersistence that handles full replacement, partial upsert, and no-change persistence in a single call, designed for the FDv2 data path.

feat: add SourceFactoryProvider for declarative data source creation

cb9d6b6

Add SourceFactoryProvider that converts declarative InitializerEntry and SynchronizerEntry config into concrete initializer factories and synchronizer slots, with support for per-entry endpoint and interval overrides.

Merge branch 'rlamb/fdv2-flag-manager-apply-changes' into rlamb/fdv2-…

c33790c

…data-manager-base

Merge branch 'main' into rlamb/fdv2-source-factory-provider

20f3d28

Merge branch 'rlamb/fdv2-source-factory-provider' into rlamb/fdv2-dat…

25121e3

…a-manager-base

fix: update FDv2DataManagerBase for restructured SourceFactoryContext

b1ca6c1

Adapt factory context construction to use nested polling/streaming config objects and remove selectorGetter from the context (now passed directly via factory sg parameter).

fix: increase bundle size limits for common and sdk-client packages

de39213

Account for new FDv2 SourceFactoryProvider and related code paths.

Merge branch 'rlamb/fdv2-source-factory-provider' into rlamb/fdv2-dat…

d9711c4

…a-manager-base

Base automatically changed from rlamb/fdv2-source-factory-provider to main March 20, 2026 20:56

kinyoklion added 4 commits March 20, 2026 14:04

Merge branch 'rlamb/fdv2-flag-manager-apply-changes' into rlamb/fdv2-…

a076479

…data-manager-base

Merge remote-tracking branch 'origin/main' into rlamb/fdv2-flag-manag…

95dabe4

…er-apply-changes # Conflicts: # packages/shared/sdk-client/src/datasource/fdv2/FDv2DataSource.ts

Merge remote-tracking branch 'origin/main' into rlamb/fdv2-data-manag…

83cb188

…er-base # Conflicts: # packages/shared/sdk-client/src/index.ts

kinyoklion changed the base branch from main to rlamb/fdv2-flag-manager-apply-changes March 20, 2026 21:14

kinyoklion added 6 commits March 20, 2026 14:21

fix: increase browser SDK bundle size limit

80852ff

Account for new FDv2 applyChanges code in FlagUpdater/FlagStore that flows into the browser SDK bundle.

Merge branch 'rlamb/fdv2-flag-manager-apply-changes' into rlamb/fdv2-…

01bb153

…data-manager-base

fix: delegate full applyChanges to init to avoid duplication

eeea559

Merge branch 'rlamb/fdv2-flag-manager-apply-changes' into rlamb/fdv2-…

806b12a

…data-manager-base

Merge branch 'rlamb/fdv2-flag-manager-apply-changes' into rlamb/fdv2-…

fece197

…data-manager-base

Base automatically changed from rlamb/fdv2-flag-manager-apply-changes to main March 20, 2026 23:04

Merge remote-tracking branch 'origin/main' into rlamb/fdv2-data-manag…

a78c26e

…er-base

fix: add ManualModeSwitching to LDClientDataSystemOptions union type

76f795c

kinyoklion commented Mar 23, 2026

View reviewed changes

fix: rename initialForegroundMode to foregroundMode

a39bdb4

The config field represents the configured foreground mode, not just the initial one. Internally aliased to configuredForegroundMode to avoid collision with the mutable foregroundMode state variable.

kinyoklion commented Mar 24, 2026

View reviewed changes

packages/shared/sdk-client/src/datasource/FDv2DataManagerBase.ts Show resolved Hide resolved

kinyoklion added 2 commits March 24, 2026 09:00

fix: simplify dataCallback by using ?? [] for transfer-none updates

a9ac466

fix: unconditionally assign selector from payload state

659ff40

Clear the selector when an FDv1 synchronizer delivers a payload without state, preventing stale selectors from being sent on subsequent requests.

kinyoklion marked this pull request as ready for review March 24, 2026 16:15

kinyoklion requested a review from a team as a code owner March 24, 2026 16:15

This comment was marked as resolved.

Sign in to view

joker23 reviewed Mar 24, 2026

View reviewed changes

kinyoklion mentioned this pull request Mar 24, 2026

feat: wire FDv2 data manager into BrowserClient #1222

Merged

kinyoklion added 2 commits March 25, 2026 09:21

fix: remove unnecessary as any cast for bootstrap check

63a0ac9

This comment was marked as resolved.

Sign in to view

fix: update doc comments to match discriminated union API

68b4baf

Update automaticModeSwitching docs to reference AutomaticModeSwitchingConfig and ManualModeSwitching types instead of re-declaring the shape inline. Add discriminant docs and cross-references to related types.

This comment was marked as resolved.

Sign in to view

kinyoklion added 2 commits March 25, 2026 10:58

cursor bot reviewed Mar 25, 2026

View reviewed changes

joker23 self-requested a review March 25, 2026 19:12

devin-ai-integration bot reviewed Mar 25, 2026

View reviewed changes

joker23 approved these changes Mar 25, 2026

View reviewed changes

kinyoklion merged commit 8f8051c into main Mar 25, 2026
46 checks passed

kinyoklion deleted the rlamb/fdv2-data-manager-base branch March 25, 2026 20:42

github-actions bot mentioned this pull request Mar 25, 2026

chore: release main #1221

Open

Conversation

kinyoklion commented Mar 19, 2026 • edited by devin-ai-integration bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

github-actions bot commented Mar 21, 2026

Uh oh!

github-actions bot commented Mar 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Mar 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Mar 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kinyoklion Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Mar 25, 2026

Choose a reason for hiding this comment

LifecycleState missing from StateDebounceManager re-exports

Uh oh!

devin-ai-integration bot left a comment

Choose a reason for hiding this comment

✅ Devin Review: No Issues Found

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

kinyoklion commented Mar 19, 2026 •

edited by devin-ai-integration bot

Loading

github-actions bot commented Mar 21, 2026 •

edited

Loading

github-actions bot commented Mar 21, 2026 •

edited

Loading

github-actions bot commented Mar 21, 2026 •

edited

Loading

`LifecycleState` missing from `StateDebounceManager` re-exports