feat: Add support for an identify queue. (#842)

Co-authored-by: Todd Anderson <127344469+tanderson-ld@users.noreply.github.com>

Author: kinyoklion

actions/package-size/action.yml

@@ -28,7 +28,9 @@ runs:
       run: |
         brotli ${{ inputs.target_file }}
         export PACK_SIZE=$(stat -c %s ${{ inputs.target_file }}.br)
+        export RAW_SIZE=$(stat -c %s ${{ inputs.target_file }})
         echo "PACK_SIZE=$PACK_SIZE" >> $GITHUB_ENV
+        echo "RAW_SIZE=$RAW_SIZE" >> $GITHUB_ENV
 
     - name: Find Size Comment
       # Only do commenting on non-forks. A fork does not have permissions for comments.
@@ -48,8 +50,9 @@ runs:
         body: |
           ${{ inputs.package_name }} size report
           This is the brotli compressed size of the ESM build.
-          Size: ${{ env.PACK_SIZE }} bytes
-          Size limit: ${{ inputs.size_limit }}
+          Compressed size: ${{ env.PACK_SIZE }} bytes
+          Compressed size limit: ${{ inputs.size_limit }}
+          Uncompressed size: ${{ env.RAW_SIZE }} bytes
 
     - name: Update comment
       if: steps.fc.outputs.comment-id != '' && github.event.pull_request.head.repo.full_name == github.repository
@@ -60,9 +63,9 @@ runs:
         body: |
           ${{ inputs.package_name }} size report
           This is the brotli compressed size of the ESM build.
-          Size: ${{ env.PACK_SIZE }} bytes
-          Size limit: ${{ inputs.size_limit }}
-
+          Compressed size: ${{ env.PACK_SIZE }} bytes
+          Compressed size limit: ${{ inputs.size_limit }}
+          Uncompressed size: ${{ env.RAW_SIZE }} bytes
     - name: Check package size limit
       shell: bash
       run: |

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

@@ -1,4 +1,8 @@
-import { AutoEnvAttributes, LDLogger } from '@launchdarkly/js-client-sdk-common';
+import {
+  AutoEnvAttributes,
+  LDLogger,
+  LDSingleKindContext,
+} from '@launchdarkly/js-client-sdk-common';
 
 import { BrowserClient } from '../src/BrowserClient';
 import { makeBasicPlatform } from './BrowserClient.mocks';
@@ -184,4 +188,198 @@ describe('given a mock platform for a BrowserClient', () => {
       variationIndex: 1,
     });
   });
