refactor: simplify getting initializationState (#1202)

This PR will align our initialization status handling closer to the base
browser sdk by:
- combining `initializing` and `unknown` state which should get rid of
one extra state dispatch on initialization
- adding additional idempotent guards to the start function. Note that
these are redundant protections.

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

---

<a href="https://app.devin.ai/review/launchdarkly/js-core/pull/1202"
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 -->


<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes the public initialization state semantics (removing
`'unknown'` and defaulting to `'initializing'`), plus alters
server-side/noop client error reporting, which may affect app gating
logic and tests.
> 
> **Overview**
> **Unifies initialization state handling** by removing the initial
`'unknown'` state in favor of starting at `'initializing'`, updating
types so `InitializedState` is derived from a new `InitializationStatus`
union.
> 
> **Tightens `start()`/context notification behavior**: `start()` now
has explicit idempotency guards and triggers `onContextChange` exactly
once after the first successful `start()` resolution; shared
context-subscriber notification logic is reused for `identify()`.
> 
> **Updates server-side/noop client behavior and docs/tests**: the noop
client now reports `getInitializationState()` as `'failed'` and returns
a concrete error from `getInitializationError()`, with corresponding
test and migration guide updates (including removing `'unknown'` from
documented `useInitializationStatus` states).
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
bac433e. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: devin-ai-integration[bot] <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: joker23

packages/sdk/react/__tests__/client/LDReactClient.test.ts

@@ -76,37 +76,63 @@ jest.mock('@launchdarkly/js-client-sdk', () => {
   };
 });
 
