launchdarkly-js-sdk-common 5.2.0 → 5.3.0

package/.circleci/config.yml

@@ -2,7 +2,7 @@ version: 2
 jobs:
   build:
     docker:
-      - image: cimg/node:12.22
+      - image: cimg/node:22.2.0
     steps:
       - checkout
 

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.3.0"
+}

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 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.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.3.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,8 @@
+{
+  "bootstrap-sha": "d49ca41718a593c071874950d301f2f00c71a371",
+  "packages": {
+    ".": {
+      "release-type": "node"
+    }
+  }
+}

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-inspectors-test.js

@@ -5,12 +5,13 @@ const stubPlatform = require('./stubPlatform');
 const envName = 'UNKNOWN_ENVIRONMENT_ID';
 const context = { key: 'context-key' };
 
-describe('given a streaming client with registered inspectors', () => {
+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 +19,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 +36,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 +47,7 @@ describe('given a streaming client with registered inspectors', () => {
     },
     {
       type: 'client-identity-changed',
+      synchronous,
       method: context => {
         eventQueue.add({
           type: 'client-identity-changed',

package/src/index.js

@@ -462,8 +462,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

@@ -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/.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"
-};