launchdarkly-js-sdk-common 5.7.1 → 5.8.1

package/src/index.js

@@ -18,7 +18,13 @@ const { checkContext, getContextKeys } = require('./context');
 const { InspectorTypes, InspectorManager } = require('./InspectorManager');
 const timedPromise = require('./timedPromise');
 const createHookRunner = require('./HookRunner');
-const { getPluginHooks, registerPlugins, createPluginEnvironment } = require('./plugins');
+const FlagStore = require('./FlagStore');
+const {
+  getPluginHooks,
+  registerPlugins,
+  registerPluginsForDebugOverride,
+  createPluginEnvironment,
+} = require('./plugins');
 const changeEvent = 'change';
 const internalChangeEvent = 'internal-change';
 const highTimeoutThreshold = 5;
@@ -76,7 +82,8 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
 
   const requestor = Requestor(platform, options, environment);
 
-  let flags = {};
+  const flagStore = FlagStore();
+
   let useLocalStorage;
   let streamActive;
   let streamForcedState = options.streaming;
@@ -188,7 +195,7 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
   function notifyInspectionFlagsChanged() {
     if (inspectorManager.hasListeners(InspectorTypes.flagDetailsChanged)) {
       inspectorManager.onFlags(
-        Object.entries(flags)
+        Object.entries(flagStore.getFlagsWithOverrides())
           .map(([key, value]) => ({ key, detail: getFlagDetail(value) }))
           .reduce((acc, cur) => {
             // eslint-disable-next-line no-param-reassign
@@ -232,7 +239,7 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
       default: defaultValue,
       creationDate: now.getTime(),
     };
-    const flag = flags[key];
+    const flag = flagStore.getFlags()[key];
     if (flag) {
       event.version = flag.flagVersion ? flag.flagVersion : flag.version;
       event.trackEvents = flag.trackEvents;
@@ -262,7 +269,10 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
     if (stateProvider) {
       // We're being controlled by another client instance, so only that instance is allowed to change the context
       logger.warn(messages.identifyDisabled());
-      return utils.wrapPromiseCallback(Promise.resolve(utils.transformVersionedValuesToValues(flags)), onDone);
+      return utils.wrapPromiseCallback(
+        Promise.resolve(utils.transformVersionedValuesToValues(flagStore.getFlagsWithOverrides())),
+        onDone
+      );
     }
     let afterIdentify;
     const clearFirst = useLocalStorage && persistentFlagStore ? persistentFlagStore.clearFlags() : Promise.resolve();
@@ -328,10 +338,10 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
 
   function variationDetailInternal(key, defaultValue, sendEvent, includeReasonInEvent, isAllFlags, notifyInspection) {
     let detail;
-    let flag;
 
-    if (flags && utils.objectHasOwnProperty(flags, key) && flags[key] && !flags[key].deleted) {
-      flag = flags[key];
+    const flag = flagStore.get(key);
+
+    if (flag) {
       detail = getFlagDetail(flag);
       if (flag.value === null || flag.value === undefined) {
         detail.value = defaultValue;
@@ -373,21 +383,14 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
   function allFlags() {
     const results = {};
 
-    if (!flags) {
+    const allFlags = flagStore.getFlagsWithOverrides();
+
+    if (!allFlags) {
       return results;
     }
 
-    for (const key in flags) {
-      if (utils.objectHasOwnProperty(flags, key) && !flags[key].deleted) {
-        results[key] = variationDetailInternal(
-          key,
-          null,
-          !options.sendEventsOnlyForVariation,
-          false,
-          true,
-          false
-        ).value;
-      }
+    for (const key in allFlags) {
+      results[key] = variationDetailInternal(key, null, !options.sendEventsOnlyForVariation, false, true, false).value;
     }
 
     return results;
@@ -485,6 +488,7 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
         // If both the flag and the patch have a version property, then the patch version must be
         // greater than the flag version for us to accept the patch.  If either one has no version
         // then the patch always succeeds.
+        const flags = flagStore.getFlags();
         const oldFlag = flags[data.key];
         if (!oldFlag || !oldFlag.version || !data.version || oldFlag.version < data.version) {
           logger.debug(messages.debugStreamPatch(data.key));
@@ -492,6 +496,7 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
           const newFlag = utils.extend({}, data);
           delete newFlag['key'];
           flags[data.key] = newFlag;
+          flagStore.setFlags(flags);
           const newDetail = getFlagDetail(newFlag);
           if (oldFlag) {
             mods[data.key] = { previous: oldFlag.value, current: newDetail };
@@ -509,6 +514,7 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
         if (!data) {
           return;
         }
+        const flags = flagStore.getFlags();
         if (!flags[data.key] || flags[data.key].version < data.version) {
           logger.debug(messages.debugStreamDelete(data.key));
           const mods = {};
@@ -516,6 +522,7 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
             mods[data.key] = { previous: flags[data.key].value };
           }
           flags[data.key] = { version: data.version, deleted: true };
+          flagStore.setFlags(flags);
           notifyInspectionFlagChanged(data, flags[data.key]);
           handleFlagChanges(mods); // don't wait for this Promise to be resolved
         } else {
@@ -542,6 +549,7 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
       return Promise.resolve();
     }
 
+    const flags = flagStore.getFlags();
     for (const key in flags) {
       if (utils.objectHasOwnProperty(flags, key) && flags[key]) {
         if (newFlags[key] && !utils.deepEquals(newFlags[key].value, flags[key].value)) {
@@ -557,7 +565,7 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
       }
     }
 
-    flags = { ...newFlags };
+    flagStore.setFlags({ ...newFlags });
 
     notifyInspectionFlagsChanged();
 
@@ -580,7 +588,7 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
       });
 
       emitter.emit(changeEvent, changeEventParams);
-      emitter.emit(internalChangeEvent, flags);
+      emitter.emit(internalChangeEvent, flagStore.getFlagsWithOverrides());
 
       // By default, we send feature evaluation events whenever we have received new flag values -
       // the client has in effect evaluated these flags just by receiving them. This can be suppressed
@@ -595,7 +603,7 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
     }
 
     if (useLocalStorage && persistentFlagStore) {
-      return persistentFlagStore.saveFlags(flags);
+      return persistentFlagStore.saveFlags(flagStore.getFlags());
     } else {
       return Promise.resolve();
     }
@@ -666,7 +674,7 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
   if (typeof options.bootstrap === 'object') {
     // Set the flags as soon as possible before we get into any async code, so application code can read
     // them even if the ready event has not yet fired.
-    flags = readFlagsFromBootstrap(options.bootstrap);
+    flagStore.setFlags(readFlagsFromBootstrap(options.bootstrap));
   }
 
   if (stateProvider) {
@@ -718,7 +726,7 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
   function finishInitWithLocalStorage() {
     return persistentFlagStore.loadFlags().then(storedFlags => {
       if (storedFlags === null || storedFlags === undefined) {
-        flags = {};
+        flagStore.setFlags({});
         return requestor
           .fetchFlagSettings(ident.getContext(), hash)
           .then(requestedFlags => replaceAllFlags(requestedFlags || {}))
@@ -731,7 +739,7 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
         // We're reading the flags from local storage. Signal that we're ready,
         // then update localStorage for the next page load. We won't signal changes or update
         // the in-memory flags unless you subscribe for changes
-        flags = storedFlags;
+        flagStore.setFlags(storedFlags);
         utils.onNextTick(signalSuccessfulInit);
 
         return requestor
@@ -746,14 +754,14 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
     return requestor
       .fetchFlagSettings(ident.getContext(), hash)
       .then(requestedFlags => {
-        flags = requestedFlags || {};
+        flagStore.setFlags(requestedFlags || {});
 
         notifyInspectionFlagsChanged();
         // Note, we don't need to call updateSettings here because local storage and change events are not relevant
         signalSuccessfulInit();
       })
       .catch(err => {
-        flags = {};
+        flagStore.setFlags({});
         signalFailedInit(err);
       });
   }
@@ -761,7 +769,7 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
   function initFromStateProvider(state) {
     environment = state.environment;
     ident.setContext(state.context);
-    flags = { ...state.flags };
+    flagStore.setFlags({ ...state.flags });
     utils.onNextTick(signalSuccessfulInit);
   }
 
@@ -800,7 +808,7 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
     }
     const finishClose = () => {
       closed = true;
-      flags = {};
+      flagStore.setFlags({});
     };
     const p = Promise.resolve()
       .then(() => {
@@ -820,7 +828,7 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
 
   function getFlagsInternal() {
     // used by Electron integration
-    return flags;
+    return flagStore.getFlagsWithOverrides();
   }
 
   function waitForInitializationWithTimeout(timeout) {
@@ -880,6 +888,94 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
 
   registerPlugins(logger, pluginEnvironment, client, plugins);
 
+  function setOverride(key, value) {
+    const mods = {};
+
+    const currentFlag = flagStore.get(key);
+    const currentValue = currentFlag ? currentFlag.value : null;
+
+    if (currentValue === value) {
+      logger.debug(`setOverride: No change needed for ${key}, value already ${value}`);
+      return;
+    }
+
+    flagStore.setOverride(key, value);
+    const newFlag = flagStore.get(key);
+    const newDetail = getFlagDetail(newFlag);
+
+    mods[key] = { previous: currentValue, current: newDetail };
+
+    notifyInspectionFlagChanged({ key }, newFlag);
+    handleFlagChanges(mods);
+  }
+
+  function removeOverride(key) {
+    const flagOverrides = flagStore.getFlagOverrides();
+    if (!flagOverrides[key]) {
+      return; // No override to remove
+    }
+
+    const mods = {};
+    const oldOverride = flagOverrides[key];
+    const flags = flagStore.getFlags();
+    const realFlag = flags[key];
+
+    mods[key] = { previous: oldOverride.value, current: realFlag ? getFlagDetail(realFlag) : undefined };
+
+    flagStore.removeOverride(key);
+    notifyInspectionFlagChanged({ key }, realFlag);
+    handleFlagChanges(mods); // don't wait for this Promise to be resolved
+  }
+
+  function clearAllOverrides() {
+    const flagOverrides = flagStore.getFlagOverrides();
+    if (Object.keys(flagOverrides).length === 0) {
+      return; // No overrides to clear
+    }
+
+    const mods = {};
+    const flags = flagStore.getFlags();
+    Object.keys(flagOverrides).forEach(key => {
+      const oldOverride = flagOverrides[key];
+      const realFlag = flags[key];
+
+      mods[key] = { previous: oldOverride.value, current: realFlag ? getFlagDetail(realFlag) : undefined };
+    });
+
+    flagStore.clearAllOverrides();
+
+    if (Object.keys(mods).length > 0) {
+      handleFlagChanges(mods); // don't wait for this Promise to be resolved
+    }
+  }
+
+  function getAllOverrides() {
+    const flagOverrides = flagStore.getFlagOverrides();
+
+    if (!flagOverrides) {
+      return {}; // No overrides set
+    }
+
+    const result = {};
+    Object.keys(flagOverrides).forEach(key => {
+      const override = flagOverrides[key];
+      if (override) {
+        result[key] = override.value;
+      }
+    });
+    return result;
+  }
+
+  const debugOverride = {
+    setOverride: setOverride,
+    removeOverride: removeOverride,
+    clearAllOverrides: clearAllOverrides,
+    getAllOverrides: getAllOverrides,
+  };
+
+  // Register plugins for debug override capabilities
+  registerPluginsForDebugOverride(logger, debugOverride, plugins);
+
   return {
     client: client, // The client object containing all public methods.
     options: options, // The validated configuration object, including all defaults.

package/src/plugins.js

@@ -56,6 +56,22 @@ function registerPlugins(logger, environmentMetadata, client, plugins) {
   });
 }
 
+/**
+ * Registers plugins for debug override capabilities
+ * @param {{ error: (message: string) => void }} logger - The logger instance
+ * @param {Object} debugOverride - The debug override interface object
+ * @param {Array<{registerDebug?: (debugOverride: object) => void}>} plugins - Array of plugin objects that may implement registerDebug
+ */
+function registerPluginsForDebugOverride(logger, debugOverride, plugins) {
+  plugins.forEach(plugin => {
+    try {
+      plugin.registerDebug?.(debugOverride);
+    } catch (error) {
+      logger.error(`Exception thrown registering debug override with plugin ${getPluginName(logger, plugin)}.`);
+    }
+  });
+}
+
 /**
  * Creates a plugin environment object
  * @param {{userAgent: string, version: string}} platform - The platform object
@@ -105,5 +121,6 @@ function createPluginEnvironment(platform, env, options) {
 module.exports = {
   getPluginHooks,
   registerPlugins,
+  registerPluginsForDebugOverride,
   createPluginEnvironment,
 };

package/src/uuid.js

@@ -0,0 +1,70 @@
+/* global crypto */
+// The implementation in this file generates UUIDs in v4 format and is suitable
+// for use as a UUID in LaunchDarkly events. It is not a rigorous implementation.
+//
+// Adapted from:
+// https://github.com/launchdarkly/js-core/blob/main/packages/sdk/browser/src/platform/randomUuidV4.ts
+
+// It uses crypto.randomUUID when available.
+// If crypto.randomUUID is not available, then it uses random values and forms
+// the UUID itself.
+// When possible it uses crypto.getRandomValues, but it can use Math.random
+// if crypto.getRandomValues is not available.
+
+// UUIDv4 Struct definition.
+// https://www.rfc-archive.org/getrfc.php?rfc=4122
+// Appendix A.  Appendix A - Sample Implementation
+const timeLow = { start: 0, end: 3 };
+const timeMid = { start: 4, end: 5 };
+const timeHiAndVersion = { start: 6, end: 7 };
+const clockSeqHiAndReserved = { start: 8, end: 8 };
+const clockSeqLow = { start: 9, end: 9 };
+const nodes = { start: 10, end: 15 };
+
+function getRandom128bit() {
+  if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+    const typedArray = new Uint8Array(16);
+    crypto.getRandomValues(typedArray);
+    return [...typedArray.values()];
+  }
+  const values = [];
+  for (let index = 0; index < 16; index += 1) {
+    values.push(Math.floor(Math.random() * 256));
+  }
+  return values;
+}
+
+function hex(bytes, range) {
+  let strVal = '';
+  for (let index = range.start; index <= range.end; index += 1) {
+    strVal += bytes[index].toString(16).padStart(2, '0');
+  }
+  return strVal;
+}
+
+function formatDataAsUuidV4(bytes) {
+  // eslint-disable-next-line no-bitwise, no-param-reassign
+  bytes[clockSeqHiAndReserved.start] = (bytes[clockSeqHiAndReserved.start] | 0x80) & 0xbf;
+  // eslint-disable-next-line no-bitwise, no-param-reassign
+  bytes[timeHiAndVersion.start] = (bytes[timeHiAndVersion.start] & 0x0f) | 0x40;
+
+  return (
+    `${hex(bytes, timeLow)}-${hex(bytes, timeMid)}-${hex(bytes, timeHiAndVersion)}-` +
+    `${hex(bytes, clockSeqHiAndReserved)}${hex(bytes, clockSeqLow)}-${hex(bytes, nodes)}`
+  );
+}
+
+function fallbackUuidV4() {
+  const bytes = getRandom128bit();
+  return formatDataAsUuidV4(bytes);
+}
+
+function randomUuidV4() {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID();
+  }
+
+  return fallbackUuidV4();
+}
+
+module.exports = { randomUuidV4, fallbackUuidV4, formatDataAsUuidV4 };

package/test-types.ts

@@ -55,7 +55,7 @@ const plugin: ld.LDPlugin = {
   }),
   register(client: ld.LDClientBase, environmentMetadata: ld.LDPluginEnvironmentMetadata): void {
   },
-
+  registerDebug(debugOverride: ld.LDDebugOverride): void {},
   getHooks(metadata: ld.LDPluginEnvironmentMetadata): ld.Hook[] {
     return [];
   },

package/typings.d.ts

@@ -74,7 +74,7 @@ declare module 'launchdarkly-js-sdk-common' {
   }
 
   /**
-   * Meta-data about a hook implementation.
+   * Metadata about a hook implementation.
    */
   export interface HookMetadata {
     /**
@@ -149,7 +149,6 @@ declare module 'launchdarkly-js-sdk-common' {
     readonly metricValue?: number;
   }
 
-
   /**
    * Interface for extending SDK functionality via hooks.
    */
@@ -251,7 +250,7 @@ declare module 'launchdarkly-js-sdk-common' {
   }
 
   /**
-   * Meta-data about a plugin implementation.
+   * Metadata about a plugin implementation.
    *
    * May be used in logs and analytics to identify the plugin.
    */
@@ -363,6 +362,59 @@ export interface LDPlugin {
    * @param metadata
    */
   getHooks?(metadata: LDPluginEnvironmentMetadata): Hook[];
+
+  /**
+   * An optional function called if the plugin wants to register debug capabilities.
+   * This method allows plugins to receive a debug override interface for
+   * temporarily overriding flag values during development and testing.
+   *
+   * @experimental This interface is experimental and intended for use by LaunchDarkly tools at this time.
+   * The API may change in future versions.
+   *
+   * @param debugOverride The debug override interface instance
+   */
+  registerDebug?(debugOverride: LDDebugOverride): void;
+}
+
+/**
+ * Debug interface for plugins that need to override flag values during development.
+ * This interface provides methods to temporarily override flag values that take
+ * precedence over the actual flag values from LaunchDarkly. These overrides are
+ * useful for testing, development, and debugging scenarios.
+ *
+ * @experimental This interface is experimental and intended for use by LaunchDarkly tools at this time.
+ * The API may change in future versions.
+ */
+export interface LDDebugOverride {
+  /**
+   * Set an override value for a flag that takes precedence over the real flag value.
+   *
+   * @param flagKey The flag key.
+   * @param value The override value.
+   */
+  setOverride(flagKey: string, value: LDFlagValue): void;
+
+  /**
+   * Remove an override value for a flag, reverting to the real flag value.
+   *
+   * @param flagKey The flag key.
+   */
+  removeOverride(flagKey: string): void;
+
+  /**
+   * Clear all override values, reverting all flags to their real values.
+   */
+  clearAllOverrides(): void;
+
+  /**
+   * Get all currently active flag overrides.
+   *
+   * @returns
+   *   An object containing all active overrides as key-value pairs,
+   *   where keys are flag keys and values are the overridden flag values.
+   *   Returns an empty object if no overrides are active.
+   */
+  getAllOverrides(): LDFlagSet;
 }
 
   /**

package/.github/workflows/manual-publish.yml

@@ -1,42 +0,0 @@
-name: Manual Publish Package
-on:
-  workflow_dispatch:
-    inputs:
-      dry-run:
-        description: 'Is this a dry run. If so no package will be published.'
-        type: boolean
-        required: true
-      prerelease:
-          description: 'Is this a prerelease. If so, then the latest tag will not be updated in npm.'
-          type: boolean
-          required: true
-
-jobs:
-  publish-package:
-    runs-on: ubuntu-latest
-    permissions:
-      id-token: write
-      contents: write
-    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: ${{ inputs.dry-run }}
-          prerelease: ${{ inputs.prerelease }}