@cadenza.io/core 3.14.0 → 3.15.0

package/dist/index.d.mts

@@ -1000,6 +1000,7 @@ declare class Task extends SignalEmitter implements Graph {
      * @return {any[]} An array containing the results of applying the callback function to each predecessor task.
      */
     mapPrevious(callback: (task: Task) => any): any[];
+    makeRoutine(name: string, description: string): this;
     /**
      * Adds the specified signals to the current instance, making it observe them.
      * If the instance is already observing a signal, it will be skipped.
@@ -1027,11 +1028,10 @@ declare class Task extends SignalEmitter implements Graph {
     /**
      * Attaches a signal to the current context and emits metadata if the register flag is set.
      *
-     * @param {string} signal - The name of the signal to attach.
-     * @param {boolean} [isOnFail=false] - Indicates if the signal should be marked as "on fail".
+     * @param {...string} signals - The names of the signals to attach.
      * @return {void} This method does not return a value.
      */
-    attachSignal(signal: string, isOnFail?: boolean): void;
+    attachSignal(...signals: string[]): Task;
     /**
      * Unsubscribes the current instance from the specified signals.
      * This method removes the signals from the observedSignals set, unsubscribes
@@ -1358,7 +1358,6 @@ declare class GraphRunner extends SignalEmitter {
      * @edge Creates 'Start run' meta-task chained to registry gets.
      */
     constructor(isMeta?: boolean);
-    init(): void;
     /**
      * Adds tasks or routines to the current execution pipeline. Supports both individual tasks,
      * routines, or arrays of tasks and routines. Handles metadata and execution context management.
@@ -1405,7 +1404,6 @@ declare class GraphRunner extends SignalEmitter {
      * @return {void}
      */
     setStrategy(strategy: GraphRunStrategy): void;
-    startRun(context: AnyObject, emit: (signal: string, ctx: AnyObject) => void): boolean;
 }
 
 /**
@@ -1440,6 +1438,7 @@ declare class SignalBroker {
         tasks: Set<Task | GraphRoutine>;
         registered: boolean;
     }>;
+    emittedSignalsRegistry: Set<string>;
     emitStacks: Map<string, Map<string, AnyObject>>;
     constructor();
     /**
@@ -1461,6 +1460,7 @@ declare class SignalBroker {
      * @edge Duplicates ignored; supports wildcards for broad listening.
      */
     observe(signal: string, routineOrTask: Task | GraphRoutine): void;
+    registerEmittedSignal(signal: string): void;
     /**
      * Unsubscribes a routine/task from a signal.
      * @param signal The signal.
@@ -1534,6 +1534,7 @@ declare class SignalBroker {
      * @returns Array of signals.
      */
     listObservedSignals(): string[];
+    listEmittedSignals(): string[];
     reset(): void;
 }
 

package/dist/index.d.ts

@@ -1000,6 +1000,7 @@ declare class Task extends SignalEmitter implements Graph {
      * @return {any[]} An array containing the results of applying the callback function to each predecessor task.
      */
     mapPrevious(callback: (task: Task) => any): any[];
+    makeRoutine(name: string, description: string): this;
     /**
      * Adds the specified signals to the current instance, making it observe them.
      * If the instance is already observing a signal, it will be skipped.
@@ -1027,11 +1028,10 @@ declare class Task extends SignalEmitter implements Graph {
     /**
      * Attaches a signal to the current context and emits metadata if the register flag is set.
      *
-     * @param {string} signal - The name of the signal to attach.
-     * @param {boolean} [isOnFail=false] - Indicates if the signal should be marked as "on fail".
+     * @param {...string} signals - The names of the signals to attach.
      * @return {void} This method does not return a value.
      */
-    attachSignal(signal: string, isOnFail?: boolean): void;
+    attachSignal(...signals: string[]): Task;
     /**
      * Unsubscribes the current instance from the specified signals.
      * This method removes the signals from the observedSignals set, unsubscribes
@@ -1358,7 +1358,6 @@ declare class GraphRunner extends SignalEmitter {
      * @edge Creates 'Start run' meta-task chained to registry gets.
      */
     constructor(isMeta?: boolean);
-    init(): void;
     /**
      * Adds tasks or routines to the current execution pipeline. Supports both individual tasks,
      * routines, or arrays of tasks and routines. Handles metadata and execution context management.
@@ -1405,7 +1404,6 @@ declare class GraphRunner extends SignalEmitter {
      * @return {void}
      */
     setStrategy(strategy: GraphRunStrategy): void;
-    startRun(context: AnyObject, emit: (signal: string, ctx: AnyObject) => void): boolean;
 }
 
 /**
@@ -1440,6 +1438,7 @@ declare class SignalBroker {
         tasks: Set<Task | GraphRoutine>;
         registered: boolean;
     }>;
+    emittedSignalsRegistry: Set<string>;
     emitStacks: Map<string, Map<string, AnyObject>>;
     constructor();
     /**
@@ -1461,6 +1460,7 @@ declare class SignalBroker {
      * @edge Duplicates ignored; supports wildcards for broad listening.
      */
     observe(signal: string, routineOrTask: Task | GraphRoutine): void;
