launchdarkly-js-sdk-common 5.4.0 → 5.5.0-beta.2

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

@@ -0,0 +1,42 @@
+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 }}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "launchdarkly-js-sdk-common",
-  "version": "5.4.0",
+  "version": "5.5.0-beta.2",
   "description": "LaunchDarkly SDK for JavaScript - common code",
   "author": "LaunchDarkly <team@launchdarkly.com>",
   "license": "Apache-2.0",

package/src/HookRunner.js

@@ -0,0 +1,119 @@
+const UNKNOWN_HOOK_NAME = 'unknown hook';
+const BEFORE_EVALUATION_STAGE_NAME = 'beforeEvaluation';
+const AFTER_EVALUATION_STAGE_NAME = 'afterEvaluation';
+
+function tryExecuteStage(logger, method, hookName, stage, def) {
+  try {
+    return stage();
+  } catch (err) {
+    logger?.error(`An error was encountered in "${method}" of the "${hookName}" hook: ${err}`);
+    return def;
+  }
+}
+
+function getHookName(logger, hook) {
+  try {
+    return hook.getMetadata().name || UNKNOWN_HOOK_NAME;
+  } catch {
+    logger.error(`Exception thrown getting metadata for hook. Unable to get hook name.`);
+    return UNKNOWN_HOOK_NAME;
+  }
+}
+
+function executeBeforeEvaluation(logger, hooks, hookContext) {
+  return hooks.map(hook =>
+    tryExecuteStage(
+      logger,
+      BEFORE_EVALUATION_STAGE_NAME,
+      getHookName(logger, hook),
+      () => hook?.beforeEvaluation?.(hookContext, {}) ?? {},
+      {}
+    )
+  );
+}
+
+function executeAfterEvaluation(logger, hooks, hookContext, updatedData, result) {
+  // This iterates in reverse, versus reversing a shallow copy of the hooks,
+  // for efficiency.
+  for (let hookIndex = hooks.length - 1; hookIndex >= 0; hookIndex -= 1) {
+    const hook = hooks[hookIndex];
+    const data = updatedData[hookIndex];
+    tryExecuteStage(
+      logger,
+      AFTER_EVALUATION_STAGE_NAME,
+      getHookName(logger, hook),
+      () => hook?.afterEvaluation?.(hookContext, data, result) ?? {},
+      {}
+    );
+  }
+}
+
+function executeBeforeIdentify(logger, hooks, hookContext) {
+  return hooks.map(hook =>
+    tryExecuteStage(
+      logger,
+      BEFORE_EVALUATION_STAGE_NAME,
+      getHookName(logger, hook),
+      () => hook?.beforeIdentify?.(hookContext, {}) ?? {},
+      {}
+    )
+  );
+}
+
+function executeAfterIdentify(logger, hooks, hookContext, updatedData, result) {
+  // This iterates in reverse, versus reversing a shallow copy of the hooks,
+  // for efficiency.
+  for (let hookIndex = hooks.length - 1; hookIndex >= 0; hookIndex -= 1) {
+    const hook = hooks[hookIndex];
+    const data = updatedData[hookIndex];
+    tryExecuteStage(
+      logger,
+      AFTER_EVALUATION_STAGE_NAME,
+      getHookName(logger, hook),
+      () => hook?.afterIdentify?.(hookContext, data, result) ?? {},
+      {}
+    );
+  }
+}
+
+class HookRunner {
+  constructor(logger, initialHooks) {
+    this._logger = logger;
+    this._hooks = initialHooks ? [...initialHooks] : [];
+  }
+
+  withEvaluation(key, context, defaultValue, method) {
+    if (this._hooks.length === 0) {
+      return method();
+    }
+    const hooks = [...this._hooks];
+    const hookContext = {
+      flagKey: key,
+      context,
+      defaultValue,
+    };
+
+    const hookData = executeBeforeEvaluation(this._logger, hooks, hookContext);
+    const result = method();
+    executeAfterEvaluation(this._logger, hooks, hookContext, hookData, result);
+    return result;
+  }
+
+  identify(context, timeout) {
+    const hooks = [...this._hooks];
+    const hookContext = {
+      context,
+      timeout,
+    };
+    const hookData = executeBeforeIdentify(this._logger, hooks, hookContext);
+    return result => {
+      executeAfterIdentify(this._logger, hooks, hookContext, hookData, result);
+    };
+  }
+
+  addHook(hook) {
+    this._hooks.push(hook);
+  }
+}
+
+module.exports = HookRunner;

package/src/index.js

@@ -17,6 +17,7 @@ const messages = require('./messages');
 const { checkContext, getContextKeys } = require('./context');
 const { InspectorTypes, InspectorManager } = require('./InspectorManager');
 const timedPromise = require('./timedPromise');
+const HookRunner = require('./HookRunner');
 
 const changeEvent = 'change';
 const internalChangeEvent = 'internal-change';
@@ -40,6 +41,7 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
   const sendEvents = options.sendEvents;
   let environment = env;
   let hash = options.hash;