-it('returns getInitializationState() === "unknown" initially', () => {
+it('returns getInitializationState() === "initializing" initially', () => {
   const { mock } = makeMockBaseClient();
   (createBaseClient as jest.Mock).mockReturnValue(mock);
 
   const client = createClient('test-id', { kind: 'user', key: 'u1' });
-  expect(client.getInitializationState()).toBe('unknown');
+  expect(client.getInitializationState()).toBe('initializing');
 });
 
-it('returns "initializing" while start() is in-flight', async () => {
+it('sets initializedState to "complete" after start() resolves', async () => {
   const { mock, resolveStart } = makeMockBaseClient();
   (createBaseClient as jest.Mock).mockReturnValue(mock);
 
   const client = createClient('test-id', { kind: 'user', key: 'u1' });
   const startPromise = client.start();
-  expect(client.getInitializationState()).toBe('initializing');
-
   resolveStart('complete');
   await startPromise;
+
   expect(client.getInitializationState()).toBe('complete');
 });
 
-it('sets initializedState to "complete" after start() resolves', async () => {
-  const { mock, resolveStart } = makeMockBaseClient();
+it('start() fires onContextChange subscribers with the new context', async () => {
+  const ctx: LDContextStrict = { kind: 'user', key: 'u1' };
+  const { mock, resolveStart, setContext } = makeMockBaseClient();
   (createBaseClient as jest.Mock).mockReturnValue(mock);
 
   const client = createClient('test-id', { kind: 'user', key: 'u1' });
+  const received: LDContextStrict[] = [];
+  client.onContextChange((c) => received.push(c));
+
   const startPromise = client.start();
+  setContext(ctx);
   resolveStart('complete');
   await startPromise;
 
-  expect(client.getInitializationState()).toBe('complete');
+  expect(received).toHaveLength(1);
+  expect(received[0]).toEqual(ctx);
+});
+
+it('start() only notifies context subscribers once even if called multiple times', async () => {
+  const ctx: LDContextStrict = { kind: 'user', key: 'u1' };
+  const { mock, resolveStart, setContext } = makeMockBaseClient();
+  (createBaseClient as jest.Mock).mockReturnValue(mock);
+
+  const client = createClient('test-id', { kind: 'user', key: 'u1' });
+  const received: LDContextStrict[] = [];
+  client.onContextChange((c) => received.push(c));
+
+  setContext(ctx);
+  const startPromise1 = client.start();
+  resolveStart('complete');
+  await startPromise1;
+
+  // Second call should not notify again
+  const startPromise2 = client.start();
+  await startPromise2;
+
+  expect(received).toHaveLength(1);
 });
 
 it('invokes onContextChange callback after identify() resolves with the new context', async () => {
@@ -296,13 +322,15 @@ it('getInitializationError() returns the error after a failed start()', async ()
   expect(client.getInitializationError()).toBe(failError);
 });
 
-it('noop client getInitializationError() returns undefined', () => {
+it('noop client getInitializationError() returns an error', () => {
   const originalWindow = global.window;
   // @ts-ignore
   delete global.window;
 
   const client = createClient('test-id', { kind: 'user', key: 'u1' });
-  expect(client.getInitializationError()).toBeUndefined();
+  expect(client.getInitializationError()).toEqual(
+    new Error('Server-side client cannot be used to evaluate flags'),
+  );
 
   // @ts-ignore
   global.window = originalWindow;

packages/sdk/react/__tests__/client/deprecated-hooks/renderHelpers.tsx

@@ -10,7 +10,7 @@ export function makeWrapper(
 ) {
   const contextValue: LDReactClientContextValue = {
     client: mockClient,
-    initializedState: 'unknown',
+    initializedState: 'initializing',
     ...contextOverrides,
   };
 

packages/sdk/react/__tests__/client/hooks/useInitializationStatus.test.tsx

@@ -4,11 +4,12 @@
 import { render } from '@testing-library/react';
 import React from 'react';
 
+import { useInitializationStatus } from '../../../src/client/hooks/useInitializationStatus';
 import {
   InitializationStatus,
-  useInitializationStatus,
-} from '../../../src/client/hooks/useInitializationStatus';
-import { InitializedState, LDReactClientContextValue } from '../../../src/client/LDClient';
+  InitializedState,
+  LDReactClientContextValue,
+} from '../../../src/client/LDClient';
 import { LDReactContext } from '../../../src/client/provider/LDReactContext';
 import { makeMockClient } from '../mockClient';
 
@@ -23,18 +24,6 @@ function StatusConsumer({ onStatus }: { onStatus: (s: InitializationStatus) => v
   return null;
 }
 
-it('returns { status: "unknown" } when initializedState is "unknown"', () => {
-  const captured: InitializationStatus[] = [];
-
-  render(
-    <LDReactContext.Provider value={makeContextValue('unknown')}>
-      <StatusConsumer onStatus={(s) => captured.push(s)} />
-    </LDReactContext.Provider>,
-  );
-
-  expect(captured[0]).toEqual({ status: 'unknown' });
-});
-
 it('returns { status: "initializing" } when initializedState is "initializing"', () => {
   const captured: InitializationStatus[] = [];
 

packages/sdk/react/__tests__/client/hooks/useLDClient.test.tsx

@@ -19,7 +19,7 @@ it('returns the client from the nearest provider context', () => {
   const mockClient = makeMockClient();
   const contextValue: LDReactClientContextValue = {
     client: mockClient,
-    initializedState: 'unknown',
+    initializedState: 'initializing',
   };
 
   let capturedClient: any;
@@ -43,7 +43,7 @@ it('returns the client from a custom react context', () => {
   const customContext = React.createContext<LDReactClientContextValue>(null as any);
   const contextValue: LDReactClientContextValue = {
     client: mockClient,
-    initializedState: 'unknown',
+    initializedState: 'initializing',
   };
 
   let capturedClient: any;

packages/sdk/react/__tests__/client/hooks/useVariation.test.tsx

@@ -20,7 +20,7 @@ function makeWrapper(
 ) {
   const contextValue: LDReactClientContextValue = {
     client: mockClient,
-    initializedState: 'unknown',
+    initializedState: 'initializing',
     ...contextOverrides,
   };
 

packages/sdk/react/__tests__/client/hooks/useVariationDetail.test.tsx

@@ -19,7 +19,7 @@ import { makeMockClient } from '../mockClient';
 function makeWrapper(mockClient: ReturnType<typeof makeMockClient>) {
   const contextValue: LDReactClientContextValue = {
     client: mockClient,
-    initializedState: 'unknown',
+    initializedState: 'initializing',
   };
 
   return function Wrapper({ children }: { children: React.ReactNode }) {

packages/sdk/react/__tests__/client/mockClient.ts

@@ -36,7 +36,7 @@ export function makeMockClient(options: MockClientOptions = {}): MockClient {
 
   const initStatusSubscribers = new Set<(result: LDWaitForInitializationResult) => void>();
   const contextChangeSubscribers = new Set<(ctx: LDContextStrict) => void>();
-  let initState: InitializedState = initialState ?? (preFailedError ? 'failed' : 'unknown');
+  let initState: InitializedState = initialState ?? (preFailedError ? 'failed' : 'initializing');
   let initError: Error | undefined = preFailedError;
   let currentContext: LDContextStrict | undefined;
   const eventHandlers = new Map<string, Set<EventHandler>>();

packages/sdk/react/__tests__/client/provider/LDReactProvider.test.tsx

@@ -80,7 +80,7 @@ it('updates initializedState and context when onInitializationStatusChange fires
     </Provider>,
   );
 
-  expect(contextValues[contextValues.length - 1]?.initializedState).toBe('unknown');
+  expect(contextValues[contextValues.length - 1]?.initializedState).toBe('initializing');
 
   await act(async () => {
     client.fireInitStatusChange('complete');

packages/sdk/react/__tests__/client/provider/multipleEnvironments.test.tsx

@@ -147,8 +147,8 @@ it('initialization state is tracked independently per context', async () => {
     </ProviderA>,
   );
 
-  expect(screen.getByTestId('status-a').textContent).toBe('unknown');
-  expect(screen.getByTestId('status-b').textContent).toBe('unknown');
+  expect(screen.getByTestId('status-a').textContent).toBe('initializing');
+  expect(screen.getByTestId('status-b').textContent).toBe('initializing');
 
   await act(async () => {
     clientA.fireInitStatusChange('complete');
@@ -157,8 +157,8 @@ it('initialization state is tracked independently per context', async () => {
   await waitFor(() => {
     expect(screen.getByTestId('status-a').textContent).toBe('complete');
   });
-  // clientB still unknown
-  expect(screen.getByTestId('status-b').textContent).toBe('unknown');
+  // clientB still initializing
+  expect(screen.getByTestId('status-b').textContent).toBe('initializing');
 
   await act(async () => {
     clientB.fireInitStatusChange('complete');

packages/sdk/react/src/client/LDClient.ts

@@ -7,10 +7,15 @@ import {
 } from '@launchdarkly/js-client-sdk';
 
 /**
- * Initialization state of the client. This type should be consistent with
- * the `status` field of the `LDWaitForInitializationResult` type.
+ * Represents the current initialization state of the LaunchDarkly client.
  */
-export type InitializedState = LDWaitForInitializationResult['status'] | 'initializing' | 'unknown';
+export type InitializationStatus = LDWaitForInitializationResult | { status: 'initializing' };
+
+/**
+ * Initialization state of the client as a string union.
+ * Derived from {@link InitializationStatus} for consistency.
+ */
+export type InitializedState = InitializationStatus['status'];
 
 /**
  * The LaunchDarkly client interface for React.