@forgehive/task 0.2.0 → 0.2.2

package/src/index.ts

@@ -51,19 +51,7 @@ export interface ReplayConfig<B extends Boundaries = Boundaries> {
 }
 
 // ToDo: Add a type for the boundaries data
-/**
- * Represents the record passed to task listeners
- */
-export interface TaskRecord<InputType = unknown, OutputType = unknown> {
-  /** The input arguments passed to the task */
-  input: InputType;
-  /** The output returned by the task (if successful) */
-  output?: OutputType | null;
-  /** The error message if the task failed */
-  error?: string;
-  /** Boundary execution data */
-  boundaries?: Record<string, unknown>;
-}
+
 
 // Make BoundaryLog generic
 export type BoundaryLog<I extends unknown[] = unknown[], O = unknown> = BoundaryRecord<I, O>;
@@ -113,9 +101,9 @@ export interface TaskInstanceType<Func extends BaseFunction = BaseFunction, B ex
   isValid: <T extends Record<string, unknown> = Parameters<Func>[0]>(argv?: T) => boolean
 
   // Listener methods
-  addListener: <I = Parameters<Func>[0], O = ReturnType<Func>>(fn: (record: TaskRecord<I, O>) => void) => void
+  addListener: <I = Parameters<Func>[0], O = ReturnType<Func>>(fn: (record: ExecutionRecord<I, O, B>) => void) => void
   removeListener: () => void
-  emit: (data: Partial<TaskRecord>) => void
+  emit: (data: ExecutionRecord<Parameters<Func>[0], ReturnType<Func>, B>) => void
 
   // Boundary methods
   asBoundary: () => (args: Parameters<Func>[0]) => Promise<ReturnType<Func>>
@@ -151,10 +139,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
@@ -191,7 +188,7 @@ export const Task = class Task<
   _boundaryMocks: Record<string, WrappedBoundaryFunction> = {}
 
   _schema: Schema<Record<string, SchemaType>> | undefined
-  _listener?: ((record: TaskRecord<Parameters<Func>[0], ReturnType<Func>>) => void) | undefined
+  _listener?: ((record: ExecutionRecord<Parameters<Func>[0], ReturnType<Func>, B>) => void) | undefined
 
   constructor (fn: Func, conf: TaskConfig<B> = {
     name: undefined,
@@ -296,8 +293,8 @@ export const Task = class Task<
   }
 
   // Posible improvement to handle multiple listeners, but so far its not needed
-  addListener<I = Parameters<Func>[0], O = ReturnType<Func>>(fn: (record: TaskRecord<I, O>) => void): void {
-    this._listener = fn as (record: TaskRecord<Parameters<Func>[0], ReturnType<Func>>) => void
+  addListener<I = Parameters<Func>[0], O = ReturnType<Func>>(fn: (record: ExecutionRecord<I, O, B>) => void): void {
+    this._listener = fn as (record: ExecutionRecord<Parameters<Func>[0], ReturnType<Func>, B>) => void
   }
 
   removeListener (): void {
@@ -308,10 +305,10 @@ export const Task = class Task<
     The listener get the input/outout of the call
     Plus all the boundary data
   */
-  emit (data: Partial<TaskRecord>): void {
+  emit (data: ExecutionRecord<Parameters<Func>[0], ReturnType<Func>, B>): void {
     if (typeof this._listener === 'undefined') { return }
 
-    this._listener(data as TaskRecord<Parameters<Func>[0], ReturnType<Func>>)
+    this._listener(data)
   }
 
   getBoundaries (): WrappedBoundaries<B> {
@@ -367,6 +364,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,
@@ -443,9 +462,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()
     }
 
@@ -482,7 +508,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
@@ -519,6 +545,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
 
@@ -578,9 +607,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()
     }
 
@@ -615,7 +653,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
@@ -644,9 +682,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)
 
@@ -696,6 +740,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)
 
@@ -835,7 +885,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
 }