@forgehive/task 0.2.1 → 0.2.3

package/src/index.ts

@@ -50,9 +50,6 @@ export interface ReplayConfig<B extends Boundaries = Boundaries> {
   }
 }
 
-// ToDo: Add a type for the boundaries data
-
-
 // Make BoundaryLog generic
 export type BoundaryLog<I extends unknown[] = unknown[], O = unknown> = BoundaryRecord<I, O>;
 
@@ -139,10 +136,19 @@ type BoundaryData = Array<{input: unknown[], output?: unknown}>
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type InferSchemaType<S> = S extends Schema<any> ? InferSchema<S> : Record<string, unknown>;
 
+// Type for execution record boundaries that are automatically injected
+// When adding new execution boundaries, add their types here
+export type ExecutionRecordBoundaries = {
+  setMetadata: (key: string, value: string) => Promise<void>
+  // Future execution boundaries can be added here:
+  // setContext: (context: Record<string, unknown>) => Promise<void>
+  // addTag: (tag: string) => Promise<void>
+}
+
 // Helper type for task function with proper typing
 export type TaskFunction<S, B extends Boundaries> =
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  (argv: InferSchemaType<S>, boundaries: WrappedBoundaries<B>) => Promise<any>;
+  (argv: InferSchemaType<S>, boundaries: WrappedBoundaries<B> & ExecutionRecordBoundaries) => Promise<any>;
 
 /**
  * Utility function to compute the execution record type based on output and error state
@@ -163,7 +169,11 @@ export const Task = class Task<
   B extends Boundaries = Boundaries,
   Func extends BaseFunction = BaseFunction
 > implements TaskInstanceType<Func, B> {
-  public version: string = '0.1.7'
+  public version: string = '0.1.8'
+
+  // Static property for global listener
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  static globalListener?: (record: ExecutionRecord<any, any, any>) => Promise<void>
 
   _fn: Func
   _mode: Mode
@@ -181,6 +191,29 @@ export const Task = class Task<
   _schema: Schema<Record<string, SchemaType>> | undefined
   _listener?: ((record: ExecutionRecord<Parameters<Func>[0], ReturnType<Func>, B>) => void) | undefined
 
+  // Static method to set global listener
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  static listenExecutionRecords(listener: (record: ExecutionRecord<any, any, any>) => Promise<void>): void {
+    this.globalListener = listener
+  }
+
+  // Static method to emit to global listener with error handling
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  static emitExecutionRecord(record: ExecutionRecord<any, any, any>): void {
+    if (this.globalListener) {
+      // Call listener on next tick to avoid blocking task execution
+      process.nextTick(async () => {
+        try {
+          await this.globalListener!(record)
+        } catch (error) {
+          // Log error but don't affect task execution
+          // eslint-disable-next-line no-console
+          console.error('ExecutionRecord listener error:', error)
+        }
+      })
+    }
+  }
+
   constructor (fn: Func, conf: TaskConfig<B> = {
     name: undefined,
     description: undefined,
@@ -297,9 +330,13 @@ export const Task = class Task<
     Plus all the boundary data
   */
   emit (data: ExecutionRecord<Parameters<Func>[0], ReturnType<Func>, B>): void {
-    if (typeof this._listener === 'undefined') { return }
+    // Emit to instance listener
+    if (typeof this._listener !== 'undefined') {
+      this._listener(data)
+    }
 
-    this._listener(data)
+    // Emit to global listener (non-blocking)
+    Task.emitExecutionRecord(data)
   }
 
   getBoundaries (): WrappedBoundaries<B> {
@@ -355,6 +392,28 @@ export const Task = class Task<
     this._boundaryMocks = {}
   }
 
+  /**
+   * Creates execution record boundaries that modify execution metadata and logging
+   * These boundaries are automatically injected into all task executions
+   *
+   * To add a new execution boundary:
+   * 1. Add the boundary function here
+   * 2. Update the ExecutionRecordBoundaries type to include the new boundary
+   * 3. That's it! The boundary will be available in all tasks automatically
+   */
+  _createExecutionBoundaries(metadata: Record<string, string>): Record<string, WrappedBoundaryFunction> {
+    return {
+      // Allows setting metadata key-value pairs from within task execution
+      setMetadata: createBoundary(async (...args: unknown[]): Promise<void> => {
+        const [key, value] = args as [string, string]
+        metadata[key] = value
+      })
+
+      // Future execution boundaries can be added here:
+      // addMetrics: createBoundary(async (...args: unknown[]): Promise<void> => { ... }),
+    }
+  }
+
   _createBounderies ({
     definition,
     baseData,
@@ -431,9 +490,16 @@ export const Task = class Task<
       mode: this._mode
     })
 
