@launchdarkly/js-client-sdk-common 1.15.2 → 1.17.0

package/dist/esm/index.mjs

@@ -1,4 +1,4 @@
-import { getPollingUri, TypeValidators, createSafeLogger, ServiceEndpoints, ApplicationTags, OptionMessages, NumberWithMinimum, SafeLogger, internal, deepCompact, clone, secondsToMillis, ClientContext, fastDeepEqual, defaultHeaders, Context, LDTimeoutError, AutoEnvAttributes, LDClientError, isHttpRecoverable, httpErrorMessage, LDPollingError, DataSourceErrorKind, getStreamingUri, shouldRetry, LDStreamingError } from '@launchdarkly/js-sdk-common';
+import { getPollingUri, TypeValidators, createSafeLogger, ServiceEndpoints, ApplicationTags, OptionMessages, NumberWithMinimum, SafeLogger, internal, deepCompact, clone, secondsToMillis, ClientContext, fastDeepEqual, defaultHeaders, Context, LDTimeoutError, AutoEnvAttributes, cancelableTimedPromise, LDClientError, isHttpRecoverable, httpErrorMessage, LDPollingError, DataSourceErrorKind, getStreamingUri, shouldRetry, LDStreamingError } from '@launchdarkly/js-sdk-common';
 export * from '@launchdarkly/js-sdk-common';
 import * as jsSdkCommon from '@launchdarkly/js-sdk-common';
 export { jsSdkCommon as platform };
@@ -242,6 +242,7 @@ const validators = {
     payloadFilterKey: TypeValidators.stringMatchingRegex(/^[a-zA-Z0-9](\w|\.|-)*$/),
     hooks: TypeValidators.createTypeArray('Hook[]', {}),
     inspectors: TypeValidators.createTypeArray('LDInspection', {}),
+    cleanOldPersistentData: TypeValidators.Boolean,
 };
 
 const DEFAULT_POLLING_INTERVAL = 60 * 5;
@@ -520,6 +521,38 @@ const addAutoEnv = async (context, platform, config) => {
     return context;
 };
 
+function createActiveContextTracker() {
+    let unwrappedContext;
+    let context;
+    return {
+        set(_unwrappedContext, _context) {
+            unwrappedContext = _unwrappedContext;
+            context = _context;
+        },
+        getContext() {
+            return context;
+        },
+        getUnwrappedContext() {
+            return unwrappedContext;
+        },
+        newIdentificationPromise() {
+            let res;
+            let rej;
+            const basePromise = new Promise((resolve, reject) => {
+                res = resolve;
+                rej = reject;
+            });
+            return { identifyPromise: basePromise, identifyResolve: res, identifyReject: rej };
+        },
+        hasContext() {
+            return context !== undefined;
+        },
+        hasValidContext() {
+            return this.hasContext() && context.valid;
+        },
+    };
+}
+
 const { isLegacyUser, isMultiKind, isSingleKind } = internal;
 /**
  * This is the root ensureKey function. All other ensureKey functions reduce to this.
@@ -813,30 +846,30 @@ class FlagPersistence {
 }
 
 /**
- * In memory flag store.
+ * Creates the default implementation of the flag store.
  */
