feat: Add hook support.

Author: kinyoklion

package.json

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

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;

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 {

typings.d.ts

@@ -40,6 +40,85 @@ declare module 'launchdarkly-js-sdk-common' {
     error: (message: string) => void;
   }
 
+  /**
+ * Contextual information provided to evaluation stages.
+ */
+export interface EvaluationSeriesContext {
+  readonly flagKey: string;
+  readonly context: LDContext;
+  readonly defaultValue: unknown;
+  readonly method: string;
+}
+
+  /**
+   * 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 {
+    readonly name: string;
+  }
+
+  /**
+   * Interface for extending SDK functionality via hooks.
+   */
+  export interface Hook {
+    /**
+     * Get metadata about the hook implementation.
+     */
+    getMetadata(): HookMetadata;
+
+    /**
+     * The before 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;
+
+    /**
+     * The after 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;
+  }
+
   /**
    * 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 +356,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 +1007,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;
   }
 
   /**