@cadenza.io/core 1.6.0 → 1.7.1

package/dist/index.d.mts

@@ -155,7 +155,9 @@ declare abstract class GraphLayer extends ExecutionChain implements Graph {
     protected nodes: GraphNode[];
     private executionTime;
     private executionStart;
+    protected debug: boolean;
     constructor(index: number);
+    setDebug(value: boolean): void;
     abstract execute(context?: GraphContext): unknown;
     get hasPreceding(): boolean;
     getNumberOfNodes(): number;
@@ -199,7 +201,9 @@ declare class GraphNode extends SignalEmitter implements Graph {
     private failed;
     private errored;
     destroyed: boolean;
-    constructor(task: Task, context: GraphContext, routineExecId: string, prevNodes?: GraphNode[]);
+    protected debug: boolean;
+    constructor(task: Task, context: GraphContext, routineExecId: string, prevNodes?: GraphNode[], debug?: boolean);
+    setDebug(value: boolean): void;
     isUnique(): boolean;
     isMeta(): boolean;
     isProcessed(): boolean;
@@ -491,6 +495,8 @@ declare abstract class GraphBuilder {
     graph: GraphLayer | undefined;
     topLayerIndex: number;
     layers: GraphLayer[];
+    debug: boolean;
+    setDebug(value: boolean): void;
     getResult(): GraphLayer;
     compose(): void;
     addNode(node: GraphNode): void;
@@ -605,6 +611,9 @@ declare class SignalBroker {
      * @returns The broker instance.
      */
     static get instance(): SignalBroker;
+    private debug;
+    setDebug(value: boolean): void;
+    protected sanitizeSignalName(signalName: string): void;
     protected runner: GraphRunner | undefined;
     protected metaRunner: GraphRunner | undefined;
     getSignalsTask: Task | undefined;
@@ -641,7 +650,6 @@ declare class SignalBroker {
      * @param context The payload.
      * @edge Fire-and-forget; guards against loops per execId (from context.__graphExecId).
      * @edge For distribution, SignalTask can prefix and proxy remote.
-     * @throws Error on detected loop.
      */
     emit(signal: string, context?: AnyObject): void;
     execute(signal: string, context: AnyObject): boolean;
@@ -652,7 +660,6 @@ declare class SignalBroker {
      * @returns Array of signals.
      */
     listObservedSignals(): string[];
-    private getRunner;
     reset(): void;
 }
 
@@ -685,17 +692,22 @@ declare class GraphRegistry {
 interface DebounceOptions {
     leading?: boolean;
     trailing?: boolean;
+    maxWait?: number;
 }
 declare class DebounceTask extends Task {
     private readonly debounceTime;
     private leading;
     private trailing;
+    private maxWait;
     private timer;
+    private maxTimer;
+    private hasLaterCall;
     private lastResolve;
     private lastReject;
     private lastContext;
     private lastTimeout;
-    constructor(name: string, task: TaskFunction, description?: string, debounceTime?: number, leading?: boolean, trailing?: boolean, concurrency?: number, timeout?: number, register?: boolean, isUnique?: boolean, isMeta?: boolean, inputSchema?: SchemaDefinition | undefined, validateInputSchema?: boolean, outputSchema?: SchemaDefinition | undefined, validateOutputSchema?: boolean);
+    private lastProgressCallback;
+    constructor(name: string, task: TaskFunction, description?: string, debounceTime?: number, leading?: boolean, trailing?: boolean, maxWait?: number, concurrency?: number, timeout?: number, register?: boolean, isUnique?: boolean, isMeta?: boolean, inputSchema?: SchemaDefinition | undefined, validateInputSchema?: boolean, outputSchema?: SchemaDefinition | undefined, validateOutputSchema?: boolean);
     private executeFunction;
     private debouncedTrigger;
     execute(context: GraphContext, progressCallback: (progress: number) => void): TaskResult;
@@ -733,17 +745,20 @@ interface TaskOptions {
     outputSchema?: SchemaDefinition;
     validateOutputContext?: boolean;
 }
+type CadenzaMode = "dev" | "debug" | "production";
 declare class Cadenza {
     static broker: SignalBroker;
     static runner: GraphRunner;
     static metaRunner: GraphRunner;
     static registry: GraphRegistry;
     protected static isBootstrapped: boolean;
+    protected static mode: CadenzaMode;
     protected static bootstrap(): void;
     static get runStrategy(): {
         PARALLEL: GraphAsyncRun;
         SEQUENTIAL: GraphStandardRun;
     };
+    static setMode(mode: CadenzaMode): void;
     /**
      * Validates a name for uniqueness and non-emptiness.
      * @param name The name to validate.

package/dist/index.d.ts

@@ -155,7 +155,9 @@ declare abstract class GraphLayer extends ExecutionChain implements Graph {
     protected nodes: GraphNode[];
     private executionTime;
     private executionStart;
+    protected debug: boolean;
     constructor(index: number);
+    setDebug(value: boolean): void;
     abstract execute(context?: GraphContext): unknown;
     get hasPreceding(): boolean;
     getNumberOfNodes(): number;
@@ -199,7 +201,9 @@ declare class GraphNode extends SignalEmitter implements Graph {
     private failed;
     private errored;
     destroyed: boolean;
-    constructor(task: Task, context: GraphContext, routineExecId: string, prevNodes?: GraphNode[]);
+    protected debug: boolean;
+    constructor(task: Task, context: GraphContext, routineExecId: string, prevNodes?: GraphNode[], debug?: boolean);
+    setDebug(value: boolean): void;
     isUnique(): boolean;
     isMeta(): boolean;
     isProcessed(): boolean;
@@ -491,6 +495,8 @@ declare abstract class GraphBuilder {
     graph: GraphLayer | undefined;
     topLayerIndex: number;
     layers: GraphLayer[];
+    debug: boolean;
+    setDebug(value: boolean): void;
     getResult(): GraphLayer;
     compose(): void;
     addNode(node: GraphNode): void;
@@ -605,6 +611,9 @@ declare class SignalBroker {
      * @returns The broker instance.
      */
     static get instance(): SignalBroker;
+    private debug;
+    setDebug(value: boolean): void;
+    protected sanitizeSignalName(signalName: string): void;
     protected runner: GraphRunner | undefined;
     protected metaRunner: GraphRunner | undefined;
     getSignalsTask: Task | undefined;
@@ -641,7 +650,6 @@ declare class SignalBroker {
      * @param context The payload.
      * @edge Fire-and-forget; guards against loops per execId (from context.__graphExecId).
      * @edge For distribution, SignalTask can prefix and proxy remote.
-     * @throws Error on detected loop.
      */
     emit(signal: string, context?: AnyObject): void;
     execute(signal: string, context: AnyObject): boolean;
@@ -652,7 +660,6 @@ declare class SignalBroker {
      * @returns Array of signals.
      */
     listObservedSignals(): string[];
-    private getRunner;
     reset(): void;
 }
 
@@ -685,17 +692,22 @@ declare class GraphRegistry {
 interface DebounceOptions {
     leading?: boolean;
     trailing?: boolean;
+    maxWait?: number;
 }
 declare class DebounceTask extends Task {
     private readonly debounceTime;
     private leading;
     private trailing;
+    private maxWait;
     private timer;
+    private maxTimer;
+    private hasLaterCall;
     private lastResolve;
     private lastReject;
     private lastContext;
     private lastTimeout;
-    constructor(name: string, task: TaskFunction, description?: string, debounceTime?: number, leading?: boolean, trailing?: boolean, concurrency?: number, timeout?: number, register?: boolean, isUnique?: boolean, isMeta?: boolean, inputSchema?: SchemaDefinition | undefined, validateInputSchema?: boolean, outputSchema?: SchemaDefinition | undefined, validateOutputSchema?: boolean);
+    private lastProgressCallback;
+    constructor(name: string, task: TaskFunction, description?: string, debounceTime?: number, leading?: boolean, trailing?: boolean, maxWait?: number, concurrency?: number, timeout?: number, register?: boolean, isUnique?: boolean, isMeta?: boolean, inputSchema?: SchemaDefinition | undefined, validateInputSchema?: boolean, outputSchema?: SchemaDefinition | undefined, validateOutputSchema?: boolean);
     private executeFunction;
     private debouncedTrigger;
     execute(context: GraphContext, progressCallback: (progress: number) => void): TaskResult;
@@ -733,17 +745,20 @@ interface TaskOptions {
     outputSchema?: SchemaDefinition;
     validateOutputContext?: boolean;
 }
+type CadenzaMode = "dev" | "debug" | "production";
 declare class Cadenza {
     static broker: SignalBroker;
     static runner: GraphRunner;
     static metaRunner: GraphRunner;
     static registry: GraphRegistry;
     protected static isBootstrapped: boolean;
+    protected static mode: CadenzaMode;
     protected static bootstrap(): void;
     static get runStrategy(): {
         PARALLEL: GraphAsyncRun;
         SEQUENTIAL: GraphStandardRun;
     };
+    static setMode(mode: CadenzaMode): void;
     /**
      * Validates a name for uniqueness and non-emptiness.
      * @param name The name to validate.

package/dist/index.js

@@ -38,9 +38,10 @@ module.exports = __toCommonJS(index_exports);
 var SignalBroker = class _SignalBroker {
   // execId -> emitted signals
   constructor() {
+    this.debug = false;
     this.signalObservers = /* @__PURE__ */ new Map();
     this.emitStacks = /* @__PURE__ */ new Map();
-    this.addSignal("meta.signal.added");
+    this.addSignal("meta.signal_broker.added");
   }
   /**
    * Singleton instance for signal management.
@@ -52,6 +53,25 @@ var SignalBroker = class _SignalBroker {
     }
     return this.instance_;
   }
+  setDebug(value) {
+    this.debug = value;
+  }
+  sanitizeSignalName(signalName) {
+    if (signalName.length > 100) {
+      throw new Error("Signal name must be less than 100 characters");
+    }
+    if (signalName.includes(" ")) {
+      throw new Error("Signal name must not contain spaces");
+    }
+    if (signalName.includes("\\")) {
+      throw new Error("Signal name must not contain backslashes");
+    }
+    if (/[A-Z]/.test(signalName.split(".").slice(1).join("."))) {
+      throw new Error(
+        "Signal name must not contain uppercase letters in the middle of the signal name. It is only allowed in the first part of the signal name."
+      );
+    }
+  }
   /**
    * Initializes with runners.
    * @param runner Standard runner for user signals.
@@ -62,7 +82,7 @@ var SignalBroker = class _SignalBroker {
     this.metaRunner = metaRunner;
   }
   init() {
-    Cadenza.createMetaTask(
+    Cadenza.createDebounceMetaTask(
       "Execute and clear queued signals",
       () => {
         for (const [id, signals] of this.emitStacks.entries()) {
@@ -74,8 +94,10 @@ var SignalBroker = class _SignalBroker {
         }
         return true;
       },
-      "Executes queued signals and clears the stack"
-    ).doOn("meta.clear_signal_queue_requested");
+      "Executes queued signals and clears the stack",
+      500,
+      { maxWait: 1e4 }
+    ).doOn("meta.process_signal_queue_requested");
     this.getSignalsTask = Cadenza.createMetaTask("Get signals", (ctx) => {
       return {
         __signals: Array.from(this.signalObservers.keys()),
@@ -114,10 +136,9 @@ var SignalBroker = class _SignalBroker {
    * @param context The payload.
    * @edge Fire-and-forget; guards against loops per execId (from context.__graphExecId).
    * @edge For distribution, SignalTask can prefix and proxy remote.
-   * @throws Error on detected loop.
    */
   emit(signal, context = {}) {
-    const execId = context.__graphExecId || "global";
+    const execId = context.__routineExecId || "global";
     if (!this.emitStacks.has(execId)) this.emitStacks.set(execId, /* @__PURE__ */ new Map());
     const stack = this.emitStacks.get(execId);
     stack.set(signal, context);
@@ -126,6 +147,7 @@ var SignalBroker = class _SignalBroker {
       executed = this.execute(signal, context);
     } finally {
       if (executed) stack.delete(signal);
+      if (stack.size === 0) this.emitStacks.delete(execId);
     }
   }
   execute(signal, context) {
@@ -136,11 +158,17 @@ var SignalBroker = class _SignalBroker {
       const parent = parts.slice(0, i).join(".");
       executed = executed || this.executeListener(parent + ".*", context);
     }
+    if (this.debug) {
+      console.log(
+        `Emitted signal ${signal} with context ${JSON.stringify(context)}`,
+        executed ? "\u2705" : "\u274C"
+      );
+    }
     return executed;
   }
   executeListener(signal, context) {
     const obs = this.signalObservers.get(signal);
-    const runner = this.getRunner(signal);
+    const runner = signal.startsWith("meta") ? this.metaRunner : this.runner;
     if (obs && obs.tasks.size && runner) {
       obs.fn(runner, Array.from(obs.tasks), context);
       return true;
@@ -149,13 +177,15 @@ var SignalBroker = class _SignalBroker {
   }
   addSignal(signal) {
     if (!this.signalObservers.has(signal)) {
+      this.sanitizeSignalName(signal);
       this.signalObservers.set(signal, {
         fn: (runner, tasks, context) => runner.run(tasks, context),
         tasks: /* @__PURE__ */ new Set()
       });
-      this.emit("meta.signal.added", { __signal: signal });
+      this.emit("meta.signal_broker.added", { __signalName: signal });
     }
   }
+  // TODO schedule signals
   /**
    * Lists all observed signals.
    * @returns Array of signals.
@@ -163,9 +193,6 @@ var SignalBroker = class _SignalBroker {
   listObservedSignals() {
     return Array.from(this.signalObservers.keys());
   }
-  getRunner(signal) {
-    return signal.startsWith("meta") ? this.metaRunner : this.runner;
-  }
   reset() {
     this.emitStacks.clear();
     this.signalObservers.clear();
@@ -612,7 +639,7 @@ var SignalEmitter = class {
 
 // src/graph/execution/GraphNode.ts
 var GraphNode = class _GraphNode extends SignalEmitter {
-  constructor(task, context, routineExecId, prevNodes = []) {
+  constructor(task, context, routineExecId, prevNodes = [], debug = false) {
     super(task.isMeta);
     this.divided = false;
     this.splitGroupId = "";
@@ -626,12 +653,17 @@ var GraphNode = class _GraphNode extends SignalEmitter {
     this.failed = false;
     this.errored = false;
     this.destroyed = false;
+    this.debug = false;
     this.task = task;
     this.context = context;
     this.previousNodes = prevNodes;
     this.id = (0, import_uuid3.v4)();
     this.routineExecId = routineExecId;
     this.splitGroupId = routineExecId;
+    this.debug = debug;
+  }
+  setDebug(value) {
+    this.debug = value;
   }
   isUnique() {
     return this.task.isUnique;
@@ -703,6 +735,9 @@ var GraphNode = class _GraphNode extends SignalEmitter {
     if (this.previousNodes.length === 0) {
       this.emit("meta.node.started_routine_execution", memento);
     }
+    if (this.debug) {
+      this.log();
+    }
     this.emit("meta.node.started", memento);
     return this.executionStart;
   }
@@ -728,7 +763,6 @@ var GraphNode = class _GraphNode extends SignalEmitter {
   }
   execute() {
     if (!this.divided && !this.processing) {
-      this.start();
       this.processing = true;
       const inputValidation = this.task.validateInput(
         this.context.getContext()
@@ -899,7 +933,13 @@ var GraphNode = class _GraphNode extends SignalEmitter {
     return this;
   }
   clone() {
-    return new _GraphNode(this.task, this.context, this.routineExecId, [this]);
+    return new _GraphNode(
+      this.task,
+      this.context,
+      this.routineExecId,
+      [this],
+      this.debug
+    );
   }
   consume(node) {
     this.context = this.context.combine(node.context);
@@ -995,7 +1035,7 @@ var GraphNode = class _GraphNode extends SignalEmitter {
     };
   }
   log() {
-    console.log(this.task.name, this.context.getContext(), this.executionTime);
+    console.log(this.task.name, this.context.getContext(), this.routineExecId);
   }
 };
 
@@ -1851,6 +1891,7 @@ var GraphRunner = class extends SignalEmitter {
     });
     const ctx = new GraphContext(context || {});
     const routineExecId = (_a = context.__routineExecId) != null ? _a : (0, import_uuid6.v4)();
+    context.__routineExecId = routineExecId;
     const data = {
       __routineExecId: routineExecId,
       __routineName: routineName,
@@ -1866,7 +1907,9 @@ var GraphRunner = class extends SignalEmitter {
     };
     this.emit("meta.runner.added_tasks", data);
     allTasks.forEach(
-      (task) => this.currentRun.addNode(new GraphNode(task, ctx, routineExecId))
+      (task) => this.currentRun.addNode(
+        new GraphNode(task, ctx, routineExecId, [], this.debug)
+      )
     );
   }
   /**
@@ -1897,9 +1940,6 @@ var GraphRunner = class extends SignalEmitter {
     return this.reset();
   }
   reset() {
-    if (this.debug) {
-      this.currentRun.log();
-    }
     this.isRunning = false;
     const lastRun = this.currentRun;
     if (!this.debug) {
@@ -1936,7 +1976,7 @@ var GraphRunner = class extends SignalEmitter {
 
 // src/graph/definition/DebounceTask.ts
 var DebounceTask = class extends Task {
-  constructor(name, task, description = "", debounceTime = 1e3, leading = false, trailing = true, concurrency = 0, timeout = 0, register = true, isUnique = false, isMeta = false, inputSchema = void 0, validateInputSchema = false, outputSchema = void 0, validateOutputSchema = false) {
+  constructor(name, task, description = "", debounceTime = 1e3, leading = false, trailing = true, maxWait = 0, concurrency = 0, timeout = 0, register = true, isUnique = false, isMeta = false, inputSchema = void 0, validateInputSchema = false, outputSchema = void 0, validateOutputSchema = false) {
     super(
       name,
       task,
@@ -1953,15 +1993,19 @@ var DebounceTask = class extends Task {
       validateOutputSchema
     );
     this.timer = null;
+    this.maxTimer = null;
+    this.hasLaterCall = false;
     this.lastResolve = null;
     this.lastReject = null;
     this.lastContext = null;
     this.lastTimeout = null;
+    this.lastProgressCallback = null;
     this.debounceTime = debounceTime;
     this.leading = leading;
     this.trailing = trailing;
+    this.maxWait = maxWait;
   }
-  executeFunction(progressCallback) {
+  executeFunction() {
     if (this.lastTimeout) {
       clearTimeout(this.lastTimeout);
     }
@@ -1969,7 +2013,7 @@ var DebounceTask = class extends Task {
     try {
       result = this.taskFunction(
         this.lastContext.getClonedContext(),
-        progressCallback
+        this.lastProgressCallback
       );
     } catch (error) {
       if (this.lastResolve) {
@@ -1987,21 +2031,46 @@ var DebounceTask = class extends Task {
   }
   debouncedTrigger(resolve, reject, context, timeout, progressCallback) {
     const callNow = this.leading && this.timer === null;
+    const isNewBurst = this.timer === null;
     if (this.timer !== null) {
       clearTimeout(this.timer);
+      this.timer = null;
     }
     this.lastResolve = resolve;
     this.lastReject = reject;
     this.lastContext = context;
     this.lastTimeout = timeout;
+    this.lastProgressCallback = progressCallback;
+    if (!callNow) {
+      this.hasLaterCall = true;
+    }
     this.timer = setTimeout(() => {
       this.timer = null;
-      if (this.trailing) {
-        this.executeFunction(progressCallback);
+      if (this.trailing && this.hasLaterCall) {
+        this.executeFunction();
+        this.hasLaterCall = false;
+      }
+      if (this.maxTimer) {
+        clearTimeout(this.maxTimer);
+        this.maxTimer = null;
       }
     }, this.debounceTime);
     if (callNow) {
-      this.executeFunction(progressCallback);
+      this.executeFunction();
+      this.hasLaterCall = false;
+    }
+    if (this.maxWait > 0 && isNewBurst) {
+      this.maxTimer = setTimeout(() => {
+        this.maxTimer = null;
+        if (this.trailing && this.hasLaterCall) {
+          if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+          }
+          this.executeFunction();
+          this.hasLaterCall = false;
+        }
+      }, this.maxWait);
     }
   }
   execute(context, progressCallback) {
@@ -2135,8 +2204,15 @@ var GraphLayer = class _GraphLayer extends ExecutionChain {
     this.nodes = [];
     this.executionTime = 0;
     this.executionStart = 0;
+    this.debug = false;
     this.index = index;
   }
+  setDebug(value) {
+    this.debug = value;
+    for (const node of this.nodes) {
+      node.setDebug(value);
+    }
+  }
   get hasPreceding() {
     return !!this.previous && this.previous instanceof _GraphLayer;
   }
@@ -2266,6 +2342,10 @@ var GraphBuilder = class {
   constructor() {
     this.topLayerIndex = 0;
     this.layers = [];
+    this.debug = false;
+  }
+  setDebug(value) {
+    this.debug = value;
   }
   getResult() {
     return this.graph;
@@ -2311,7 +2391,9 @@ var GraphBuilder = class {
     }
   }
   createLayer(index) {
-    return new SyncGraphLayer(index);
+    const layer = new SyncGraphLayer(index);
+    layer.setDebug(this.debug);
+    return layer;
   }
   getLayer(layerIndex) {
     return this.layers[layerIndex - this.topLayerIndex];
@@ -2523,7 +2605,9 @@ var GraphAsyncQueueBuilder = class extends GraphBuilder {
     }
   }
   createLayer(index) {
-    return new AsyncGraphLayer(index);
+    const layer = new AsyncGraphLayer(index);
+    layer.setDebug(this.debug);
+    return layer;
   }
 };
 
@@ -2567,6 +2651,10 @@ var Cadenza = class {
     this.runner = new GraphRunner();
     this.metaRunner = new GraphRunner(true);
     this.broker.bootstrap(this.runner, this.metaRunner);
+    if (this.mode === "debug" || this.mode === "dev") {
+      this.broker.setDebug(true);
+      this.runner.setDebug(true);
+    }
     this.registry = GraphRegistry.instance;
     this.broker.init();
     this.runner.init();
@@ -2578,6 +2666,14 @@ var Cadenza = class {
       SEQUENTIAL: new GraphStandardRun()
     };
   }
+  static setMode(mode) {
+    this.mode = mode;
+    this.bootstrap();
+    if (mode === "debug" || mode === "dev") {
+      this.broker.setDebug(true);
+      this.runner.setDebug(true);
+    }
+  }
   /**
    * Validates a name for uniqueness and non-emptiness.
    * @param name The name to validate.
@@ -2769,6 +2865,7 @@ var Cadenza = class {
     register: true,
     leading: false,
     trailing: true,
+    maxWait: 0,
     isUnique: false,
     isMeta: false,
     inputSchema: void 0,
@@ -2785,6 +2882,7 @@ var Cadenza = class {
       debounceTime,
       options.leading,
       options.trailing,
+      options.maxWait,
       options.concurrency,
       options.timeout,
       options.register,
@@ -2811,6 +2909,7 @@ var Cadenza = class {
     register: true,
     leading: false,
     trailing: true,
+    maxWait: 0,
     isUnique: false,
     isMeta: false,
     inputSchema: void 0,
@@ -2941,6 +3040,7 @@ var Cadenza = class {
   }
 };
 Cadenza.isBootstrapped = false;
+Cadenza.mode = "production";
 
 // src/graph/definition/SignalTask.ts
 var SignalTask = class extends Task {