feat: allow clients to evaluate bootstrapped flags when not ready (#1036)

**Related issues**

sdk-1653
sdk-1376
sdk-1663
sdk-1681

**Describe the solution you've provided**
- Introduced `ActiveContextTracker` to manage the current active context
and its serialized state.
- Updated `LDClientImpl` to utilize the new context tracker for
identifying and evaluating flags.
- Added logic in `BrowserClientImpl` to read flags from bootstrap data
during the initial identification process.
- Added a new `presetFlags` function in client sdk common that allow
flagstore to take in contexless data before initialization
- Bootstrapped data will first `preset` the flag store so they can be
evaluated before a full context is made
- Added logic to suppress event creation if context is not validated
(while the client only has preset data)

**Additional context**
- eventually I would like to consolidate the context tracker with the
tracking logic we have for waitForInitialization and have a general
state tracker for client sdk common.
- I am also open to suggestions on distinguishing between "no context"
state and "pre initialized" state. Though, it seems like, at the moment,
those 2 states are handled in the same way.

Supersedes #1024

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Enable flag evaluation from bootstrap data before identify completes
and refactor context handling via ActiveContextTracker with event
suppression when no valid context.
> 
> - **Browser SDK**:
> - Read bootstrap data in `BrowserClient.identifyResult` and `preset`
flags for immediate evaluation; track first-identify via
`_identifyAttempted`.
> - Add test verifying flags evaluate from bootstrap before identify
completes in `packages/sdk/browser/__tests__/BrowserClient.test.ts`.
> - **Core SDK (shared)**:
> - Introduce `ActiveContextTracker`
(`src/context/createActiveContextTracker.ts`) and update `LDClientImpl`
to use it for getting/setting context and coordinating identify
promises.
> - Allow evaluations without an active context (log warning) and
suppress event creation when context is absent; add `presetFlags` to
`LDClientImpl`.
> - **Flag management**:
> - Add `presetFlags` to `FlagManager`/`DefaultFlagManager` to
initialize in-memory flags without persistence.
> - Update `FlagUpdater` to track active `Context` (not just key) and
adjust `init/initCached/upsert` and change callbacks accordingly.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
b7b4bf8. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: joker23

packages/sdk/browser/__tests__/BrowserClient.test.ts

@@ -189,6 +189,43 @@ describe('given a mock platform for a BrowserClient', () => {
     });
   });
 
