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

package/dist/esm/flag-manager/FlagManager.d.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 { FlagsChangeCallback } from './FlagUpdater';
 import { ItemDescriptor } from './ItemDescriptor';
 /**
@@ -34,6 +34,16 @@ export interface FlagManager {
      * Asynchronously load cached values from persistence.
      */
     loadCached(context: Context): Promise<boolean>;
+    /**
+     * Updates in-memory storage with the specified flags without a context
+     * or persistent storage. Flags set in this way are considered emphemeral and
+     * should be replaced as soon as initialization is done.
+     *
+     * @param newFlags - cached flags
+     */
+    presetFlags(newFlags: {
+        [key: string]: ItemDescriptor;
+    }): void;
     /**
      * Update in-memory storage with the specified flags, but do not persistent them to cache
      * storage.
@@ -49,11 +59,59 @@ export interface FlagManager {
      * Unregister a flag change callback.
      */
     off(callback: FlagsChangeCallback): void;
+    /**
+     * 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;
     private _flagUpdater;
     private _flagPersistencePromise;
+    private _overrides?;
     /**
      * @param platform implementation of various platform provided functionality
      * @param sdkKey that will be used to distinguish different environments
@@ -67,6 +125,9 @@ export default class DefaultFlagManager implements FlagManager {
     getAll(): {
         [key: string]: ItemDescriptor;
     };
+    presetFlags(newFlags: {
+        [key: string]: ItemDescriptor;
+    }): void;
     setBootstrap(context: Context, newFlags: {
         [key: string]: ItemDescriptor;
     }): void;
@@ -77,5 +138,13 @@ export default class DefaultFlagManager implements FlagManager {
     loadCached(context: Context): Promise<boolean>;
     on(callback: FlagsChangeCallback): void;
     off(callback: FlagsChangeCallback): void;
+    private _convertValueToOverrideDescripter;
+    setOverride(key: string, value: LDFlagValue): void;
+    removeOverride(flagKey: string): void;
+    clearAllOverrides(): void;
+    getAllOverrides(): {
+        [key: string]: ItemDescriptor;
+    };
+    getDebugOverride(): LDDebugOverride;
 }
 //# sourceMappingURL=FlagManager.d.ts.map

package/dist/esm/flag-manager/FlagManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FlagManager.d.ts","sourceRoot":"","sources":["../../src/flag-manager/FlagManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAK1E,OAAoB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAC;IAE7C;;OAEG;IACH,MAAM,IAAI;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAAA;KAAE,CAAC;IAE5C;;;OAGG;IACH,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnF;;;OAGG;IACH,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE9E;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE/C;;;OAGG;IACH,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAAA;KAAE,GAAG,IAAI,CAAC;IAElF;;OAEG;IACH,EAAE,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAExC;;OAEG;IACH,GAAG,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAAC;CAC1C;AAED,MAAM,CAAC,OAAO,OAAO,kBAAmB,YAAW,WAAW;IAC5D,OAAO,CAAC,UAAU,CAA0B;IAC5C,OAAO,CAAC,YAAY,CAAc;IAClC,OAAO,CAAC,uBAAuB,CAA2B;IAE1D;;;;;;OAMG;gBAED,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,MAAM,EACd,iBAAiB,EAAE,MAAM,EACzB,MAAM,EAAE,QAAQ,EAChB,WAAW,GAAE,MAAM,MAAyB;YAYhC,gBAAgB;IAoB9B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAI5C,MAAM,IAAI;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAAA;KAAE;IAI3C,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAAA;KAAE,GAAG,IAAI;IAM3E,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlF,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IAI7E,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAIpD,EAAE,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI;IAIvC,GAAG,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI;CAGzC"}
+{"version":3,"file":"FlagManager.d.ts","sourceRoot":"","sources":["../../src/flag-manager/FlagManager.ts"],"names":[],"mappings":"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"}

package/dist/esm/flag-manager/FlagUpdater.d.ts

@@ -1,7 +1,7 @@
 import { Context, LDLogger } from '@launchdarkly/js-sdk-common';
 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
  * have changed.
@@ -24,9 +24,10 @@ export type FlagsChangeCallback = (context: Context, flagKeys: Array<string>, ty
 export default class FlagUpdater {
     private _flagStore;
     private _logger;
-    private _activeContextKey;
+    private _activeContext;
     private _changeCallbacks;
     constructor(flagStore: FlagStore, logger: LDLogger);
+    handleFlagChanges(keys: string[], type: FlagChangeType): void;
     init(context: Context, newFlags: {
         [key: string]: ItemDescriptor;
     }): void;

package/dist/esm/flag-manager/FlagUpdater.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FlagUpdater.d.ts","sourceRoot":"","sources":["../../src/flag-manager/FlagUpdater.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAGhE,OAAO,SAAS,MAAM,aAAa,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,OAAO,CAAC;AAE9C;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAChC,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,EACvB,IAAI,EAAE,cAAc,KACjB,IAAI,CAAC;AAEV;;;;GAIG;AACH,MAAM,CAAC,OAAO,OAAO,WAAW;IAC9B,OAAO,CAAC,UAAU,CAAY;IAC9B,OAAO,CAAC,OAAO,CAAW;IAC1B,OAAO,CAAC,iBAAiB,CAAqB;IAC9C,OAAO,CAAC,gBAAgB,CAAoC;gBAEhD,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ;IAKlD,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAAA;KAAE;IAgBlE,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAAA;KAAE;IAQxE,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO;IAuBpE,EAAE,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI;IAIvC,GAAG,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI;CAMzC"}
+{"version":3,"file":"FlagUpdater.d.ts","sourceRoot":"","sources":["../../src/flag-manager/FlagUpdater.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAGhE,OAAO,SAAS,MAAM,aAAa,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;AAE3D;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAChC,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,EACvB,IAAI,EAAE,cAAc,KACjB,IAAI,CAAC;AAEV;;;;GAIG;AACH,MAAM,CAAC,OAAO,OAAO,WAAW;IAC9B,OAAO,CAAC,UAAU,CAAY;IAC9B,OAAO,CAAC,OAAO,CAAW;IAC1B,OAAO,CAAC,cAAc,CAAsB;IAC5C,OAAO,CAAC,gBAAgB,CAAoC;gBAEhD,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ;IAKlD,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI;IAgB7D,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAAA;KAAE;IAUlE,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAAA;KAAE;IAQxE,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO;IAiBpE,EAAE,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI;IAIvC,GAAG,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI;CAMzC"}

package/dist/esm/index.d.ts

@@ -6,9 +6,10 @@ import LDClientImpl from './LDClientImpl';
 import LDEmitter, { EventName } from './LDEmitter';
 export * from '@launchdarkly/js-sdk-common';
 export * as platform from '@launchdarkly/js-sdk-common';
-export type { LDEvaluationDetail, LDEvaluationDetailTyped, LDClient, LDOptions, ConnectionMode, LDIdentifyOptions, Hook, HookMetadata, EvaluationSeriesContext, EvaluationSeriesData, IdentifySeriesContext, IdentifySeriesData, IdentifySeriesResult, IdentifySeriesStatus, TrackSeriesContext, LDInspection, LDIdentifyResult, LDIdentifySuccess, LDIdentifyError, LDIdentifyTimeout, LDIdentifyShed, LDClientIdentifyResult, } from './api';
+export type { LDEvaluationDetail, LDEvaluationDetailTyped, LDClient, LDOptions, ConnectionMode, LDIdentifyOptions, Hook, HookMetadata, EvaluationSeriesContext, EvaluationSeriesData, IdentifySeriesContext, IdentifySeriesData, IdentifySeriesResult, IdentifySeriesStatus, TrackSeriesContext, LDInspection, LDIdentifyResult, LDIdentifySuccess, LDIdentifyError, LDIdentifyTimeout, LDIdentifyShed, LDClientIdentifyResult, LDPluginBase, } 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 };
 export type { ItemDescriptor } from './flag-manager/ItemDescriptor';

package/dist/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AACxE,OAAO,gBAAgB,EAAE,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAClF,OAAO,yBAAyB,MAAM,wCAAwC,CAAC;AAC/E,OAAO,SAAS,EAAE,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,YAAY,MAAM,gBAAgB,CAAC;AAC1C,OAAO,SAAS,EAAE,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAEnD,cAAc,6BAA6B,CAAC;AAE5C,OAAO,KAAK,QAAQ,MAAM,6BAA6B,CAAC;AAMxD,YAAY,EACV,kBAAkB,EAClB,uBAAuB,EACvB,QAAQ,EACR,SAAS,EACT,cAAc,EACd,iBAAiB,EACjB,IAAI,EACJ,YAAY,EACZ,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,sBAAsB,GACvB,MAAM,OAAO,CAAC;AAEf,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACvF,YAAY,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC9D,YAAY,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE,YAAY,EAAE,SAAS,EAAE,CAAC;AAC1B,YAAY,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,YAAY,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAEpC,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,CAAC;AAEpC,OAAO,EACL,gBAAgB,EAChB,yBAAyB,EACzB,YAAY,EACZ,uBAAuB,EACvB,eAAe,EACf,SAAS,IAAI,kBAAkB,GAChC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AACxE,OAAO,gBAAgB,EAAE,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAClF,OAAO,yBAAyB,MAAM,wCAAwC,CAAC;AAC/E,OAAO,SAAS,EAAE,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,YAAY,MAAM,gBAAgB,CAAC;AAC1C,OAAO,SAAS,EAAE,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAEnD,cAAc,6BAA6B,CAAC;AAE5C,OAAO,KAAK,QAAQ,MAAM,6BAA6B,CAAC;AAMxD,YAAY,EACV,kBAAkB,EAClB,uBAAuB,EACvB,QAAQ,EACR,SAAS,EACT,cAAc,EACd,iBAAiB,EACjB,IAAI,EACJ,YAAY,EACZ,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,sBAAsB,EACtB,YAAY,GACb,MAAM,OAAO,CAAC;AAEf,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACvF,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC/E,OAAO,EAAE,gCAAgC,EAAE,MAAM,4CAA4C,CAAC;AAC9F,YAAY,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE,YAAY,EAAE,SAAS,EAAE,CAAC;AAC1B,YAAY,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,YAAY,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAEpC,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,CAAC;AAEpC,OAAO,EACL,gBAAgB,EAChB,yBAAyB,EACzB,YAAY,EACZ,uBAAuB,EACvB,eAAe,EACf,SAAS,IAAI,kBAAkB,GAChC,CAAC"}

package/dist/esm/index.mjs

@@ -520,6 +520,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.
@@ -868,30 +900,38 @@ class FlagUpdater {
         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) {
+    handleFlagChanges(keys, type) {
+        if (this._activeContext) {
             this._changeCallbacks.forEach((callback) => {
                 try {
-                    callback(context, changed, 'init');
+                    callback(this._activeContext, keys, type);
                 }
                 catch (err) {
                     /* intentionally empty */
                 }
             });
         }
