feat: implement debug override functionality in client SDK

- 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

Author: joker23

packages/sdk/browser/src/BrowserClient.ts

@@ -18,6 +18,7 @@ import {
   LDPluginEnvironmentMetadata,
   LDTimeoutError,
   Platform,
+  safeRegisterDebugOverridePlugins
 } from '@launchdarkly/js-client-sdk-common';
 
 import { getHref } from './BrowserApi';
@@ -207,6 +208,11 @@ class BrowserClientImpl extends LDClientImpl {
       client,
       this._plugins || [],
     );
+
+    const override = this.getDebugOverrides()
+    if (override) {
+      safeRegisterDebugOverridePlugins(this.logger, override, this._plugins || [])
+    }
   }
 
   override async identify(context: LDContext, identifyOptions?: LDIdentifyOptions): Promise<void> {

packages/sdk/browser/src/LDPlugin.ts

@@ -1,5 +1,4 @@
-import { Hook, LDPluginBase } from '@launchdarkly/js-client-sdk-common';
-
+import { Hook, LDPlugin as LDPluginBase } from '@launchdarkly/js-client-sdk-common';
 import { LDClient } from './LDClient';
 
 /**

packages/sdk/browser/src/common.ts

@@ -43,6 +43,7 @@ export type {
   LDIdentifyError,
   LDIdentifyTimeout,
   LDIdentifyShed,
+  LDDebugOverride,
 } from '@launchdarkly/js-client-sdk-common';
 
 /**

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

@@ -41,7 +41,7 @@ import {
 } from './evaluation/evaluationDetail';
 import createEventProcessor from './events/createEventProcessor';
 import EventFactory from './events/EventFactory';
-import DefaultFlagManager, { FlagManager } from './flag-manager/FlagManager';
+import DefaultFlagManager, { LDDebugOverride, FlagManager } from './flag-manager/FlagManager';
 import { FlagChangeType } from './flag-manager/FlagUpdater';
 import HookRunner from './HookRunner';
 import { getInspectorHook } from './inspection/getInspectorHook';
@@ -127,7 +127,7 @@ export default class LDClientImpl implements LDClient, LDClientIdentifyResult {
 
     this._flagManager.on((context, flagKeys, type) => {
       this._handleInspectionChanged(flagKeys, type);
-      const ldContext = Context.toLDContext(context);
+      const ldContext = context ? Context.toLDContext(context) : null;
       this.emitter.emit('change', ldContext, flagKeys);
       flagKeys.forEach((it) => {
         this.emitter.emit(`change:${it}`, ldContext);
@@ -582,6 +582,14 @@ export default class LDClientImpl implements LDClient, LDClientIdentifyResult {
     this._eventProcessor?.sendEvent(event);
   }
 
+  protected getDebugOverrides(): LDDebugOverride | null {
+    if (this._flagManager.getDebugOverride) {
+      return this._flagManager.getDebugOverride()
+    }
+
+    return null
+  }
+
   private _handleInspectionChanged(flagKeys: Array<string>, type: FlagChangeType) {
     if (!this._inspectorManager.hasInspectors()) {
       return;

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

@@ -0,0 +1,16 @@
+import { LDPluginBase } from '@launchdarkly/js-sdk-common';
+import { LDDebugOverride } from '../flag-manager/FlagManager';
+
+export interface LDPlugin<TClient, THook> extends LDPluginBase<TClient, THook> {
+    /**
+   * An optional function called if the plugin wants to register debug capabilities.
+   * This method allows plugins to receive a debug override interface for
+   * temporarily overriding flag values during development and testing.
+   *
+   * @experimental This interface is experimental and intended for use by LaunchDarkly tools at this time.
+   * The API may change in future versions.
+   *
+   * @param debugOverride The debug override interface instance
+   */
+    registerDebug?(debugOverride: LDDebugOverride): void;
+}

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

@@ -9,3 +9,4 @@ export { ConnectionMode };
 export * from './LDIdentifyOptions';
 export * from './LDInspection';
 export * from './LDIdentifyResult';
+export * from './LDPlugin';

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

@@ -1,4 +1,4 @@
-import { Context, LDLogger, Platform } from '@launchdarkly/js-sdk-common';
+import { Context, LDFlagValue, LDLogger, Platform } from '@launchdarkly/js-sdk-common';
 
 import { namespaceForEnvironment } from '../storage/namespaceUtils';
 import FlagPersistence from './FlagPersistence';
