chore: addressing PR comments

Author: joker23

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

@@ -382,12 +382,12 @@ describe('given a mock platform for a BrowserClient', () => {
       platform,
     );
 
-    const waitPromise = client.waitForInitialization(10);
+    const waitPromise = client.waitForInitialization({ timeout: 10 });
     const identifyPromise = client.identify({ key: 'user-key', kind: 'user' });
 
     await Promise.all([waitPromise, identifyPromise]);
 
-    await expect(waitPromise).resolves.toBeUndefined();
+    await expect(waitPromise).resolves.toEqual({ status: 'complete' });
     await expect(identifyPromise).resolves.toEqual({ status: 'completed' });
   });
 
@@ -417,10 +417,10 @@ describe('given a mock platform for a BrowserClient', () => {
     client.identify({ key: 'user-key', kind: 'user' });
 
     // Call waitForInitialization with a short timeout (0.1 seconds)
-    const waitPromise = client.waitForInitialization(0.1);
+    const waitPromise = client.waitForInitialization({ timeout: 0.1 });
 
     // Verify that waitForInitialization rejects with a timeout error
-    await expect(waitPromise).rejects.toThrow();
+    await expect(waitPromise).resolves.toEqual({ status: 'timeout' });
 
     // Clean up: resolve the fetch to avoid hanging promises and restore fake timers
     resolveFetch!({});

packages/sdk/browser/src/BrowserClient.ts

@@ -26,16 +26,23 @@ import { BrowserIdentifyOptions as LDIdentifyOptions } from './BrowserIdentifyOp
 import { registerStateDetection } from './BrowserStateDetector';
 import GoalManager from './goals/GoalManager';
 import { Goal, isClick } from './goals/Goals';
-import { LDClient } from './LDClient';
+import {
+  LDClient,
+  LDWaitForInitializationComplete,
+  LDWaitForInitializationFailed,
+  LDWaitForInitializationOptions,
+  LDWaitForInitializationResult,
+  LDWaitForInitializationTimeout,
+} from './LDClient';
 import { LDPlugin } from './LDPlugin';
 import validateBrowserOptions, { BrowserOptions, filterToBaseOptionsWithDefaults } from './options';
 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 _initializedPromise?: Promise<LDWaitForInitializationResult>;
+  private _initResolve?: (result: LDWaitForInitializationResult) => void;
   private _isInitialized: boolean = false;
 
   constructor(
@@ -219,13 +226,17 @@ class BrowserClientImpl extends LDClientImpl {
     const res = await super.identifyResult(context, identifyOptionsWithUpdatedDefaults);
     if (res.status === 'completed') {
       this._isInitialized = true;
-      this._initResolve?.();
+      this._initResolve?.({ status: 'complete' });
     }
     this._goalManager?.startTracking();
     return res;
   }
 
-  waitForInitialization(timeout: number = 5): Promise<void> {
+  waitForInitialization(
+    options?: LDWaitForInitializationOptions,
+  ): Promise<LDWaitForInitializationResult> {
+    const timeout = options?.timeout ?? 5;
+
     // 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
@@ -238,7 +249,9 @@ class BrowserClientImpl extends LDClientImpl {
     }
 
     if (this._isInitialized) {
-      return Promise.resolve();
+      return Promise.resolve({
+        status: 'complete',
+      });
     }
 
     if (!this._initializedPromise) {
@@ -258,16 +271,25 @@ class BrowserClientImpl extends LDClientImpl {
    * @param logger A logger to log when the timeout expires.
    * @returns
    */
-  private _promiseWithTimeout(basePromise: Promise<void>, timeout: number): Promise<void> {
+  private _promiseWithTimeout(
+    basePromise: Promise<LDWaitForInitializationResult>,
+    timeout: number,
+  ): Promise<LDWaitForInitializationResult> {
     const cancelableTimeout = cancelableTimedPromise(timeout, 'waitForInitialization');
     return Promise.race([
-      basePromise.then(() => cancelableTimeout.cancel()),
-      cancelableTimeout.promise,
+      basePromise.then((res: LDWaitForInitializationResult) => {
+        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' }) as LDWaitForInitializationComplete)
+        .catch(() => ({ status: 'timeout' }) as LDWaitForInitializationTimeout),
     ]).catch((reason) => {
-      if (reason instanceof LDTimeoutError) {
-        this.logger?.error(reason.message);
-      }
-      throw reason;
+      this.logger?.error(reason.message);
+      return { status: 'failed', error: reason as Error } as LDWaitForInitializationFailed;
     });
   }
 
@@ -337,7 +359,8 @@ export function makeClient(
     close: () => impl.close(),
     allFlags: () => impl.allFlags(),
     addHook: (hook: Hook) => impl.addHook(hook),
-    waitForInitialization: (timeout: number) => impl.waitForInitialization(timeout),
+    waitForInitialization: (LDWaitForInitializationOptions) =>
+      impl.waitForInitialization(LDWaitForInitializationOptions),
     logger: impl.logger,
   };
 

packages/sdk/browser/src/LDClient.ts

@@ -6,6 +6,63 @@ import {
 
 import { BrowserIdentifyOptions as LDIdentifyOptions } from './BrowserIdentifyOptions';
 
+/**
+ * @ignore
+ * Currently these options and the waitForInitialization method signiture will mirror the one
+ * that is defined in the server common. We will be consolidating this mehod so that it will
+ * be common to all sdks in the future.
+ */
+/**
+ * Options for the waitForInitialization method.
+ */
+export interface LDWaitForInitializationOptions {
+  /**
+   * The timeout duration in seconds to wait for initialization before resolving the promise.
+   * If exceeded, the promise will resolve to a {@link LDWaitForInitializationTimeout} object.
+   *
+   * If no options are specified on the `waitForInitialization`, the default timeout of 5 seconds will be used.
+   *
+   * Using a high timeout, or no timeout, is not recommended because it could result in a long
+   * delay when conditions prevent successful initialization.
+   *
+   * A value of 0 will cause the promise to resolve without waiting. In that scenario it would be
+   * more effective to not call `waitForInitialization`.
+   *
+   * @default 5 seconds
+   */
+  timeout: number;
+}
+
+/**
+ * The waitForInitialization operation failed.
+ */
+export interface LDWaitForInitializationFailed {
+  status: 'failed';
+  error: Error;
+}
+
+/**
+ * The waitForInitialization operation timed out.
+ */
+export interface LDWaitForInitializationTimeout {
+  status: 'timeout';
+}
+
+/**
+ * The waitForInitialization operation completed successfully.
+ */
+export interface LDWaitForInitializationComplete {
+  status: 'complete';
+}
+
+/**
+ * The result of the waitForInitialization operation.
+ */
+export type LDWaitForInitializationResult =
+  | LDWaitForInitializationFailed
+  | LDWaitForInitializationTimeout
+  | LDWaitForInitializationComplete;
+
 /**
  *
  * The LaunchDarkly SDK client object.
@@ -70,38 +127,35 @@ export type LDClient = Omit<
   /**
    * 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.
+   * The Promise will be resolved to a {@link LDWaitForInitializationResult} object containing the
+   * status of the waitForInitialization operation.
    *
+   * @example
+   * This example shows use of async/await syntax for specifying handlers:
    * ```
-   *     // using async/await
-   *     try {
-   *         await client.waitForInitialization(5);
-   *         doSomethingWithSuccessfullyInitializedClient();
-   *     } catch (err) {
-   *         doSomethingForFailedStartup(err);
+   *     const result = await client.waitForInitialization({ timeout: 5 });
+   *
+   *     if (result.status === 'complete') {
+   *       doSomethingWithSuccessfullyInitializedClient();
+   *     } else if (result.status === 'failed') {
+   *       doSomethingForFailedStartup(result.error);
+   *     } else if (result.status === 'timeout') {
+   *       doSomethingForTimedOutStartup();
    *     }
    * ```
    *
-   * 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"`
+   * @remarks
+   * 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
+   * @param options
+   *  Optional configuration. Please see {@link LDWaitForInitializationOptions}.
    *
    * @returns
-   *   A Promise that will be resolved if the client initializes successfully, or rejected if it
-   *   fails or the specified timeout elapses.
+   *   A Promise that will be resolved to a {@link LDWaitForInitializationResult} object containing the
+   *   status of the waitForInitialization operation.
    */
-  waitForInitialization(timeout?: number): Promise<void>;
+  waitForInitialization(
+    options?: LDWaitForInitializationOptions,
+  ): Promise<LDWaitForInitializationResult>;
 };

packages/sdk/browser/src/compat/LDClientCompat.ts

@@ -14,7 +14,7 @@ import { LDClient as LDCLientBrowser } from '../LDClient';
  */
 export interface LDClient extends Omit<
   LDCLientBrowser,
-  'close' | 'flush' | 'identify' | 'identifyResult'
+  'close' | 'flush' | 'identify' | 'identifyResult' | 'waitForInitialization'
 > {
   /**
    * Identifies a context to LaunchDarkly.