+    // Create and inject execution record boundaries (setMetadata, etc.)
+    const executionRecordBoundaries = this._createExecutionBoundaries(metadata)
+    const allBoundaries = {
+      ...executionBoundaries,
+      ...executionRecordBoundaries
+    }
+
     // Start run for each boundary
-    for (const name in executionBoundaries) {
-      const boundary = executionBoundaries[name]
+    for (const name in allBoundaries) {
+      const boundary = allBoundaries[name]
       boundary.startRun()
     }
 
@@ -470,7 +536,7 @@ export const Task = class Task<
       // Execute the task function
       output = await this._fn(
         argv as Parameters<Func>[0],
-        executionBoundaries as unknown as Parameters<Func>[1]
+        allBoundaries as unknown as Parameters<Func>[1]
       )
 
       logItem.output = output
@@ -507,6 +573,9 @@ export const Task = class Task<
       }
     }
 
+    // Filter out setMetadata boundary calls from the logs (they should not appear in execution record)
+    // Note: setMetadata is not part of the original boundaries definition, so it won't be in boundariesRunLog anyway
+
     // Set boundaries in log item before emitting
     logItem.boundaries = boundariesRunLog
 
@@ -566,9 +635,18 @@ export const Task = class Task<
       boundaryModes: config.boundaries
     })
 
+    // Create and inject execution record boundaries (setMetadata, etc.)
+    // Clone the metadata to avoid mutating the original metadata
+    const replayMetadata = { ...(logItem.metadata || {}) }
+    const executionRecordBoundaries = this._createExecutionBoundaries(replayMetadata)
+    const allBoundaries = {
+      ...executionBoundaries,
+      ...executionRecordBoundaries
+    }
+
     // Start run for each boundary
-    for (const name in executionBoundaries) {
-      const boundary = executionBoundaries[name]
+    for (const name in allBoundaries) {
+      const boundary = allBoundaries[name]
       boundary.startRun()
     }
 
@@ -603,7 +681,7 @@ export const Task = class Task<
       // Execute the task function with replay boundaries
       output = await this._fn(
         argv,
-        executionBoundaries as unknown as Parameters<Func>[1]
+        allBoundaries as unknown as Parameters<Func>[1]
       )
 
       logItem.output = output
@@ -632,9 +710,15 @@ export const Task = class Task<
       }
     }
 
+    // Filter out setMetadata boundary calls from the logs (they should not appear in execution record)
+    // Note: setMetadata is not part of the original boundaries definition, so it won't be in boundariesRunLog anyway
+
     // Set boundaries in log item before emitting
     logItem.boundaries = boundariesRunLog
 
+    // Update the log item metadata with changes made during replay
+    logItem.metadata = replayMetadata
+
     // Emit the log item
     this.emit(logItem)
 
@@ -684,6 +768,12 @@ export const Task = class Task<
       // Call the task's safeRun method
       const [outcome, error, log] = await this.safeRun(eventArgs)
 
+      // Extend log metadata with environment info
+      log.metadata = {
+        ...log.metadata,
+        environment: 'hive-lambda'
+      }
+
       // Send log to Hive if environment variables are present
       await this._sendToHive(log)
 
@@ -823,7 +913,7 @@ export interface CreateTaskConfig<
   description?: string
   schema: S
   boundaries: B
-  fn: (argv: InferSchemaType<S>, boundaries: WrappedBoundaries<B>) => Promise<R>
+  fn: (argv: InferSchemaType<S>, boundaries: WrappedBoundaries<B> & ExecutionRecordBoundaries) => Promise<R>
   mode?: Mode
   boundariesData?: BoundaryTapeData
 }

package/src/test/execution-record-boundaries.test.ts