+  it('can evaluate flags with bootstrap data before identify completes', async () => {
+    const client = makeClient(
+      'client-side-id',
+      AutoEnvAttributes.Disabled,
+      {
+        streaming: false,
+        logger,
+        diagnosticOptOut: true,
+      },
+      platform,
+    );
+
+    const identifyPromise = client.identify(
+      { kind: 'user', key: 'bob' },
+      {
+        bootstrap: goodBootstrapDataWithReasons,
+      },
+    );
+
+    const flagValue = client.jsonVariationDetail('json', undefined);
+    expect(flagValue).toEqual({
+      reason: {
+        kind: 'OFF',
+      },
+      value: ['a', 'b', 'c', 'd'],
+      variationIndex: 1,
+    });
+
+    expect(client.getContext()).toBeUndefined();
+
+    // Wait for identify to complete
+    await identifyPromise;
+
+    // Verify that active context is now set
+    expect(client.getContext()).toEqual({ kind: 'user', key: 'bob' });
+  });
+
   it('can shed intermediate identify calls', async () => {
     const client = makeClient(
       'client-side-id',

packages/sdk/browser/src/BrowserClient.ts

@@ -19,6 +19,7 @@ import {
   Platform,
 } from '@launchdarkly/js-client-sdk-common';
 
+import { readFlagsFromBootstrap } from './bootstrap';
 import { getHref } from './BrowserApi';
 import BrowserDataManager from './BrowserDataManager';
 import { BrowserIdentifyOptions as LDIdentifyOptions } from './BrowserIdentifyOptions';
@@ -44,6 +45,10 @@ class BrowserClientImpl extends LDClientImpl {
   private _initResolve?: (result: LDWaitForInitializationResult) => void;
   private _initializeResult?: LDWaitForInitializationResult;
 
+  // NOTE: keeps track of when we tried an initial identification. We should consolidate this
+  // with the waitForInitialization logic in the future.
+  private _identifyAttempted: boolean = false;
+
   constructor(
     clientSideId: string,
     autoEnvAttributes: AutoEnvAttributes,
@@ -222,6 +227,22 @@ class BrowserClientImpl extends LDClientImpl {
     if (identifyOptions?.sheddable === undefined) {
       identifyOptionsWithUpdatedDefaults.sheddable = true;
     }
+
+    if (!this._identifyAttempted) {
+      this._identifyAttempted = true;
+      if (identifyOptionsWithUpdatedDefaults.bootstrap) {
+        try {
+          const bootstrapData = readFlagsFromBootstrap(
+            this.logger,
+            identifyOptionsWithUpdatedDefaults.bootstrap,
+          );
+          this.presetFlags(bootstrapData);
+        } catch (error) {
+          this.logger.error('Failed to bootstrap data', error);
+        }
+      }
+    }
+
     const res = await super.identifyResult(context, identifyOptionsWithUpdatedDefaults);
     if (res.status === 'completed') {
       this._initializeResult = { status: 'complete' };

packages/shared/sdk-client/package.json

@@ -37,7 +37,7 @@
     "build": "npx tsc --noEmit && rollup -c rollup.config.js && npm run make-package-jsons",
     "clean": "rimraf dist",
     "lint": "npx eslint . --ext .ts",
-    "lint:fix": "yarn run lint -- --fix",
+    "lint:fix": "npx eslint . --ext .ts --fix",
     "prettier": "prettier --write 'src/*.@(js|ts|tsx|json)'",
     "check": "yarn && yarn prettier && yarn lint && tsc && yarn test"
   },

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

@@ -32,6 +32,10 @@ import { LDIdentifyOptions } from './api/LDIdentifyOptions';
 import { createAsyncTaskQueue } from './async/AsyncTaskQueue';
 import { Configuration, ConfigurationImpl, LDClientInternalOptions } from './configuration';
 import { addAutoEnv } from './context/addAutoEnv';
+import {
+  ActiveContextTracker,
+  createActiveContextTracker,
+} from './context/createActiveContextTracker';
 import { ensureKey } from './context/ensureKey';
 import { DataManager, DataManagerFactory } from './DataManager';
 import createDiagnosticsManager from './diagnostics/createDiagnosticsManager';
@@ -43,6 +47,7 @@ import createEventProcessor from './events/createEventProcessor';
 import EventFactory from './events/EventFactory';
 import DefaultFlagManager, { FlagManager } from './flag-manager/FlagManager';
 import { FlagChangeType } from './flag-manager/FlagUpdater';
+import { ItemDescriptor } from './flag-manager/ItemDescriptor';
 import HookRunner from './HookRunner';
 import { getInspectorHook } from './inspection/getInspectorHook';
 import InspectorManager from './inspection/InspectorManager';
@@ -55,12 +60,12 @@ const DEFAULT_IDENTIFY_TIMEOUT_SECONDS = 5;
 
 export default class LDClientImpl implements LDClient, LDClientIdentifyResult {
   private readonly _config: Configuration;
-  private _uncheckedContext?: LDContext;
-  private _checkedContext?: Context;
   private readonly _diagnosticsManager?: internal.DiagnosticsManager;
   private _eventProcessor?: internal.EventProcessor;
   readonly logger: LDLogger;
 
+  private _activeContextTracker: ActiveContextTracker = createActiveContextTracker();
+
   private readonly _highTimeoutThreshold: number = 15;
 
   private _eventFactoryDefault = new EventFactory(false);
@@ -200,27 +205,22 @@ export default class LDClientImpl implements LDClient, LDClientIdentifyResult {
     // 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<LDContext>(this._uncheckedContext) : undefined;
+    return this._activeContextTracker.hasContext()
+      ? clone<LDContext>(this._activeContextTracker.getUnwrappedContext())
+      : undefined;
   }
 
   protected getInternalContext(): Context | undefined {
-    return this._checkedContext;
+    return this._activeContextTracker.getContext();
   }
 
-  private _createIdentifyPromise(): {
-    identifyPromise: Promise<void>;
-    identifyResolve: () => void;
-    identifyReject: (err: Error) => void;
-  } {
-    let res: any;
-    let rej: any;
-
-    const basePromise = new Promise<void>((resolve, reject) => {
-      res = resolve;
-      rej = reject;
-    });
-
-    return { identifyPromise: basePromise, identifyResolve: res, identifyReject: rej };
+  /**
+   * 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.
+   */
+  protected presetFlags(newFlags: { [key: string]: ItemDescriptor }) {
+    this._flagManager.presetFlags(newFlags);
   }
 
   /**
@@ -307,15 +307,14 @@ export default class LDClientImpl implements LDClient, LDClientIdentifyResult {
               this.emitter.emit('error', context, error);
               return Promise.reject(error);
             }
-            this._uncheckedContext = context;
-            this._checkedContext = checkedContext;
+            this._activeContextTracker.set(context, checkedContext);
 
             this._eventProcessor?.sendEvent(
-              this._eventFactoryDefault.identifyEvent(this._checkedContext),
+              this._eventFactoryDefault.identifyEvent(checkedContext),
             );
             const { identifyPromise, identifyResolve, identifyReject } =
-              this._createIdentifyPromise();
-            this.logger.debug(`Identifying ${JSON.stringify(this._checkedContext)}`);
+              this._activeContextTracker.newIdentificationPromise();
+            this.logger.debug(`Identifying ${JSON.stringify(checkedContext)}`);
 
             await this.dataManager.identify(
               identifyResolve,
@@ -370,7 +369,7 @@ export default class LDClientImpl implements LDClient, LDClientIdentifyResult {
   }
 
   track(key: string, data?: any, metricValue?: number): void {
-    if (!this._checkedContext || !this._checkedContext.valid) {
+    if (!this._activeContextTracker.hasValidContext()) {
       this.logger.warn(ClientMessages.MissingContextKeyNoEvent);
       return;
     }
@@ -382,14 +381,19 @@ export default class LDClientImpl implements LDClient, LDClientIdentifyResult {
 
     this._eventProcessor?.sendEvent(
       this._config.trackEventModifier(
-        this._eventFactoryDefault.customEvent(key, this._checkedContext!, data, metricValue),
+        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,
     });
@@ -401,23 +405,34 @@ export default class LDClientImpl implements LDClient, LDClientIdentifyResult {
     eventFactory: EventFactory,
     typeChecker?: (value: any) => [boolean, string],
   ): LDEvaluationDetail {
-    if (!this._uncheckedContext) {
-      this.logger.debug(ClientMessages.MissingContextKeyNoEvent);
-      return createErrorEvaluationDetail(ErrorKinds.UserNotSpecified, defaultValue);
+    // 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 = Context.fromLDContext(this._uncheckedContext);
+    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);
     }
 
@@ -426,20 +441,22 @@ export default class LDClientImpl implements LDClient, LDClientIdentifyResult {
     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);
       }
     }
@@ -453,31 +470,36 @@ export default class LDClientImpl implements LDClient, LDClientIdentifyResult {
     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: string, defaultValue?: LDFlagValue): LDFlagValue {
     const { value } = this._hookRunner.withEvaluation(
       flagKey,
-      this._uncheckedContext,
+      this._activeContextTracker.getUnwrappedContext(),
       defaultValue,
       () => this._variationInternal(flagKey, defaultValue, this._eventFactoryDefault),
     );
     return value;
   }
   variationDetail(flagKey: string, defaultValue?: LDFlagValue): LDEvaluationDetail {
-    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),
     );
   }
 
@@ -487,8 +509,11 @@ export default class LDClientImpl implements LDClient, LDClientIdentifyResult {
     eventFactory: EventFactory,
     typeChecker: (value: unknown) => [boolean, string],
   ): LDEvaluationDetailTyped<T> {
-    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),
     );
   }