feat: adding start() method to common client sdk package (#1244)

This PR will consolidate the `start()` method into the shared client sdk
package.

To do this we also:
- introduce an internal option called `requiresStart` which should be
`true` for new SDKs (and only RN has it default `false`)
- `requiresStart` is, effectively, a feature flag for whether the SDK is
using the new `create` + `start` initialization pattern
- consolidated the unit tests for the `start` method into client common
- moved `start` method out of browser and electron sdks

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Touches core initialization/identify behavior across multiple SDKs and
changes when bootstrap parsing and goal tracking occur, which could
affect startup sequencing and existing integrations if edge cases
regress.
> 
> **Overview**
> Moves the `start()` implementation (including bootstrap flag
preloading and init promise caching/timeout behavior) from the Browser
and Electron SDKs into the shared `packages/shared/sdk-client`
`LDClientImpl`.
> 
> Introduces `LDStartOptions` in the shared API and adds internal
options `requiresStart` and `initialContext` so platform SDKs can
enforce the new create+`start()` initialization pattern;
`identifyResult()` now blocks pre-`start()` calls when `requiresStart`
is enabled and updates the logged error message.
> 
> Updates Browser/Electron wrappers and tests accordingly
(Browser/Electron remove their custom `start()` logic, Browser ensures
goal tracking only starts after `start()`), and adds a consolidated
`LDClientImpl.start()` test suite in the shared package.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
5c9e61f. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/launchdarkly/js-core/pull/1244"
target="_blank">
  <picture>
<source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-open-in-devin-review-dark.svg?v=1">
<img
src="https://static.devin.ai/assets/gh-open-in-devin-review-light.svg?v=1"
alt="Open with Devin">
  </picture>
</a>
<!-- devin-review-badge-end -->

---------

Co-authored-by: Ryan Lamb <4955475+kinyoklion@users.noreply.github.com>

Author: joker23

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

@@ -246,37 +246,6 @@ describe('given a mock platform for a BrowserClient', () => {
     expect(client.getContext()).toEqual({ kind: 'user', key: 'bob' });
   });
 
-  it('parses bootstrap data only once when using start()', async () => {
-    const bootstrapModule = await import('@launchdarkly/js-client-sdk-common');
-    const readFlagsFromBootstrapSpy = jest.spyOn(bootstrapModule, 'readFlagsFromBootstrap');
-
-    const client = makeClient(
-      'client-side-id',
-      { kind: 'user', key: 'bob' },
-      AutoEnvAttributes.Disabled,
-      {
-        streaming: false,
-        logger,
-        diagnosticOptOut: true,
-      },
-      platform,
-    );
-
-    await client.start({
-      identifyOptions: {
-        bootstrap: goodBootstrapDataWithReasons,
-      },
-    });
-
-    expect(readFlagsFromBootstrapSpy).toHaveBeenCalledTimes(1);
-    expect(readFlagsFromBootstrapSpy).toHaveBeenCalledWith(
-      expect.anything(),
-      goodBootstrapDataWithReasons,
-    );
-
-    readFlagsFromBootstrapSpy.mockRestore();
-  });
-
   it('uses the latest bootstrap data when identify is called with new bootstrap data', async () => {
     const initialBootstrapData = {
       'string-flag': 'is bob',
@@ -866,7 +835,7 @@ describe('given a mock platform for a BrowserClient', () => {
 
     // Verify that the logger was called with the error message
     expect(logger.error).toHaveBeenCalledWith(
-      'Client must be started before it can identify a context, did you forget to call start()?',
+      'The client must be started before a context can be identified. Call start() prior to identifying a context.',
     );
 
     // Verify that no fetch calls were made

packages/sdk/browser/src/BrowserClient.ts

@@ -21,10 +21,8 @@ import {
   LDIdentifyResult,
   LDPluginEnvironmentMetadata,
   LDWaitForInitializationOptions,
-  LDWaitForInitializationResult,
   MODE_TABLE,
   Platform,
-  readFlagsFromBootstrap,
   resolveForegroundMode,
   safeRegisterDebugOverridePlugins,
 } from '@launchdarkly/js-client-sdk-common';
@@ -45,13 +43,9 @@ class BrowserClientImpl extends LDClientImpl {
   private readonly _goalManager?: GoalManager;
   private readonly _plugins?: LDPlugin[];
 
-  private _initialContext?: LDContext;
-
-  // NOTE: This also keeps track of when we tried to initialize the client.
-  private _startPromise?: Promise<LDWaitForInitializationResult>;
-
   constructor(
     clientSideId: string,
+    initialContext: LDContext,
     autoEnvAttributes: AutoEnvAttributes,
     options: BrowserOptions = {},
     overridePlatform?: Platform,
@@ -156,6 +150,8 @@ class BrowserClientImpl extends LDClientImpl {
       getImplementationHooks: (environmentMetadata: LDPluginEnvironmentMetadata) =>
         internal.safeGetHooks(logger, environmentMetadata, validatedBrowserOptions.plugins),
       credentialType: 'clientSideId',
+      requiresStart: true,
+      initialContext,
     });
 
     this.setEventSendingEnabled(true, false);
@@ -234,10 +230,6 @@ class BrowserClientImpl extends LDClientImpl {
     }
   }
 
-  setInitialContext(context: LDContext): void {
-    this._initialContext = context;
-  }
-
   override async identify(context: LDContext, identifyOptions?: LDIdentifyOptions): Promise<void> {
     return super.identify(context, identifyOptions);
   }
@@ -246,79 +238,18 @@ class BrowserClientImpl extends LDClientImpl {
     context: LDContext,
     identifyOptions?: LDIdentifyOptions,
   ): Promise<LDIdentifyResult> {
-    if (!this._startPromise) {
-      this.logger.error(
-        'Client must be started before it can identify a context, did you forget to call start()?',
-      );
-      return { status: 'error', error: new Error('Identify called before start') };
-    }
-
-    const identifyOptionsWithUpdatedDefaults = {
-      ...identifyOptions,
-    };
-    if (identifyOptions?.sheddable === undefined) {
-      identifyOptionsWithUpdatedDefaults.sheddable = true;
+    const options =
+      identifyOptions?.sheddable === undefined
+        ? { ...identifyOptions, sheddable: true }
+        : identifyOptions;
+    const res = await super.identifyResult(context, options);
+    // Ensure that we do not start the goal manager if start() is not called.
+    if (this.startPromise) {
+      this._goalManager?.startTracking();
     }
-
-    const res = await super.identifyResult(context, identifyOptionsWithUpdatedDefaults);
-
-    this._goalManager?.startTracking();
     return res;
   }
 
-  start(options?: LDStartOptions): Promise<LDWaitForInitializationResult> {
-    if (this.initializeResult) {
-      return Promise.resolve(this.initializeResult);
-    }
-    if (this._startPromise) {
-      return this._startPromise;
-    }
-    if (!this._initialContext) {
-      this.logger.error('Initial context not set');
-      return Promise.resolve({ status: 'failed', error: new Error('Initial context not set') });
-    }
-
-    // When we get to this point, we assume this is the first time that start is being
-    // attempted. This line should only be called once during the lifetime of the client.
-    const identifyOptions = {
-      ...(options?.identifyOptions ?? {}),
-
-      // Initial identify operations are not sheddable.
-      sheddable: false,
-    };
-
-    // If the bootstrap data is provided in the start options, and the identify options do not have bootstrap data,
-    // then use the bootstrap data from the start options.
-    if (options?.bootstrap && !identifyOptions.bootstrap) {
-      identifyOptions.bootstrap = options.bootstrap;
-    }
-
-    if (identifyOptions?.bootstrap) {
-      try {
-        if (!identifyOptions.bootstrapParsed) {
-          identifyOptions.bootstrapParsed = readFlagsFromBootstrap(
-            this.logger,
-            identifyOptions.bootstrap,
-          );
-        }
-        this.presetFlags(identifyOptions.bootstrapParsed!);
-      } catch (error) {
-        this.logger.error('Failed to bootstrap data', error);
-      }
-    }
-
-    if (!this.initializedPromise) {
-      this.initializedPromise = new Promise((resolve) => {
-        this.initResolve = resolve;
-      });
-    }
-
-    this._startPromise = this.promiseWithTimeout(this.initializedPromise!, options?.timeout ?? 5);
-
-    this.identifyResult(this._initialContext!, identifyOptions);
-    return this._startPromise;
-  }
-
   setConnectionMode(mode?: FDv2ConnectionMode): void {
     if (!this.dataManager.setConnectionMode) {
       this.logger.warn(
@@ -366,8 +297,13 @@ export function makeClient(
   options: BrowserOptions = {},
   overridePlatform?: Platform,
 ): LDClient {
-  const impl = new BrowserClientImpl(clientSideId, autoEnvAttributes, options, overridePlatform);
-  impl.setInitialContext(initialContext);
+  const impl = new BrowserClientImpl(
+    clientSideId,
+    initialContext,
+    autoEnvAttributes,
+    options,
+    overridePlatform,
+  );
 
   // Return a PIMPL style implementation. This decouples the interface from the interface of the implementation.
   // In the future we should consider updating the common SDK code to not use inheritance and instead compose

packages/sdk/browser/src/LDClient.ts

@@ -1,5 +1,6 @@
 import {
   LDClient as CommonClient,
+  LDStartOptions as CommonLDStartOptions,
   FDv2ConnectionMode,
   LDContext,
   LDIdentifyResult,
@@ -9,18 +10,11 @@ import {
 
 import { BrowserIdentifyOptions as LDIdentifyOptions } from './BrowserIdentifyOptions';
 
-export interface LDStartOptions extends LDWaitForInitializationOptions {
-  /**
-   * Optional bootstrap data to use for the identify operation. If {@link LDIdentifyOptions.bootstrap} is provided, it will be ignored.
-   */
-  bootstrap?: unknown;
-
-  /**
-   * Optional identify options to use for the identify operation. See {@link LDIdentifyOptions} for more information.
-   *
-   * @remarks
-   * Since the first identify option should never be sheddable, we omit the sheddable option from the interface to avoid confusion.
-   */
+/**
+ * Browser-specific start options that extend the common start options
+ * with browser-specific identify options (see {@link LDIdentifyOptions}).
+ */
+export interface LDStartOptions extends CommonLDStartOptions {
   identifyOptions?: Omit<LDIdentifyOptions, 'sheddable'>;
 }
 

packages/sdk/electron/__tests__/ElectronClient.test.ts

@@ -766,10 +766,7 @@ it('can use bootstrap data with identify', async () => {
   expect(mockedCreateEventSource).toHaveBeenCalled();
 });
 
-it('parses bootstrap data only once when identify is called with bootstrap', async () => {
-  const commonModule = await import('@launchdarkly/js-client-sdk-common');
-  const readFlagsFromBootstrapSpy = jest.spyOn(commonModule, 'readFlagsFromBootstrap');
-
+it('parses bootstrap data when start is called with bootstrap', async () => {
   (ElectronPlatform as jest.Mock).mockReturnValue({
     crypto: new ElectronCrypto(),
     info: new ElectronInfo(),
@@ -796,7 +793,8 @@ it('parses bootstrap data only once when identify is called with bootstrap', asy
 
   await client.start({ bootstrap: goodBootstrapData });
 
-  expect(readFlagsFromBootstrapSpy).toHaveBeenCalledTimes(1);
-  expect(readFlagsFromBootstrapSpy).toHaveBeenCalledWith(expect.anything(), goodBootstrapData);
-  readFlagsFromBootstrapSpy.mockRestore();
+  // Verify that bootstrap data was parsed and flags are available.
+  expect(client.allFlags().killswitch).toBe(true);
+  expect(client.allFlags()['string-flag']).toBe('is bob');
+  expect(client.allFlags().cat).toBe(false);
 });

packages/sdk/electron/src/ElectronClient.ts

@@ -23,7 +23,6 @@ import {
   LDWaitForInitializationOptions,
   LDWaitForInitializationResult,
   mobileFdv1Endpoints,
-  readFlagsFromBootstrap,
 } from '@launchdarkly/js-client-sdk-common';
 
 import ElectronDataManager from './ElectronDataManager';
@@ -43,10 +42,6 @@ import ElectronPlatform from './platform/ElectronPlatform';
 const VALID_LOG_LEVELS: ReadonlySet<string> = new Set(['error', 'warn', 'info', 'debug']);
 
 export class ElectronClient extends LDClientImpl {
-  private readonly _initialContext: LDContext;
-
-  private _startPromise?: Promise<LDWaitForInitializationResult>;
-
   private readonly _plugins: LDPlugin[];
 
   private _ipcNamespace?: string;
@@ -93,6 +88,8 @@ export class ElectronClient extends LDClientImpl {
       getImplementationHooks: (_environmentMetadata: LDPluginEnvironmentMetadata) =>
         internal.safeGetHooks(logger, _environmentMetadata, validatedElectronOptions.plugins),
       credentialType: useClientSideId ? 'clientSideId' : 'mobileKey',
+      requiresStart: true,
+      initialContext,
     };
 
     const platform = new ElectronPlatform(logger, options);
@@ -125,7 +122,6 @@ export class ElectronClient extends LDClientImpl {
       internalOptions,
     );
 
-    this._initialContext = initialContext;
     this._plugins = validatedElectronOptions.plugins;
     this.setEventSendingEnabled(!this.isOffline(), false);
 
@@ -142,76 +138,15 @@ export class ElectronClient extends LDClientImpl {
     internal.safeRegisterPlugins(this.logger, this.environmentMetadata, client, this._plugins);
   }
 
-  start(options?: LDStartOptions): Promise<LDWaitForInitializationResult> {
-    if (this.initializeResult !== undefined) {
-      return Promise.resolve(this.initializeResult);
-    }
-    if (this._startPromise) {
-      return this._startPromise;
-    }
-    if (!this._initialContext) {
-      this.logger.error('Initial context not set');
-      return Promise.resolve({ status: 'failed', error: new Error('Initial context not set') });
-    }
-
-    const identifyOptions: LDIdentifyOptions = {
-      ...(options?.identifyOptions ?? {}),
-      sheddable: false,
-    };
-
-    if (
-      options?.bootstrap !== undefined &&
-      options?.bootstrap !== null &&
-      !identifyOptions.bootstrap
-    ) {
-      identifyOptions.bootstrap = options.bootstrap;
-    }
-
-    if (identifyOptions.bootstrap) {
-      try {
-        if (!identifyOptions.bootstrapParsed) {
-          identifyOptions.bootstrapParsed = readFlagsFromBootstrap(
-            this.logger,
-            identifyOptions.bootstrap,
-          );
-        }
-        this.presetFlags(identifyOptions.bootstrapParsed!);
-      } catch (error) {
-        this.logger.error('Failed to bootstrap data', error);
-      }
-    }
-
-    if (!this.initializedPromise) {
-      this.initializedPromise = new Promise((resolve) => {
-        this.initResolve = resolve;
-      });
-    }
-
-    this._startPromise = this.promiseWithTimeout(this.initializedPromise!, options?.timeout ?? 5);
-
-    this.identifyResult(this._initialContext, identifyOptions);
-    return this._startPromise;
-  }
-
   override async identifyResult(
-    pristineContext: LDContext,
+    context: LDContext,
     identifyOptions?: LDIdentifyOptions,
   ): Promise<LDIdentifyResult> {
-    if (!this._startPromise) {
-      this.logger.error(
-        'Client must be started before it can identify a context, did you forget to call start()?',
-      );
-      return { status: 'error', error: new Error('Identify called before start') };
-    }
-
-    const identifyOptionsWithUpdatedDefaults = {
-      ...identifyOptions,
-    };
-    if (identifyOptions?.sheddable === undefined) {
-      identifyOptionsWithUpdatedDefaults.sheddable = true;
-    }
-
-    return super.identifyResult(pristineContext, identifyOptionsWithUpdatedDefaults);
+    const options =
+      identifyOptions?.sheddable === undefined
+        ? { ...identifyOptions, sheddable: true }
+        : identifyOptions;
+    return super.identifyResult(context, options);
   }
 
   async setConnectionMode(mode: ConnectionMode): Promise<void> {

packages/sdk/electron/src/LDClient.ts

@@ -4,23 +4,11 @@ import type {
   LDContext,
   LDIdentifyOptions,
   LDIdentifyResult,
-  LDWaitForInitializationOptions,
+  LDStartOptions,
   LDWaitForInitializationResult,
 } from '@launchdarkly/js-client-sdk-common';
 
-export interface LDStartOptions extends LDWaitForInitializationOptions {
-  /**
-   * Optional bootstrap data to use for the identify operation. If
-   * {@link LDIdentifyOptions.bootstrap} is provided in identifyOptions, it takes precedence.
-   */
-  bootstrap?: unknown;
-
-  /**
-   * Optional identify options to use for the first identify. Since the first identify is not
-   * sheddable, the sheddable option is omitted from this type.
-   */
-  identifyOptions?: Omit<LDIdentifyOptions, 'sheddable'>;
-}
+export type { LDStartOptions };
 
 export interface LDClient extends Omit<LDClientBase, 'identify'> {
   /**