feat: Add hook support for the track series.

Author: kinyoklion

packages/shared/sdk-client/__tests__/LDClientImpl.hooks.test.ts

@@ -308,3 +308,49 @@ it('should not execute hooks for prerequisite evaluations', async () => {
     },
   );
 });
+
+it('should execute afterTrack hooks when tracking events', async () => {
+  const testHook: Hook = {
+    beforeEvaluation: jest.fn(),
+    afterEvaluation: jest.fn(),
+    beforeIdentify: jest.fn(),
+    afterIdentify: jest.fn(),
+    afterTrack: jest.fn(),
+    getMetadata(): HookMetadata {
+      return {
+        name: 'test hook',
+      };
+    },
+  };
+
+  const platform = createBasicPlatform();
+  const factory = makeTestDataManagerFactory('sdk-key', platform, {
+    disableNetwork: true,
+  });
+  const client = new LDClientImpl(
+    'sdk-key',
+    AutoEnvAttributes.Disabled,
+    platform,
+    {
+      sendEvents: false,
+      hooks: [testHook],
+      logger: {
+        debug: jest.fn(),
+        info: jest.fn(),
+        warn: jest.fn(),
+        error: jest.fn(),
+      },
+    },
+    factory,
+  );
+
+  await client.identify({ kind: 'user', key: 'user-key' });
+  client.track('test', { test: 'data' }, 42);
+
+  expect(testHook.afterTrack).toHaveBeenCalledWith({
+    key: 'test',
+    context: { kind: 'user', key: 'user-key' },
+    data: { test: 'data' },
+    metricValue: 42,
+  });
+});

packages/shared/sdk-client/__tests__/HookRunner.test.ts renamed to packages/shared/sdk-client/__tests__/hooks/HookRunner.test.ts

@@ -1,7 +1,8 @@
 import { LDContext, LDEvaluationDetail, LDLogger } from '@launchdarkly/js-sdk-common';
 
