@forgehive/task 0.1.13 → 0.2.1

package/src/index.ts

@@ -35,6 +35,8 @@ export type {
 export { Schema }
 
 export interface TaskConfig<B extends Boundaries = Boundaries> {
+  name?: string
+  description?: string
   schema?: Schema<Record<string, SchemaType>>
   mode?: Mode
   boundaries?: B
@@ -49,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>;
@@ -85,11 +75,19 @@ export interface ExecutionRecord<InputType = unknown, OutputType = unknown, B ex
   error?: string
   /** Boundary execution data */
   boundaries: BoundaryLogsFor<B>
+  /** The name of the task (if set) */
+  taskName?: string
+  /** Additional context metadata */
+  metadata?: Record<string, string>
+  /** The type of execution record - computed from output/error state */
+  type: 'success' | 'error' | 'pending'
 }
 
 export interface TaskInstanceType<Func extends BaseFunction = BaseFunction, B extends Boundaries = Boundaries> {
   version: string
 
+  getName: () => string | undefined
+  setName: (name: string) => void
   getMode: () => Mode
   setMode: (mode: Mode) => void
   setSchema: (base: Schema<Record<string, SchemaType>>) => void
@@ -103,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>>
@@ -119,7 +117,7 @@ export interface TaskInstanceType<Func extends BaseFunction = BaseFunction, B ex
   resetMocks: () => void
 
   run: (argv?: Parameters<Func>[0]) => Promise<ReturnType<Func>>
-  safeRun: (argv?: Parameters<Func>[0]) => Promise<[Awaited<ReturnType<Func>> | null, Error | null, ExecutionRecord<Parameters<Func>[0], ReturnType<Func>, B>]>
+  safeRun: (argv?: Parameters<Func>[0], context?: Record<string, string>) => Promise<[Awaited<ReturnType<Func>> | null, Error | null, ExecutionRecord<Parameters<Func>[0], ReturnType<Func>, B>]>
 
   // Method for replaying task execution
   safeReplay: (
@@ -146,6 +144,21 @@ export type TaskFunction<S, B extends Boundaries> =
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   (argv: InferSchemaType<S>, boundaries: WrappedBoundaries<B>) => Promise<any>;
 
+/**
+ * Utility function to compute the execution record type based on output and error state
+ */
+export function getExecutionRecordType<InputType = unknown, OutputType = unknown, B extends Boundaries = Boundaries>(
+  record: Omit<ExecutionRecord<InputType, OutputType, B>, 'type'>
+): 'success' | 'error' | 'pending' {
+  if (record.error !== undefined && record.error !== null) {
+    return 'error'
+  }
+  if (record.output !== undefined && record.output !== null) {
+    return 'success'
+  }
+  return 'pending'
+}
+
 export const Task = class Task<
   B extends Boundaries = Boundaries,
   Func extends BaseFunction = BaseFunction
@@ -155,6 +168,7 @@ export const Task = class Task<
   _fn: Func
   _mode: Mode
   _coolDown: number
+  _name?: string
   _description?: string
 
   _boundariesDefinition: B
@@ -165,9 +179,11 @@ 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,
+    description: undefined,
     schema: undefined,
     mode: 'proxy',
     boundaries: undefined,
@@ -182,6 +198,10 @@ export const Task = class Task<
     this._mode = conf.mode ?? 'proxy'
     this._boundariesDefinition = conf.boundaries ?? {} as B
 
+    // Set name and description from config
+    this._name = conf.name
+    this._description = conf.description
+
     this._listener = undefined
 
     // Cool down time before killing the process on cli runner
@@ -208,6 +228,14 @@ export const Task = class Task<
     }
   }
 
+  getName(): string | undefined {
+    return this._name
+  }
+
+  setName(name: string): void {
+    this._name = name
+  }
+
   getMode (): Mode {
     return this._mode
   }
@@ -256,8 +284,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 {
@@ -268,10 +296,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> {
@@ -378,10 +406,22 @@ export const Task = class Task<
     Error | null,
     ExecutionRecord<Parameters<Func>[0], ReturnType<Func>, B>
   ]> {
-    // Initialize log item
-    const logItem: ExecutionRecord<Parameters<Func>[0], ReturnType<Func>, B> = {
+    // Metadata is empty at start. Then will be populated on the task execution
+    // Need to implement that task have a ctx and setMetadata({key, value}) boundary
+    const metadata = {} as Record<string, string>
+
+    // Initialize log item (without type initially)
+    const logItemBase = {
       input: argv as Parameters<Func>[0],
-      boundaries: {} as BoundaryLogsFor<B>
+      boundaries: {} as BoundaryLogsFor<B>,
+      taskName: this._name,
+      metadata: metadata || {}
+    }
+
+    // Create the log item with computed type
+    const logItem: ExecutionRecord<Parameters<Func>[0], ReturnType<Func>, B> = {
+      ...logItemBase,
+      type: getExecutionRecordType(logItemBase)
     }
 
     // Create fresh boundaries for this execution
@@ -410,6 +450,7 @@ export const Task = class Task<
           : 'Invalid input'
 
         logItem.error = errorMessage
+        logItem.type = 'error'
         logItem.boundaries = {} as BoundaryLogsFor<B>
 
         // Add boundary elements empty
@@ -433,9 +474,11 @@ export const Task = class Task<
       )
 
       logItem.output = output
+      logItem.type = 'success'
     } catch (caughtError) {
       const errorMessage = caughtError instanceof Error ? caughtError.message : String(caughtError)
       logItem.error = errorMessage
+      logItem.type = 'error'
       error = new Error(errorMessage)
     }
 
@@ -487,10 +530,18 @@ export const Task = class Task<
     // Extract the input from the execution log
     const argv = executionLog.input
 
-    // Initialize log item for this replay
-    const logItem: ExecutionRecord<Parameters<Func>[0], ReturnType<Func>, B> = {
+    // Initialize log item for this replay (without type initially)
+    const logItemBase = {
       input: argv,
-      boundaries: {} as BoundaryLogsFor<B>
+      boundaries: {} as BoundaryLogsFor<B>,
+      taskName: this._name,
+      metadata: executionLog.metadata || {}
+    }
+
+    // Create the log item with computed type
+    const logItem: ExecutionRecord<Parameters<Func>[0], ReturnType<Func>, B> = {
+      ...logItemBase,
+      type: getExecutionRecordType(logItemBase)
     }
 
     // Create boundaries for this replay execution with custom modes based on config
@@ -534,6 +585,7 @@ export const Task = class Task<
           : 'Invalid input'
 
         logItem.error = errorMessage
+        logItem.type = 'error'
         logItem.output = executionLog.output // Keep the original output
 
         // Copy the boundary data from the execution log
@@ -555,9 +607,11 @@ export const Task = class Task<
       )
 
       logItem.output = output
+      logItem.type = 'success'
     } catch (caughtError) {
       const errorMessage = caughtError instanceof Error ? caughtError.message : String(caughtError)
       logItem.error = errorMessage
+      logItem.type = 'error'
       error = new Error(errorMessage)
     }
 
@@ -757,12 +811,26 @@ export const Task = class Task<
   }
 }
 
