@forgehive/task 0.2.2 → 0.2.4

package/src/test/task-with-boundaries.test.ts

@@ -54,7 +54,15 @@ describe('Boundaries tasks tests', () => {
       },
       boundariesData: {
         fetchExternalData: [
-          { input: [], output: { foo: false } }
+          {
+            input: [],
+            output: { foo: false },
+            timing: {
+              startTime: 1000,
+              endTime: 1100,
+              duration: 100
+            }
+          }
         ]
       },
       mode: 'proxy-pass'
@@ -122,7 +130,15 @@ describe('Boundaries tasks tests', () => {
       },
       boundariesData: {
         fetchExternalData: [
-          { input: [4], output: 2 }
+          {
+            input: [4],
+            output: 2,
+            timing: {
+              startTime: 1000,
+              endTime: 1100,
+              duration: 100
+            }
+          }
         ]
       },
       mode: 'proxy-pass'
@@ -140,6 +156,11 @@ describe('Boundaries tasks tests', () => {
     type BoundaryData = {
       input: unknown[];
       output?: unknown;
+      timing?: {
+        startTime: number;
+        endTime: number;
+        duration: number;
+      };
     };
 
     // Define a type for the record boundaries
@@ -203,6 +224,11 @@ describe('Boundaries tasks tests', () => {
     expect(boundaries0.fetchExternalData).toHaveLength(1)
     expect(boundaries0.fetchExternalData[0].input).toEqual([2])
     expect(boundaries0.fetchExternalData[0].output).toBe(4)
+    expect(boundaries0.fetchExternalData[0].timing).toEqual(expect.objectContaining({
+      startTime: expect.any(Number),
+      endTime: expect.any(Number),
+      duration: expect.any(Number)
+    }))
 
     // Check record for second task (value: 3)
     expect(sortedRecords[1].input).toEqual({ value: 3 })
@@ -213,6 +239,11 @@ describe('Boundaries tasks tests', () => {
     expect(boundaries1.fetchExternalData).toHaveLength(1)
     expect(boundaries1.fetchExternalData[0].input).toEqual([3])
     expect(boundaries1.fetchExternalData[0].output).toBe(6)
+    expect(boundaries1.fetchExternalData[0].timing).toEqual(expect.objectContaining({
+      startTime: expect.any(Number),
+      endTime: expect.any(Number),
+      duration: expect.any(Number)
+    }))
 
     // Check record for third task (value: 4)
     expect(sortedRecords[2].input).toEqual({ value: 4 })
@@ -223,6 +254,11 @@ describe('Boundaries tasks tests', () => {
     expect(boundaries2.fetchExternalData).toHaveLength(1)
     expect(boundaries2.fetchExternalData[0].input).toEqual([4])
     expect(boundaries2.fetchExternalData[0].output).toBe(8)
+    expect(boundaries2.fetchExternalData[0].timing).toEqual(expect.objectContaining({
+      startTime: expect.any(Number),
+      endTime: expect.any(Number),
+      duration: expect.any(Number)
+    }))
   })
 
   it('Boundary data accumulates run data correctly', async () => {
@@ -261,9 +297,14 @@ describe('Boundaries tasks tests', () => {
     expect(boundariesData1.fetchExternalData).toHaveLength(1)
 
     // Verify the tape entry for first run
-    const firstRunTape = boundariesData1.fetchExternalData as Array<{input: unknown[], output: unknown}>
+    const firstRunTape = boundariesData1.fetchExternalData as Array<{input: unknown[], output: unknown, timing?: { startTime: number; endTime: number; duration: number }}>
     expect(firstRunTape[0].input).toEqual([2])
     expect(firstRunTape[0].output).toBe(4)
+    expect(firstRunTape[0].timing).toEqual(expect.objectContaining({
+      startTime: expect.any(Number),
+      endTime: expect.any(Number),
+      duration: expect.any(Number)
+    }))
 
     // Run task with value 3
     await multiplyTask.run({ value: 3 })
@@ -275,16 +316,26 @@ describe('Boundaries tasks tests', () => {
     expect(boundariesData2.fetchExternalData).toHaveLength(2)
 
     // Sort the tape by input value for consistent testing
-    const secondRunTape = boundariesData2.fetchExternalData as Array<{input: unknown[], output: unknown}>
+    const secondRunTape = boundariesData2.fetchExternalData as Array<{input: unknown[], output: unknown, timing?: { startTime: number; endTime: number; duration: number }}>
     const sortedTape = [...secondRunTape].sort((a, b) => (a.input[0] as number) - (b.input[0] as number))
 
     // First entry should still be the same
     expect(sortedTape[0].input).toEqual([2])
     expect(sortedTape[0].output).toBe(4)
+    expect(sortedTape[0].timing).toEqual(expect.objectContaining({
+      startTime: expect.any(Number),
+      endTime: expect.any(Number),
+      duration: expect.any(Number)
+    }))
 
     // Second entry should be from the second run
     expect(sortedTape[1].input).toEqual([3])
     expect(sortedTape[1].output).toBe(6)
+    expect(sortedTape[1].timing).toEqual(expect.objectContaining({
+      startTime: expect.any(Number),
+      endTime: expect.any(Number),
+      duration: expect.any(Number)
+    }))
 
     // Run task with value 4
     await multiplyTask.run({ value: 4 })
@@ -296,18 +347,33 @@ describe('Boundaries tasks tests', () => {
     expect(boundariesData3.fetchExternalData).toHaveLength(3)
 
     // Sort the tape again
-    const thirdRunTape = boundariesData3.fetchExternalData as Array<{input: unknown[], output: unknown}>
+    const thirdRunTape = boundariesData3.fetchExternalData as Array<{input: unknown[], output: unknown, timing?: { startTime: number; endTime: number; duration: number }}>
     const finalSortedTape = [...thirdRunTape].sort((a, b) => (a.input[0] as number) - (b.input[0] as number))
 
     // Verify all three entries
     expect(finalSortedTape[0].input).toEqual([2])
     expect(finalSortedTape[0].output).toBe(4)
+    expect(finalSortedTape[0].timing).toEqual(expect.objectContaining({
+      startTime: expect.any(Number),
+      endTime: expect.any(Number),
+      duration: expect.any(Number)
+    }))
 
     expect(finalSortedTape[1].input).toEqual([3])
     expect(finalSortedTape[1].output).toBe(6)
+    expect(finalSortedTape[1].timing).toEqual(expect.objectContaining({
+      startTime: expect.any(Number),
+      endTime: expect.any(Number),
+      duration: expect.any(Number)
+    }))
 
     expect(finalSortedTape[2].input).toEqual([4])
     expect(finalSortedTape[2].output).toBe(8)
+    expect(finalSortedTape[2].timing).toEqual(expect.objectContaining({
+      startTime: expect.any(Number),
+      endTime: expect.any(Number),
+      duration: expect.any(Number)
+    }))
 
     // Verify tape can be used for replay in proxy-pass mode
     const replayTask = createTask({

package/src/test/timing-capture.test.ts

@@ -0,0 +1,348 @@
+import { createTask, TimingTracker } from '../index'
+import { Schema } from '@forgehive/schema'
+
+describe('Timing Capture Tests', () => {
+  describe('TimingTracker accuracy and reliability', () => {
+    it('should capture timing with millisecond precision', async () => {
+      const tracker = TimingTracker.create()
+
+      tracker.start()
+      await new Promise(resolve => setTimeout(resolve, 100)) // Wait 100ms
+      const timing = tracker.end()
+
+      expect(timing).not.toBeNull()
+      if (timing) {
+        expect(timing.duration).toBeGreaterThanOrEqual(90) // Allow for some variance
+        expect(timing.duration).toBeLessThan(150) // But not too much
+        expect(timing.endTime - timing.startTime).toBe(timing.duration)
+      }
+    })
+
+    it('should handle rapid successive timing operations', () => {
+      const timings: Array<{ startTime: number; endTime: number; duration?: number }> = []
+
+      for (let i = 0; i < 10; i++) {
+        const tracker = TimingTracker.create()
+        tracker.start()
+        // Immediate end
+        const timing = tracker.end()
+        if (timing) {
+          timings.push(timing)
+        }
+      }
+
+      timings.forEach(timing => {
+        expect(timing).not.toBeNull()
+        expect(timing.duration).toBeGreaterThanOrEqual(0)
+        expect(timing.duration).toBeLessThan(10) // Should be very fast
+      })
+    })
+
+    it('should provide monotonic timestamps', () => {
+      const tracker1 = TimingTracker.create()
+      const tracker2 = TimingTracker.create()
+
+      tracker1.start()
+      tracker2.start()
+
+      const timing1 = tracker1.end()
+      const timing2 = tracker2.end()
+
+      expect(timing1).not.toBeNull()
+      expect(timing2).not.toBeNull()
+      if (timing1 && timing2) {
+        expect(timing2.startTime).toBeGreaterThanOrEqual(timing1.startTime)
+      }
+    })
+  })
+
+  describe('Boundary timing capture in various scenarios', () => {
+    it('should capture timing for successful boundary calls', async () => {
+      const task = createTask({
+        name: 'timing-test-success',
+        schema: new Schema({ input: Schema.string() }),
+        boundaries: {
+          slowOperation: async (data: string) => {
+            await new Promise(resolve => setTimeout(resolve, 50))
+            return `processed: ${data}`
+          }
+        },
+        fn: async ({ input }, { slowOperation }) => {
+          const result = await slowOperation(input)
+          return { result }
+        }
+      })
+
+      const [result, error, record] = await task.safeRun({ input: 'test' })
+
+      expect(error).toBeNull()
+      expect(result).toEqual({ result: 'processed: test' })
+      expect(record.boundaries.slowOperation).toHaveLength(1)
+
+      const boundaryCall = record.boundaries.slowOperation[0]
+      expect(boundaryCall.timing).toEqual(expect.objectContaining({
+        startTime: expect.any(Number),
+        endTime: expect.any(Number),
+        duration: expect.any(Number)
+      }))
+      expect(boundaryCall.timing.duration).toBeGreaterThanOrEqual(40)
+      expect(boundaryCall.timing.duration).toBeLessThan(100)
+    })
+
+    it('should capture timing for failed boundary calls', async () => {
+      const task = createTask({
+        name: 'timing-test-error',
+        schema: new Schema({ input: Schema.string() }),
+        boundaries: {
+          failingOperation: async (data: string) => {
+            await new Promise(resolve => setTimeout(resolve, 30))
+            throw new Error(`Failed to process: ${data}`)
+          }
+        },
+        fn: async ({ input }, { failingOperation }) => {
+          const result = await failingOperation(input)
+          return { result }
+        }
+      })
+
+      const [result, error, record] = await task.safeRun({ input: 'test' })
+
+      expect(result).toBeNull()
+      expect(error).not.toBeNull()
+      expect(record.boundaries.failingOperation).toHaveLength(1)
+
+      const boundaryCall = record.boundaries.failingOperation[0]
+      expect(boundaryCall.timing).toEqual(expect.objectContaining({
+        startTime: expect.any(Number),
+        endTime: expect.any(Number),
+        duration: expect.any(Number)
+      }))
+      expect(boundaryCall.timing.duration).toBeGreaterThanOrEqual(20)
+      expect(boundaryCall.timing.duration).toBeLessThan(60)
+      expect('error' in boundaryCall).toBe(true)
+    })
+
+    it('should capture timing for multiple boundary calls', async () => {
+      const task = createTask({
+        name: 'timing-test-multiple',
+        schema: new Schema({ count: Schema.number() }),
+        boundaries: {
+          operation: async (index: number) => {
+            await new Promise(resolve => setTimeout(resolve, 20 + index * 10))
+            return `result-${index}`
+          }
+        },
+        fn: async ({ count }, { operation }) => {
+          const results = []
+          for (let i = 0; i < count; i++) {
+            results.push(await operation(i))
+          }
+          return { results }
+        }
+      })
+
+      const [result, error, record] = await task.safeRun({ count: 3 })
+
+      expect(error).toBeNull()
+      expect(result?.results).toEqual(['result-0', 'result-1', 'result-2'])
+      expect(record.boundaries.operation).toHaveLength(3)
+
+      record.boundaries.operation.forEach((call, index) => {
+        expect(call.timing).toEqual(expect.objectContaining({
+          startTime: expect.any(Number),
+          endTime: expect.any(Number),
+          duration: expect.any(Number)
+        }))
+        // Each call should take longer than the previous
+        expect(call.timing.duration).toBeGreaterThanOrEqual(15 + index * 10)
+        expect(call.timing.duration).toBeLessThan(50 + index * 10)
+      })
+    })
+
+    it('should capture timing for parallel boundary calls', async () => {
+      const task = createTask({
+        name: 'timing-test-parallel',
+        schema: new Schema({ delay: Schema.number() }),
+        boundaries: {
+          operationA: async (delay: number) => {
+            await new Promise(resolve => setTimeout(resolve, delay))
+            return 'A'
+          },
+          operationB: async (delay: number) => {
+            await new Promise(resolve => setTimeout(resolve, delay))
+            return 'B'
+          }
+        },
+        fn: async ({ delay }, { operationA, operationB }) => {
+          const [resultA, resultB] = await Promise.all([
+            operationA(delay),
+            operationB(delay)
+          ])
+          return { resultA, resultB }
+        }
+      })
+
+      const [result, error, record] = await task.safeRun({ delay: 50 })
+
+      expect(error).toBeNull()
+      expect(result).toEqual({ resultA: 'A', resultB: 'B' })
+      expect(record.boundaries.operationA).toHaveLength(1)
+      expect(record.boundaries.operationB).toHaveLength(1)
+
+      const callA = record.boundaries.operationA[0]
+      const callB = record.boundaries.operationB[0]
+
+      expect(callA.timing.duration).toBeGreaterThanOrEqual(40)
+      expect(callB.timing.duration).toBeGreaterThanOrEqual(40)
+
+      // Both calls should overlap in time since they run in parallel
+      const startDiff = Math.abs(callA.timing.startTime - callB.timing.startTime)
+      expect(startDiff).toBeLessThan(20) // Started within 20ms of each other
+    })
+  })
+
+  describe('Main function timing capture', () => {
+    it('should capture timing for main task function execution', async () => {
+      const task = createTask({
+        name: 'timing-test-main',
+        schema: new Schema({ delay: Schema.number() }),
+        boundaries: {},
+        fn: async ({ delay }) => {
+          await new Promise(resolve => setTimeout(resolve, delay))
+          return { completed: true }
+        }
+      })
+
+      const [result, error, record] = await task.safeRun({ delay: 100 })
+
+      expect(error).toBeNull()
+      expect(result).toEqual({ completed: true })
+      expect(record.timing).toEqual(expect.objectContaining({
+        startTime: expect.any(Number),
+        endTime: expect.any(Number),
+        duration: expect.any(Number)
+      }))
+      expect(record.timing?.duration).toBeGreaterThanOrEqual(90)
+      expect(record.timing?.duration).toBeLessThan(150)
+    })
+
+    it('should capture timing even when main function throws error', async () => {
+      const task = createTask({
+        name: 'timing-test-main-error',
+        schema: new Schema({ delay: Schema.number() }),
+        boundaries: {},
+        fn: async ({ delay }) => {
+          await new Promise(resolve => setTimeout(resolve, delay))
+          throw new Error('Intentional error')
+        }
+      })
+
+      const [result, error, record] = await task.safeRun({ delay: 80 })
+
+      expect(result).toBeNull()
+      expect(error).not.toBeNull()
+      expect(record.timing).toEqual(expect.objectContaining({
+        startTime: expect.any(Number),
+        endTime: expect.any(Number),
+        duration: expect.any(Number)
+      }))
+      expect(record.timing?.duration).toBeGreaterThanOrEqual(70)
+      expect(record.timing?.duration).toBeLessThan(120)
+    })
+
+    it('should include both main function and boundary timing', async () => {
+      const task = createTask({
+        name: 'timing-test-comprehensive',
+        schema: new Schema({ delay: Schema.number() }),
+        boundaries: {
+          slowBoundary: async (delay: number) => {
+            await new Promise(resolve => setTimeout(resolve, delay))
+            return 'boundary-result'
+          }
+        },
+        fn: async ({ delay }, { slowBoundary }) => {
+          await new Promise(resolve => setTimeout(resolve, delay))
+          const boundaryResult = await slowBoundary(delay)
+          await new Promise(resolve => setTimeout(resolve, delay))
+          return { main: 'completed', boundary: boundaryResult }
+        }
+      })
+
+      const [result, error, record] = await task.safeRun({ delay: 50 })
+
+      expect(error).toBeNull()
+      expect(result).toEqual({ main: 'completed', boundary: 'boundary-result' })
+
+      // Main function timing should include all delays
+      expect(record.timing?.duration).toBeGreaterThanOrEqual(140) // 3 * 50ms delays
+      expect(record.timing?.duration).toBeLessThan(200)
+
+      // Boundary timing should only include its delay
+      expect(record.boundaries.slowBoundary[0].timing.duration).toBeGreaterThanOrEqual(40)
+      expect(record.boundaries.slowBoundary[0].timing.duration).toBeLessThan(80)
+
+      // Boundary timing should be within the main function timing
+      const mainTiming = record.timing!
+      const boundaryTiming = record.boundaries.slowBoundary[0].timing
+
+      expect(boundaryTiming.startTime).toBeGreaterThanOrEqual(mainTiming.startTime)
+      expect(boundaryTiming.endTime).toBeLessThanOrEqual(mainTiming.endTime)
+    })
+  })
+
+  describe('Edge cases and error scenarios', () => {
+    it('should handle timing when schema validation fails', async () => {
+      const task = createTask({
+        name: 'timing-test-validation-error',
+        schema: new Schema({ requiredField: Schema.string() }),
+        boundaries: {},
+        fn: async ({ requiredField }) => {
+          return { field: requiredField }
+        }
+      })
+
+      // siabled to test an incorrect execution
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const [result, error, record] = await task.safeRun({ wrongField: 'test' } as any)
+
+      expect(result).toBeNull()
+      expect(error).not.toBeNull()
+      expect(record.type).toBe('error')
+
+      // Should not have main function timing since function wasn't executed
+      expect(record.timing).toBeUndefined()
+    })
+
+    it('should handle timing with very fast operations', async () => {
+      const task = createTask({
+        name: 'timing-test-fast',
+        schema: new Schema({ input: Schema.string() }),
+        boundaries: {
+          fastOperation: async (data: string) => {
+            return data.toUpperCase() // Very fast operation
+          }
+        },
+        fn: async ({ input }, { fastOperation }) => {
+          const result = await fastOperation(input)
+          return { result }
+        }
+      })
+
+      const [result, error, record] = await task.safeRun({ input: 'test' })
+
+      expect(error).toBeNull()
+      expect(result).toEqual({ result: 'TEST' })
+
+      const boundaryCall = record.boundaries.fastOperation[0]
+      expect(boundaryCall.timing).toEqual(expect.objectContaining({
+        startTime: expect.any(Number),
+        endTime: expect.any(Number),
+        duration: expect.any(Number)
+      }))
+
+      // Even very fast operations should have non-negative duration
+      expect(boundaryCall.timing.duration).toBeGreaterThanOrEqual(0)
+      expect(boundaryCall.timing.duration).toBeLessThan(50)
+    })
+  })
+})

package/src/test/timing-utilities.test.ts

@@ -0,0 +1,145 @@
+import { TimingTracker, type TimingInfo, type Metric, type BoundaryTimingRecord, type BaseExecutionRecord } from '../types'
+
+describe('Timing Utilities', () => {
+  describe('TimingTracker', () => {
+    it('should track timing correctly with proper TypeScript types', () => {
+      const tracker: TimingTracker = new TimingTracker()
+
+      tracker.start()
+      const timing: TimingInfo | null = tracker.end()
+
+      expect(timing).not.toBeNull()
+      if (timing) {
+        expect(typeof timing.startTime).toBe('number')
+        expect(typeof timing.endTime).toBe('number')
+        expect(typeof timing.duration).toBe('number')
+        expect(timing.startTime).toBeLessThanOrEqual(timing.endTime)
+        expect(timing.duration).toBeGreaterThanOrEqual(0)
+        expect(timing.duration).toBe(timing.endTime - timing.startTime)
+      }
+    })
+
+    it('should return null if end() called without start()', () => {
+      const tracker: TimingTracker = new TimingTracker()
+      const timing: TimingInfo | null = tracker.end()
+
+      expect(timing).toBeNull()
+    })
+
+    it('should create new instances via static method with correct type', () => {
+      const tracker: TimingTracker = TimingTracker.create()
+      expect(tracker).toBeInstanceOf(TimingTracker)
+    })
+
+    it('should handle multiple start/end cycles', () => {
+      const tracker: TimingTracker = new TimingTracker()
+
+      // First cycle
+      tracker.start()
+      const timing1: TimingInfo | null = tracker.end()
+      expect(timing1).not.toBeNull()
+
+      // Second cycle
+      tracker.start()
+      const timing2: TimingInfo | null = tracker.end()
+      expect(timing2).not.toBeNull()
+
+      if (timing1 && timing2) {
+        expect(timing2.startTime).toBeGreaterThanOrEqual(timing1.endTime)
+      }
+    })
+  })
+
+  describe('TypeScript Type Definitions', () => {
+    it('should enforce TimingInfo structure with required properties', () => {
+      const timing: TimingInfo = {
+        startTime: 1000,
+        endTime: 2000,
+        duration: 1000
+      }
+
+      expect(timing.startTime).toBe(1000)
+      expect(timing.endTime).toBe(2000)
+      expect(timing.duration).toBe(1000)
+
+      // TypeScript should enforce these are numbers
+      expect(typeof timing.startTime).toBe('number')
+      expect(typeof timing.endTime).toBe('number')
+      expect(typeof timing.duration).toBe('number')
+    })
+
+    it('should enforce Metric structure with typed properties', () => {
+      const metric: Metric = {
+        type: 'performance',
+        name: 'response_time',
+        value: 150
+      }
+
+      expect(metric.type).toBe('performance')
+      expect(metric.name).toBe('response_time')
+      expect(metric.value).toBe(150)
+
+      // TypeScript should enforce correct types
+      expect(typeof metric.type).toBe('string')
+      expect(typeof metric.name).toBe('string')
+      expect(typeof metric.value).toBe('number')
+    })
+
+    it('should support generic BoundaryTimingRecord with proper typing', () => {
+      const stringNumberRecord: BoundaryTimingRecord<[string], number> = {
+        input: ['test'],
+        output: 42,
+        timing: {
+          startTime: 1000,
+          endTime: 2000,
+          duration: 1000
+        }
+      }
+
+      expect(stringNumberRecord.input).toEqual(['test'])
+      expect(stringNumberRecord.output).toBe(42)
+      expect(stringNumberRecord.timing.duration).toBe(1000)
+
+      // Test with error record
+      const errorRecord: BoundaryTimingRecord<[string], never> = {
+        input: ['test'],
+        error: 'Something went wrong',
+        timing: {
+          startTime: 1000,
+          endTime: 2000,
+          duration: 1000
+        }
+      }
+
+      expect(errorRecord.input).toEqual(['test'])
+      expect(errorRecord.error).toBe('Something went wrong')
+      expect(errorRecord.output).toBeUndefined()
+    })
+
+    it('should support BaseExecutionRecord with comprehensive typing', () => {
+      const executionRecord: BaseExecutionRecord<{ userId: string }, { result: number }> = {
+        input: { userId: 'user123' },
+        output: { result: 42 },
+        taskName: 'testTask',
+        metadata: { environment: 'test' },
+        metrics: [
+          { type: 'performance', name: 'execution_time', value: 150 }
+        ],
+        timing: {
+          startTime: 1000,
+          endTime: 2000,
+          duration: 1000
+        },
+        type: 'success'
+      }
+
+      expect(executionRecord.input.userId).toBe('user123')
+      expect(executionRecord.output?.result).toBe(42)
+      expect(executionRecord.taskName).toBe('testTask')
+      expect(executionRecord.metadata?.environment).toBe('test')
+      expect(executionRecord.metrics?.[0].value).toBe(150)
+      expect(executionRecord.timing?.duration).toBe(1000)
+      expect(executionRecord.type).toBe('success')
+    })
+  })
+})