-import { Hook, IdentifySeriesResult } from '../src/api/integrations/Hooks';
-import HookRunner from '../src/HookRunner';
+import { Hook, IdentifySeriesResult } from '../../src/api/integrations/Hooks';
+import HookRunner from '../../src/HookRunner';
+import { TestHook } from './TestHook';
 
 describe('given a hook runner and test hook', () => {
   let logger: LDLogger;
@@ -22,6 +23,7 @@ describe('given a hook runner and test hook', () => {
       afterEvaluation: jest.fn(),
       beforeIdentify: jest.fn(),
       afterIdentify: jest.fn(),
+      afterTrack: jest.fn(),
     };
 
     hookRunner = new HookRunner(logger, [testHook]);
@@ -301,4 +303,161 @@ describe('given a hook runner and test hook', () => {
       ),
     );
   });
+
+  it('should execute afterTrack hooks', () => {
+    const context: LDContext = { kind: 'user', key: 'user-123' };
+    const key = 'test';
+    const data = { test: 'data' };
+    const metricValue = 42;
+
+    const trackContext = {
+      key,
+      context,
+      data,
+      metricValue,
+    };
+
+    testHook.afterTrack = jest.fn();
+
+    hookRunner.afterTrack(trackContext);
+
+    expect(testHook.afterTrack).toHaveBeenCalledWith(trackContext);
+  });
+
+  it('should handle errors in afterTrack hooks', () => {
+    const errorHook: Hook = {
+      getMetadata: jest.fn().mockReturnValue({ name: 'Error Hook' }),
+      afterTrack: jest.fn().mockImplementation(() => {
+        throw new Error('Hook error');
+      }),
+    };
+
+    const errorHookRunner = new HookRunner(logger, [errorHook]);
+
+    errorHookRunner.afterTrack({
+      key: 'test',
+      context: { kind: 'user', key: 'user-123' },
+    });
+
+    expect(logger.error).toHaveBeenCalledWith(
+      expect.stringContaining(
+        'An error was encountered in "afterTrack" of the "Error Hook" hook: Error: Hook error',
+      ),
+    );
+  });
+
+  it('should skip afterTrack execution if there are no hooks', () => {
+    const emptyHookRunner = new HookRunner(logger, []);
+
+    emptyHookRunner.afterTrack({
+      key: 'test',
+      context: { kind: 'user', key: 'user-123' },
+    });
+
+    expect(logger.error).not.toHaveBeenCalled();
+  });
+
+  it('executes hook stages in the specified order', () => {
+    const beforeEvalOrder: string[] = [];
+    const afterEvalOrder: string[] = [];
+    const beforeIdentifyOrder: string[] = [];
+    const afterIdentifyOrder: string[] = [];
+    const afterTrackOrder: string[] = [];
+
+    const hookA = new TestHook();
+    hookA.beforeEvalImpl = (_context, data) => {
+      beforeEvalOrder.push('a');
+      return data;
+    };
+    hookA.afterEvalImpl = (_context, data, _detail) => {
+      afterEvalOrder.push('a');
+      return data;
+    };
+    hookA.beforeIdentifyImpl = (_context, data) => {
+      beforeIdentifyOrder.push('a');
+      return data;
+    };
+    hookA.afterIdentifyImpl = (_context, data, _result) => {
+      afterIdentifyOrder.push('a');
+      return data;
+    };
+    hookA.afterTrackImpl = () => {
+      afterTrackOrder.push('a');
+    };
+
+    const hookB = new TestHook();
+    hookB.beforeEvalImpl = (_context, data) => {
+      beforeEvalOrder.push('b');
+      return data;
+    };
+    hookB.afterEvalImpl = (_context, data, _detail) => {
+      afterEvalOrder.push('b');
+      return data;
+    };
+    hookB.beforeIdentifyImpl = (_context, data) => {
+      beforeIdentifyOrder.push('b');
+      return data;
+    };
+    hookB.afterIdentifyImpl = (_context, data, _result) => {
+      afterIdentifyOrder.push('b');
+      return data;
+    };
+    hookB.afterTrackImpl = () => {
+      afterTrackOrder.push('b');
+    };
+
+    const hookC = new TestHook();
+    hookC.beforeEvalImpl = (_context, data) => {
+      beforeEvalOrder.push('c');
+      return data;
+    };
+    hookC.afterEvalImpl = (_context, data, _detail) => {
+      afterEvalOrder.push('c');
+      return data;
+    };
+    hookC.beforeIdentifyImpl = (_context, data) => {
+      beforeIdentifyOrder.push('c');
+      return data;
+    };
+    hookC.afterIdentifyImpl = (_context, data, _result) => {
+      afterIdentifyOrder.push('c');
+      return data;
+    };
+    hookC.afterTrackImpl = () => {
+      afterTrackOrder.push('c');
+    };
+
+    const runner = new HookRunner(logger, [hookA, hookB]);
+    runner.addHook(hookC);
+
+    // Test evaluation order
+    runner.withEvaluation('flagKey', { kind: 'user', key: 'bob' }, 'default', () => ({
+      value: false,
+      reason: { kind: 'ERROR', errorKind: 'FLAG_NOT_FOUND' },
+      variationIndex: null,
+    }));
+
+    // Test identify order
+    const identifyCallback = runner.identify({ kind: 'user', key: 'bob' }, 1000);
+    identifyCallback({ status: 'completed' });
+
+    // Test track order
+    runner.afterTrack({
+      key: 'test',
+      context: { kind: 'user', key: 'bob' },
+      data: { test: 'data' },
+      metricValue: 42,
+    });
+
+    // Verify evaluation hooks order
+    expect(beforeEvalOrder).toEqual(['a', 'b', 'c']);
+    expect(afterEvalOrder).toEqual(['c', 'b', 'a']);
+
+    // Verify identify hooks order
+    expect(beforeIdentifyOrder).toEqual(['a', 'b', 'c']);
+    expect(afterIdentifyOrder).toEqual(['c', 'b', 'a']);
+
+    // Verify track hooks order
+    expect(afterTrackOrder).toEqual(['c', 'b', 'a']);
+  });
 });

packages/shared/sdk-client/__tests__/hooks/TestHook.ts

