refactor!: align browser v4 intialization flow to specs

[joker23]

Requirements

• I have added test coverage for new or changed functionality
• I have followed the repository's pull request submission guidelines
• I have validated my changes against all supported platform versions

Related issues

sdk-1667

Describe the solution you've provided

• Introduced start method in BrowserClient to handle client initialization.
• Replaced direct calls to identify with setInitialContext and start for better context management.
• Updated example app to reflect changes in client initialization and context handling.
• Added tests to ensure proper functionality of new initialization flow.

Additional context

• The main motiviation behind this change is to present a more organized front on when a client is starting.
• I'll be making a task to push this behavior down to the shared client code as an optional start and start adding a deprecated message on the old flow.

---

Note

Adds an explicit client start() flow and new createClient API (with required initial context), updates initialization/identify behavior, and refreshes tests, examples, and compat layer accordingly.

• API/Initialization:
  • Add LDClient.start(options?) returning LDWaitForInitializationResult; cache promise; support bootstrap via start/identifyOptions.
  • Replace initialize(...) with createClient(clientSideId, context, options); makeClient now requires an initial LDContext.
  • Disallow identify before start (returns { status: 'error' } and logs); initial identify is non-sheddable.
  • Normalize init statuses: waitForInitialization returns { status: 'complete' | 'failed' | 'timeout' } (note: some tests updated from error→failed).
  • Make LDWaitForInitializationOptions.timeout optional; add LDStartOptions.
• BrowserClient:
  • Track _initialContext, _startPromise, _initializedPromise; preset flags from bootstrap before identify.
  • Update plugin registration/hook calls to run through new flow; continue goal tracking logic, URL transformation for events.
• Compat (/compat):
  • initialize(envKey, context, options) now builds via makeClient(envKey, context, ...); immediately start() then perform identify to mirror old behavior; re-export unchanged surface minus start/setInitialContext.
• Examples/Contract Tests:
  • Update example app and contract entity to use createClient(..., context) and client.start() + waitForInitialization().
• Tests:
  • Revise unit tests to use start() and required initial context; add cases for start idempotency, shedding order, bootstrap pre-eval, URL filtering, waitForInitialization timing/failure.

^{Written by Cursor Bugbot for commit 846ae61. This will update automatically on new commits. Configure here.}

[github-actions]

@launchdarkly/browser size report
This is the brotli compressed size of the ESM build.
Compressed size: 169118 bytes
Compressed size limit: 200000
Uncompressed size: 789399 bytes

[github-actions]

@launchdarkly/js-sdk-common size report
This is the brotli compressed size of the ESM build.
Compressed size: 25394 bytes
Compressed size limit: 26000
Uncompressed size: 124693 bytes

[github-actions]

@launchdarkly/js-client-sdk-common size report
This is the brotli compressed size of the ESM build.
Compressed size: 18527 bytes
Compressed size limit: 20000
Uncompressed size: 95226 bytes

[github-actions]

@launchdarkly/js-client-sdk size report
This is the brotli compressed size of the ESM build.
Compressed size: 23128 bytes
Compressed size limit: 25000
Uncompressed size: 80393 bytes

[cursor]

Bug: Compat layer bootstrap data now silently ignored

The removal of bootstrap handling from identifyResult breaks the compat layer's bootstrap functionality. LDClientCompatImpl._initIdentify passes bootstrap to this._client.identify(), which maps to identifyResult. However, identifyResult no longer processes the bootstrap option (that code was moved to start() only). This causes bootstrap data passed through the compat API to be silently ignored, breaking backwards compatibility for compat layer users who rely on bootstrap.

packages/sdk/browser/src/BrowserClient.ts#L274-L285

js-core/packages/sdk/browser/src/BrowserClient.ts

