@furystack/utils 7.0.2 → 8.0.0

package/src/trace.spec.ts

@@ -1,200 +0,0 @@
-import { describe, it, expect, vi } from 'vitest'
-import { Trace } from './trace.js'
-
-class MockClass {
-  constructor(private testValue?: string) {}
-
-  public testError(msg: string) {
-    throw Error(msg)
-  }
-
-  public testScope() {
-    return this.testValue
-  }
-
-  public static addStatic(this: void, ...args: number[]) {
-    return args.reduce((a, b) => a + b, 0)
-  }
-
-  public addInstance(this: void, ...args: number[]) {
-    return args.reduce((a, b) => a + b, 0)
-  }
-
-  public async addInstanceAsync(this: void, ...args: number[]): Promise<number> {
-    return args.reduce((a, b) => a + b, 0)
-  }
-
-  public async testErrorAsync(msg: string): Promise<number> {
-    throw Error(msg)
-  }
-}
-
-export const traceTests = describe('Trace tests', () => {
-  describe('Static method traces', () => {
-    it('Static Methods call should be traced with args', () => {
-      const args = [1, 2, 3]
-      const doneCallback = vi.fn()
-      const observer = Trace.method({
-        object: MockClass,
-        method: MockClass.addStatic,
-        onCalled: (traceData) => {
-          expect(args).toEqual(traceData.methodArguments)
-          observer.dispose()
-          doneCallback()
-        },
-      })
-      MockClass.addStatic(...args)
-      expect(doneCallback).toBeCalled()
-    })
-
-    it('Static Methods call should be traced with args and return value', () => {
-      const args = [1, 2, 3]
-      const doneCallback = vi.fn()
-      const observer = Trace.method({
-        object: MockClass,
-        method: MockClass.addStatic,
-        onFinished: (traceData) => {
-          expect(args).toEqual(traceData.methodArguments)
-          expect(traceData.returned).toBe(1 + 2 + 3)
-          observer.dispose()
-          doneCallback()
-        },
-      })
-      MockClass.addStatic(...args)
-      expect(doneCallback).toBeCalled()
-    })
-
-    it("shouldn't be triggered after observer is disposed", () => {
-      const args = [1, 2, 3]
-      const shouldNotCall = vi.fn()
-      const doneCallback = vi.fn()
-
-      const observer = Trace.method({
-        object: MockClass,
-        method: MockClass.addStatic,
-        onCalled: () => {
-          shouldNotCall("Shouldn't be triggered here")
-        },
-      })
-      const observer2 = Trace.method({
-        object: MockClass,
-        method: MockClass.addStatic,
-        onCalled: () => {
-          observer2.dispose()
-          doneCallback()
-        },
-      })
-      observer.dispose()
-      const returned = MockClass.addStatic(...args)
-      expect(returned).toEqual(1 + 2 + 3)
-      expect(doneCallback).toBeCalled()
-      expect(shouldNotCall).not.toBeCalled()
-    })
-  })
-
-  describe('Instance method traces', () => {
-    it('should be traced with arguments', () => {
-      const instance = new MockClass()
-      const args = [1, 2, 3]
-      const doneCallback = vi.fn()
-
-      const observer = Trace.method({
-        object: instance,
-        method: instance.addInstance,
-        onFinished: (traceData) => {
-          expect(args).toEqual(traceData.methodArguments)
-          expect(traceData.returned).toBe(1 + 2 + 3)
-          observer.dispose()
-          doneCallback()
-        },
-      })
-      instance.addInstance(...args)
-      expect(doneCallback).toBeCalled()
-    })
-
-    it('should be traced asynchronously', async () => {
-      const instance = new MockClass()
-      const args = [1, 2, 3]
-      const doneCallback = vi.fn()
-
-      const observer = Trace.method({
-        object: instance,
-        method: instance.addInstanceAsync,
-        isAsync: true,
-        onFinished: (traceData) => {
-          expect(args).toEqual(traceData.methodArguments)
-          const { returned } = traceData
-          expect(returned).toBe(1 + 2 + 3)
-          observer.dispose()
-          doneCallback()
-        },
-      })
-      await instance.addInstanceAsync(...args)
-      expect(doneCallback).toBeCalled()
-    })
-
-    it("should have a valid 'this' scope", () => {
-      const instance = new MockClass('testValue')
-      const doneCallback = vi.fn()
-
-      const observer = Trace.method({
-        object: instance,
-        method: instance.testScope,
-        onFinished: (traceData) => {
-          if (traceData.returned) {
-            expect(traceData.returned).toBe('testValue')
-            observer.dispose()
-            doneCallback()
-          }
-        },
-      })
-      expect(instance.testScope()).toBe('testValue')
-      expect(doneCallback).toBeCalled()
-    })
-
-    it('should handle throwing errors', () => {
-      const instance = new MockClass('testValue')
-      const doneCallback = vi.fn()
-
-      const observer = Trace.method({
-        object: instance,
-        method: instance.testError,
-        onError: (traceData) => {
-          if (traceData.error) {
-            expect(traceData.error.message).toBe('message')
-            observer.dispose()
-            doneCallback()
-          }
-        },
-      })
-      expect(() => {
-        instance.testError('message')
-      }).toThrow()
-      expect(doneCallback).toBeCalled()
-    })
-
-    it('should handle throwing errors with asyncs', async () => {
-      const instance = new MockClass('testValue')
-      const doneCallback = vi.fn()
-
-      const observer = Trace.method({
-        object: instance,
-        method: instance.testErrorAsync,
-        isAsync: true,
-        onError: (traceData) => {
-          if (traceData.error) {
-            expect(traceData.error.message).toBe('message')
-            observer.dispose()
-            doneCallback()
-          }
-        },
-      })
-      try {
-        await instance.testErrorAsync('message')
-      } catch (error) {
-        // ignore
-      }
-      expect(doneCallback).toBeCalled()
-    })
-  })
-})