-class DefaultFlagStore {
-    constructor() {
-        this._flags = {};
-    }
-    init(newFlags) {
-        this._flags = Object.entries(newFlags).reduce((acc, [key, flag]) => {
-            acc[key] = flag;
-            return acc;
-        }, {});
-    }
-    insertOrUpdate(key, update) {
-        this._flags[key] = update;
-    }
-    get(key) {
-        if (Object.prototype.hasOwnProperty.call(this._flags, key)) {
-            return this._flags[key];
-        }
-        return undefined;
-    }
-    getAll() {
-        return this._flags;
-    }
+function createDefaultFlagStore() {
+    let flags = {};
+    return {
+        init(newFlags) {
+            flags = Object.entries(newFlags).reduce((acc, [key, flag]) => {
+                acc[key] = flag;
+                return acc;
+            }, {});
+        },
+        insertOrUpdate(key, update) {
+            flags[key] = update;
+        },
+        get(key) {
+            if (Object.prototype.hasOwnProperty.call(flags, key)) {
+                return flags[key];
+            }
+            return undefined;
+        },
+        getAll() {
+            return flags;
+        },
+    };
 }
 
 function calculateChangedKeys(existingObject, newObject) {
@@ -857,69 +890,66 @@ function calculateChangedKeys(existingObject, newObject) {
     return changedKeys;
 }
 
-/**
- * The flag updater handles logic required during the flag update process.
- * It handles versions checking to handle out of order flag updates and
- * also handles flag comparisons for change notification.
- */
-class FlagUpdater {
-    constructor(flagStore, logger) {
-        this._changeCallbacks = new Array();
-        this._flagStore = flagStore;
-        this._logger = logger;
-    }
-    init(context, newFlags) {
-        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 */
-                }
-            });
-        }
-    }
-    initCached(context, newFlags) {
-        if (this._activeContextKey === context.canonicalKey) {
-            return;
-        }
-        this.init(context, newFlags);
-    }
-    upsert(context, key, item) {
-        if (this._activeContextKey !== context.canonicalKey) {
-            this._logger.warn('Received an update for an inactive context.');
-            return false;
-        }
-        const currentValue = this._flagStore.get(key);
-        if (currentValue !== undefined && currentValue.version >= item.version) {
-            // this is an out of order update that can be ignored
-            return false;
-        }
-        this._flagStore.insertOrUpdate(key, item);
-        this._changeCallbacks.forEach((callback) => {
-            try {
-                callback(context, [key], 'patch');
+function createFlagUpdater(_flagStore, _logger) {
+    const flagStore = _flagStore;
+    const logger = _logger;
+    let activeContext;
+    const changeCallbacks = new Array();
+    return {
+        handleFlagChanges(keys, type) {
+            if (activeContext) {
+                changeCallbacks.forEach((callback) => {
+                    try {
+                        callback(activeContext, keys, type);
+                    }
+                    catch (err) {
+                        /* intentionally empty */
+                    }
+                });
             }
-            catch (err) {
-                /* intentionally empty */
+            else {
+                logger.warn('Received a change event without an active context. Changes will not be propagated.');
             }
-        });
-        return true;
-    }
-    on(callback) {
-        this._changeCallbacks.push(callback);
-    }
-    off(callback) {
-        const index = this._changeCallbacks.indexOf(callback);
-        if (index > -1) {
-            this._changeCallbacks.splice(index, 1);
-        }
-    }
+        },
+        init(context, newFlags) {
+            activeContext = context;
+            const oldFlags = flagStore.getAll();
+            flagStore.init(newFlags);
+            const changed = calculateChangedKeys(oldFlags, newFlags);
+            if (changed.length > 0) {
+                this.handleFlagChanges(changed, 'init');
+            }
+        },
+        initCached(context, newFlags) {
+            if (activeContext?.canonicalKey === context.canonicalKey) {
+                return;
+            }
+            this.init(context, newFlags);
+        },
+        upsert(context, key, item) {
+            if (activeContext?.canonicalKey !== context.canonicalKey) {
+                logger.warn('Received an update for an inactive context.');
+                return false;
+            }
+            const currentValue = flagStore.get(key);
+            if (currentValue !== undefined && currentValue.version >= item.version) {
+                // this is an out of order update that can be ignored
+                return false;
+            }
+            flagStore.insertOrUpdate(key, item);
+            this.handleFlagChanges([key], 'patch');
+            return true;
+        },
+        on(callback) {
+            changeCallbacks.push(callback);
+        },
+        off(callback) {
+            const index = changeCallbacks.indexOf(callback);
+            if (index > -1) {
+                changeCallbacks.splice(index, 1);
+            }
+        },
+    };
 }
 
 class DefaultFlagManager {
@@ -931,8 +961,8 @@ class DefaultFlagManager {
      * @param timeStamper exists for testing purposes
      */
     constructor(platform, sdkKey, maxCachedContexts, logger, timeStamper = () => Date.now()) {
-        this._flagStore = new DefaultFlagStore();
-        this._flagUpdater = new FlagUpdater(this._flagStore, logger);
+        this._flagStore = createDefaultFlagStore();
+        this._flagUpdater = createFlagUpdater(this._flagStore, logger);
         this._flagPersistencePromise = this._initPersistence(platform, sdkKey, maxCachedContexts, logger, timeStamper);
     }
     async _initPersistence(platform, sdkKey, maxCachedContexts, logger, timeStamper = () => Date.now()) {
@@ -940,11 +970,26 @@ class DefaultFlagManager {
         return new FlagPersistence(platform, environmentNamespace, maxCachedContexts, this._flagStore, this._flagUpdater, logger, timeStamper);
     }
     get(key) {
+        if (this._overrides && Object.prototype.hasOwnProperty.call(this._overrides, key)) {
+            return this._convertValueToOverrideDescripter(this._overrides[key]);
+        }
         return this._flagStore.get(key);
     }
     getAll() {
+        if (this._overrides) {
+            return {
+                ...this._flagStore.getAll(),
+                ...Object.entries(this._overrides).reduce((acc, [key, value]) => {
+                    acc[key] = this._convertValueToOverrideDescripter(value);
+                    return acc;
+                }, {}),
+            };
+        }
         return this._flagStore.getAll();
     }
+    presetFlags(newFlags) {
+        this._flagStore.init(newFlags);
+    }
     setBootstrap(context, newFlags) {
         // Bypasses the persistence as we do not want to put these flags into any cache.
         // Generally speaking persistence likely *SHOULD* be disabled when using bootstrap.
@@ -965,6 +1010,58 @@ class DefaultFlagManager {
     off(callback) {
         this._flagUpdater.off(callback);
     }
+    _convertValueToOverrideDescripter(value) {
+        return {
+            flag: {
+                value,
+                version: 0,
+            },
+            version: 0,
+        };
+    }
+    setOverride(key, value) {
+        if (!this._overrides) {
+            this._overrides = {};
+        }
+        this._overrides[key] = value;
+        this._flagUpdater.handleFlagChanges([key], 'override');
+    }
+    removeOverride(flagKey) {
+        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([flagKey], 'override');
+    }
+    clearAllOverrides() {
+        if (this._overrides) {
+            const clearedOverrides = { ...this._overrides };
+            this._overrides = undefined; // Reset to undefined
+            this._flagUpdater.handleFlagChanges(Object.keys(clearedOverrides), 'override');
+        }
+    }
+    getAllOverrides() {
+        if (!this._overrides) {
+            return {};
+        }
+        const result = {};
+        Object.entries(this._overrides).forEach(([key, value]) => {
+            result[key] = this._convertValueToOverrideDescripter(value);
+        });
+        return result;
+    }
+    getDebugOverride() {
+        return {
+            setOverride: this.setOverride.bind(this),
+            removeOverride: this.removeOverride.bind(this),
+            clearAllOverrides: this.clearAllOverrides.bind(this),
+            getAllOverrides: this.getAllOverrides.bind(this),
+        };
+    }
 }
 
 const UNKNOWN_HOOK_NAME = 'unknown hook';
@@ -1327,6 +1424,7 @@ class LDClientImpl {
         this.sdkKey = sdkKey;
         this.autoEnvAttributes = autoEnvAttributes;
         this.platform = platform;
+        this._activeContextTracker = createActiveContextTracker();
         this._highTimeoutThreshold = 15;
         this._eventFactoryDefault = new EventFactory(false);
         this._eventFactoryWithReasons = new EventFactory(true);
@@ -1367,6 +1465,24 @@ class LDClientImpl {
         if (this._inspectorManager.hasInspectors()) {
             this._hookRunner.addHook(getInspectorHook(this._inspectorManager));
         }
+        if (options.cleanOldPersistentData &&
+            internalOptions?.getLegacyStorageKeys &&
+            this.platform.storage) {
+            // NOTE: we are letting this fail silently because it's not critical and we don't want to block the client from initializing.
+            try {
+                this.logger.debug('Cleaning old persistent data.');
+                Promise.all(internalOptions.getLegacyStorageKeys().map((key) => this.platform.storage?.clear(key)))
+                    .catch((error) => {
+                    this.logger.error(`Error cleaning old persistent data: ${error}`);
+                })
+                    .finally(() => {
+                    this.logger.debug('Cleaned old persistent data.');
+                });
+            }
+            catch (error) {
+                this.logger.error(`Error cleaning old persistent data: ${error}`);
+            }
+        }
     }
     allFlags() {
         // extracting all flag values
@@ -1401,19 +1517,20 @@ class LDClientImpl {
         // code.  We are returned the unchecked context so that if a consumer identifies with an invalid context
         // and then calls getContext, they get back the same context they provided, without any assertion about
         // validity.
-        return this._uncheckedContext ? clone(this._uncheckedContext) : undefined;
+        return this._activeContextTracker.hasContext()
+            ? clone(this._activeContextTracker.getUnwrappedContext())
+            : undefined;
     }
     getInternalContext() {
-        return this._checkedContext;
-    }
-    _createIdentifyPromise() {
-        let res;
-        let rej;
-        const basePromise = new Promise((resolve, reject) => {
-            res = resolve;
-            rej = reject;
-        });
-        return { identifyPromise: basePromise, identifyResolve: res, identifyReject: rej };
+        return this._activeContextTracker.getContext();
+    }
+    /**
+     * Preset flags are used to set the flags before the client is initialized. This is useful for
+     * when client has precached flags that are ready to evaluate without full initialization.
+     * @param newFlags - The flags to preset.
+     */
+    presetFlags(newFlags) {
+        this._flagManager.presetFlags(newFlags);
     }
     /**
      * Identifies a context to LaunchDarkly. See {@link LDClient.identify}.
@@ -1489,11 +1606,10 @@ class LDClientImpl {
                     this.emitter.emit('error', context, error);
                     return Promise.reject(error);
                 }
-                this._uncheckedContext = context;
-                this._checkedContext = checkedContext;
-                this._eventProcessor?.sendEvent(this._eventFactoryDefault.identifyEvent(this._checkedContext));
-                const { identifyPromise, identifyResolve, identifyReject } = this._createIdentifyPromise();
-                this.logger.debug(`Identifying ${JSON.stringify(this._checkedContext)}`);
+                this._activeContextTracker.set(context, checkedContext);
+                this._eventProcessor?.sendEvent(this._eventFactoryDefault.identifyEvent(checkedContext));
+                const { identifyPromise, identifyResolve, identifyReject } = this._activeContextTracker.newIdentificationPromise();
+                this.logger.debug(`Identifying ${JSON.stringify(checkedContext)}`);
                 await this.dataManager.identify(identifyResolve, identifyReject, checkedContext, identifyOptions);
                 return identifyPromise;
             },
@@ -1511,12 +1627,18 @@ class LDClientImpl {
         }, identifyOptions?.sheddable ?? false)
             .then((res) => {
             if (res.status === 'error') {
-                return { status: 'error', error: res.error };
+                const errorResult = { status: 'error', error: res.error };
+                // Track initialization state for waitForInitialization
+                this.maybeSetInitializationResult({ status: 'failed', error: res.error });
+                return errorResult;
             }
             if (res.status === 'shed') {
                 return { status: 'shed' };
             }
-            return { status: 'completed' };
+            const successResult = { status: 'completed' };
+            // Track initialization state for waitForInitialization
+            this.maybeSetInitializationResult({ status: 'complete' });
+            return successResult;
         });
         if (noTimeout) {
             return callSitePromise;
@@ -1528,6 +1650,74 @@ class LDClientImpl {
         });
         return Promise.race([callSitePromise, timeoutPromise]);
     }
+    /**
+     * Sets the initialization result and resolves any pending waitForInitialization promises.
+     * This method is idempotent and will only be set by the initialization flow. Subsequent calls
+     * should not do anything.
+     * @param result The initialization result.
+     */
+    maybeSetInitializationResult(result) {
+        if (this.initializeResult === undefined) {
+            this.initializeResult = result;
+            this.emitter.emit('ready');
+            if (result.status === 'complete') {
+                this.emitter.emit('initialized');
+            }
+            if (this.initResolve) {
+                this.initResolve(result);
+                this.initResolve = undefined;
+            }
+        }
+    }
+    waitForInitialization(options) {
+        const timeout = options?.timeout ?? 5;
+        // If initialization has already completed (successfully or failed), return the result immediately.
+        if (this.initializeResult) {
+            return Promise.resolve(this.initializeResult);
+        }
+        // If waitForInitialization was previously called, then return the promise with a timeout.
+        // This condition should only be triggered if waitForInitialization was called multiple times.
+        if (this.initializedPromise) {
+            return this.promiseWithTimeout(this.initializedPromise, timeout);
+        }
+        // Create a new promise for tracking initialization
+        if (!this.initializedPromise) {
+            this.initializedPromise = new Promise((resolve) => {
+                this.initResolve = resolve;
+            });
+        }
+        return this.promiseWithTimeout(this.initializedPromise, timeout);
+    }
+    /**
+     * Apply a timeout promise to a base promise. This is for use with waitForInitialization.
+     *
+     * @param basePromise The promise to race against a timeout.
+     * @param timeout The timeout in seconds.
+     * @returns A promise that resolves to the initialization result or timeout.
+     *
+     * @privateRemarks
+     * This method is protected because it is used by the browser SDK's `start` method.
+     * Eventually, the start method will be moved to this common implementation and this method will
+     * be made private.
+     */
+    promiseWithTimeout(basePromise, timeout) {
+        const cancelableTimeout = cancelableTimedPromise(timeout, 'waitForInitialization');
+        return Promise.race([
+            basePromise.then((res) => {
+                cancelableTimeout.cancel();
+                return res;
+            }),
+            cancelableTimeout.promise
+                // If the promise resolves without error, then the initialization completed successfully.
+                // NOTE: this should never return as the resolution would only be triggered by the basePromise
+                // being resolved.
+                .then(() => ({ status: 'complete' }))
+                .catch(() => ({ status: 'timeout' })),
+        ]).catch((reason) => {
+            this.logger?.error(reason.message);
+            return { status: 'failed', error: reason };
+        });
+    }
     on(eventName, listener) {
         this.emitter.on(eventName, listener);
     }
@@ -1535,7 +1725,7 @@ class LDClientImpl {
         this.emitter.off(eventName, listener);
     }
     track(key, data, metricValue) {
-        if (!this._checkedContext || !this._checkedContext.valid) {
+        if (!this._activeContextTracker.hasValidContext()) {
             this.logger.warn(ClientMessages.MissingContextKeyNoEvent);
             return;
         }
@@ -1543,37 +1733,46 @@ class LDClientImpl {
         if (metricValue !== undefined && !TypeValidators.Number.is(metricValue)) {
             this.logger?.warn(ClientMessages.invalidMetricValue(typeof metricValue));
         }
-        this._eventProcessor?.sendEvent(this._config.trackEventModifier(this._eventFactoryDefault.customEvent(key, this._checkedContext, data, metricValue)));
+        this._eventProcessor?.sendEvent(this._config.trackEventModifier(this._eventFactoryDefault.customEvent(key, this._activeContextTracker.getContext(), data, metricValue)));
         this._hookRunner.afterTrack({
             key,
             // The context is pre-checked above, so we know it can be unwrapped.
-            context: this._uncheckedContext,
+            context: this._activeContextTracker.getUnwrappedContext(),
             data,
             metricValue,
         });
     }
     _variationInternal(flagKey, defaultValue, eventFactory, typeChecker) {
-        if (!this._uncheckedContext) {
-            this.logger.debug(ClientMessages.MissingContextKeyNoEvent);
-            return createErrorEvaluationDetail(ErrorKinds.UserNotSpecified, defaultValue);
-        }
-        const evalContext = Context.fromLDContext(this._uncheckedContext);
+        // We are letting evaulations happen without a context. The main case for this
+        // is when cached data is loaded, but the client is not fully initialized. In this
+        // case, we will write out a warning for each evaluation attempt.
+        // NOTE: we will be changing this behavior soon once we have a tracker on the
+        // client initialization state.
+        const hasContext = this._activeContextTracker.hasContext();
+        if (!hasContext) {
+            this.logger?.warn('Flag evaluation called before client is fully initialized, data from this evaulation could be stale.');
+        }
+        const evalContext = this._activeContextTracker.getContext();
         const foundItem = this._flagManager.get(flagKey);
         if (foundItem === undefined || foundItem.flag.deleted) {
             const defVal = defaultValue ?? null;
             const error = new LDClientError(`Unknown feature flag "${flagKey}"; returning default value ${defVal}.`);
-            this.emitter.emit('error', this._uncheckedContext, error);
-            this._eventProcessor?.sendEvent(this._eventFactoryDefault.unknownFlagEvent(flagKey, defVal, evalContext));
+            this.emitter.emit('error', this._activeContextTracker.getUnwrappedContext(), error);
+            if (hasContext) {
+                this._eventProcessor?.sendEvent(this._eventFactoryDefault.unknownFlagEvent(flagKey, defVal, evalContext));
+            }
             return createErrorEvaluationDetail(ErrorKinds.FlagNotFound, defaultValue);
         }
         const { reason, value, variation, prerequisites } = foundItem.flag;
         if (typeChecker) {
             const [matched, type] = typeChecker(value);
             if (!matched) {
-                this._eventProcessor?.sendEvent(eventFactory.evalEventClient(flagKey, defaultValue, // track default value on type errors
-                defaultValue, foundItem.flag, evalContext, reason));
+                if (hasContext) {
+                    this._eventProcessor?.sendEvent(eventFactory.evalEventClient(flagKey, defaultValue, // track default value on type errors
+                    defaultValue, foundItem.flag, evalContext, reason));
+                }
                 const error = new LDClientError(`Wrong type "${type}" for feature flag "${flagKey}"; returning default value`);
-                this.emitter.emit('error', this._uncheckedContext, error);
+                this.emitter.emit('error', this._activeContextTracker.getUnwrappedContext(), error);
                 return createErrorEvaluationDetail(ErrorKinds.WrongType, defaultValue);
             }
         }
@@ -1585,18 +1784,20 @@ class LDClientImpl {
         prerequisites?.forEach((prereqKey) => {
             this._variationInternal(prereqKey, undefined, this._eventFactoryDefault);
         });
-        this._eventProcessor?.sendEvent(eventFactory.evalEventClient(flagKey, value, defaultValue, foundItem.flag, evalContext, reason));
+        if (hasContext) {
+            this._eventProcessor?.sendEvent(eventFactory.evalEventClient(flagKey, value, defaultValue, foundItem.flag, evalContext, reason));
+        }
         return successDetail;
     }
     variation(flagKey, defaultValue) {
-        const { value } = this._hookRunner.withEvaluation(flagKey, this._uncheckedContext, defaultValue, () => this._variationInternal(flagKey, defaultValue, this._eventFactoryDefault));
+        const { value } = this._hookRunner.withEvaluation(flagKey, this._activeContextTracker.getUnwrappedContext(), defaultValue, () => this._variationInternal(flagKey, defaultValue, this._eventFactoryDefault));
         return value;
     }
     variationDetail(flagKey, defaultValue) {
-        return this._hookRunner.withEvaluation(flagKey, this._uncheckedContext, defaultValue, () => this._variationInternal(flagKey, defaultValue, this._eventFactoryWithReasons));
+        return this._hookRunner.withEvaluation(flagKey, this._activeContextTracker.getUnwrappedContext(), defaultValue, () => this._variationInternal(flagKey, defaultValue, this._eventFactoryWithReasons));
     }
     _typedEval(key, defaultValue, eventFactory, typeChecker) {
-        return this._hookRunner.withEvaluation(key, this._uncheckedContext, defaultValue, () => this._variationInternal(key, defaultValue, eventFactory, typeChecker));
+        return this._hookRunner.withEvaluation(key, this._activeContextTracker.getUnwrappedContext(), defaultValue, () => this._variationInternal(key, defaultValue, eventFactory, typeChecker));
     }
     boolVariation(key, defaultValue) {
         return this._typedEval(key, defaultValue, this._eventFactoryDefault, (value) => [
@@ -1678,6 +1879,9 @@ class LDClientImpl {
     sendEvent(event) {
         this._eventProcessor?.sendEvent(event);
     }
+    getDebugOverrides() {
+        return this._flagManager.getDebugOverride?.();
+    }
     _handleInspectionChanged(flagKeys, type) {
         if (!this._inspectorManager.hasInspectors()) {
             return;
@@ -1699,6 +1903,9 @@ class LDClientImpl {
                 };
             }
         });
+        // NOTE: we are not tracking "override" changes because, at the time of writing,
+        // these changes are only used for debugging purposes and are not persisted. This
+        // may change in the future.
         if (type === 'init') {
             this._inspectorManager.onFlagsChanged(details);
         }
@@ -1710,6 +1917,24 @@ class LDClientImpl {
     }
 }
 
+/**
+ * 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.
+ */
+function safeRegisterDebugOverridePlugins(logger, debugOverride, plugins) {
+    plugins.forEach((plugin) => {
+        try {
+            plugin.registerDebug?.(debugOverride);
+        }
+        catch (error) {
+            logger.error(`Exception thrown registering plugin ${internal.safeGetName(logger, plugin)}.`);
+        }
+    });
+}
+
 class DataSourceEventHandler {
     constructor(_flagManager, _statusManager, _logger) {
         this._flagManager = _flagManager;
@@ -2185,5 +2410,5 @@ class BaseDataManager {
     }
 }
 
-export { BaseDataManager, DataSourceState, LDClientImpl, Requestor, makeRequestor };
+export { BaseDataManager, DataSourceState, LDClientImpl, Requestor, makeRequestor, safeRegisterDebugOverridePlugins };
 //# sourceMappingURL=index.mjs.map