+
+  it('can shed intermediate identifyResult calls', async () => {
+    const client = new BrowserClient(
+      'client-side-id',
+      AutoEnvAttributes.Disabled,
+      { streaming: false, logger, diagnosticOptOut: true, sendEvents: false, fetchGoals: false },
+      platform,
+    );
+
+    const promise1 = client.identifyResult({ key: 'user-key-1', kind: 'user' });
+    const promise2 = client.identifyResult({ key: 'user-key-2', kind: 'user' });
+    const promise3 = client.identifyResult({ key: 'user-key-3', kind: 'user' });
+
+    const [result1, result2, result3] = await Promise.all([promise1, promise2, promise3]);
+
+    expect(result1).toEqual({ status: 'completed' });
+    expect(result2).toEqual({ status: 'shed' });
+    expect(result3).toEqual({ status: 'completed' });
+    // With events and goals disabled the only fetch calls should be for polling requests.
+    expect(platform.requests.fetch.mock.calls.length).toBe(2);
+  });
+
+  it('calls beforeIdentify in order', async () => {
+    const order: string[] = [];
+    const client = new BrowserClient(
+      'client-side-id',
+      AutoEnvAttributes.Disabled,
+      {
+        streaming: false,
+        logger,
+        diagnosticOptOut: true,
+        sendEvents: false,
+        fetchGoals: false,
+        hooks: [
+          {
+            beforeIdentify: (hookContext, data) => {
+              if ('kind' in hookContext.context && hookContext.context.kind !== 'multi') {
+                order.push((hookContext.context as LDSingleKindContext).key);
+              }
+
+              return data;
+            },
+            getMetadata: () => ({
+              name: 'test-hook',
+              version: '1.0.0',
+            }),
+          },
+        ],
+      },
+      platform,
+    );
+
+    const promise1 = client.identify({ key: 'user-key-1', kind: 'user' });
+    const promise2 = client.identify({ key: 'user-key-2', kind: 'user' });
+    const promise3 = client.identify({ key: 'user-key-3', kind: 'user' });
+
+    await Promise.all([promise1, promise2, promise3]);
+    expect(order).toEqual(['user-key-1', 'user-key-2', 'user-key-3']);
+  });
+
+  it('completes identify calls in order', async () => {
+    const order: string[] = [];
+    const client = new BrowserClient(
+      'client-side-id',
+      AutoEnvAttributes.Disabled,
+      {
+        streaming: false,
+        logger,
+        diagnosticOptOut: true,
+        sendEvents: false,
+        fetchGoals: false,
+        hooks: [
+          {
+            afterIdentify: (hookContext, data, result) => {
+              if (result.status === 'shed') {
+                return data;
+              }
+              if ('kind' in hookContext.context && hookContext.context.kind !== 'multi') {
+                order.push((hookContext.context as LDSingleKindContext).key);
+              }
+
+              return data;
+            },
+            getMetadata: () => ({
+              name: 'test-hook',
+              version: '1.0.0',
+            }),
+          },
+        ],
+      },
+      platform,
+    );
+
+    const promise1 = client.identify({ key: 'user-key-1', kind: 'user' });
+    const promise2 = client.identify({ key: 'user-key-2', kind: 'user' });
+    const promise3 = client.identify({ key: 'user-key-3', kind: 'user' });
+
+    await Promise.all([promise1, promise2, promise3]);
+    // user-key-2 is shed, so it is not included in the order
+    expect(order).toEqual(['user-key-1', 'user-key-3']);
+  });
+
+  it('completes awaited identify calls in order without shedding', async () => {
+    const order: string[] = [];
+    const client = new BrowserClient(
+      'client-side-id',
+      AutoEnvAttributes.Disabled,
+      {
+        streaming: false,
+        logger,
+        diagnosticOptOut: true,
+        sendEvents: false,
+        fetchGoals: false,
+        hooks: [
+          {
+            afterIdentify: (hookContext, data, result) => {
+              if (result.status === 'shed') {
+                return data;
+              }
+              if ('kind' in hookContext.context && hookContext.context.kind !== 'multi') {
+                order.push((hookContext.context as LDSingleKindContext).key);
+              }
+
+              return data;
+            },
+            getMetadata: () => ({
+              name: 'test-hook',
+              version: '1.0.0',
+            }),
+          },
+        ],
+      },
+      platform,
+    );
+
+    const result1 = await client.identifyResult({ key: 'user-key-1', kind: 'user' });
+    const result2 = await client.identifyResult({ key: 'user-key-2', kind: 'user' });
+    const result3 = await client.identifyResult({ key: 'user-key-3', kind: 'user' });
+
+    expect(result1.status).toEqual('completed');
+    expect(result2.status).toEqual('completed');
+    expect(result3.status).toEqual('completed');
+
+    // user-key-2 is shed, so it is not included in the order
+    expect(order).toEqual(['user-key-1', 'user-key-2', 'user-key-3']);
+  });
+
+  it('can shed intermediate identify calls', async () => {
+    const client = new BrowserClient(
+      'client-side-id',
+      AutoEnvAttributes.Disabled,
+      { streaming: false, logger, diagnosticOptOut: true, sendEvents: false, fetchGoals: false },
+      platform,
+    );
+
+    const promise1 = client.identify({ key: 'user-key-1', kind: 'user' });
+    const promise2 = client.identify({ key: 'user-key-2', kind: 'user' });
+    const promise3 = client.identify({ key: 'user-key-3', kind: 'user' });
+
+    await Promise.all([promise1, promise2, promise3]);
+
+    // With events and goals disabled the only fetch calls should be for polling requests.
+    expect(platform.requests.fetch.mock.calls.length).toBe(2);
+  });
+
+  it('it does not shed non-shedable identify calls', async () => {
+    const client = new BrowserClient(
+      'client-side-id',
+      AutoEnvAttributes.Disabled,
+      { streaming: false, logger, diagnosticOptOut: true, sendEvents: false, fetchGoals: false },
+      platform,
+    );
+
+    const promise1 = client.identifyResult(
+      { key: 'user-key-1', kind: 'user' },
+      { sheddable: false },
+    );
+    const promise2 = client.identifyResult(
+      { key: 'user-key-2', kind: 'user' },
+      { sheddable: false },
+    );
+    const promise3 = client.identifyResult(
+      { key: 'user-key-3', kind: 'user' },
+      { sheddable: false },
+    );
+
+    const [result1, result2, result3] = await Promise.all([promise1, promise2, promise3]);
+
+    expect(result1).toEqual({ status: 'completed' });
+    expect(result2).toEqual({ status: 'completed' });
+    expect(result3).toEqual({ status: 'completed' });
+    // With events and goals disabled the only fetch calls should be for polling requests.
+    expect(platform.requests.fetch.mock.calls.length).toBe(3);
+  });
 });

packages/sdk/browser/src/BrowserClient.ts

@@ -11,6 +11,7 @@ import {
   LDEmitter,
   LDEmitterEventName,
   LDHeaders,
+  LDIdentifyResult,
   LDPluginEnvironmentMetadata,
   Platform,
 } from '@launchdarkly/js-client-sdk-common';