@@ -0,0 +1,113 @@
+import { LDEvaluationDetail } from '@launchdarkly/js-sdk-common';
+
+import {
+  EvaluationSeriesContext,
+  EvaluationSeriesData,
+  Hook,
+  HookMetadata,
+  IdentifySeriesContext,
+  IdentifySeriesData,
+  IdentifySeriesResult,
+  TrackSeriesContext,
+} from '../../src/api/integrations/Hooks';
+
+export type EvalCapture = {
+  method: string;
+  hookContext: EvaluationSeriesContext;
+  hookData: EvaluationSeriesData;
+  detail?: LDEvaluationDetail;
+};
+
+export type IdentifyCapture = {
+  method: string;
+  hookContext: IdentifySeriesContext;
+  hookData: IdentifySeriesData;
+  result?: IdentifySeriesResult;
+};
+
+export type TrackCapture = {
+  method: string;
+  hookContext: TrackSeriesContext;
+};
+
+export class TestHook implements Hook {
+  captureBefore: EvalCapture[] = [];
+  captureAfter: EvalCapture[] = [];
+  captureIdentifyBefore: IdentifyCapture[] = [];
+  captureIdentifyAfter: IdentifyCapture[] = [];
+  captureTrack: TrackCapture[] = [];
+
+  getMetadataImpl: () => HookMetadata = () => ({ name: 'LaunchDarkly Test Hook' });
+
+  getMetadata(): HookMetadata {
+    return this.getMetadataImpl();
+  }
+
+  beforeEvalImpl: (
+    hookContext: EvaluationSeriesContext,
+    data: EvaluationSeriesData,
+  ) => EvaluationSeriesData = (_hookContext, data) => data;
+
+  afterEvalImpl: (
+    hookContext: EvaluationSeriesContext,
+    data: EvaluationSeriesData,
+    detail: LDEvaluationDetail,
+  ) => EvaluationSeriesData = (_hookContext, data, _detail) => data;
+
+  beforeEvaluation?(
+    hookContext: EvaluationSeriesContext,
+    data: EvaluationSeriesData,
+  ): EvaluationSeriesData {
+    this.captureBefore.push({ method: 'beforeEvaluation', hookContext, hookData: data });
+    return this.beforeEvalImpl(hookContext, data);
+  }
+
+  afterEvaluation?(
+    hookContext: EvaluationSeriesContext,
+    data: EvaluationSeriesData,
+    detail: LDEvaluationDetail,
+  ): EvaluationSeriesData {
+    this.captureAfter.push({ method: 'afterEvaluation', hookContext, hookData: data, detail });
+    return this.afterEvalImpl(hookContext, data, detail);
+  }
+
+  beforeIdentifyImpl: (
+    hookContext: IdentifySeriesContext,
+    data: IdentifySeriesData,
+  ) => IdentifySeriesData = (_hookContext, data) => data;
+
+  afterIdentifyImpl: (
+    hookContext: IdentifySeriesContext,
+    data: IdentifySeriesData,
+    result: IdentifySeriesResult,
+  ) => IdentifySeriesData = (_hookContext, data, _result) => data;
+
+  afterTrackImpl: (hookContext: TrackSeriesContext) => void = () => {};
+
+  beforeIdentify?(
+    hookContext: IdentifySeriesContext,
+    data: IdentifySeriesData,
+  ): IdentifySeriesData {
+    this.captureIdentifyBefore.push({ method: 'beforeIdentify', hookContext, hookData: data });
+    return this.beforeIdentifyImpl(hookContext, data);
+  }
+
+  afterIdentify?(
+    hookContext: IdentifySeriesContext,
+    data: IdentifySeriesData,
+    result: IdentifySeriesResult,
+  ): IdentifySeriesData {
+    this.captureIdentifyAfter.push({
+      method: 'afterIdentify',
+      hookContext,
+      hookData: data,
+      result,
+    });
+    return this.afterIdentifyImpl(hookContext, data, result);
+  }
+
+  afterTrack?(hookContext: TrackSeriesContext): void {
+    this.captureTrack.push({ method: 'afterTrack', hookContext });
+    this.afterTrackImpl(hookContext);
+  }
+}

packages/shared/sdk-client/src/HookRunner.ts

@@ -7,12 +7,14 @@ import {
   IdentifySeriesContext,
   IdentifySeriesData,
   IdentifySeriesResult,
+  TrackSeriesContext,
 } from './api/integrations/Hooks';
 import { LDEvaluationDetail } from './api/LDEvaluationDetail';
 
 const UNKNOWN_HOOK_NAME = 'unknown hook';
 const BEFORE_EVALUATION_STAGE_NAME = 'beforeEvaluation';
 const AFTER_EVALUATION_STAGE_NAME = 'afterEvaluation';
+const AFTER_TRACK_STAGE_NAME = 'afterTrack';
 
 function tryExecuteStage<TData>(
   logger: LDLogger,
@@ -114,6 +116,21 @@ function executeAfterIdentify(
   }
 }
 
+function executeAfterTrack(logger: LDLogger, hooks: Hook[], hookContext: TrackSeriesContext) {
+  // 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];
+    tryExecuteStage(
+      logger,
+      AFTER_TRACK_STAGE_NAME,
+      getHookName(logger, hook),
+      () => hook?.afterTrack?.(hookContext),
+      undefined,
+    );
+  }
+}
+
 export default class HookRunner {
   private readonly _hooks: Hook[] = [];
 
@@ -164,4 +181,12 @@ export default class HookRunner {
   addHook(hook: Hook): void {
     this._hooks.push(hook);
   }
+
+  afterTrack(hookContext: TrackSeriesContext): void {
+    if (this._hooks.length === 0) {
+      return;
+    }
+    const hooks: Hook[] = [...this._hooks];
+    executeAfterTrack(this._logger, hooks, hookContext);
+  }
 }