launchdarkly-js-sdk-common 5.2.0 → 5.4.0

package/.github/actions/publish-docs/action.yml

@@ -0,0 +1,16 @@
+name: Publish Documentation
+description: 'Publish documentation to github pages.'
+
+inputs:
+  github_token:
+    description: 'The github token to use for committing'
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - uses: launchdarkly/gh-actions/actions/publish-pages@publish-pages-v1.0.2
+      name: 'Publish to Github pages'
+      with:
+        docs_path: docs
+        github_token: ${{ inputs.github_token }}

package/.github/actions/publish-npm/action.yml

@@ -0,0 +1,20 @@
+name: Publish to NPM
+description: Publish an npm package.
+inputs:
+  prerelease:
+    description: 'Is this a prerelease. If so, then the latest tag will not be updated in npm.'
+    required: false
+  dry-run:
+    description: 'Is this a dry run. If so no package will be published.'
+    required: false
+
+runs:
+  using: composite
+  steps:
+    - name: Publish
+      shell: bash
+      run: |
+        ./scripts/publish-npm.sh
+      env:
+        LD_RELEASE_IS_PRERELEASE: ${{ inputs.prerelease }}
+        LD_RELEASE_IS_DRYRUN: ${{ inputs.dry-run }}

package/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: Build and Test
+
+on:
+  push:
+    branches: [main]
+    paths-ignore:
+      - '**.md' #Do not need to run CI for markdown changes.
+  pull_request:
+    branches: [main]
+    paths-ignore:
+      - '**.md'
+
+jobs:
+  build-test:
+    strategy:
+      matrix:
+        variations: [
+          {os: ubuntu-latest, node: latest},
+          {os: ubuntu-latest, node: 18}
+        ]
+
+    runs-on: ${{ matrix.variations.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.variations.node }}
+          registry-url: 'https://registry.npmjs.org'
+      - name: Install
+        run: npm install
+      - name: Test
+        run: npm test
+        env:
+          JEST_JUNIT_OUTPUT_FILE: "reports/junit/js-test-results.xml"
+      - name: Lint
+        run: npm run lint:all
+      - name: Check typescript
+        run: npm run check-typescript
+      - name: Build Docs
+        run: npm run doc

package/.github/workflows/lint-pr-title.yml

@@ -0,0 +1,12 @@
+name: Lint PR title
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - edited
+      - synchronize
+
+jobs:
+  lint-pr-title:
+    uses: launchdarkly/gh-actions/.github/workflows/lint-pr-title.yml@main

package/.github/workflows/release-please.yml

@@ -0,0 +1,57 @@
+name: Release Please
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          token: ${{secrets.GITHUB_TOKEN}}
+
+  publish-package:
+    runs-on: ubuntu-latest
+    needs: ['release-please']
+    permissions:
+      id-token: write
+      contents: write
+    if: ${{ needs.release-please.outputs.release_created == 'true' }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          registry-url: 'https://registry.npmjs.org'
+
+      - uses: launchdarkly/gh-actions/actions/release-secrets@release-secrets-v1.2.0
+        name: 'Get NPM token'
+        with:
+          aws_assume_role: ${{ vars.AWS_ROLE_ARN }}
+          ssm_parameter_pairs: '/production/common/releasing/npm/token = NODE_AUTH_TOKEN'
+
+      - name: Install Dependencies
+        run: npm install
+
+      - id: publish-npm
+        name: Publish NPM Package
+        uses: ./.github/actions/publish-npm
+        with:
+          dry-run: 'false'
+          prerelease: 'false'
+
+      - name: Build Documentation
+        run: npm run doc
+
+      - id: publish-docs
+        name: Publish Documentation
+        uses: ./.github/actions/publish-docs
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}