@@ -188,8 +189,22 @@ export class BrowserClient extends LDClientImpl implements LDClient {
   }
 
   override async identify(context: LDContext, identifyOptions?: LDIdentifyOptions): Promise<void> {
-    await super.identify(context, identifyOptions);
+    return super.identify(context, identifyOptions);
+  }
+
+  override async identifyResult(
+    context: LDContext,
+    identifyOptions?: LDIdentifyOptions,
+  ): Promise<LDIdentifyResult> {
+    const identifyOptionsWithUpdatedDefaults = {
+      ...identifyOptions,
+    };
+    if (identifyOptions?.sheddable === undefined) {
+      identifyOptionsWithUpdatedDefaults.sheddable = true;
+    }
+    const res = await super.identifyResult(context, identifyOptionsWithUpdatedDefaults);
     this._goalManager?.startTracking();
+    return res;
   }
 
   setStreaming(streaming?: boolean): void {

packages/sdk/browser/src/BrowserIdentifyOptions.ts

@@ -1,5 +1,12 @@
 import { LDIdentifyOptions } from '@launchdarkly/js-client-sdk-common';
 
+/**
+ * @property sheddable - If true, the identify operation will be sheddable. This means that if multiple identify operations are done, without
+ * waiting for the previous one to complete, then intermediate results will be discarded. When false, identify
+ * operations will be queued and completed sequentially.
+ *
+ * Defaults to true.
+ */
 export interface BrowserIdentifyOptions extends Omit<LDIdentifyOptions, 'waitForNetworkResults'> {
   /**
    * The signed context key if you are using [Secure Mode]

packages/sdk/browser/src/LDClient.ts

@@ -1,4 +1,8 @@
-import { LDClient as CommonClient, LDContext } from '@launchdarkly/js-client-sdk-common';
+import {
+  LDClient as CommonClient,
+  LDContext,
+  LDIdentifyResult,
+} from '@launchdarkly/js-client-sdk-common';
 
 import { BrowserIdentifyOptions as LDIdentifyOptions } from './BrowserIdentifyOptions';
 
@@ -34,7 +38,8 @@ export type LDClient = Omit<
   setStreaming(streaming?: boolean): void;
 
   /**
-   * Identifies a context to LaunchDarkly.
+   * Identifies a context to LaunchDarkly and returns a promise which resolves to an object containing the result of
+   * the identify operation.
    *
    * Unlike the server-side SDKs, the client-side JavaScript SDKs maintain a current context state,
    * which is set when you call `identify()`.
@@ -43,6 +48,10 @@ export type LDClient = Omit<
    * 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.
    *
+   * This function will shed intermediate identify operations by default. For example, if you call identify 3 times in
+   * a row, without waiting for the previous one to complete, the middle call to identify may be discarded. To disable
+   * this set `sheddable` to `false` in the `identifyOptions` parameter.
+   *
    * @param context
    *    The LDContext object.
    * @param identifyOptions
@@ -61,4 +70,34 @@ export type LDClient = Omit<
    * @ignore Implementation Note: Browser implementation has different options.
    */
   identify(context: LDContext, identifyOptions?: LDIdentifyOptions): Promise<void>;
+
+  /**
+   * Identifies a context to LaunchDarkly and returns a promise which resolves to an object containing the result of
+   * the identify operation.
+   *
+   * 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.
+   *
+   * If used with the `sheddable` option set to true, then the identify operation will be sheddable. This means that if
+   * multiple identify operations are done, without waiting for the previous one to complete, then intermediate
+   * operations may be discarded.
+   *
+   * @param context
+   *    The LDContext object.
+   * @param identifyOptions
+   *    Optional configuration. Please see {@link LDIdentifyOptions}.
+   * @returns
+   *    A promise which resolves to an object containing the result of the identify operation.
+   *    The promise returned from this method will not be rejected.
+   *
+   * @ignore Implementation Note: Browser implementation has different options.
+   */
+  identifyResult(
+    pristineContext: LDContext,
+    identifyOptions?: LDIdentifyOptions,
+  ): Promise<LDIdentifyResult>;
 };

packages/sdk/browser/src/common.ts

@@ -38,6 +38,11 @@ export type {
   LDPluginSdkMetadata,
   LDPluginApplicationMetadata,
   LDPluginMetadata,
+  LDIdentifyResult,
+  LDIdentifySuccess,
+  LDIdentifyError,
+  LDIdentifyTimeout,
+  LDIdentifyShed,
 } from '@launchdarkly/js-client-sdk-common';
 
 /**

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

@@ -12,7 +12,8 @@ import { LDClient as LDCLientBrowser } from '../LDClient';
  * incorrect. Any function which optionally returned a promise based on a callback had incorrect
  * typings. Those have been corrected in this implementation.
  */
-export interface LDClient extends Omit<LDCLientBrowser, 'close' | 'flush' | 'identify'> {
+export interface LDClient
+  extends Omit<LDCLientBrowser, 'close' | 'flush' | 'identify' | 'identifyResult'> {
   /**
    * Identifies a context to LaunchDarkly.
    *