feat: adding waitForInitialize to browser 4.x

Author: joker23

packages/sdk/browser/src/BrowserClient.ts

@@ -2,6 +2,7 @@ import {
   AutoEnvAttributes,
   base64UrlEncode,
   BasicLogger,
+  cancelableTimedPromise,
   Configuration,
   Encoding,
   FlagManager,
@@ -15,6 +16,7 @@ import {
   LDHeaders,
   LDIdentifyResult,
   LDPluginEnvironmentMetadata,
+  LDTimeoutError,
   Platform,
 } from '@launchdarkly/js-client-sdk-common';
 
@@ -32,6 +34,9 @@ import BrowserPlatform from './platform/BrowserPlatform';
 class BrowserClientImpl extends LDClientImpl {
   private readonly _goalManager?: GoalManager;
   private readonly _plugins?: LDPlugin[];
+  private _initializedPromise?: Promise<void>;
+  private _initResolve?: () => void;
+  private _isInitialized: boolean = false;
 
   constructor(
     clientSideId: string,
@@ -212,10 +217,60 @@ class BrowserClientImpl extends LDClientImpl {
       identifyOptionsWithUpdatedDefaults.sheddable = true;
     }
     const res = await super.identifyResult(context, identifyOptionsWithUpdatedDefaults);
+    if (res.status === 'completed') {
+      this._isInitialized = true;
+      this._initResolve?.();
+    }
     this._goalManager?.startTracking();
     return res;
   }
 
+  waitForInitialization(timeout: number = 5): Promise<void> {
+    // An initialization promise is only created if someone is going to use that promise.
+    // If we always created an initialization promise, and there was no call waitForInitialization
+    // by the time the promise was rejected, then that would result in an unhandled promise
+    // rejection.
+
+    // It waitForInitialization was previously called, then we can use that promise even if it has
+    // been resolved or rejected.
+    if (this._initializedPromise) {
+      return this._promiseWithTimeout(this._initializedPromise, timeout);
+    }
+
+    if (this._isInitialized) {
+      return Promise.resolve();
+    }
+
+    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.
+   * @param logger A logger to log when the timeout expires.
+   * @returns
+   */
+  private _promiseWithTimeout(basePromise: Promise<void>, timeout: number): Promise<void> {
+    const cancelableTimeout = cancelableTimedPromise(timeout, 'waitForInitialization');
+    return Promise.race([
+      basePromise.then(() => cancelableTimeout.cancel()),
+      cancelableTimeout.promise,
+    ]).catch((reason) => {
+      if (reason instanceof LDTimeoutError) {
+        this.logger?.error(reason.message);
+      }
+      throw reason;
+    });
+  }
+
   setStreaming(streaming?: boolean): void {
     // With FDv2 we may want to consider if we support connection mode directly.
     // Maybe with an extension to connection mode for 'automatic'.
@@ -282,6 +337,7 @@ export function makeClient(
     close: () => impl.close(),
     allFlags: () => impl.allFlags(),
     addHook: (hook: Hook) => impl.addHook(hook),
+    waitForInitialization: (timeout: number) => impl.waitForInitialization(timeout),
     logger: impl.logger,
   };
 

packages/sdk/browser/src/LDClient.ts

@@ -66,4 +66,42 @@ export type LDClient = Omit<
     pristineContext: LDContext,
     identifyOptions?: LDIdentifyOptions,
   ): Promise<LDIdentifyResult>;
+
+  /**
+   * Returns a Promise that tracks the client's initialization state.
+   *
+   * The Promise will be resolved if the client successfully initializes, or rejected if client
+   * initialization takes longer than the set timeout.
+   *
+   * ```
+   *     // using async/await
+   *     try {
+   *         await client.waitForInitialization(5);
+   *         doSomethingWithSuccessfullyInitializedClient();
+   *     } catch (err) {
+   *         doSomethingForFailedStartup(err);
+   *     }
+   * ```
+   *
+   * It is important that you handle the rejection case; otherwise it will become an unhandled Promise
+   * rejection, which is a serious error on some platforms. The Promise is not created unless you
+   * request it, so if you never call `waitForInitialization()` then you do not have to worry about
+   * unhandled rejections.
+   *
+   * Note that you can also use event listeners ({@link on}) for the same purpose: the event `"initialized"`
+   * indicates success, and `"error"` indicates an error.
+   *
+   * @param timeout
+   *  The amount of time, in seconds, to wait for initialization before rejecting the promise.
+   *  Using a large timeout is not recommended. If you use a large timeout and await it, then
+   *  any network delays will cause your application to wait a long time before
+   *  continuing execution.
+   *
+   *  @default 5 seconds
+   *
+   * @returns
+   *   A Promise that will be resolved if the client initializes successfully, or rejected if it
+   *   fails or the specified timeout elapses.
+   */
+  waitForInitialization(timeout?: number): Promise<void>;
 };

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

@@ -345,6 +345,7 @@ export default class LDClientImpl implements LDClient, LDClientIdentifyResult {
         if (res.status === 'shed') {
           return { status: 'shed' } as LDIdentifyShed;
         }
+        this.emitter.emit('initialized');
         return { status: 'completed' } as LDIdentifySuccess;
       });
 

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

@@ -6,7 +6,7 @@ type FlagChangeKey = `change:${string}`;
  * Type for name of emitted events. 'change' is used for all flag changes. 'change:flag-name-here' is used
  * for specific flag changes.
  */
-export type EventName = 'change' | FlagChangeKey | 'dataSourceStatus' | 'error';
+export type EventName = 'change' | FlagChangeKey | 'dataSourceStatus' | 'error' | 'initialized';
 
 /**
  * Implementation Note: There should not be any default listeners for change events in a client