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

package/dist/cjs/index.cjs

@@ -538,6 +538,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 } = jsSdkCommon.internal;
 /**
  * This is the root ensureKey function. All other ensureKey functions reduce to this.
@@ -886,30 +918,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;
         }
@@ -919,14 +959,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) {
@@ -958,11 +991,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.
@@ -983,6 +1031,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';
@@ -1345,6 +1445,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);
@@ -1419,19 +1520,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 ? jsSdkCommon.clone(this._uncheckedContext) : undefined;
+        return this._activeContextTracker.hasContext()
+            ? jsSdkCommon.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}.
@@ -1507,11 +1609,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;
             },
@@ -1534,6 +1635,7 @@ class LDClientImpl {
             if (res.status === 'shed') {
                 return { status: 'shed' };
             }
+            this.emitter.emit('initialized');
             return { status: 'completed' };
         });
         if (noTimeout) {
@@ -1553,7 +1655,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;
         }
@@ -1561,37 +1663,46 @@ class LDClientImpl {
         if (metricValue !== undefined && !jsSdkCommon.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 = jsSdkCommon.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 jsSdkCommon.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 jsSdkCommon.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);
             }
         }
@@ -1603,18 +1714,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) => [
@@ -1696,6 +1809,9 @@ class LDClientImpl {
     sendEvent(event) {
         this._eventProcessor?.sendEvent(event);
     }
+    getDebugOverrides() {
+        return this._flagManager.getDebugOverride?.();
+    }
     _handleInspectionChanged(flagKeys, type) {
         if (!this._inspectorManager.hasInspectors()) {
             return;
@@ -1728,6 +1844,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 ${jsSdkCommon.internal.safeGetName(logger, plugin)}.`);
+        }
+    });
+}
+
 class DataSourceEventHandler {
     constructor(_flagManager, _statusManager, _logger) {
         this._flagManager = _flagManager;
@@ -2208,6 +2342,7 @@ exports.BaseDataManager = BaseDataManager;
 exports.LDClientImpl = LDClientImpl;
 exports.Requestor = Requestor;
 exports.makeRequestor = makeRequestor;
+exports.safeRegisterDebugOverridePlugins = safeRegisterDebugOverridePlugins;
 Object.keys(jsSdkCommon).forEach(function (k) {
     if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
         enumerable: true,