@@ -55,12 +55,67 @@ export interface FlagManager {
    * Unregister a flag change callback.
    */
   off(callback: FlagsChangeCallback): void;
+
+  // REVIEWER: My reasoning here is to have the flagmanager implementation determine
+  // whether or not we can support debug plugins so I put the override methods here.
+  // Would like some thoughts on this as it is a deviation from previous implementation.
+
+  /**
+   * Obtain debug override functions that allows plugins
+   * to manipulate the outcome of the flags managed by
+   * this manager
+   *
+   * @experimental This function is experimental and intended for use by LaunchDarkly tools at this time.
+   */
+  getDebugOverride?(): LDDebugOverride
+}
+
+/**
+ * Debug interface for plugins that need to override flag values during development.
+ * This interface provides methods to temporarily override flag values that take
+ * precedence over the actual flag values from LaunchDarkly. These overrides are
+ * useful for testing, development, and debugging scenarios.
+ *
+ * @experimental This interface is experimental and intended for use by LaunchDarkly tools at this time.
+ * The API may change in future versions.
+ */
+export interface LDDebugOverride {
+  /**
+   * Set an override value for a flag that takes precedence over the real flag value.
+   *
+   * @param flagKey The flag key.
+   * @param value The override value.
+   */
+  setOverride(flagKey: string, value: LDFlagValue): void;
+
+  /**
+   * Remove an override value for a flag, reverting to the real flag value.
+   *
+   * @param flagKey The flag key.
+   */
+  removeOverride(flagKey: string): void;
+
+  /**
+   * Clear all override values, reverting all flags to their real values.
+   */
+  clearAllOverrides(): void;
+
+  /**
+   * Get all currently active flag overrides.
+   *
+   * @returns
+   *   An object containing all active overrides as key-value pairs,
+   *   where keys are flag keys and values are the overridden flag values.
+   *   Returns an empty object if no overrides are active.
+   */
+  getAllOverrides(): { [key: string]: ItemDescriptor };
 }
 
 export default class DefaultFlagManager implements FlagManager {
   private _flagStore = new DefaultFlagStore();
   private _flagUpdater: FlagUpdater;
   private _flagPersistencePromise: Promise<FlagPersistence>;
+  private _overrides?: { [key: string]: LDFlagValue };
 
   /**
    * @param platform implementation of various platform provided functionality
@@ -107,11 +162,25 @@ export default class DefaultFlagManager implements FlagManager {
   }
 
   get(key: string): ItemDescriptor | undefined {
+    if (this._overrides && Object.prototype.hasOwnProperty.call(this._overrides, key)) {
+      return this._convertValueToOverrideDescripter(this._overrides[key]);
+    }
+
     return this._flagStore.get(key);
   }
 
   getAll(): { [key: string]: ItemDescriptor } {
-    return this._flagStore.getAll();
+    if (this._overrides) {
+      return {
+        ...this._flagStore.getAll(),
+        ...Object.entries(this._overrides).reduce((acc: {[key: string]: ItemDescriptor}, [key, value]) => {
+          acc[key] = this._convertValueToOverrideDescripter(value);
+          return acc
+        }, {})
+      }
+    } else {
+      return this._flagStore.getAll();
+    }
   }
 
   setBootstrap(context: Context, newFlags: { [key: string]: ItemDescriptor }): void {
@@ -139,4 +208,63 @@ export default class DefaultFlagManager implements FlagManager {
   off(callback: FlagsChangeCallback): void {
     this._flagUpdater.off(callback);
   }
+
+  private _convertValueToOverrideDescripter(value: LDFlagValue): ItemDescriptor {
+    return {
+      flag: {
+        value: value,
+        version: 0
+      },
+      version: 0
+    };
+  }
+
+  setOverride(key: string, value: LDFlagValue) {
+    if (!this._overrides) {
+      this._overrides = {};
+    }
+    this._overrides[key] = value;
+    this._flagUpdater.handleFlagChanges(null, [key], 'override');
+  }
+
+  removeOverride(flagKey: string) {
+    if (!this._overrides || !Object.prototype.hasOwnProperty.call(this._overrides, flagKey)) {
+      return; // No override to remove
+    }
+
+    delete this._overrides[flagKey];
+
+    // If no more overrides, reset to undefined for performance
+    if (Object.keys(this._overrides).length === 0) {
+      this._overrides = undefined;
+    }
+
+    this._flagUpdater.handleFlagChanges(null, [flagKey], 'override');
+  }
+
+  clearAllOverrides() {
+    if (!this._overrides) {
+      return {}; // No overrides to clear, return empty object for consistency
+    }
+
+    const clearedOverrides = { ...this._overrides };
+    this._overrides = undefined; // Reset to undefined
+    this._flagUpdater.handleFlagChanges(null, Object.keys(clearedOverrides), 'override');
+    return clearedOverrides;
+  }
+
+  getAllOverrides() {
+    if (!this._overrides) {
+      return {};
+    }
+    const result = {} as { [key: string]: ItemDescriptor };
+    Object.entries(this._overrides).forEach(([key, value]) => {
+      result[key] = this._convertValueToOverrideDescripter(value);
+    });
+    return result;
+  }
+
+  getDebugOverride(): LDDebugOverride {
+    return this as LDDebugOverride;
+  }
 }

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

@@ -4,7 +4,7 @@ import calculateChangedKeys from './calculateChangedKeys';
 import FlagStore from './FlagStore';
 import { ItemDescriptor } from './ItemDescriptor';
 
-export type FlagChangeType = 'init' | 'patch';
+export type FlagChangeType = 'init' | 'patch' | 'override';
 
 /**
  * This callback indicates that the details associated with one or more flags
@@ -20,7 +20,12 @@ export type FlagChangeType = 'init' | 'patch';
  * will call a variation method for flag values which you require.
  */
 export type FlagsChangeCallback = (
-  context: Context,
+  // REVIEWER: This is probably not desired, but I think there are some updates
+  // such as overrides that do not really have a context? Unless I am misunderstanding
+  // what context is exactly. Being able to support a null context may also help
+  // with distinguishing between being in the emphemeral state between the start of
+  // initialization and the end of identification and having an invalid context?
+  context: Context | null,
   flagKeys: Array<string>,
   type: FlagChangeType,
 ) => void;
@@ -41,19 +46,23 @@ export default class FlagUpdater {
     this._logger = logger;
   }
 
+  handleFlagChanges(context: Context | null, keys: string[], type: FlagChangeType): void {
+    this._changeCallbacks.forEach((callback) => {
+      try {
+        callback(context, keys, type);
+      } catch (err) {
+        /* intentionally empty */
+      }
+    });
+  }
+
   init(context: Context, newFlags: { [key: string]: ItemDescriptor }) {
     this._activeContextKey = context.canonicalKey;
     const oldFlags = this._flagStore.getAll();
     this._flagStore.init(newFlags);
     const changed = calculateChangedKeys(oldFlags, newFlags);
     if (changed.length > 0) {
-      this._changeCallbacks.forEach((callback) => {
-        try {
-          callback(context, changed, 'init');
-        } catch (err) {
-          /* intentionally empty */
-        }
-      });
+      this.handleFlagChanges(context, changed, 'init');
     }
   }
 
@@ -78,13 +87,7 @@ export default class FlagUpdater {
     }
 
     this._flagStore.insertOrUpdate(key, item);
-    this._changeCallbacks.forEach((callback) => {
-      try {
-        callback(context, [key], 'patch');
-      } catch (err) {
-        /* intentionally empty */
-      }
-    });
+    this.handleFlagChanges(context, [key], 'patch');
     return true;
   }
 

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