+/**
+ * Configuration object for creating a task
+ */
+export interface CreateTaskConfig<
+  S extends Schema<Record<string, SchemaType>>,
+  B extends Boundaries,
+  R
+> {
+  name?: string
+  description?: string
+  schema: S
+  boundaries: B
+  fn: (argv: InferSchemaType<S>, boundaries: WrappedBoundaries<B>) => Promise<R>
+  mode?: Mode
+  boundariesData?: BoundaryTapeData
+}
+
 /**
  * Helper function to create a task with proper type inference
- * @param schema The schema to validate input against
- * @param boundaries The boundaries to use
- * @param fn The task function
- * @param config Additional task configuration
+ * @param config Configuration object containing schema, boundaries, and function
  * @returns A new Task instance with proper type inference
  */
 export function createTask<
@@ -770,17 +838,18 @@ export function createTask<
   B extends Boundaries,
   R
 >(
-  schema: S,
-  boundaries: B,
-  fn: (argv: InferSchemaType<S>, boundaries: WrappedBoundaries<B>) => Promise<R>,
-  config?: Omit<TaskConfig<B>, 'schema' | 'boundaries'>
+  config: CreateTaskConfig<S, B, R>
 ): TaskInstanceType<(argv: InferSchemaType<S>, boundaries: WrappedBoundaries<B>) => Promise<R>, B> {
-  return new Task(
-    fn,
+  const task = new Task(
+    config.fn,
     {
-      schema,
-      boundaries,
-      ...config
+      name: config.name,
+      description: config.description,
+      schema: config.schema,
+      boundaries: config.boundaries,
+      mode: config.mode,
+      boundariesData: config.boundariesData
     }
   )
+  return task
 }