+  const hookRunner = new HookRunner(logger, options.hooks);
 
   const persistentStorage = PersistentStorage(platform.localStorage, logger);
 
@@ -256,11 +258,16 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
       logger.warn(messages.identifyDisabled());
       return utils.wrapPromiseCallback(Promise.resolve(utils.transformVersionedValuesToValues(flags)), onDone);
     }
+    let afterIdentify;
     const clearFirst = useLocalStorage && persistentFlagStore ? persistentFlagStore.clearFlags() : Promise.resolve();
     return utils.wrapPromiseCallback(
       clearFirst
         .then(() => anonymousContextProcessor.processContext(context))
         .then(verifyContext)
+        .then(context => {
+          afterIdentify = hookRunner.identify(context, undefined);
+          return context;
+        })
         .then(validatedContext =>
           requestor
             .fetchFlagSettings(validatedContext, newHash)
@@ -277,12 +284,14 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
             })
         )
         .then(flagValueMap => {
+          afterIdentify?.({ status: 'completed' });
           if (streamActive) {
             connectStream();
           }
           return flagValueMap;
         })
         .catch(err => {
+          afterIdentify?.({ status: 'error' });
           emitter.maybeReportError(err);
           return Promise.reject(err);
         }),
@@ -299,11 +308,16 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
   }
 
   function variation(key, defaultValue) {
-    return variationDetailInternal(key, defaultValue, true, false, false, true).value;
+    const { value } = hookRunner.withEvaluation(key, ident.getContext(), defaultValue, () =>
+      variationDetailInternal(key, defaultValue, true, false, false, true)
+    );
+    return value;
   }
 
   function variationDetail(key, defaultValue) {
-    return variationDetailInternal(key, defaultValue, true, true, false, true);
+    return hookRunner.withEvaluation(key, ident.getContext(), defaultValue, () =>
+      variationDetailInternal(key, defaultValue, true, true, false, true)
+    );
   }
 
   function variationDetailInternal(key, defaultValue, sendEvent, includeReasonInEvent, isAllFlags, notifyInspection) {
@@ -826,6 +840,10 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
     return initializationStateTracker.getInitializationPromise();
   }
 