@@ -36,10 +36,12 @@ export type {
   LDIdentifyTimeout,
   LDIdentifyShed,
   LDClientIdentifyResult,
+  LDPlugin,
 } from './api';
 
 export type { DataManager, DataManagerFactory, ConnectionParams } from './DataManager';
-export type { FlagManager } from './flag-manager/FlagManager';
+export type { FlagManager, LDDebugOverride } from './flag-manager/FlagManager';
+export {safeRegisterDebugOverridePlugins} from './plugins/safeRegisterDebugOverridePlugins';
 export type { Configuration } from './configuration/Configuration';
 
 export type { LDEmitter };

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

@@ -0,0 +1,24 @@
+import { internal, LDLogger } from "@launchdarkly/js-sdk-common";
+import { LDPlugin } from "../api";
+import { LDDebugOverride } from "../flag-manager/FlagManager";
+
+/**
+ * Safe register debug override plugins.
+ *
+ * @param logger - The logger to use for logging errors.
+ * @param debugOverride - The debug override to register.
+ * @param plugins - The plugins to register.
+ */
+export function safeRegisterDebugOverridePlugins<TClient, THook>(
+  logger: LDLogger,
+  debugOverride: LDDebugOverride,
+  plugins: LDPlugin<TClient, THook>[]
+): void {
+  plugins.forEach(plugin => {
+    try {
+      plugin.registerDebug?.(debugOverride);
+    } catch (error) {
+      logger.error(`Exception thrown registering plugin ${internal.safeGetName(logger, plugin)}.`);
+    }
+  });
+};