+    registerEmittedSignal(signal: string): void;
     /**
      * Unsubscribes a routine/task from a signal.
      * @param signal The signal.
@@ -1534,6 +1534,7 @@ declare class SignalBroker {
      * @returns Array of signals.
      */
     listObservedSignals(): string[];
+    listEmittedSignals(): string[];
     reset(): void;
 }
 

package/dist/index.js

@@ -302,6 +302,7 @@ var SignalBroker = class _SignalBroker {
     this.debouncedEmitters = /* @__PURE__ */ new Map();
     // TODO: Signals should be a class with a the observers, registered flag and other data.
     this.signalObservers = /* @__PURE__ */ new Map();
+    this.emittedSignalsRegistry = /* @__PURE__ */ new Set();
     this.emitStacks = /* @__PURE__ */ new Map();
     this.addSignal("meta.signal_broker.added");
   }
@@ -408,6 +409,9 @@ var SignalBroker = class _SignalBroker {
     this.addSignal(signal);
     this.signalObservers.get(signal).tasks.add(routineOrTask);
   }
+  registerEmittedSignal(signal) {
+    this.emittedSignalsRegistry.add(signal);
+  }
   /**
    * Unsubscribes a routine/task from a signal.
    * @param signal The signal.
@@ -683,14 +687,18 @@ var SignalBroker = class _SignalBroker {
   listObservedSignals() {
     return Array.from(this.signalObservers.keys());
   }
+  listEmittedSignals() {
+    return Array.from(this.emittedSignalsRegistry);
+  }
   reset() {
     this.emitStacks.clear();
     this.signalObservers.clear();
+    this.emittedSignalsRegistry.clear();
   }
 };
 
 // src/engine/GraphRunner.ts
-var import_uuid6 = require("uuid");
+var import_uuid5 = require("uuid");
 
 // src/engine/GraphRun.ts
 var import_uuid2 = require("uuid");
@@ -2195,8 +2203,178 @@ var GraphRoutine = class extends SignalEmitter {
   }
 };
 
+// src/engine/GraphRunner.ts
+var GraphRunner = class extends SignalEmitter {
+  /**
+   * Constructs a runner.
+   * @param isMeta Meta flag (default false).
+   * @edge Creates 'Start run' meta-task chained to registry gets.
+   */
+  constructor(isMeta = false) {
+    super(isMeta);
+    this.debug = false;
+    this.verbose = false;
+    this.isRunning = false;
+    this.isMeta = false;
+    this.isMeta = isMeta;
+    this.strategy = Cadenza.runStrategy.PARALLEL;
+    this.currentRun = new GraphRun(this.strategy);
+  }
+  /**
+   * Adds tasks or routines to the current execution pipeline. Supports both individual tasks,
+   * routines, or arrays of tasks and routines. Handles metadata and execution context management.
+   *
+   * @param {Task|GraphRoutine|(Task|GraphRoutine)[]} tasks - The task(s) or routine(s) to be added.
+   * It can be a single task, a single routine, or an array of tasks and routines.
+   * @param {AnyObject} [context={}] - Optional context object to provide execution trace and metadata.
+   * Used to propagate information across task or routine executions.
+   * @return {void} - This method does not return a value.
+   */
+  addTasks(tasks, context = {}) {
+    let _tasks = Array.isArray(tasks) ? tasks : [tasks];
+    if (_tasks.length === 0) {
+      console.warn("No tasks/routines to add.");
+      return;
+    }
+    let routineName = _tasks.map((t) => t.name).join(" | ");
+    let routineVersion = null;
+    let isMeta = _tasks.every((t) => t.isMeta);
+    const allTasks = _tasks.flatMap((t) => {
+      if (t instanceof GraphRoutine) {
+        routineName = t.name;
+        routineVersion = t.version;
+        isMeta = t.isMeta;
+        const routineTasks = [];
+        t.forEachTask((task) => routineTasks.push(task));
+        return routineTasks;
+      }
+      return t;
+    });
+    const isSubMeta = allTasks.some((t) => t.isSubMeta) || !!context.__isSubMeta;
+    context.__isSubMeta = isSubMeta;
+    const isNewTrace = !context.__routineExecId && !context.__metadata?.__executionTraceId && !context.__executionTraceId;
+    const executionTraceId = context.__metadata?.__executionTraceId ?? context.__executionTraceId ?? (0, import_uuid5.v4)();
+    context.__executionTraceId = executionTraceId;
+    const routineExecId = context.__routineExecId ?? (0, import_uuid5.v4)();
+    context.__routineExecId = routineExecId;
+    const ctx = new GraphContext(context || {});
+    if (!isSubMeta) {
+      const contextData = ctx.export();
+      if (isNewTrace) {
+        this.emitMetrics("meta.runner.new_trace", {
+          data: {
+            uuid: executionTraceId,
+            issuer_type: "service",
+            // TODO: Add issuer type
+            issuer_id: context.__metadata?.__issuerId ?? context.__issuerId ?? null,
+            issued_at: formatTimestamp(Date.now()),
+            intent: context.__metadata?.__intent ?? context.__intent ?? null,
+            context: contextData,
+            is_meta: isMeta
+          },
+          __metadata: {
+            __executionTraceId: executionTraceId
+          }
+        });
+      }
+      this.emitMetrics("meta.runner.added_tasks", {
+        data: {
+          uuid: routineExecId,
+          name: routineName,
+          routineVersion,
+          isMeta,
+          executionTraceId,
+          context: isNewTrace ? contextData.id : contextData,
+          previousRoutineExecution: context.__localRoutineExecId ?? context.__metadata?.__routineExecId ?? null,
+          created: formatTimestamp(Date.now())
+        },
+        __metadata: {
+          __executionTraceId: executionTraceId
+        }
+      });
+    }
+    allTasks.forEach(
+      (task) => this.currentRun.addNode(
+        new GraphNode(task, ctx, routineExecId, [], this.debug, this.verbose)
+      )
+    );
+  }
+  /**
+   * Executes the provided tasks or routines. Maintains the execution state
+   * and handles synchronous or asynchronous processing.
+   *
+   * @param {Task|GraphRoutine|(Task|GraphRoutine)[]} [tasks] - A single task, a single routine, or an array of tasks or routines to execute. Optional.
+   * @param {AnyObject} [context] - An optional context object to be used during task execution.
+   * @return {GraphRun|Promise<GraphRun>} - Returns a `GraphRun` instance if the execution is synchronous, or a `Promise` resolving to a `GraphRun` for asynchronous execution.
+   */
+  run(tasks, context) {
+    if (tasks) {
+      this.addTasks(tasks, context ?? {});
+    }
+    if (this.isRunning) {
+      return this.currentRun;
+    }
+    if (this.currentRun) {
+      this.isRunning = true;
+      const runResult = this.currentRun.run();
+      if (runResult instanceof Promise) {
+        return this.runAsync(runResult);
+      }
+    }
+    return this.reset();
+  }
+  /**
+   * Executes the provided asynchronous operation and resets the state afterwards.
+   *
+   * @param {Promise<void>} run - A promise representing the asynchronous operation to execute.
+   * @return {Promise<GraphRun>} A promise that resolves to the result of the reset operation after the asynchronous operation completes.
+   */
+  async runAsync(run) {
+    await run;
+    return this.reset();
+  }
+  /**
+   * Resets the current state of the graph, creating a new GraphRun instance
+   * and returning the previous run instance.
+   * If the debug mode is not enabled, it will destroy the existing resources.
+   *
+   * @return {GraphRun} The last GraphRun instance before the reset.
+   */
+  reset() {
+    this.isRunning = false;
+    const lastRun = this.currentRun;
+    if (!this.debug) {
+      this.destroy();
+    }
+    this.currentRun = new GraphRun(this.strategy);
+    return lastRun;
+  }
+  setDebug(value) {
+    this.debug = value;
+  }
+  setVerbose(value) {
+    this.verbose = value;
+  }
+  destroy() {
+    this.currentRun.destroy();
+  }
+  /**
+   * Sets the strategy to be used for running the graph and initializes
+   * the current run with the provided strategy if no process is currently running.
+   *
+   * @param {GraphRunStrategy} strategy - The strategy to use for running the graph.
+   * @return {void}
+   */
+  setStrategy(strategy) {
+    this.strategy = strategy;
+    if (!this.isRunning) {
+      this.currentRun = new GraphRun(this.strategy);
+    }
+  }
+};
+
 // src/graph/definition/Task.ts
