feat: common identify now reports identify status

packages/sdk/browser/src/BrowserClient.ts

@@ -230,19 +230,15 @@ class BrowserClientImpl extends LDClientImpl {
     }
   }
 
-  override async identify(context: LDContext, identifyOptions?: LDIdentifyOptions): Promise<void> {
-    return super.identify(context, identifyOptions);
-  }
-
-  override async identifyResult(
+  override async identify(
     context: LDContext,
     identifyOptions?: LDIdentifyOptions,
   ): Promise<LDIdentifyResult> {
     const options =
       identifyOptions?.sheddable === undefined
         ? { ...identifyOptions, sheddable: true }
         : identifyOptions;
-    const res = await super.identifyResult(context, options);
+    const res = await super.identify(context, options);
     // Ensure that we do not start the goal manager if start() is not called.
     if (this.startPromise) {
       this._goalManager?.startTracking();
@@ -308,7 +304,6 @@ export function makeClient(
   // 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
   // the leaf-implementation.
-  // The purpose for this in the short-term is to have a signature for identify that is different than the class implementation.
   // Using an object with PIMPL here also allows us to completely hide the underlying implementation, where with a class
   // it is trivial to access what should be protected (or even private) fields.
   const client: LDClient = {
@@ -334,7 +329,7 @@ export function makeClient(
     setConnectionMode: (mode?: FDv2ConnectionMode) => impl.setConnectionMode(mode),
     setStreaming: (streaming?: boolean) => impl.setStreaming(streaming),
     identify: (pristineContext: LDContext, identifyOptions?: LDIdentifyOptions) =>
-      impl.identifyResult(pristineContext, identifyOptions),
+      impl.identify(pristineContext, identifyOptions),
     getContext: () => impl.getContext(),
     close: () => impl.close(),
     allFlags: () => impl.allFlags(),

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

@@ -152,7 +152,7 @@ describe('given an initialized ElectronClient', () => {
     const context: LDContext = { kind: 'user', key: 'test-user-id' };
     const options: LDIdentifyOptions = { waitForNetworkResults: true };
 
-    const spy = jest.spyOn(client, 'identifyResult');
+    const spy = jest.spyOn(client, 'identify');
     spy.mockResolvedValueOnce({ status: 'completed' });
 
     const result = await mockIpcMain.getHandler(getEventName('identify'))?.({}, context, options);

packages/sdk/electron/src/ElectronClient.ts

@@ -140,15 +140,15 @@ export class ElectronClient extends LDClientImpl {
     internal.safeRegisterPlugins(this.logger, this.environmentMetadata, client, this._plugins);
   }
 
-  override async identifyResult(
+  override async identify(
     context: LDContext,
     identifyOptions?: LDIdentifyOptions,
   ): Promise<LDIdentifyResult> {
     const options =
       identifyOptions?.sheddable === undefined
         ? { ...identifyOptions, sheddable: true }
         : identifyOptions;
-    return super.identifyResult(context, options);
+    return super.identify(context, options);
   }
 
   async setConnectionMode(mode: ConnectionMode): Promise<void> {
@@ -223,7 +223,7 @@ export class ElectronClient extends LDClientImpl {
     });
 
     ipcMain.handle(getIPCChannelName(namespace, 'identify'), (_event, context, identifyOptions) =>
-      this.identifyResult(context, identifyOptions),
+      this.identify(context, identifyOptions),
     );
 
     ipcMain.on(getIPCChannelName(namespace, 'log'), (_event, level: string, message: string) => {
@@ -434,7 +434,7 @@ export function makeClient(
       impl.off(key as LDEmitterEventName, callback as (...args: unknown[]) => void),
     flush: () => impl.flush(),
     identify: (ctx: LDContext, identifyOptions?: LDIdentifyOptions) =>
-      impl.identifyResult(ctx, identifyOptions),
+      impl.identify(ctx, identifyOptions),
     getContext: () => impl.getContext(),
     close: () => impl.close(),
     allFlags: () => impl.allFlags(),

packages/sdk/react-native/src/LDClient.ts

@@ -0,0 +1,38 @@
+import {
+  LDClient as CommonClient,
+  LDContext,
+  LDIdentifyOptions,
+} from '@launchdarkly/js-client-sdk-common';
+
+/**
+ * React Native LDClient type. Overrides `identify()` to return `Promise<void>` and throw on
+ * error/timeout to maintain backward compatibility with existing React Native consumers.
+ */
+export type LDClient = Omit<CommonClient, 'identify'> & {
+  /**
+   * Identifies a context to LaunchDarkly.
+   *
+   * Unlike the server-side SDKs, the client-side JavaScript SDKs maintain a current context state,
+   * which is set when you call `identify()`.
+   *
+   * Changing the current context also causes all feature flag values to be reloaded. Until that has
+   * finished, calls to {@link variation} will still return flag values for the previous context. You can
+   * await the Promise to determine when the new flag values are available.
+   *
+   * @param context
+   *    The LDContext object.
+   * @param identifyOptions
+   *    Optional configuration. Please see {@link LDIdentifyOptions}.
+   * @returns
+   *    A Promise which resolves when the flag values for the specified
+   * context are available. It rejects when:
+   *
+   * 1. The context is unspecified or has no key.
+   *
+   * 2. The identify timeout is exceeded. In client SDKs this defaults to 5s.
+   * You can customize this timeout with {@link LDIdentifyOptions | identifyOptions}.
+   *
+   * 3. A network error is encountered during initialization.
+   */
+  identify(context: LDContext, identifyOptions?: LDIdentifyOptions): Promise<void>;
+};

packages/sdk/react-native/src/ReactNativeLDClient.ts

@@ -13,9 +13,14 @@ import {
   type LDClientDataSystemOptions,
   LDClientImpl,
   LDClientInternalOptions,
+  type LDContext,
   LDEmitter,
   LDHeaders,
+  type LDIdentifyOptions,
+  type LDIdentifyResult,
   LDPluginEnvironmentMetadata,
+  LDTimeoutError,
+  type LDWaitForInitializationResult,
   MOBILE_DATA_SYSTEM_DEFAULTS,
   MOBILE_TRANSITION_TABLE,
   mobileFdv1Endpoints,
@@ -227,6 +232,33 @@ export default class ReactNativeLDClient extends LDClientImpl {
     );
   }
 
+  override async identify(
+    context: LDContext,
+    identifyOptions?: LDIdentifyOptions,
+  ): Promise<LDIdentifyResult> {
+    const result = await super.identify(context, identifyOptions);
+    if (result.status === 'error') {
+      throw result.error;
+    } else if (result.status === 'timeout') {
+      const timeoutError = new LDTimeoutError(
+        `identify timed out after ${result.timeout} seconds.`,
+      );
+      this.logger.error(timeoutError.message);
+      throw timeoutError;
+    }
+    return result;
+  }
+
+  /**
+   * Protect against trying to use start() in RN.
+   *
+   * @internal
+   **/
+
+  override start(): Promise<LDWaitForInitializationResult> {
+    throw new Error('start() is not supported in the React Native SDK. Use identify() directly.');
+  }
+
   override async close(): Promise<void> {
     this._stateDetector?.stopListening();
     this._connectionManager?.close();

packages/sdk/react-native/src/index.ts

@@ -10,6 +10,10 @@ import RNOptions, { RNDataSystemOptions, RNStorage } from './RNOptions';
 
 export * from '@launchdarkly/js-client-sdk-common';
 
+// Override the common LDClient type with a React Native-specific one that
+// preserves backward-compatible identify() returning Promise<void>.
+export type { LDClient } from './LDClient';
+
 export * from './hooks';
 export * from './provider';
 export * from './LDPlugin';

packages/shared/sdk-client/__tests__/LDClientImpl.start.test.ts

@@ -246,7 +246,7 @@ describe('LDClientImpl.start()', () => {
         initialContext: context,
       });
 
-      const result = await ldc.identifyResult({ kind: 'user', key: 'other-user' });
+      const result = await ldc.identify({ kind: 'user', key: 'other-user' });
 
       expect(result.status).toBe('error');
       if (result.status === 'error') {
@@ -263,15 +263,15 @@ describe('LDClientImpl.start()', () => {
 
       await ldc.start();
 
-      const result = await ldc.identifyResult({ kind: 'user', key: 'other-user' });
+      const result = await ldc.identify({ kind: 'user', key: 'other-user' });
       expect(result.status).toBe('completed');
     });
 
     it('allows identify without start when requiresStart is false', async () => {
       const mockPlatform = setupStreamingPlatform();
       const { ldc } = setupClient(mockPlatform, { requiresStart: false });
 
-      const result = await ldc.identifyResult(context);
+      const result = await ldc.identify(context);
       expect(result.status).toBe('completed');
     });
 
@@ -280,9 +280,9 @@ describe('LDClientImpl.start()', () => {
       const { ldc } = setupClient(mockPlatform, { requiresStart: true, initialContext: context });
 
       const startPromise = ldc.start();
-      const promise1 = ldc.identifyResult({ kind: 'user', key: 'user-1' });
-      const promise2 = ldc.identifyResult({ kind: 'user', key: 'user-2' });
-      const promise3 = ldc.identifyResult({ kind: 'user', key: 'user-3' });
+      const promise1 = ldc.identify({ kind: 'user', key: 'user-1' });
+      const promise2 = ldc.identify({ kind: 'user', key: 'user-2' });
+      const promise3 = ldc.identify({ kind: 'user', key: 'user-3' });
 
       const [startResult, result1, result2, result3] = await Promise.all([
         startPromise,

packages/shared/sdk-client/__tests__/LDClientImpl.test.ts

@@ -285,17 +285,17 @@ describe('sdk-client object', () => {
     const carContext = { kind: 'car' };
 
     // @ts-expect-error - invalid context
-    await expect(ldc.identify(carContext)).rejects.toThrow(/no key/);
-    expect(logger.error).toHaveBeenCalledTimes(1);
+    const result = await ldc.identify(carContext);
+    expect(result).toEqual(expect.objectContaining({ status: 'error', error: expect.any(Error) }));
     expect(ldc.getContext()).toBeUndefined();
   });
 
   test('identify error invalid multi kindcontext', async () => {
     const carContext = { kind: 'multi', user: { name: 'test' } };
 
     // @ts-ignore - invalid context
-    await expect(ldc.identify(carContext)).rejects.toThrow(/no key/);
-    expect(logger.error).toHaveBeenCalledTimes(1);
+    const result = await ldc.identify(carContext);
+    expect(result).toEqual(expect.objectContaining({ status: 'error', error: expect.any(Error) }));
     expect(ldc.getContext()).toBeUndefined();
   });
 
@@ -310,7 +310,8 @@ describe('sdk-client object', () => {
 
     const carContext: LDContext = { kind: 'car', key: 'test-car' };
 
-    await expect(ldc.identify(carContext)).rejects.toThrow('test-error');
+    const result = await ldc.identify(carContext);
+    expect(result).toEqual(expect.objectContaining({ status: 'error' }));
     expect(logger.error).toHaveBeenCalledTimes(2);
     expect(logger.error).toHaveBeenNthCalledWith(1, expect.stringMatching(/^error:.*test-error/));
     expect(logger.error).toHaveBeenNthCalledWith(2, expect.stringContaining('Received error 404'));
@@ -430,7 +431,8 @@ describe('sdk-client object', () => {
     const spyListener = jest.fn();
     ldc.on('dataSourceStatus', spyListener);
     const changePromise = onDataSourceChangePromise(2);
-    await expect(ldc.identify(carContext)).rejects.toThrow('test-error');
+    const identifyResult = await ldc.identify(carContext);
+    expect(identifyResult).toEqual(expect.objectContaining({ status: 'error' }));
     await changePromise;
 
     expect(spyListener).toHaveBeenCalledTimes(2);

packages/shared/sdk-client/__tests__/LDClientImpl.timeout.test.ts

@@ -63,25 +63,30 @@ describe('sdk-client identify timeout', () => {
     jest.resetAllMocks();
   });
 
-  test('rejects with default timeout of 5s', async () => {
+  test('returns timeout result with default timeout of 5s', async () => {
     jest.advanceTimersByTimeAsync(DEFAULT_IDENTIFY_TIMEOUT * 1000).then();
-    await expect(ldc.identify(carContext)).rejects.toThrow(/identify timed out/);
-    expect(logger.error).toHaveBeenCalledWith(expect.stringMatching(/identify timed out/));
+    await expect(ldc.identify(carContext)).resolves.toEqual({
+      status: 'timeout',
+      timeout: DEFAULT_IDENTIFY_TIMEOUT,
+    });
   });
 
-  test('rejects with custom timeout', async () => {
+  test('returns timeout result with custom timeout', async () => {
     const timeout = 15;
     jest.advanceTimersByTimeAsync(timeout * 1000).then();
-    await expect(ldc.identify(carContext, { timeout })).rejects.toThrow(/identify timed out/);
+    await expect(ldc.identify(carContext, { timeout })).resolves.toEqual({
+      status: 'timeout',
+      timeout,
+    });
   });
 
-  test('resolves with default timeout', async () => {
+  test('resolves with completed status on default timeout', async () => {
     // set simulated events to be default response
     simulatedEvents = [{ data: JSON.stringify(defaultPutResponse) }];
 
     jest.advanceTimersByTimeAsync(DEFAULT_IDENTIFY_TIMEOUT * 1000).then();
 
-    await expect(ldc.identify(carContext)).resolves.toBeUndefined();
+    await expect(ldc.identify(carContext)).resolves.toEqual({ status: 'completed' });
 
     expect(ldc.getContext()).toEqual(expect.objectContaining(toMulti(carContext)));
     expect(ldc.allFlags()).toEqual({
@@ -106,7 +111,7 @@ describe('sdk-client identify timeout', () => {
 
     jest.advanceTimersByTimeAsync(timeout).then();
 
-    await expect(ldc.identify(carContext, { timeout })).resolves.toBeUndefined();
+    await expect(ldc.identify(carContext, { timeout })).resolves.toEqual({ status: 'completed' });
 
     expect(ldc.getContext()).toEqual(expect.objectContaining(toMulti(carContext)));
     expect(ldc.allFlags()).toEqual({
@@ -208,7 +213,7 @@ describe('sdk-client waitForInitialization', () => {
     simulatedEvents = [{ data: JSON.stringify(defaultPutResponse) }];
 
     const waitPromise = ldc.waitForInitialization({ timeout: 10 });
-    const identifyPromise = ldc.identifyResult(carContext);
+    const identifyPromise = ldc.identify(carContext);
 
     jest.advanceTimersByTimeAsync(DEFAULT_IDENTIFY_TIMEOUT).then();
 
@@ -222,7 +227,7 @@ describe('sdk-client waitForInitialization', () => {
     simulatedEvents = [{ data: JSON.stringify(defaultPutResponse) }];
 
     const waitPromise = ldc.waitForInitialization({ timeout: 10 });
-    const identifyPromise = ldc.identifyResult(carContext);
+    const identifyPromise = ldc.identify(carContext);
 
     jest.advanceTimersByTimeAsync(DEFAULT_IDENTIFY_TIMEOUT).then();
 
@@ -240,7 +245,7 @@ describe('sdk-client waitForInitialization', () => {
     simulatedEvents = [];
 
     const waitPromise = ldc.waitForInitialization({ timeout: 10 });
-    const identifyPromise = ldc.identifyResult(carContext);
+    const identifyPromise = ldc.identify(carContext);
 
     jest.advanceTimersByTimeAsync(10 * 1000 + 1).then();
 
@@ -274,7 +279,7 @@ describe('sdk-client waitForInitialization', () => {
     );
 
     const waitPromise = errorLdc.waitForInitialization({ timeout: 10 });
-    const identifyPromise = errorLdc.identifyResult(carContext);
+    const identifyPromise = errorLdc.identify(carContext);
 
     // Advance timers to allow error handler to be set up and error to propagate
     await jest.advanceTimersByTimeAsync(DEFAULT_IDENTIFY_TIMEOUT);

packages/shared/sdk-client/__tests__/LDClientImpl.variation.test.ts

@@ -77,7 +77,7 @@ describe('sdk-client object', () => {
     const p = ldc.identify(context);
     const flagValue = ldc.variation('does-not-exist', 'not-found');
 
-    await expect(p).resolves.toBeUndefined();
+    await expect(p).resolves.toEqual({ status: 'completed' });
 
     expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('Unknown feature'));
     expect(flagValue).toBe('not-found');