+  function addHook(hook) {
+    hookRunner.addHook(hook);
+  }
+
   const client = {
     waitForInitialization,
     waitUntilReady: () => initializationStateTracker.getReadyPromise(),
@@ -840,6 +858,7 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
     flush: flush,
     allFlags: allFlags,
     close: close,
+    addHook: addHook,
   };
 
   return {

package/typings.d.ts

@@ -40,6 +40,184 @@ declare module 'launchdarkly-js-sdk-common' {
     error: (message: string) => void;
   }
 
+  /**
+   * Contextual information provided to evaluation stages.
+   */
+  export interface EvaluationSeriesContext {
+    /**
+     * The flag key the evaluation is for.
+     */
+    readonly flagKey: string;
+    /**
+     * Optional in case evaluations are performed before a context is set.
+     */
+    readonly context?: LDContext;
+    /**
+     * The default value that was provided.
+     */
+    readonly defaultValue: unknown;
+
+    /**
+     * Implementation note: Omitting method name because of the associated size.
+     * If we need this functionality, then we may want to consider adding it and
+     * taking the associated size hit.
+     */
+  }
+
+  /**
+   * Implementation specific hook data for evaluation stages.
+   *
+   * Hook implementations can use this to store data needed between stages.
+   */
+  export interface EvaluationSeriesData {
+    readonly [index: string]: unknown;
+  }
+
+  /**
+   * Meta-data about a hook implementation.
+   */
+  export interface HookMetadata {
+    /**
+     * Name of the hook.
+     */
+    readonly name: string;
+  }
+
+  /**
+   * Contextual information provided to identify stages.
+   */
+  export interface IdentifySeriesContext {
+    /**
+     * The context associated with the identify operation.
+     */
+    readonly context: LDContext;
+    /**
+     * The timeout, in seconds, associated with the identify operation.
+     */
+    readonly timeout?: number;
+  }
+
+  /**
+   * Implementation specific hook data for identify stages.
+   *
+   * Hook implementations can use this to store data needed between stages.
+   */
+  export interface IdentifySeriesData {
+    readonly [index: string]: unknown;
+  }
+
+  /**
+   * The status an identify operation completed with.
+   *
+   * An example in which an error may occur is lack of network connectivity
+   * preventing the SDK from functioning.
+   */
+  export type IdentifySeriesStatus = 'completed' | 'error';
+
+  /**
+   * The result applies to a single identify operation. An operation may complete
+   * with an error and then later complete successfully. Only the first completion
+   * will be executed in the identify series.
+   *
+   * For example, a network issue may cause an identify to error since the SDK
+   * can't refresh its cached data from the cloud at that moment, but then later
+   * the when the network issue is resolved, the SDK will refresh cached data.
+   */
+  export interface IdentifySeriesResult {
+    status: IdentifySeriesStatus;
+  }
+
+  /**
+   * Interface for extending SDK functionality via hooks.
+   */
+  export interface Hook {
+    /**
+     * Get metadata about the hook implementation.
+     */
+    getMetadata(): HookMetadata;
+
+    /**
+     * This method is called during the execution of a variation method
+     * before the flag value has been determined. The method is executed synchronously.
+     *
+     * @param hookContext Contains information about the evaluation being performed. This is not
+     *  mutable.
+     * @param data A record associated with each stage of hook invocations. Each stage is called with
+     * the data of the previous stage for a series. The input record should not be modified.
+     * @returns Data to use when executing the next state of the hook in the evaluation series. It is
+     * recommended to expand the previous input into the return. This helps ensure your stage remains
+     * compatible moving forward as more stages are added.
+     * ```js
+     * return {...data, "my-new-field": /*my data/*}
+     * ```
+     */
+    beforeEvaluation?(
+      hookContext: EvaluationSeriesContext,
+      data: EvaluationSeriesData,
+    ): EvaluationSeriesData;
+
+    /**
+     * This method is called during the execution of the variation method
+     * after the flag value has been determined. The method is executed synchronously.
+     *
+     * @param hookContext Contains read-only information about the evaluation
+     * being performed.
+     * @param data A record associated with each stage of hook invocations. Each
+     *  stage is called with the data of the previous stage for a series.
+     * @param detail The result of the evaluation. This value should not be
+     * modified.
+     * @returns Data to use when executing the next state of the hook in the evaluation series. It is
+     * recommended to expand the previous input into the return. This helps ensure your stage remains
+     * compatible moving forward as more stages are added.
+     * ```js
+     * return {...data, "my-new-field": /*my data/*}
+     * ```
+     */
+    afterEvaluation?(
+      hookContext: EvaluationSeriesContext,
+      data: EvaluationSeriesData,
+      detail: LDEvaluationDetail,
+    ): EvaluationSeriesData;
+
+    /**
+     * This method is called during the execution of the identify process before the operation
+     * completes, but after any context modifications are performed.
+     *
+     * @param hookContext Contains information about the evaluation being performed. This is not
+     *  mutable.
+     * @param data A record associated with each stage of hook invocations. Each stage is called with
+     * the data of the previous stage for a series. The input record should not be modified.
+     * @returns Data to use when executing the next state of the hook in the evaluation series. It is
+     * recommended to expand the previous input into the return. This helps ensure your stage remains
+     * compatible moving forward as more stages are added.
+     * ```js
+     * return {...data, "my-new-field": /*my data/*}
+     * ```
+     */
+    beforeIdentify?(hookContext: IdentifySeriesContext, data: IdentifySeriesData): IdentifySeriesData;
+
+    /**
+     * This method is called during the execution of the identify process before the operation
+     * completes, but after any context modifications are performed.
+     *
+     * @param hookContext Contains information about the evaluation being performed. This is not
+     *  mutable.
+     * @param data A record associated with each stage of hook invocations. Each stage is called with
+     * the data of the previous stage for a series. The input record should not be modified.
+     * @returns Data to use when executing the next state of the hook in the evaluation series. It is
+     * recommended to expand the previous input into the return. This helps ensure your stage remains
+     * compatible moving forward as more stages are added.
+     * ```js
+     * return {...data, "my-new-field": /*my data/*}
+     * ```
+     */
+    afterIdentify?(
+      hookContext: IdentifySeriesContext,
+      data: IdentifySeriesData,
+      result: IdentifySeriesResult,
+    ): IdentifySeriesData;
+  }
+
   /**
    * LaunchDarkly initialization options that are supported by all variants of the JS client.
    * The browser SDK and Electron SDK may support additional options.
@@ -277,6 +455,25 @@ declare module 'launchdarkly-js-sdk-common' {
      * Inspectors can be used for collecting information for monitoring, analytics, and debugging.
      */
     inspectors?: LDInspection[];
+
+    /**
+     * Initial set of hooks for the client.
+     *
+     * Hooks provide entrypoints which allow for observation of SDK functions.
+     *
+     * LaunchDarkly provides integration packages, and most applications will not
+     * need to implement their own hooks. Refer to the `@launchdarkly/node-server-sdk-otel`
+     * for instrumentation for the `@launchdarkly/node-server-sdk`.
+     *
+     * Example:
+     * ```typescript
+     * import { init } from '@launchdarkly/node-server-sdk';
+     * import { TheHook } from '@launchdarkly/some-hook';
+     *
+     * const client = init('my-sdk-key', { hooks: [new TheHook()] });
+     * ```
+     */
+    hooks?: Hook[];
   }
 
   /**
@@ -909,6 +1106,16 @@ declare module 'launchdarkly-js-sdk-common' {
      *   closing is finished. It will never be rejected.
      */
     close(onDone?: () => void): Promise<void>;
+
+    /**
+     * Add a hook to the client. In order to register a hook before the client
+     * starts, please use the `hooks` property of {@link LDOptions}.
+     *
+     * Hooks provide entrypoints which allow for observation of SDK functions.
+     *
+     * @param Hook The hook to add.
+     */
+    addHook(hook: Hook): void;
   }
 
   /**