feat: adding support for debug override plugins #1033

joker23 · 2025-12-10T19:06:39Z

Requirements

I have added test coverage for new or changed functionality
I have followed the repository's pull request submission guidelines
I have validated my changes against all supported platform versions

sdk-1653
sdk-1565

Describe the solution you've provided

Added LDDebugOverride interface to manage flag value overrides during development.
Introduced safeRegisterDebugOverridePlugins function to register plugins with debug capabilities.
Updated FlagManager to support debug overrides, including methods to set, remove, and clear overrides.
Enhanced LDClientImpl to utilize debug overrides during client initialization.
Refactored LDPlugin interface to include optional registerDebug method for plugins.

This PR will enable @launchdarkly/toolbar to use 4.x

Additional context

~~This PR is based off of feat: implement waitForInitialization for browser sdk 4.x #1028 (will need to do some rebase magic later)~~
There are a few places that I've marked REVIEWER that I would like some additional discussions before merging
In this change we are assuming that the plugin support (eg registering plugins) is still the responsibility of individual SDK implementations.

Note

Introduces a debug flag override interface, wires plugin registration for overrides, and updates flag management and clients to support and emit override-driven changes.

Flag management:
- Add LDDebugOverride interface and implement in DefaultFlagManager (setOverride, removeOverride, clearAllOverrides, getAllOverrides).
- get/getAll now merge in-memory overrides with stored flags; override values take precedence.
- Emit change callbacks with type "override" via FlagUpdater.handleFlagChanges.
Updater:
- Extend FlagChangeType with "override"; add handleFlagChanges helper; refactor init/upsert to use it.
Client integration:
- LDClientImpl: expose getDebugOverrides() from FlagManager and continue inspection updates on changes.
- Browser client: during registerPlugins, call safeRegisterDebugOverridePlugins to pass overrides to plugins.
Plugin API & utilities:
- Add LDPluginBase.registerDebug(debugOverride) optional method.
- New safeRegisterDebugOverridePlugins utility to safely register debug override plugins.
Exports:
- Re-export LDPluginBase, LDDebugOverride, and safeRegisterDebugOverridePlugins in public entrypoints.
Tests:
- Add comprehensive FlagManager override tests covering precedence, callbacks, clearing, and merging.

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

github-actions · 2025-12-10T19:07:58Z

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

github-actions · 2025-12-10T19:08:07Z

@launchdarkly/js-sdk-common size report
This is the brotli compressed size of the ESM build.
Compressed size: 25394 bytes
Compressed size limit: 26000
Uncompressed size: 124693 bytes

github-actions · 2025-12-10T19:08:27Z

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

github-actions · 2025-12-10T19:08:32Z

@launchdarkly/js-client-sdk size report
This is the brotli compressed size of the ESM build.
Compressed size: 22955 bytes
Compressed size limit: 25000
Uncompressed size: 79621 bytes

packages/shared/sdk-client/src/flag-manager/FlagManager.ts

packages/shared/sdk-client/src/flag-manager/FlagUpdater.ts

- Added `LDDebugOverride` interface to manage flag value overrides during development. - Introduced `safeRegisterDebugOverridePlugins` function to register plugins with debug capabilities. - Updated `FlagManager` to support debug overrides, including methods to set, remove, and clear overrides. - Enhanced `LDClientImpl` to utilize debug overrides during client initialization. - Refactored `LDPlugin` interface to include optional `registerDebug` method for plugins. This commit will enable `@launchdarkly/toolbar` to use 4.x

cursor

Bug: Inspection manager not notified for override flag changes

The _handleInspectionChanged method only handles 'init' and 'patch' flag change types, but the PR introduces a new 'override' type. When override changes occur (via setOverride, removeOverride, or clearAllOverrides), the method computes the details object but never sends it to the inspector manager because there's no branch handling type === 'override'. This means inspectors will not be notified when debug overrides change flag values.

packages/shared/sdk-client/src/LDClientImpl.ts#L638-L645

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

Lines 638 to 645 in cfd87be

    
           }); 
        
           if (type === 'init') { 
        
             this._inspectorManager.onFlagsChanged(details); 
        
           } else if (type === 'patch') { 
        
             Object.entries(details).forEach(([flagKey, detail]) => { 
        
               this._inspectorManager.onFlagChanged(flagKey, detail); 
        
             }); 
        
           }

joker23 · 2025-12-16T00:06:24Z

@kinyoklion would we want to treat overrides the same as normal flag changes? My thoughts are no since the debug override use cases so far has mostly been for development. Or perhaps we can create another inspector type for these events?

cursor

Bug: Inspector notifications silently skipped for override changes