+        else {
+            this._logger.warn('Received a change event without an active context. Changes will not be propagated.');
+        }
+    }
+    init(context, newFlags) {
+        this._activeContext = context;
+        const oldFlags = this._flagStore.getAll();
+        this._flagStore.init(newFlags);
+        const changed = calculateChangedKeys(oldFlags, newFlags);
+        if (changed.length > 0) {
+            this.handleFlagChanges(changed, 'init');
+        }
     }
     initCached(context, newFlags) {
-        if (this._activeContextKey === context.canonicalKey) {
+        if (this._activeContext?.canonicalKey === context.canonicalKey) {
             return;
         }
         this.init(context, newFlags);
     }
     upsert(context, key, item) {
-        if (this._activeContextKey !== context.canonicalKey) {
+        if (this._activeContext?.canonicalKey !== context.canonicalKey) {
             this._logger.warn('Received an update for an inactive context.');
             return false;
         }
@@ -901,14 +941,7 @@ class FlagUpdater {
             return false;
         }
         this._flagStore.insertOrUpdate(key, item);
-        this._changeCallbacks.forEach((callback) => {
-            try {
-                callback(context, [key], 'patch');
-            }
-            catch (err) {
-                /* intentionally empty */
-            }
-        });
+        this.handleFlagChanges([key], 'patch');
         return true;
     }
     on(callback) {
@@ -940,11 +973,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 +1013,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 +1427,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);
@@ -1401,19 +1502,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 +1591,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;
             },
@@ -1516,6 +1617,7 @@ class LDClientImpl {
             if (res.status === 'shed') {
                 return { status: 'shed' };
             }
+            this.emitter.emit('initialized');
             return { status: 'completed' };
         });
         if (noTimeout) {
@@ -1535,7 +1637,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 +1645,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 +1696,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 +1791,9 @@ class LDClientImpl {
     sendEvent(event) {
         this._eventProcessor?.sendEvent(event);
     }
+    getDebugOverrides() {
+        return this._flagManager.getDebugOverride?.();
+    }
     _handleInspectionChanged(flagKeys, type) {
         if (!this._inspectorManager.hasInspectors()) {
             return;
@@ -1710,6 +1826,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 +2319,5 @@ class BaseDataManager {
     }
 }
 
-export { BaseDataManager, DataSourceState, LDClientImpl, Requestor, makeRequestor };
+export { BaseDataManager, DataSourceState, LDClientImpl, Requestor, makeRequestor, safeRegisterDebugOverridePlugins };
 //# sourceMappingURL=index.mjs.map