feat: add @trace()decorator in order to be able to pass a handler for execution tracing

Author: tabkram

src/trace/trace.ts

@@ -13,6 +13,36 @@ function calculateTimeAndDuration(executionTimer: ExecutionTimer): TimerDetailsM
   return timerDetails;
 }
 
+
+export function trace<O>(
+  blockFunction: (...params) => Promise<O>,
+  inputs: Array<unknown>,
+  traceHandler?: (
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    traceContext: Record<string, any>,
+    executionTrace?: ExecutionTrace<Array<unknown>, O>,
+    options?: TraceOptions<Array<unknown>, O>['config']
+  ) => void,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  traceContext?: Record<string, any>,
+  errorStrategy?: 'catch' | 'throw'
+): Promise<ExecutionTrace<Array<unknown>, Awaited<O>>>;
+
+export function trace<O>(
+  blockFunction: (...params) => O,
+  inputs: Array<unknown>,
+  traceHandler?: (
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    traceContext: Record<string, any>,
+    executionTrace?: ExecutionTrace<Array<unknown>, O>,
+    options?: TraceOptions<Array<unknown>, O>['config']
+  ) => void,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  traceContext?: Record<string, any>,
+  errorStrategy?: 'catch' | 'throw'
+): ExecutionTrace<Array<unknown>, O>;
+
+
 export function trace<O>(
   blockFunction: (...params) => O | Promise<O>,
   inputs: Array<unknown> = [],

src/trace/traceDecorator.spec.ts

@@ -0,0 +1,117 @@
+import { trace } from './traceDecorator';
+
+describe('trace decorator', () => {
+  const executionTraceExpectation = {
+    inputs: expect.any(Array),
+    startTime: expect.any(Date),
+    endTime: expect.any(Date),
+    duration: expect.any(Number),
+    elapsedTime: expect.any(String)
+  };
+
+  const successfulExecutionTraceExpectation = {
+    ...executionTraceExpectation,
+    outputs: expect.anything()
+  };
+
+  const failedExecutionTraceExpectation = {
+    ...executionTraceExpectation,
+    errors: expect.anything()
+  };
+
+  describe('Synchronous functions', () => {
+    class SyncClass {
+      @trace()
+      helloWorld(): string {
+        return 'Hello World';
+      }
+    }
+
+    it('should trace a synchronous function', () => {
+      const instance = new SyncClass();
+      const response = instance.helloWorld();
+      expect(response).toEqual('Hello World');
+    });
+  });
+
+  describe('Asynchronous functions', () => {
+    class AsyncClass {
+      @trace()
+      async helloWorldAsync(): Promise<string> {
+        return 'Hello World async';
+      }
+    }
+
+    it('should trace an async function', async () => {
+      const instance = new AsyncClass();
+      const response = await instance.helloWorldAsync();
+      expect(response).toEqual('Hello World async');
+    });
+  });
+
+  describe('Tracing function traceHandlerMock and traceContext', () => {
+    const traceContextDivision = { metadata: { requestId: '12345' } };
+    const traceContextFetchData = { metadata: { requestId: '6789' } };
+    const traceHandlerDivisionMock= jest.fn();
+    const traceHandlerFetchDataMock= jest.fn();
+    class MyClass {
+      @trace(traceHandlerDivisionMock, traceContextDivision)
+      divisionFunction(x: number, y: number, traceContext: Record<string, unknown> = {}): number {
+        if (y === 0) {
+          traceContext['narratives'] = [`Throwing because division of ${x} by ${y}`];
+          throw new Error('Throwing because division by zero is not allowed.');
+        }
+        traceContext['narratives'] = [`Calculating the division of ${x} by ${y}`];
+        return x / y;
+      }
+
+      @trace(traceHandlerFetchDataMock, traceContextFetchData)
+      async fetchDataFunction(url: string, traceContext: Record<string, unknown> = {}): Promise<{ data: string }> {
+        traceContext['narratives'] = [`Fetching data from ${url}`];
+        if (!url.startsWith('http')) {
+          traceContext['narratives'] = [`Throwing because the URL ${url} is invalid`];
+          throw new Error('Invalid URL provided.');
+        }
+        return { data: 'Success' };
+      }
+    }
+
+    it('should sync trace successfully and pass correct traceHandlerMock and traceContext', () => {
+
+      const classInstance = new MyClass();
+      const response = classInstance.divisionFunction(1, 2);
+      expect(traceHandlerDivisionMock).toHaveBeenCalledWith(
+        { ...traceContextDivision, narratives: ['Calculating the division of 1 by 2'] },
+        expect.objectContaining(successfulExecutionTraceExpectation)
+      );
+      expect(response).toEqual(0.5);
+
+
+    });
+
+    it('should sync trace errors and pass correct traceHandlerMock and traceContext', async () => {
+      expect(() => new MyClass().divisionFunction(1, 0)).toThrow('Throwing because division by zero is not allowed.');
+      expect(traceHandlerDivisionMock).toHaveBeenCalledWith(
+        { ...traceContextDivision, narratives: ['Throwing because division of 1 by 0'] },
+        expect.objectContaining(failedExecutionTraceExpectation)
+      );
+    });
+
+    it('should async trace successfully and pass correct traceHandlerMock and traceContext', async () => {
+      const response =await new MyClass().fetchDataFunction('https://api.example.com/data');
+      expect(traceHandlerFetchDataMock).toHaveBeenCalledWith(
+        { ...traceContextFetchData, narratives: ['Fetching data from https://api.example.com/data'] },
+        expect.objectContaining(successfulExecutionTraceExpectation)
+      );
+      expect(response).toMatchObject({ data: 'Success' });
+    });
+
+    it('should async trace errors and pass correct traceHandlerMock and traceContext', async () => {
+      await expect(new MyClass().fetchDataFunction('invalid-url')).rejects.toThrow('Invalid URL provided.');
+      expect(traceHandlerFetchDataMock).toHaveBeenCalledWith(
+        { ...traceContextFetchData, narratives: ['Throwing because the URL invalid-url is invalid'] },
+        expect.objectContaining(failedExecutionTraceExpectation)
+      );
+    });
+  });
+});

src/trace/traceDecorator.ts

@@ -0,0 +1,31 @@
+import { TraceOptions } from './models/engineTraceOptions.model';
+import { ExecutionTrace } from './models/executionTrace.model';
+import { trace as traceExecution } from './trace';
+import { isAsync } from '../common/isAsync';
+
+
+export function trace<O>(
+  traceHandler?: (
+    traceContext: Record<string, any>,
+    executionTrace: ExecutionTrace<Array<unknown>, O>,
+    options?: TraceOptions<Array<unknown>, O>['config']
+  ) => void,
+  traceContext: Record<string, any> = {},
+  errorStrategy: 'catch' | 'throw' = 'throw'
+): MethodDecorator {
+  return function (
+    target: object,
+    propertyKey: string | symbol,
+    descriptor: PropertyDescriptor
+  ): void {
+    const originalMethod = descriptor.value;
+
+    descriptor.value = function (...args: unknown[]) {
+      if (isAsync(originalMethod)) {
+        return traceExecution<O>(originalMethod.bind(this), args, traceHandler, traceContext, errorStrategy)?.then((r) => r.outputs);
+      } else {
+        return traceExecution<O>(originalMethod.bind(this) as () => O, args, traceHandler, traceContext, errorStrategy)?.outputs;
+      }
+    };
+  };
+}