@@ -0,0 +1,266 @@
+import { createTask, Schema } from '../index'
+
+describe('execution-record-boundaries', () => {
+  describe('setMetadata boundary', () => {
+    it('should add metadata to execution record when setMetadata is called', async () => {
+      // Create a schema
+      const schema = new Schema({
+        value: Schema.number()
+      })
+
+      // Create a task that uses setMetadata
+      const task = createTask({
+        name: 'metadata-test-task',
+        schema,
+        boundaries: {
+          multiply: async (value: number) => value * 2
+        },
+        fn: async ({ value }, { multiply, setMetadata }) => {
+          await setMetadata('userId', '12345')
+          await setMetadata('executionType', 'background')
+
+          const result = await multiply(value)
+          return { result }
+        }
+      })
+
+      // Run the task with safeRun
+      const [result, error, record] = await task.safeRun({ value: 5 })
+
+      // Verify the execution was successful
+      expect(error).toBeNull()
+      expect(result).toEqual({ result: 10 })
+
+      // Verify the metadata is included in the record
+      expect(record.metadata).toEqual({
+        userId: '12345',
+        executionType: 'background'
+      })
+
+      // Verify the task name and other fields are correct
+      expect(record.taskName).toBe('metadata-test-task')
+      expect(record.input).toEqual({ value: 5 })
+      expect(record.output).toEqual({ result: 10 })
+      expect(record.type).toBe('success')
+    })
+
+    it('should not include setMetadata calls in boundary logs', async () => {
+      // Create a schema
+      const schema = new Schema({
+        value: Schema.number()
+      })
+
+      // Create a task that uses setMetadata and other boundaries
+      const task = createTask({
+        name: 'boundary-log-test',
+        schema,
+        boundaries: {
+          multiply: async (value: number) => value * 2,
+          fetchData: async (data: string) => `fetched-${data}`
+        },
+        fn: async ({ value }, { multiply, fetchData, setMetadata }) => {
+          await setMetadata('step', 'start')
+
+          const multiplied = await multiply(value)
+          await setMetadata('step', 'multiplied')
+
+          const fetched = await fetchData('test')
+          await setMetadata('step', 'completed')
+
+          return { multiplied, fetched }
+        }
+      })
+
+      // Run the task with safeRun
+      const [result, error, record] = await task.safeRun({ value: 3 })
+
+      // Verify the execution was successful
+      expect(error).toBeNull()
+      expect(result).toEqual({ multiplied: 6, fetched: 'fetched-test' })
+
+      // Verify the metadata is updated to the final value
+      expect(record.metadata).toEqual({
+        step: 'completed'
+      })
+
+      // Verify that only the actual boundaries appear in the logs
+      expect(record.boundaries).toHaveProperty('multiply')
+      expect(record.boundaries).toHaveProperty('fetchData')
+      expect(record.boundaries).not.toHaveProperty('setMetadata')
+
+      // Verify the boundary logs contain the expected calls
+      expect(record.boundaries.multiply).toHaveLength(1)
+      expect(record.boundaries.multiply[0]).toEqual({
+        input: [3],
+        output: 6
+      })
+
+      expect(record.boundaries.fetchData).toHaveLength(1)
+      expect(record.boundaries.fetchData[0]).toEqual({
+        input: ['test'],
+        output: 'fetched-test'
+      })
+    })
+
+    it('should preserve metadata in error scenarios', async () => {
+      // Create a schema
+      const schema = new Schema({
+        value: Schema.number()
+      })
+
+      // Create a task that sets metadata before throwing an error
+      const task = createTask({
+        name: 'error-metadata-test',
+        schema,
+        boundaries: {},
+        fn: async ({ value }, { setMetadata }) => {
+          await setMetadata('errorContext', 'validation')
+          await setMetadata('userId', '67890')
+
+          if (value < 0) {
+            throw new Error('Value cannot be negative')
+          }
+
+          return { result: value }
+        }
+      })
+
+      // Run the task with a value that will cause an error
+      const [result, error, record] = await task.safeRun({ value: -1 })
+
+      // Verify the execution failed as expected
+      expect(result).toBeNull()
+      expect(error).not.toBeNull()
+      expect(error?.message).toBe('Value cannot be negative')
+
+      // Verify the metadata is preserved in the error record
+      expect(record.metadata).toEqual({
+        errorContext: 'validation',
+        userId: '67890'
+      })
+
+      // Verify other record fields
+      expect(record.taskName).toBe('error-metadata-test')
+      expect(record.input).toEqual({ value: -1 })
+      expect(record.error).toBe('Value cannot be negative')
+      expect(record.type).toBe('error')
+    })
+
+    it('should preserve existing metadata when adding new metadata', async () => {
+      // Create a schema
+      const schema = new Schema({
+        value: Schema.number()
+      })
+
+      // Create a task that uses setMetadata
+      const task = createTask({
+        name: 'preserve-metadata-test',
+        schema,
+        boundaries: {},
+        fn: async ({ value }, { setMetadata }) => {
+          await setMetadata('step1', 'completed')
+          await setMetadata('step2', 'in-progress')
+          await setMetadata('step1', 'updated') // Overwrite step1
+
+          return { result: value * 2 }
+        }
+      })
+
+      // Run the task with initial metadata context
+      const [result, error, record] = await task.safeRun({ value: 4 })
+
+      // Verify the execution was successful
+      expect(error).toBeNull()
+      expect(result).toEqual({ result: 8 })
+
+      // Verify the metadata contains the final values
+      expect(record.metadata).toEqual({
+        step1: 'updated',
+        step2: 'in-progress'
+      })
+    })
+
+    it('should work with setMetadata in safeReplay', async () => {
+      // Create a schema
+      const schema = new Schema({
+        value: Schema.number()
+      })
+
+      // Use a counter to ensure different values between original and replay
+      let executionCounter = 0
+
+      // Create a task with boundaries and metadata
+      const task = createTask({
+        name: 'replay-metadata-test',
+        schema,
+        boundaries: {
+          fetchData: async (value: number) => value * 3
+        },
+        fn: async ({ value }, { fetchData, setMetadata }) => {
+          executionCounter++
+          await setMetadata('replayTest', 'true')
+          await setMetadata('executionNumber', executionCounter.toString())
+
+          const result = await fetchData(value)
+          return { result }
+        }
+      })
+
+      // First, run the task normally to get an execution record
+      const [, , originalRecord] = await task.safeRun({ value: 2 })
+
+      // Verify original metadata was set
+      expect(originalRecord.metadata).toHaveProperty('replayTest', 'true')
+      expect(originalRecord.metadata).toHaveProperty('executionNumber', '1')
+
+      // Now replay the task
+      const [replayResult, replayError, replayRecord] = await task.safeReplay(
+        originalRecord,
+        { boundaries: { fetchData: 'replay' } }
+      )
+
+      // Verify the replay was successful
+      expect(replayError).toBeNull()
+      expect(replayResult).toEqual({ result: 6 })
+
+      // Verify that the replay has its own metadata (setMetadata was called again)
+      expect(replayRecord.metadata).toHaveProperty('replayTest', 'true')
+      expect(replayRecord.metadata).toHaveProperty('executionNumber', '2')
+
+      // The execution numbers should be different since setMetadata was called again
+      expect(replayRecord.metadata?.executionNumber).not.toBe(originalRecord.metadata?.executionNumber)
+      expect(originalRecord.metadata?.executionNumber).toBe('1')
+      expect(replayRecord.metadata?.executionNumber).toBe('2')
+    })
+
+    it('should handle empty metadata gracefully', async () => {
+      // Create a schema
+      const schema = new Schema({
+        value: Schema.number()
+      })
+
+      // Create a task that doesn't use setMetadata
+      const task = createTask({
+        name: 'no-metadata-test',
+        schema,
+        boundaries: {
+          multiply: async (value: number) => value * 2
+        },
+        fn: async ({ value }, { multiply }) => {
+          const result = await multiply(value)
+          return { result }
+        }
+      })
+
+      // Run the task without using setMetadata
+      const [result, error, record] = await task.safeRun({ value: 7 })
+
+      // Verify the execution was successful
+      expect(error).toBeNull()
+      expect(result).toEqual({ result: 14 })
+
+      // Verify the metadata is empty but defined
+      expect(record.metadata).toEqual({})
+    })
+  })
+})