package/src/trace.ts

@@ -1,265 +0,0 @@
-import type { Disposable } from './disposable.js'
-import { ObservableValue } from './observable-value.js'
-
-/**
- * Options object for tracing method calls
- */
-export interface TraceMethodOptions<T, TMethod extends (...args: TArgs) => unknown, TArgs extends unknown[]> {
-  /**
-   * The context object. Can be an instance or a constructor for static methods
-   */
-  object: T
-  /**
-   * The method reference that needs to be traced
-   */
-  method: TMethod
-  /**
-   * Callback that will be called right before executing the method
-   */
-  onCalled?: (newValue: TraceMethodCall<TArgs>) => void
-  /**
-   * Callback that will be called right after the method returns
-   */
-  onFinished?: (newValue: TraceMethodFinished<ReturnType<TMethod>, TArgs>) => void
-  /**
-   * Callback that will be called when a method throws an error
-   */
-  onError?: (newValue: TraceMethodError<TArgs>) => void
-
-  /**
-   * The method execution will be awaited if set
-   */
-  isAsync?: boolean
-}
-
-/**
- * Defines a trace method call object
- */
-export interface TraceMethodCall<TArgs extends any[]> {
-  /**
-   * The timestamp when the event occured
-   */
-  startDateTime: Date
-
-  /**
-   * The provided arguments for the call
-   */
-  methodArguments: TArgs
-}
-
-/**
- * Defines a trace event when a method call has been finished
- */
-export interface TraceMethodFinished<TReturns, TArgs extends any[]> extends TraceMethodCall<TArgs> {
-  returned: TReturns
-  finishedDateTime: Date
-}
-
-/**
- * Defines a trace event when an error was thrown during a method call
- */
-export interface TraceMethodError<TArgs extends any[]> extends TraceMethodCall<TArgs> {
-  error: any
-  errorDateTime: Date
-}
-
-/**
- * Defines a method mapping object
- */
-export interface MethodMapping<TReturns, TArgs extends any[]> {
-  /**
-   * The original method instance
-   */
-  originalMethod: (...args: TArgs) => TReturns
-  /**
-   * An observable for distributing the events
-   */
-  callObservable: ObservableValue<TraceMethodCall<TArgs>>
-
-  finishedObservable: ObservableValue<TraceMethodFinished<any, TArgs>>
-  errorObservable: ObservableValue<TraceMethodError<TArgs>>
-}
-
-/**
- * Defines an Object Trace mapping
- */
-export interface ObjectTrace {
-  /**
-   * Map about the already wrapped methods
-   */
-  methodMappings: Map<string, MethodMapping<any, any[]>>
-}
-
-/**
- * Helper class that can be used to trace method calls programmatically
- *
- * Usage example:
- * ```ts
- * const methodTracer: IDisposable = Trace.method({
- *     object: myObjectInstance,           // You can define an object constructor for static methods as well
- *     method: myObjectInstance.method,    // The method to be tracked
- *     isAsync: true,                      // if you set to async, method finished will be *await*-ed
- *     onCalled: (traceData) => {
- *         console.log("Method called:", traceData)
- *     },
- *     onFinished: (traceData) => {
- *         console.log("Method call finished:", traceData)
- *     },
- *     onError: (traceData) => {
- *         console.log("Method throwed an error:", traceData)
- *     }
- * });
- * ```
- */
-export class Trace {
-  private static objectTraces: Map<object, ObjectTrace> = new Map()
-
-  private static getMethodTrace<TArgs extends any[], TReturns>(
-    object: object,
-    method: (...args: TArgs) => TReturns,
-  ): MethodMapping<TReturns, TArgs> {
-    const objectTrace = this.objectTraces.get(object) as any as ObjectTrace
-    return objectTrace.methodMappings.get(method.name) as any as MethodMapping<TReturns, TArgs>
-  }
-
-  private static traceStart<TReturns, TArgs extends any[]>(
-    methodTrace: MethodMapping<TReturns, TArgs[]>,
-    args: TArgs[],
-  ) {
-    const startDateTime = new Date()
-    const traceValue = {
-      methodArguments: args,
-      startDateTime,
-    }
-    methodTrace.callObservable.setValue(traceValue)
-    return traceValue
-  }
-
-  private static traceFinished<TReturns, TArgs extends any[]>(
-    methodTrace: MethodMapping<TReturns, TArgs>,
-    args: TArgs,
-    callTrace: TraceMethodCall<TArgs>,
-    returned: any,
-  ) {
-    const finishedTrace: TraceMethodFinished<TReturns, TArgs> = {
-      methodArguments: args,
-      startDateTime: callTrace.startDateTime,
-      finishedDateTime: new Date(),
-      returned,
-    }
-    methodTrace.finishedObservable.setValue(finishedTrace)
-  }
-
-  private static traceError<TReturns, TArgs extends any[]>(
-    methodTrace: MethodMapping<TReturns, TArgs>,
-    args: TArgs,
-    callTrace: TraceMethodCall<TArgs>,
-    error: any,
-  ) {
-    const errorTrace: TraceMethodError<TArgs> = {
-      methodArguments: args,
-      startDateTime: callTrace.startDateTime,
-      errorDateTime: new Date(),
-      error,
-    }
-    methodTrace.errorObservable.setValue(errorTrace)
-    return errorTrace
-  }
-
-  private static callMethod<TReturns, TArgs extends any[]>(
-    object: object,
-    method: (...args: TArgs) => TReturns,
-    args: TArgs,
-  ) {
-    const methodTrace: any = this.getMethodTrace(object, method)
-    const start = this.traceStart(methodTrace, args)
-    try {
-      const returned = methodTrace.originalMethod.call(object, ...args)
-      this.traceFinished(methodTrace, args, start, returned)
-      return returned
-    } catch (error) {
-      this.traceError(methodTrace, args, start, error)
-      throw error
-    }
-  }
-
-  private static async callMethodAsync<TReturns, TArgs extends any[]>(
-    object: object,
-    method: (...args: TArgs) => TReturns,
-    args: TArgs,
-  ) {
-    const methodTrace: any = this.getMethodTrace(object, method)
-    const start = this.traceStart(methodTrace, args)
-    try {
-      const returned = await methodTrace.originalMethod.call(object, ...args)
-      this.traceFinished(methodTrace, args, start, returned)
-      return returned
-    } catch (error) {
-      this.traceError(methodTrace, args, start, error)
-      throw error
-    }
-  }
-
-  /**
-   * Creates an observer that will be observe method calls, finishes and errors
-   * @param options The options object for the trace
-   * @returns the trace object that can be disposed after usage
-   */
-  public static method<T extends object, TMethod extends (...args: TArgs) => any, TArgs extends any[]>(
-    options: TraceMethodOptions<T, TMethod, TArgs>,
-  ): Disposable {
-    // add object mapping
-    if (!this.objectTraces.has(options.object)) {
-      this.objectTraces.set(options.object, {
-        methodMappings: new Map(),
-      })
-    }
-    // setup override if needed
-    if (!(options.method as any).isTraced) {
-      const overriddenMethod = options.isAsync
-        ? (...args: TArgs) => this.callMethodAsync(options.object, options.method, args)
-        : (...args: TArgs) => this.callMethod(options.object, options.method, args)
-      Object.defineProperty(overriddenMethod, 'name', { value: options.method.name })
-      Object.defineProperty(overriddenMethod, 'isTraced', { value: options.method.name })
-      ;(options.object as any)[options.method.name] = overriddenMethod
-    }
-    const objectTrace = this.objectTraces.get(options.object) as any as ObjectTrace
-
-    // add method mapping if needed
-    if (!objectTrace.methodMappings.has(options.method.name)) {
-      objectTrace.methodMappings.set(options.method.name, {
-        originalMethod: options.method,
-        callObservable: new ObservableValue<TraceMethodCall<any>>({
-          methodArguments: [],
-          startDateTime: new Date(''),
-        }),
-        finishedObservable: new ObservableValue<TraceMethodFinished<ReturnType<TMethod>, any>>({
-          methodArguments: [],
-          startDateTime: new Date(''),
-          finishedDateTime: new Date(''),
-          returned: undefined as ReturnType<TMethod>,
-        }),
-        errorObservable: new ObservableValue<TraceMethodError<any>>({
-          methodArguments: [],
-          startDateTime: new Date(''),
-          errorDateTime: new Date(''),
-          error: undefined,
-        }),
-      })
-    }
-    const methodTrace = objectTrace.methodMappings.get(options.method.name) as any as MethodMapping<
-      ReturnType<TMethod>,
-      TArgs
-    >
-    const callbacks = [
-      options.onCalled && methodTrace.callObservable.subscribe(options.onCalled),
-      options.onFinished && methodTrace.finishedObservable.subscribe(options.onFinished),
-      options.onError && methodTrace.errorObservable.subscribe(options.onError),
-    ]
-
-    // Subscribe and return the observer
-    return {
-      dispose: () => callbacks.forEach((c) => c && c.dispose()),
-    }
-  }
-}