package/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "5.4.0"
+}

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to the `launchdarkly-js-sdk-common` package will be documented in this file. Changes that affect the dependent SDKs such as `launchdarkly-js-client-sdk` should also be logged in those projects, in the next release that uses the updated version of this package. This project adheres to [Semantic Versioning](http://semver.org).
 
+## [5.4.0](https://github.com/launchdarkly/js-sdk-common/compare/5.3.0...5.4.0) (2024-10-18)
+
+
+### Features
+
+* Add support for client-side prerequisite events. ([#112](https://github.com/launchdarkly/js-sdk-common/issues/112)) ([9d1708b](https://github.com/launchdarkly/js-sdk-common/commit/9d1708b212246c5650794af99f79cd6a95cfbcd1))
+
+## [5.3.0](https://github.com/launchdarkly/js-sdk-common/compare/launchdarkly-js-sdk-common-v5.2.0...launchdarkly-js-sdk-common-v5.3.0) (2024-06-18)
+
+
+### Features
+
+* Add inExperiment to evaluation reason. ([#105](https://github.com/launchdarkly/js-sdk-common/issues/105)) ([cf69770](https://github.com/launchdarkly/js-sdk-common/commit/cf6977080e67e4e54f773df410a671764dbcb304))
+* Allow for synchronous inspectors. ([#103](https://github.com/launchdarkly/js-sdk-common/issues/103)) ([7e490f4](https://github.com/launchdarkly/js-sdk-common/commit/7e490f479299f772a9db78efd1c2235645785250))
+
+## [5.2.0] - 2024-05-01
+### Added:
+- Added an optional timeout to the `waitForInitialization` method. When a timeout is specified the returned promise will be rejected after the timeout elapses if the client has not finished initializing within that time. When no timeout is specified the returned promise will not be resolved or rejected until the initialization either completes or fails.
+
+### Changed:
+- The track method now validates that the provided metricValue is a number. If a metric value is provided, and it is not a number, then a warning will be logged.
+
+### Fixed:
+- Fixed the documentation for `evaluationReasons` for the `identify` method.
+
 ## [5.1.0] - 2024-03-19
 ### Changed:
 - Redact anonymous attributes within feature events

package/README.md

@@ -1,6 +1,6 @@
 # LaunchDarkly Javascript SDK Core Components
 
-[![Circle CI](https://circleci.com/gh/launchdarkly/js-sdk-common/tree/master.svg?style=svg)](https://circleci.com/gh/launchdarkly/js-sdk-common/tree/master)
+[![Actions Status][ci-badge]][ci]
 
 ## LaunchDarkly overview
 
@@ -33,3 +33,6 @@ We encourage pull requests and other contributions from the community. Check out
     * [docs.launchdarkly.com](https://docs.launchdarkly.com/  "LaunchDarkly Documentation") for our documentation and SDK reference guides
     * [apidocs.launchdarkly.com](https://apidocs.launchdarkly.com/  "LaunchDarkly API Documentation") for our API documentation
     * [blog.launchdarkly.com](https://blog.launchdarkly.com/  "LaunchDarkly Blog Documentation") for the latest product updates
+
+[ci-badge]: https://github.com/launchdarkly/js-sdk-common/actions/workflows/ci.yml/badge.svg
+[ci]: https://github.com/launchdarkly/js-sdk-common/actions/workflows/ci.yml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "launchdarkly-js-sdk-common",
-  "version": "5.2.0",
+  "version": "5.4.0",
   "description": "LaunchDarkly SDK for JavaScript - common code",
   "author": "LaunchDarkly <team@launchdarkly.com>",
   "license": "Apache-2.0",
@@ -17,7 +17,8 @@
     "format:test:md": "prettier --parser markdown --ignore-path .prettierignore --list-different '*.md'",
     "format:test:js": "prettier --ignore-path .prettierignore --list-different 'src/**/*.js'",
     "test": "cross-env NODE_ENV=test jest",
-    "check-typescript": "node_modules/typescript/bin/tsc"
+    "check-typescript": "tsc",
+    "doc": "typedoc"
   },
   "devDependencies": {
     "@babel/cli": "^7.8.4",
@@ -43,7 +44,8 @@
     "launchdarkly-js-test-helpers": "1.1.0",
     "prettier": "1.19.1",
     "readline-sync": "^1.4.9",
-    "typescript": "~4.4.4"
+    "typescript": "~5.4.5",
+    "typedoc": "^0.25.13"
   },
   "dependencies": {
     "base64-js": "^1.3.0",

package/release-please-config.json

@@ -0,0 +1,10 @@
+{
+  "bootstrap-sha": "d49ca41718a593c071874950d301f2f00c71a371",
+  "packages": {
+    ".": {
+      "release-type": "node",
+      "include-v-in-tag": false,
+      "include-component-in-tag": false
+    }
+  }
+}

package/scripts/publish-npm.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+if $LD_RELEASE_IS_DRYRUN ; then
+  echo "Doing a dry run of publishing."
+else
+  if $LD_RELEASE_IS_PRERELEASE ; then
+    echo "Publishing with prerelease tag."
+    npm publish --tag prerelease --provenance --access public || { echo "npm publish failed" >&2; exit 1; }
+  else
+    npm publish --provenance --access public || { echo "npm publish failed" >&2; exit 1; }
+  fi
+fi

package/src/InspectorManager.js

@@ -22,6 +22,9 @@ function InspectorManager(inspectors, logger) {
 
   /**
    * Collection of inspectors keyed by type.
+   *
+   * Inspectors are async by default.
+   *
    * @type {{[type: string]: object[]}}
    */
   const inspectorsByType = {
@@ -30,14 +33,30 @@ function InspectorManager(inspectors, logger) {
     [InspectorTypes.flagDetailChanged]: [],
     [InspectorTypes.clientIdentityChanged]: [],
   };
+  /**
+   * Collection synchronous of inspectors keyed by type.
+   *
+   * @type {{[type: string]: object[]}}
+   */
+  const synchronousInspectorsByType = {
+    [InspectorTypes.flagUsed]: [],
+    [InspectorTypes.flagDetailsChanged]: [],
+    [InspectorTypes.flagDetailChanged]: [],
+    [InspectorTypes.clientIdentityChanged]: [],
+  };
 
   const safeInspectors = inspectors && inspectors.map(inspector => SafeInspector(inspector, logger));
 
   safeInspectors &&
     safeInspectors.forEach(safeInspector => {
       // Only add inspectors of supported types.
-      if (Object.prototype.hasOwnProperty.call(inspectorsByType, safeInspector.type)) {
+      if (Object.prototype.hasOwnProperty.call(inspectorsByType, safeInspector.type) && !safeInspector.synchronous) {
         inspectorsByType[safeInspector.type].push(safeInspector);
+      } else if (
+        Object.prototype.hasOwnProperty.call(synchronousInspectorsByType, safeInspector.type) &&
+        safeInspector.synchronous
+      ) {
+        synchronousInspectorsByType[safeInspector.type].push(safeInspector);
       } else {
         logger.warn(messages.invalidInspector(safeInspector.type, safeInspector.name));
       }
@@ -49,7 +68,9 @@ function InspectorManager(inspectors, logger) {
    * @param {string} type The type of the inspector to check.
    * @returns True if there are any inspectors of that type registered.
    */
-  manager.hasListeners = type => inspectorsByType[type] && inspectorsByType[type].length;
+  manager.hasListeners = type =>
+    (inspectorsByType[type] && inspectorsByType[type].length) ||
+    (synchronousInspectorsByType[type] && synchronousInspectorsByType[type].length);
 
   /**
    * Notify registered inspectors of a flag being used.
@@ -61,9 +82,13 @@ function InspectorManager(inspectors, logger) {
    * @param {Object} context The LDContext for the flag.
    */
   manager.onFlagUsed = (flagKey, detail, context) => {
-    if (inspectorsByType[InspectorTypes.flagUsed].length) {
+    const type = InspectorTypes.flagUsed;
+    if (synchronousInspectorsByType[type].length) {
+      synchronousInspectorsByType[type].forEach(inspector => inspector.method(flagKey, detail, context));
+    }
+    if (inspectorsByType[type].length) {
       onNextTick(() => {
-        inspectorsByType[InspectorTypes.flagUsed].forEach(inspector => inspector.method(flagKey, detail, context));
+        inspectorsByType[type].forEach(inspector => inspector.method(flagKey, detail, context));
       });
     }
   };
@@ -76,9 +101,13 @@ function InspectorManager(inspectors, logger) {
    * @param {Record<string, Object>} flags The current flags as a Record<string, LDEvaluationDetail>.
    */
   manager.onFlags = flags => {
-    if (inspectorsByType[InspectorTypes.flagDetailsChanged].length) {
+    const type = InspectorTypes.flagDetailsChanged;
+    if (synchronousInspectorsByType[type].length) {
+      synchronousInspectorsByType[type].forEach(inspector => inspector.method(flags));
+    }
+    if (inspectorsByType[type].length) {
       onNextTick(() => {
-        inspectorsByType[InspectorTypes.flagDetailsChanged].forEach(inspector => inspector.method(flags));
+        inspectorsByType[type].forEach(inspector => inspector.method(flags));
       });
     }
   };
@@ -92,9 +121,13 @@ function InspectorManager(inspectors, logger) {
    * @param {Object} flag An `LDEvaluationDetail` for the flag.
    */
   manager.onFlagChanged = (flagKey, flag) => {
-    if (inspectorsByType[InspectorTypes.flagDetailChanged].length) {
+    const type = InspectorTypes.flagDetailChanged;
+    if (synchronousInspectorsByType[type].length) {
+      synchronousInspectorsByType[type].forEach(inspector => inspector.method(flagKey, flag));
+    }
+    if (inspectorsByType[type].length) {
       onNextTick(() => {
-        inspectorsByType[InspectorTypes.flagDetailChanged].forEach(inspector => inspector.method(flagKey, flag));
+        inspectorsByType[type].forEach(inspector => inspector.method(flagKey, flag));
       });
     }
   };
@@ -107,9 +140,13 @@ function InspectorManager(inspectors, logger) {
    * @param {Object} context The `LDContext` which is now identified.
    */
   manager.onIdentityChanged = context => {
-    if (inspectorsByType[InspectorTypes.clientIdentityChanged].length) {
+    const type = InspectorTypes.clientIdentityChanged;
+    if (synchronousInspectorsByType[type].length) {
+      synchronousInspectorsByType[type].forEach(inspector => inspector.method(context));
+    }
+    if (inspectorsByType[type].length) {
       onNextTick(() => {
-        inspectorsByType[InspectorTypes.clientIdentityChanged].forEach(inspector => inspector.method(context));
+        inspectorsByType[type].forEach(inspector => inspector.method(context));
       });
     }
   };

package/src/SafeInspector.js

@@ -9,6 +9,7 @@ function SafeInspector(inspector, logger) {
   const wrapper = {
     type: inspector.type,
     name: inspector.name,
+    synchronous: inspector.synchronous,
   };
 
   wrapper.method = (...args) => {

package/src/__tests__/InspectorManager-test.js

@@ -28,7 +28,7 @@ describe('given an inspector manager with no registered inspectors', () => {
   });
 });
 
-describe('given an inspector with callbacks of every type', () => {
+describe.each([true, false])('given an inspector with callbacks of every type: synchronous: %p', synchronous => {
   /**
    * @type {AsyncQueue}
    */
@@ -39,6 +39,7 @@ describe('given an inspector with callbacks of every type', () => {
       {
         type: 'flag-used',
         name: 'my-flag-used-inspector',
+        synchronous,
         method: (flagKey, flagDetail, context) => {
           eventQueue.add({ type: 'flag-used', flagKey, flagDetail, context });
         },
@@ -47,6 +48,7 @@ describe('given an inspector with callbacks of every type', () => {
       {
         type: 'flag-used',
         name: 'my-other-flag-used-inspector',
+        synchronous,
         method: (flagKey, flagDetail, context) => {
           eventQueue.add({ type: 'flag-used', flagKey, flagDetail, context });
         },
@@ -54,6 +56,7 @@ describe('given an inspector with callbacks of every type', () => {
       {
         type: 'flag-details-changed',
         name: 'my-flag-details-inspector',
+        synchronous,
         method: details => {
           eventQueue.add({
             type: 'flag-details-changed',
@@ -64,6 +67,7 @@ describe('given an inspector with callbacks of every type', () => {
       {
         type: 'flag-detail-changed',
         name: 'my-flag-detail-inspector',
+        synchronous,
         method: (flagKey, flagDetail) => {
           eventQueue.add({
             type: 'flag-detail-changed',
@@ -75,6 +79,7 @@ describe('given an inspector with callbacks of every type', () => {
       {
         type: 'client-identity-changed',
         name: 'my-identity-inspector',
+        synchronous,
         method: context => {
           eventQueue.add({
             type: 'client-identity-changed',
@@ -85,6 +90,7 @@ describe('given an inspector with callbacks of every type', () => {
       // Invalid inspector shouldn't have an effect.
       {
         type: 'potato',
+        synchronous,
         name: 'my-potato-inspector',
         method: () => {},
       },

package/src/__tests__/LDClient-events-test.js

@@ -1,3 +1,4 @@
+// @ts-nocheck
 import * as messages from '../messages';
 
 import { withCloseable, sleepAsync } from 'launchdarkly-js-test-helpers';
@@ -253,6 +254,81 @@ describe('LDClient events', () => {
     });
   });
 
+  it('sends events for prerequisites', async () => {
+    const initData = makeBootstrap({
+      'is-prereq': {
+        value: true,
+        variation: 1,
+        reason: {
+          kind: 'FALLTHROUGH',
+        },
+        version: 1,
+        trackEvents: true,
+        trackReason: true,
+      },
+      'has-prereq-depth-1': {
+        value: true,
+        variation: 0,
+        prerequisites: ['is-prereq'],
+        reason: {
+          kind: 'FALLTHROUGH',
+        },
+        version: 4,
+        trackEvents: true,
+        trackReason: true,
+      },
+      'has-prereq-depth-2': {
+        value: true,
+        variation: 0,
+        prerequisites: ['has-prereq-depth-1'],
+        reason: {
+          kind: 'FALLTHROUGH',
+        },
+        version: 5,
+        trackEvents: true,
+        trackReason: true,
+      },
+    });
+    await withClientAndEventProcessor(user, { bootstrap: initData }, async (client, ep) => {
+      await client.waitForInitialization(5);
+      client.variation('has-prereq-depth-2', false);
+
+      // An identify event and 3 feature events.
+      expect(ep.events.length).toEqual(4);
+      expectIdentifyEvent(ep.events[0], user);
+      expect(ep.events[1]).toMatchObject({
+        kind: 'feature',
+        key: 'is-prereq',
+        variation: 1,
+        value: true,
+        version: 1,
+        reason: {
+          kind: 'FALLTHROUGH',
+        },
+      });
+      expect(ep.events[2]).toMatchObject({
+        kind: 'feature',
+        key: 'has-prereq-depth-1',
+        variation: 0,
+        value: true,
+        version: 4,
+        reason: {
+          kind: 'FALLTHROUGH',
+        },
+      });
+      expect(ep.events[3]).toMatchObject({
+        kind: 'feature',
+        key: 'has-prereq-depth-2',
+        variation: 0,
+        value: true,
+        version: 5,
+        reason: {
+          kind: 'FALLTHROUGH',
+        },
+      });
+    });
+  });
+
   it('sends a feature event on receiving a new flag value', async () => {
     const oldFlags = { foo: { value: 'a', variation: 1, version: 2, flagVersion: 2000 } };
     const newFlags = { foo: { value: 'b', variation: 2, version: 3, flagVersion: 2001 } };
@@ -327,6 +403,22 @@ describe('LDClient events', () => {
     });
   });
 
+  it('does not send duplicate events for prerequisites with all flags.', async () => {
+    const initData = makeBootstrap({
+      foo: { value: 'a', variation: 1, version: 2 },
+      bar: { value: 'b', variation: 1, version: 3, prerequisites: ['foo'] },
+    });
+    await withClientAndEventProcessor(user, { bootstrap: initData }, async (client, ep) => {
+      await client.waitForInitialization(5);
+      client.allFlags();
+
+      expect(ep.events.length).toEqual(3);
+      expectIdentifyEvent(ep.events[0], user);
+      expectFeatureEvent({ e: ep.events[1], key: 'foo', user, value: 'a', variation: 1, version: 2, defaultVal: null });
+      expectFeatureEvent({ e: ep.events[2], key: 'bar', user, value: 'b', variation: 1, version: 3, defaultVal: null });
+    });
+  });
+
   it('does not send feature events for allFlags() if sendEventsOnlyForVariation is set', async () => {
     const initData = makeBootstrap({
       foo: { value: 'a', variation: 1, version: 2 },

package/src/__tests__/LDClient-inspectors-test.js

@@ -5,12 +5,48 @@ const stubPlatform = require('./stubPlatform');
 const envName = 'UNKNOWN_ENVIRONMENT_ID';
 const context = { key: 'context-key' };
 
-describe('given a streaming client with registered inspectors', () => {
+const flagPayload = {
+  'is-prereq': {
+    value: true,
+    variation: 1,
+    reason: {
+      kind: 'FALLTHROUGH',
+    },
+    version: 1,
+    trackEvents: true,
+    trackReason: true,
+  },
+  'has-prereq-depth-1': {
+    value: true,
+    variation: 0,
+    prerequisites: ['is-prereq'],
+    reason: {
+      kind: 'FALLTHROUGH',
+    },
+    version: 4,
+    trackEvents: true,
+    trackReason: true,
+  },
+  'has-prereq-depth-2': {
+    value: true,
+    variation: 0,
+    prerequisites: ['has-prereq-depth-1'],
+    reason: {
+      kind: 'FALLTHROUGH',
+    },
+    version: 5,
+    trackEvents: true,
+    trackReason: true,
+  },
+};
+
+describe.each([true, false])('given a streaming client with registered inspectors, synchronous: %p', synchronous => {
   const eventQueue = new AsyncQueue();
 
   const inspectors = [
     {
       type: 'flag-used',
+      synchronous,
       method: (flagKey, flagDetail, context) => {
         eventQueue.add({ type: 'flag-used', flagKey, flagDetail, context });
       },
@@ -18,12 +54,14 @@ describe('given a streaming client with registered inspectors', () => {
     // 'flag-used registered twice.
     {
       type: 'flag-used',
+      synchronous,
       method: (flagKey, flagDetail, context) => {
         eventQueue.add({ type: 'flag-used', flagKey, flagDetail, context });
       },
     },
     {
       type: 'flag-details-changed',
+      synchronous,
       method: details => {
         eventQueue.add({
           type: 'flag-details-changed',
@@ -33,6 +71,7 @@ describe('given a streaming client with registered inspectors', () => {
     },
     {
       type: 'flag-detail-changed',
+      synchronous,
       method: (flagKey, flagDetail) => {
         eventQueue.add({
           type: 'flag-detail-changed',
@@ -43,6 +82,7 @@ describe('given a streaming client with registered inspectors', () => {
     },
     {
       type: 'client-identity-changed',
+      synchronous,
       method: context => {
         eventQueue.add({
           type: 'client-identity-changed',
@@ -58,7 +98,7 @@ describe('given a streaming client with registered inspectors', () => {
   beforeEach(async () => {
     platform = stubPlatform.defaults();
     const server = platform.testing.http.newServer();
-    server.byDefault(respondJson({}));
+    server.byDefault(respondJson(flagPayload));
     const config = { streaming: true, baseUrl: server.url, inspectors, sendEvents: false };
     client = platform.testing.makeClient(envName, context, config);
     await client.waitUntilReady();
@@ -86,7 +126,29 @@ describe('given a streaming client with registered inspectors', () => {
     const flagsEvent = await eventQueue.take();
     expect(flagsEvent).toMatchObject({
       type: 'flag-details-changed',
-      details: {},
+      details: {
+        'is-prereq': {
+          value: true,
+          variationIndex: 1,
+          reason: {
+            kind: 'FALLTHROUGH',
+          },
+        },
+        'has-prereq-depth-1': {
+          value: true,
+          variationIndex: 0,
+          reason: {
+            kind: 'FALLTHROUGH',
+          },
+        },
+        'has-prereq-depth-2': {
+          value: true,
+          variationIndex: 0,
+          reason: {
+            kind: 'FALLTHROUGH',
+          },
+        },
+      },
     });
   });
 
@@ -124,4 +186,51 @@ describe('given a streaming client with registered inspectors', () => {
       flagDetail: { value: false },
     });
   });
+
+  it('emits an event when a flag is used', async () => {
+    // Take initial events.
+    eventQueue.take();
+    eventQueue.take();
+
+    await platform.testing.eventSourcesCreated.take();
+    client.variation('is-prereq', false);
+    const updateEvent = await eventQueue.take();
+    expect(updateEvent).toMatchObject({
+      type: 'flag-used',
+      flagKey: 'is-prereq',
+      flagDetail: { value: true },
+    });
+    // Two inspectors are handling this
+    const updateEvent2 = await eventQueue.take();
+    expect(updateEvent2).toMatchObject({
+      type: 'flag-used',
+      flagKey: 'is-prereq',
+      flagDetail: { value: true },
+    });
+  });
+
+  it('does not execute flag-used for prerequisites', async () => {
+    // Take initial events.
+    eventQueue.take();
+    eventQueue.take();
+
+    await platform.testing.eventSourcesCreated.take();
+    client.variation('has-prereq-depth-2', false);
+    // There would be many more than 2 events if prerequisites were inspected.
+    const updateEvent = await eventQueue.take();
+    expect(updateEvent).toMatchObject({
+      type: 'flag-used',
+      flagKey: 'has-prereq-depth-2',
+      flagDetail: { value: true },
+    });
+    // Two inspectors are handling this
+    const updateEvent2 = await eventQueue.take();
+    expect(updateEvent2).toMatchObject({
+      type: 'flag-used',
+      flagKey: 'has-prereq-depth-2',
+      flagDetail: { value: true },
+    });
+
+    expect(eventQueue.length()).toEqual(0);
+  });
 });

package/src/index.js

@@ -299,18 +299,19 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
   }
 
   function variation(key, defaultValue) {
-    return variationDetailInternal(key, defaultValue, true, false, false).value;
+    return variationDetailInternal(key, defaultValue, true, false, false, true).value;
   }
 
   function variationDetail(key, defaultValue) {
-    return variationDetailInternal(key, defaultValue, true, true, false);
+    return variationDetailInternal(key, defaultValue, true, true, false, true);
   }
 
-  function variationDetailInternal(key, defaultValue, sendEvent, includeReasonInEvent, isAllFlags) {
+  function variationDetailInternal(key, defaultValue, sendEvent, includeReasonInEvent, isAllFlags, notifyInspection) {
     let detail;
+    let flag;
 
     if (flags && utils.objectHasOwnProperty(flags, key) && flags[key] && !flags[key].deleted) {
-      const flag = flags[key];
+      flag = flags[key];
       detail = getFlagDetail(flag);
       if (flag.value === null || flag.value === undefined) {
         detail.value = defaultValue;
@@ -320,11 +321,18 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
     }
 
     if (sendEvent) {
+      // For an all-flags evaluation, with events enabled, each flag will get an event, so we do not
+      // need to duplicate the prerequisites.
+      if (!isAllFlags) {
+        flag?.prerequisites?.forEach(key => {
+          variationDetailInternal(key, undefined, sendEvent, false, false, false);
+        });
+      }
       sendFlagEvent(key, detail, defaultValue, includeReasonInEvent);
     }
 
     // For the all flags case `onFlags` will be called instead.
-    if (!isAllFlags) {
+    if (!isAllFlags && notifyInspection) {
       notifyInspectionFlagUsed(key, detail);
     }
 
@@ -351,7 +359,14 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
 
     for (const key in flags) {
       if (utils.objectHasOwnProperty(flags, key) && !flags[key].deleted) {
-        results[key] = variationDetailInternal(key, null, !options.sendEventsOnlyForVariation, false, true).value;
+        results[key] = variationDetailInternal(
+          key,
+          null,
+          !options.sendEventsOnlyForVariation,
+          false,
+          true,
+          false
+        ).value;
       }
     }
 
@@ -462,8 +477,8 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
           } else {
             mods[data.key] = { current: newDetail };
           }
-          handleFlagChanges(mods); // don't wait for this Promise to be resolved
           notifyInspectionFlagChanged(data, newFlag);
+          handleFlagChanges(mods); // don't wait for this Promise to be resolved
         } else {
           logger.debug(messages.debugStreamPatchIgnored(data.key));
         }

package/src/messages.js

@@ -15,7 +15,7 @@ const clientInitialized = function() {
 };
 
 const docLink =
-  ' Please see https://docs.launchdarkly.com/sdk/client-side/javascript#initializing-the-client for instructions on SDK initialization.';
+  ' Please see https://docs.launchdarkly.com/sdk/client-side/javascript#initialize-the-client for instructions on SDK initialization.';
 
 const clientNotReady = function() {
   return 'LaunchDarkly client is not ready';

package/typedoc.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "name": "launchdarkly-js-sdk-common",
+  "includeVersion": true,
+  "entryPoints": [
+      "typings.d.ts",
+  ]
+}

package/typings.d.ts

@@ -552,7 +552,7 @@ declare module 'launchdarkly-js-sdk-common' {
 
   /**
    * Describes the reason that a flag evaluation produced a particular value. This is
-   * part of the {@link LDEvaluationDetail} object returned by {@link LDClient.variationDetail]].
+   * part of the {@link LDEvaluationDetail} object returned by {@link LDClient.variationDetail}.
    */
   export interface LDEvaluationReason {
     /**
@@ -588,6 +588,14 @@ declare module 'launchdarkly-js-sdk-common' {
      * The key of the failed prerequisite flag, if the kind was `'PREREQUISITE_FAILED'`.
      */
     prerequisiteKey?: string;
+
+    /**
+     * Whether the evaluation was part of an experiment.
+     *
+     * This is true if the evaluation resulted in an experiment rollout and served one of
+     * the variations in the experiment. Otherwise it is false or undefined.
+     */
+    inExperiment?: boolean;
   }
 
   /**
@@ -1013,6 +1021,13 @@ declare module 'launchdarkly-js-sdk-common' {
      */
     name: string;
 
+    /**
+     * If `true`, then the inspector will be ran synchronously with evaluation.
+     * Synchronous inspectors execute inline with evaluation and care should be taken to ensure
+     * they have minimal performance overhead.
+     */
+    synchronous?: boolean,
+
     /**
      * This method is called when a flag is accessed via a variation method, or it can be called based on actions in
      * wrapper SDKs which have different methods of tracking when a flag was accessed. It is not called when a call is made
@@ -1040,6 +1055,11 @@ declare module 'launchdarkly-js-sdk-common' {
      */
     name: string;
 
+    /**
+     * If `true`, then the inspector will be ran synchronously with flag updates.
+     */
+    synchronous?: boolean,
+
     /**
      * This method is called when the flags in the store are replaced with new flags. It will contain all flags
      * regardless of if they have been evaluated.
@@ -1065,6 +1085,11 @@ declare module 'launchdarkly-js-sdk-common' {
      */
     name: string;
 
+    /**
+     * If `true`, then the inspector will be ran synchronously with flag updates.
+     */
+    synchronous?: boolean,
+
     /**
      * This method is called when a flag is updated. It will not be called
      * when all flags are updated.
@@ -1088,6 +1113,11 @@ declare module 'launchdarkly-js-sdk-common' {
      */
     name: string;
 
+    /**
+     * If `true`, then the inspector will be ran synchronously with identification.
+     */
+    synchronous?: boolean,
+
     /**
      * This method will be called when an identify operation completes.
      */

package/.circleci/config.yml

@@ -1,22 +0,0 @@
-version: 2
-jobs:
-  build:
-    docker:
-      - image: cimg/node:12.22
-    steps:
-      - checkout
-
-      - run: npm install
-      - run: npm run lint:all
-      - run:
-          command: npm test
-          environment:
-            JEST_JUNIT_OUTPUT: "reports/junit/js-test-results.xml"
-      - run: npm run check-typescript
-      - run:
-          name: dependency audit
-          command: ./scripts/better-audit.sh
-      - store_test_results:
-          path: reports/junit/
-      - store_artifacts:
-          path: reports/junit/

package/.ldrelease/config.yml

@@ -1,25 +0,0 @@
-version: 2
-
-repo:
-  public: js-sdk-common
-  private: js-sdk-common-private
-
-branches:
-  - name: main
-    description: 5.x
-  - name: 4.x
-  - name: 3.x
-
-publications:
-  - url: https://www.npmjs.com/package/launchdarkly-js-sdk-common
-    description: npm
-
-jobs:
-  - docker:
-      image: node:12-buster
-    template:
-      name: npm
-
-documentation:
-  gitHubPages: true
-  title: LaunchDarkly Javascript SDK Core Components

package/docs/typedoc.js

@@ -1,11 +0,0 @@
-module.exports = {
-  out: '/tmp/project-releaser/project/docs/build/html',
-  exclude: [
-    '**/node_modules/**',
-    'test-types.ts'
-  ],
-  name: "LaunchDarkly Javascript SDK Core Components (4.0.2)",
-  readme: 'none',                // don't add a home page with a copy of README.md
-  entryPoints: "/tmp/project-releaser/project/typings.d.ts",
-  entryPointStrategy: "expand"
-};