The _handleInspectionChanged method only handles 'init' and 'patch' flag change types with explicit if/else if conditions, but the newly added 'override' type falls through without any handling. This causes inspector notifications (onFlagsChanged and onFlagChanged) to be silently skipped when flag overrides change, while the regular change events are still emitted via the emitter. This inconsistency means inspector hooks won't be notified of override changes.

packages/shared/sdk-client/src/LDClientImpl.ts#L634-L641

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

Lines 634 to 641 in b8f8d9a

    
           }); 
        
           if (type === 'init') { 
        
             this._inspectorManager.onFlagsChanged(details); 
        
           } else if (type === 'patch') { 
        
             Object.entries(details).forEach(([flagKey, detail]) => { 
        
               this._inspectorManager.onFlagChanged(flagKey, detail); 
        
             }); 
        
           }

packages/shared/sdk-client/src/flag-manager/FlagUpdater.ts#L6-L7

js-core/packages/shared/sdk-client/src/flag-manager/FlagUpdater.ts

Lines 6 to 7 in b8f8d9a


	export type FlagChangeType = 'init' \| 'patch' \| 'override';

kinyoklion · 2025-12-16T21:57:07Z

packages/shared/sdk-client/src/plugins/safeRegisterDebugOverridePlugins.ts

+/**
+ * Safe register debug override plugins.
+ *
+ * @param logger - The logger to use for logging errors.


nit: We don't need the hyphens. Maybe leftover from the jsdoc.

packages/shared/sdk-client/src/flag-manager/FlagUpdater.ts

kinyoklion · 2025-12-16T22:04:41Z

packages/shared/sdk-client/src/flag-manager/FlagManager.ts

+    if (this._overrides) {
+      const clearedOverrides = { ...this._overrides };
+      this._overrides = undefined; // Reset to undefined
+      this._flagUpdater.handleFlagChanges(Object.keys(clearedOverrides), 'override');


Co-authored-by: Ryan Lamb <[email protected]>

kinyoklion · 2025-12-17T00:20:15Z

Bug: Inspector notifications silently skipped for override changes

The _handleInspectionChanged method only handles 'init' and 'patch' flag change types with explicit if/else if conditions, but the newly added 'override' type falls through without any handling. This causes inspector notifications (onFlagsChanged and onFlagChanged) to be silently skipped when flag overrides change, while the regular change events are still emitted via the emitter. This inconsistency means inspector hooks won't be notified of override changes.

packages/shared/sdk-client/src/LDClientImpl.ts#L634-L641

packages/shared/sdk-client/src/flag-manager/FlagUpdater.ts#L6-L7

This sounds like the desired behavior? I don't think we would want to inform them of debug activity. But maybe we would want an explicit comment.

cursor

Bug: New 'override' FlagChangeType not handled in inspection callback

The new 'override' value is added to FlagChangeType, but _handleInspectionChanged only handles 'init' and 'patch' types. When override changes occur, the function builds the details object (lines 619-633) but then neither conditional branch (line 635-641) applies, so the details object is discarded without being used. This causes unnecessary work when inspectors exist and override changes happen. The function needs to either return early when type === 'override' to avoid the wasted computation, or explicitly handle the 'override' case if inspectors should be notified of override changes.

packages/shared/sdk-client/src/LDClientImpl.ts#L613-L642

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

Lines 613 to 642 in 2bf10a3

    
           private _handleInspectionChanged(flagKeys: Array<string>, type: FlagChangeType) { 
        
             if (!this._inspectorManager.hasInspectors()) { 
        
               return; 
        
             } 
        
             const details: Record<string, LDEvaluationDetail> = {}; 
        
             flagKeys.forEach((flagKey) => { 
        
               const item = this._flagManager.get(flagKey); 
        
               if (item?.flag && !item.flag.deleted) { 
        
                 const { reason, value, variation } = item.flag; 
        
                 details[flagKey] = createSuccessEvaluationDetail(value, variation, reason); 
        
               } else { 
        
                 details[flagKey] = { 
        
                   value: undefined, 
        
                   // For backwards compatibility purposes reason and variationIndex are null instead of 
        
                   // being undefined. 
        
                   reason: null, 
        
                   variationIndex: null, 
        
                 }; 
        
               } 
        
             }); 
        
             if (type === 'init') { 
        
               this._inspectorManager.onFlagsChanged(details); 
        
             } else if (type === 'patch') { 
        
               Object.entries(details).forEach(([flagKey, detail]) => { 
        
                 this._inspectorManager.onFlagChanged(flagKey, detail); 
        
               }); 
        
             } 
        
           }

packages/shared/sdk-client/src/flag-manager/FlagUpdater.ts#L6-L7

js-core/packages/shared/sdk-client/src/flag-manager/FlagUpdater.ts

Lines 6 to 7 in 2bf10a3


	export type FlagChangeType = 'init' \| 'patch' \| 'override';

joker23 changed the base branch from main to skz/sdk-1360/browser-4.x-waitforinit December 10, 2025 19:32

joker23 changed the base branch from skz/sdk-1360/browser-4.x-waitforinit to main December 10, 2025 19:32

joker23 commented Dec 10, 2025

View reviewed changes

packages/shared/sdk-client/src/flag-manager/FlagManager.ts Show resolved Hide resolved

packages/shared/sdk-client/src/flag-manager/FlagUpdater.ts Show resolved Hide resolved

joker23 force-pushed the skz/sdk-1653/add-debug-override branch from d13c429 to 1fd0057 Compare December 15, 2025 19:55

joker23 added 5 commits December 15, 2025 15:57

feat: adding waitForInitialize to browser 4.x

2c89dfa

test: add unit tests for FlagManager debug override functionality

fc458c5

chore: fixing lint issues

a45f0c2

chore: fix build issue

60d8969

joker23 force-pushed the skz/sdk-1653/add-debug-override branch 2 times, most recently from 8b6f8d9 to cfd87be Compare December 15, 2025 22:32

joker23 marked this pull request as ready for review December 15, 2025 23:37

joker23 requested a review from a team as a code owner December 15, 2025 23:37

joker23 requested a review from kinyoklion December 15, 2025 23:37

cursor bot reviewed Dec 15, 2025

View reviewed changes

fix: issues from rebase

b8f8d9a

joker23 force-pushed the skz/sdk-1653/add-debug-override branch from cfd87be to b8f8d9a Compare December 16, 2025 16:09

cursor bot reviewed Dec 16, 2025

View reviewed changes

kinyoklion reviewed Dec 16, 2025

View reviewed changes

packages/shared/sdk-client/src/flag-manager/FlagUpdater.ts Outdated Show resolved Hide resolved

kinyoklion reviewed Dec 16, 2025

View reviewed changes

kinyoklion approved these changes Dec 16, 2025

View reviewed changes

joker23 and others added 2 commits December 16, 2025 18:09

Update packages/shared/sdk-client/src/flag-manager/FlagUpdater.ts

df0921c

Co-authored-by: Ryan Lamb <[email protected]>

chore: addressing PR comments

2bf10a3

cursor bot reviewed Dec 17, 2025

View reviewed changes

joker23 merged commit 17f5e7d into main Dec 17, 2025
37 checks passed

joker23 deleted the skz/sdk-1653/add-debug-override branch December 17, 2025 00:29

github-actions bot mentioned this pull request Dec 17, 2025

chore: release main #1035

Open

	});
	if (type === 'init') {
	this._inspectorManager.onFlagsChanged(details);
	} else if (type === 'patch') {
	Object.entries(details).forEach(([flagKey, detail]) => {
	this._inspectorManager.onFlagChanged(flagKey, detail);
	});
	}


	private _handleInspectionChanged(flagKeys: Array<string>, type: FlagChangeType) {
	if (!this._inspectorManager.hasInspectors()) {
	return;
	}

	const details: Record<string, LDEvaluationDetail> = {};
	flagKeys.forEach((flagKey) => {
	const item = this._flagManager.get(flagKey);
	if (item?.flag && !item.flag.deleted) {
	const { reason, value, variation } = item.flag;
	details[flagKey] = createSuccessEvaluationDetail(value, variation, reason);
	} else {
	details[flagKey] = {
	value: undefined,
	// For backwards compatibility purposes reason and variationIndex are null instead of
	// being undefined.
	reason: null,
	variationIndex: null,
	};
	}
	});
	if (type === 'init') {
	this._inspectorManager.onFlagsChanged(details);
	} else if (type === 'patch') {
	Object.entries(details).forEach(([flagKey, detail]) => {
	this._inspectorManager.onFlagChanged(flagKey, detail);
	});
	}
	}

feat: adding support for debug override plugins #1033

feat: adding support for debug override plugins #1033

Uh oh!

Conversation

joker23 commented Dec 10, 2025 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Dec 10, 2025

Uh oh!

github-actions bot commented Dec 10, 2025

Uh oh!

github-actions bot commented Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Bug: Inspection manager not notified for override flag changes

Uh oh!

joker23 commented Dec 16, 2025

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Bug: Inspector notifications silently skipped for override changes

Uh oh!

kinyoklion Dec 16, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kinyoklion Dec 16, 2025

Choose a reason for hiding this comment

Uh oh!

kinyoklion commented Dec 17, 2025

Bug: Inspector notifications silently skipped for override changes

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Bug: New 'override' FlagChangeType not handled in inspection callback

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

joker23 commented Dec 10, 2025 •

edited by cursor bot

Loading

github-actions bot commented Dec 10, 2025 •

edited

Loading

github-actions bot commented Dec 10, 2025 •

edited

Loading