Lines 274 to 285 in b00509f

	const res = await super.identifyResult(context, identifyOptionsWithUpdatedDefaults);
	if (res.status === 'completed') {
	this._initializeResult = { status: 'complete' };
	this._initResolve?.(this._initializeResult);
	} else if (res.status === 'error') {
	this._initializeResult = { status: 'failed', error: res.error };
	this._initResolve?.(this._initializeResult);
	}
	this._goalManager?.startTracking();
	return res;

 

---

[kinyoklion]

So, bootstrap would be in start instead of in the options.

[joker23]

So I wasn't sure if bootstrap data is something users will typically tie with their context? If not then 100% should be in start function.

[joker23]

Added the bootstrap option in start, I kept the additional bootstrap option in case it is more natural for users to tie a certain set of identify options to a context

[cursor]

Bug: Compat layer calls identify before start, breaking initialization

The compat layer's _initIdentify method calls this._client.identify() directly without calling start() first. However, the new identifyResult implementation now requires _startPromise to be set before identify can be called, otherwise it returns { status: 'error', error: new Error('Identify called before start') }. Since the compat layer never calls start(), all initialization attempts through the compat layer will fail immediately. The unit tests don't catch this because they mock identify to return success without exercising the real BrowserClient code. The compat layer needs to call start() with the bootstrap/hash options instead of calling identify() directly.

packages/sdk/browser/src/compat/LDClientCompatImpl.ts#L47-L62

js-core/packages/sdk/browser/src/compat/LDClientCompatImpl.ts

Lines 47 to 62 in 437b864

	this.logger = this._client.logger;
	this._initIdentify(context, bootstrap, hash);
	}
	private async _initIdentify(
	context: LDContext,
	bootstrap?: LDFlagSet,
	hash?: string,
	): Promise<void> {
	try {
	const result = await this._client.identify(context, {
	noTimeout: true,
	bootstrap,
	hash,
	sheddable: false,
	});

packages/sdk/browser/src/BrowserClient.ts#L233-L239

js-core/packages/sdk/browser/src/BrowserClient.ts

Lines 233 to 239 in 437b864

	): 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') };
	}

 

---

[cursor]

Bug: Compat layer fails because identify requires start first

The compat layer's _initIdentify method calls this._client.identify() without first calling start(). However, the new identifyResult implementation in BrowserClient now checks if _startPromise is set and returns an error status if not. Since the compat layer never calls start(), every initialization via the compat path will fail with "Identify called before start" error. The compat layer needs to call start() instead of identify() for its initial identification, or the identifyResult check needs to allow calls from the compat path.

packages/sdk/browser/src/compat/LDClientCompatImpl.ts#L56-L62

js-core/packages/sdk/browser/src/compat/LDClientCompatImpl.ts

Lines 56 to 62 in ad18342

	try {
	const result = await this._client.identify(context, {
	noTimeout: true,
	bootstrap,
	hash,
	sheddable: false,
	});

packages/sdk/browser/src/BrowserClient.ts#L233-L238

js-core/packages/sdk/browser/src/BrowserClient.ts

Lines 233 to 238 in ad18342

	): 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') };

 

---

[cursor]

Bug: Missing sheddable:false allows initial identify to be discarded

The compat layer's initial identify no longer passes sheddable: false. The old code explicitly set sheddable: false when calling identify(), but the new start() call doesn't include it. Since identifyResult() defaults sheddable to true when undefined, the initial identify can now be discarded if a user immediately calls identify() on the returned client. The comment on line 69 even states 'shed' cannot happen with sheddable: false, but this invariant no longer holds.

 

[cursor]

Bug: Compat layer triggers duplicate non-sheddable identify operations

The compat layer calls start() on line 51, which internally calls identifyResult with sheddable: false for the initial context. Then it immediately calls _initIdentify() on line 52, which calls identify() also with sheddable: false for the same context. Since both operations are non-sheddable, neither can be discarded, resulting in two full network requests to LaunchDarkly for the same context. This is a regression from the previous SDK behavior where only one identify operation occurred.

Additional Locations (1)

• packages/sdk/browser/src/BrowserClient.ts#L310-L311