-var import_uuid5 = require("uuid");
+var import_uuid6 = require("uuid");
 
 // src/graph/iterators/TaskIterator.ts
 var TaskIterator = class {
@@ -2345,7 +2523,7 @@ var Task = class _Task extends SignalEmitter {
   }
   clone(traverse = false, includeSignals = false) {
     const clonedTask = new _Task(
-      `${this.name} (clone ${(0, import_uuid5.v4)().slice(0, 8)})`,
+      `${this.name} (clone ${(0, import_uuid6.v4)().slice(0, 8)})`,
       this.taskFunction,
       this.description,
       this.concurrency,
@@ -2830,6 +3008,14 @@ var Task = class _Task extends SignalEmitter {
   mapPrevious(callback) {
     return Array.from(this.predecessorTasks).map(callback);
   }
+  makeRoutine(name, description) {
+    if (this.isMeta) {
+      Cadenza.createMetaRoutine(name, [this], description);
+    } else {
+      Cadenza.createRoutine(name, [this], description);
+    }
+    return this;
+  }
   /**
    * Adds the specified signals to the current instance, making it observe them.
    * If the instance is already observing a signal, it will be skipped.
@@ -2886,29 +3072,33 @@ var Task = class _Task extends SignalEmitter {
   emitsOnFail(...signals) {
     signals.forEach((signal) => {
       this.signalsToEmitOnFail.add(signal);
-      this.attachSignal(signal, true);
+      this.attachSignal(signal);
     });
     return this;
   }
   /**
    * Attaches a signal to the current context and emits metadata if the register flag is set.
    *
-   * @param {string} signal - The name of the signal to attach.
-   * @param {boolean} [isOnFail=false] - Indicates if the signal should be marked as "on fail".
+   * @param {...string} signals - The names of the signals to attach.
    * @return {void} This method does not return a value.
    */
-  attachSignal(signal, isOnFail = false) {
-    this.emitsSignals.add(signal);
-    if (this.register) {
-      this.emitWithMetadata("meta.task.attached_signal", {
-        data: {
-          signalName: signal.split(":")[0],
-          taskName: this.name,
-          taskVersion: this.version,
-          isOnFail
-        }
-      });
-    }
+  attachSignal(...signals) {
+    signals.forEach((signal) => {
+      this.emitsSignals.add(signal);
+      Cadenza.broker.registerEmittedSignal(signal);
+      if (this.register) {
+        const isOnFail = this.signalsToEmitOnFail.has(signal);
+        this.emitWithMetadata("meta.task.attached_signal", {
+          data: {
+            signalName: signal.split(":")[0],
+            taskName: this.name,
+            taskVersion: this.version,
+            isOnFail
+          }
+        });
+      }
+    });
+    return this;
   }
   /**
    * Unsubscribes the current instance from the specified signals.
@@ -3288,205 +3478,6 @@ var GraphRegistry = class _GraphRegistry {
   }
 };
 
-// src/engine/GraphRunner.ts
-var GraphRunner = class extends SignalEmitter {
-  /**
-   * Constructs a runner.
-   * @param isMeta Meta flag (default false).
-   * @edge Creates 'Start run' meta-task chained to registry gets.
-   */
-  constructor(isMeta = false) {
-    super(isMeta);
-    this.debug = false;
-    this.verbose = false;
-    this.isRunning = false;
-    this.isMeta = false;
-    this.isMeta = isMeta;
-    this.strategy = Cadenza.runStrategy.PARALLEL;
-    this.currentRun = new GraphRun(this.strategy);
-  }
-  init() {
-    if (this.isMeta) return;
-    Cadenza.createMetaTask(
-      "Start run",
-      this.startRun.bind(this),
-      "Starts a run"
-    ).doAfter(
-      GraphRegistry.instance.getTaskByName,
-      GraphRegistry.instance.getRoutineByName
-    );
-  }
-  /**
-   * Adds tasks or routines to the current execution pipeline. Supports both individual tasks,
-   * routines, or arrays of tasks and routines. Handles metadata and execution context management.
-   *
-   * @param {Task|GraphRoutine|(Task|GraphRoutine)[]} tasks - The task(s) or routine(s) to be added.
-   * It can be a single task, a single routine, or an array of tasks and routines.
-   * @param {AnyObject} [context={}] - Optional context object to provide execution trace and metadata.
-   * Used to propagate information across task or routine executions.
-   * @return {void} - This method does not return a value.
-   */
-  addTasks(tasks, context = {}) {
-    let _tasks = Array.isArray(tasks) ? tasks : [tasks];
-    if (_tasks.length === 0) {
-      console.warn("No tasks/routines to add.");
-      return;
-    }
-    let routineName = _tasks.map((t) => t.name).join(" | ");
-    let routineVersion = null;
-    let isMeta = _tasks.every((t) => t.isMeta);
-    const allTasks = _tasks.flatMap((t) => {
-      if (t instanceof GraphRoutine) {
-        routineName = t.name;
-        routineVersion = t.version;
-        isMeta = t.isMeta;
-        const routineTasks = [];
-        t.forEachTask((task) => routineTasks.push(task));
-        return routineTasks;
-      }
-      return t;
-    });
-    const isSubMeta = allTasks.some((t) => t.isSubMeta) || !!context.__isSubMeta;
-    context.__isSubMeta = isSubMeta;
-    const isNewTrace = !context.__routineExecId && !context.__metadata?.__executionTraceId && !context.__executionTraceId;
-    const executionTraceId = context.__metadata?.__executionTraceId ?? context.__executionTraceId ?? (0, import_uuid6.v4)();
-    context.__executionTraceId = executionTraceId;
-    const routineExecId = context.__routineExecId ?? (0, import_uuid6.v4)();
-    context.__routineExecId = routineExecId;
-    const ctx = new GraphContext(context || {});
-    if (!isSubMeta) {
-      const contextData = ctx.export();
-      if (isNewTrace) {
-        this.emitMetrics("meta.runner.new_trace", {
-          data: {
-            uuid: executionTraceId,
-            issuer_type: "service",
-            // TODO: Add issuer type
-            issuer_id: context.__metadata?.__issuerId ?? context.__issuerId ?? null,
-            issued_at: formatTimestamp(Date.now()),
-            intent: context.__metadata?.__intent ?? context.__intent ?? null,
-            context: contextData,
-            is_meta: isMeta
-          },
-          __metadata: {
-            __executionTraceId: executionTraceId
-          }
-        });
-      }
-      this.emitMetrics("meta.runner.added_tasks", {
-        data: {
-          uuid: routineExecId,
-          name: routineName,
-          routineVersion,
-          isMeta,
-          executionTraceId,
-          context: isNewTrace ? contextData.id : contextData,
-          previousRoutineExecution: context.__localRoutineExecId ?? context.__metadata?.__routineExecId ?? null,
-          // TODO: There is a chance this is not added to the database yet...
-          created: formatTimestamp(Date.now())
-        },
-        __metadata: {
-          __executionTraceId: executionTraceId
-        }
-      });
-    }
-    allTasks.forEach(
-      (task) => this.currentRun.addNode(
-        new GraphNode(task, ctx, routineExecId, [], this.debug, this.verbose)
-      )
-    );
-  }
-  /**
-   * Executes the provided tasks or routines. Maintains the execution state
-   * and handles synchronous or asynchronous processing.
-   *
-   * @param {Task|GraphRoutine|(Task|GraphRoutine)[]} [tasks] - A single task, a single routine, or an array of tasks or routines to execute. Optional.
-   * @param {AnyObject} [context] - An optional context object to be used during task execution.
-   * @return {GraphRun|Promise<GraphRun>} - Returns a `GraphRun` instance if the execution is synchronous, or a `Promise` resolving to a `GraphRun` for asynchronous execution.
-   */
-  run(tasks, context) {
-    if (tasks) {
-      this.addTasks(tasks, context ?? {});
-    }
-    if (this.isRunning) {
-      return this.currentRun;
-    }
-    if (this.currentRun) {
-      this.isRunning = true;
-      const runResult = this.currentRun.run();
-      if (runResult instanceof Promise) {
-        return this.runAsync(runResult);
-      }
-    }
-    return this.reset();
-  }
-  /**
-   * Executes the provided asynchronous operation and resets the state afterwards.
-   *
-   * @param {Promise<void>} run - A promise representing the asynchronous operation to execute.
-   * @return {Promise<GraphRun>} A promise that resolves to the result of the reset operation after the asynchronous operation completes.
-   */
-  async runAsync(run) {
-    await run;
-    return this.reset();
-  }
-  /**
-   * Resets the current state of the graph, creating a new GraphRun instance
-   * and returning the previous run instance.
-   * If the debug mode is not enabled, it will destroy the existing resources.
-   *
-   * @return {GraphRun} The last GraphRun instance before the reset.
-   */
-  reset() {
-    this.isRunning = false;
-    const lastRun = this.currentRun;
-    if (!this.debug) {
-      this.destroy();
-    }
-    this.currentRun = new GraphRun(this.strategy);
-    return lastRun;
-  }
-  setDebug(value) {
-    this.debug = value;
-  }
-  setVerbose(value) {
-    this.verbose = value;
-  }
-  destroy() {
-    this.currentRun.destroy();
-  }
-  /**
-   * Sets the strategy to be used for running the graph and initializes
-   * the current run with the provided strategy if no process is currently running.
-   *
-   * @param {GraphRunStrategy} strategy - The strategy to use for running the graph.
-   * @return {void}
-   */
-  setStrategy(strategy) {
-    this.strategy = strategy;
-    if (!this.isRunning) {
-      this.currentRun = new GraphRun(this.strategy);
-    }
-  }
-  // TODO This should not live here. This is deputy related.
-  startRun(context, emit) {
-    if (context.task || context.routine) {
-      const routine = context.task ?? context.routine;
-      delete context.task;
-      delete context.routine;
-      context.__routineExecId = context.__metadata?.__deputyExecId ?? null;
-      context.__isDeputy = true;
-      this.run(routine, context);
-      return true;
-    } else {
-      context.errored = true;
-      context.__error = "No routine or task defined.";
-      emit("meta.runner.failed", context);
-      return false;
-    }
-  }
-};
-
 // src/graph/definition/DebounceTask.ts
 var DebounceTask = class extends Task {
   constructor(name, task, description = "", debounceTime = 1e3, leading = false, trailing = true, maxWait = 0, concurrency = 0, timeout = 0, register = true, isUnique = false, isMeta = false, isSubMeta = false, isHidden = false, inputSchema = void 0, validateInputSchema = false, outputSchema = void 0, validateOutputSchema = false) {
@@ -4445,8 +4436,6 @@ var Cadenza = class {
     }
     this.registry = GraphRegistry.instance;
     this.broker.init();
-    this.runner.init();
-    this.metaRunner.init();
   }
   /**
    * Retrieves the available strategies for running graphs.