@cadenza.io/core 1.3.0 → 1.5.0

package/dist/index.d.ts

@@ -361,20 +361,48 @@ declare class SignalParticipant extends SignalEmitter {
     destroy(): void;
 }
 
+type SchemaType = "string" | "number" | "boolean" | "array" | "object" | "null" | "any";
+type SchemaConstraints = {
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    enum?: any[];
+    multipleOf?: number;
+    format?: "email" | "url" | "date-time" | "uuid" | "custom";
+    oneOf?: any[];
+};
+type SchemaDefinition = {
+    type: SchemaType;
+    required?: string[];
+    properties?: {
+        [key: string]: SchemaDefinition;
+    };
+    items?: SchemaDefinition;
+    constraints?: SchemaConstraints;
+    description?: string;
+};
+
 type TaskFunction = (context: AnyObject, progressCallback: (progress: number) => void) => TaskResult;
 type TaskResult = boolean | object | Generator | Promise<any> | void;
+type ThrottleTagGetter = (context?: AnyObject, task?: Task) => string;
 declare class Task extends SignalParticipant implements Graph {
     id: string;
     readonly name: string;
     readonly description: string;
     concurrency: number;
     timeout: number;
+    readonly isMeta: boolean;
     readonly isUnique: boolean;
     readonly throttled: boolean;
     readonly isSignal: boolean;
-    readonly isMeta: boolean;
     readonly isDeputy: boolean;
     readonly isEphemeral: boolean;
+    protected inputContextSchema: SchemaDefinition | undefined;
+    protected validateInputContext: boolean;
+    protected outputContextSchema: SchemaDefinition | undefined;
+    protected validateOutputContext: boolean;
     layerIndex: number;
     progressWeight: number;
     private nextTasks;
@@ -390,14 +418,47 @@ declare class Task extends SignalParticipant implements Graph {
      * @param concurrency Limit.
      * @param timeout ms.
      * @param register Register via signal (default true).
+     * @param isUnique
+     * @param isMeta
+     * @param getTagCallback
+     * @param inputSchema
+     * @param validateInputContext
+     * @param outputSchema
+     * @param validateOutputContext
      * @edge Emits 'meta.task.created' with { __task: this } for seed.
      */
-    constructor(name: string, task: TaskFunction, description?: string, concurrency?: number, timeout?: number, register?: boolean);
+    constructor(name: string, task: TaskFunction, description?: string, concurrency?: number, timeout?: number, register?: boolean, isUnique?: boolean, isMeta?: boolean, getTagCallback?: ThrottleTagGetter | undefined, inputSchema?: SchemaDefinition | undefined, validateInputContext?: boolean, outputSchema?: SchemaDefinition | undefined, validateOutputContext?: boolean);
     getTag(context?: AnyObject): string;
     setGlobalId(id: string): void;
     setTimeout(timeout: number): void;
     setConcurrency(concurrency: number): void;
     setProgressWeight(weight: number): void;
+    setInputContextSchema(schema: SchemaDefinition): void;
+    setOutputContextSchema(schema: SchemaDefinition): void;
+    setValidateInputContext(value: boolean): void;
+    setValidateOutputContext(value: boolean): void;
+    /**
+     * Validates a context deeply against a schema.
+     * @param data - The data to validate (input context or output result).
+     * @param schema - The schema definition.
+     * @param path - The current path for error reporting (default: 'root').
+     * @returns { { valid: boolean, errors: Record<string, string> } } - Validation result with detailed errors if invalid.
+     * @description Recursively checks types, required fields, and constraints; allows extra properties not in schema.
+     */
+    protected validateSchema(data: any, schema: SchemaDefinition | undefined, path?: string): {
+        valid: boolean;
+        errors: Record<string, string>;
+    };
+    validateInput(context: AnyObject): true | AnyObject;
+    validateOutput(context: AnyObject): true | AnyObject;
+    /**
+     * Executes the task function after optional input validation.
+     * @param context - The GraphContext to validate and execute.
+     * @param progressCallback - Callback for progress updates.
+     * @returns TaskResult from the taskFunction or error object on validation failure.
+     * @edge If validateInputContext is true, validates context; on failure, emits 'meta.task.validationFailed' with detailed errors.
+     * @edge If validateOutputContext is true, validates output; on failure, emits 'meta.task.outputValidationFailed' with detailed errors.
+     */
     execute(context: GraphContext, progressCallback: (progress: number) => void): TaskResult;
     doAfter(...tasks: Task[]): this;
     then(...tasks: Task[]): this;
@@ -479,7 +540,7 @@ declare class GraphRoutine extends SignalParticipant {
     readonly description: string;
     readonly isMeta: boolean;
     private tasks;
-    constructor(name: string, tasks: Task[], description: string);
+    constructor(name: string, tasks: Task[], description: string, isMeta?: boolean);
     /**
      * Applies callback to starting tasks.
      * @param callBack The callback.
@@ -519,7 +580,7 @@ declare class GraphRunner extends SignalEmitter {
      * @edge Emits 'meta.runner.added_tasks' with metadata.
      * @edge Empty tasks warns no-op.
      */
-    protected addTasks(tasks: Task | GraphRoutine | (Task | GraphRoutine)[], context: AnyObject): void;
+    protected addTasks(tasks: Task | GraphRoutine | (Task | GraphRoutine)[], context?: AnyObject): void;
     /**
      * Runs tasks/routines.
      * @param tasks Optional tasks/routines.
@@ -545,18 +606,20 @@ declare class SignalBroker {
     static get instance(): SignalBroker;
     protected runner: GraphRunner | undefined;
     protected metaRunner: GraphRunner | undefined;
+    getSignalsTask: Task | undefined;
     protected signalObservers: Map<string, {
         fn: (runner: GraphRunner, tasks: (Task | GraphRoutine)[], context: AnyObject) => void;
         tasks: Set<Task | GraphRoutine>;
     }>;
-    protected emitStacks: Map<string, Set<string>>;
+    protected emitStacks: Map<string, Map<string, AnyObject>>;
     protected constructor();
     /**
      * Initializes with runners.
      * @param runner Standard runner for user signals.
      * @param metaRunner Meta runner for 'meta.' signals (suppresses further meta-emits).
      */
-    init(runner: GraphRunner, metaRunner: GraphRunner): void;
+    bootstrap(runner: GraphRunner, metaRunner: GraphRunner): void;
+    init(): void;
     /**
      * Observes a signal with a routine/task.
      * @param signal The signal (e.g., 'domain.action', 'domain.*' for wildcards).
@@ -580,6 +643,7 @@ declare class SignalBroker {
      * @throws Error on detected loop.
      */
     emit(signal: string, context?: AnyObject): void;
+    execute(signal: string, context: AnyObject): boolean;
     private executeListener;
     private addSignal;
     /**
@@ -591,55 +655,30 @@ declare class SignalBroker {
     reset(): void;
 }
 
-declare class MetaTask extends Task {
-    readonly isMeta: boolean;
-}
-
 declare class GraphRegistry {
     private static _instance;
     static get instance(): GraphRegistry;
     private tasks;
     private routines;
-    registerTask: MetaTask;
-    updateTaskId: MetaTask;
-    getTaskById: MetaTask;
-    getTaskByName: MetaTask;
-    getTasksByLayer: MetaTask;
-    getAllTasks: MetaTask;
-    doForEachTask: MetaTask;
-    deleteTask: MetaTask;
-    registerRoutine: MetaTask;
-    updateRoutineId: MetaTask;
-    getRoutineById: MetaTask;
-    getRoutineByName: MetaTask;
-    getAllRoutines: MetaTask;
-    doForEachRoutine: MetaTask;
-    deleteRoutine: MetaTask;
+    registerTask: Task;
+    updateTaskId: Task;
+    getTaskById: Task;
+    getTaskByName: Task;
+    getTasksByLayer: Task;
+    getAllTasks: Task;
+    doForEachTask: Task;
+    deleteTask: Task;
+    registerRoutine: Task;
+    updateRoutineId: Task;
+    getRoutineById: Task;
+    getRoutineByName: Task;
+    getAllRoutines: Task;
+    doForEachRoutine: Task;
+    deleteRoutine: Task;
     private constructor();
     reset(): void;
 }
 
-declare class UniqueTask extends Task {
-    readonly isUnique: boolean;
-}
-
-declare class UniqueMetaTask extends UniqueTask {
-    readonly isMeta: boolean;
-}
-
-type ThrottleTagGetter = (context?: AnyObject, task?: Task) => string;
-declare class ThrottledTask extends Task {
-    readonly throttled: boolean;
-    constructor(name: string, task: TaskFunction, description?: string, getTagCallback?: ThrottleTagGetter, concurrency?: number, timeout?: number, register?: boolean);
-    export(): {
-        __getTagCallback: string;
-    };
-}
-
-declare class ThrottledMetaTask extends ThrottledTask {
-    readonly isMeta: boolean;
-}
-
 interface DebounceOptions {
     leading?: boolean;
     trailing?: boolean;
@@ -653,32 +692,20 @@ declare class DebounceTask extends Task {
     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);
+    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 executeFunction;
     private debouncedTrigger;
     execute(context: GraphContext, progressCallback: (progress: number) => void): TaskResult;
 }
 
-declare class DebouncedMetaTask extends DebounceTask {
-    readonly isMeta: boolean;
-}
-
 declare class EphemeralTask extends Task {
     private readonly once;
     private readonly condition;
     readonly isEphemeral: boolean;
-    constructor(name: string, task: TaskFunction, description?: string, once?: boolean, condition?: (context: any) => boolean, concurrency?: number, timeout?: number, register?: boolean);
+    constructor(name: string, task: TaskFunction, description?: string, once?: boolean, condition?: (context: any) => boolean, concurrency?: number, timeout?: number, register?: boolean, isUnique?: boolean, isMeta?: boolean, getTagCallback?: ThrottleTagGetter | undefined, inputSchema?: SchemaDefinition | undefined, validateInputContext?: boolean, outputSchema?: SchemaDefinition | undefined, validateOutputContext?: boolean);
     execute(context: any, progressCallback: (progress: number) => void): TaskResult;
 }
 
-declare class EphemeralMetaTask extends EphemeralTask {
-    readonly isMeta: boolean;
-}
-
-declare class MetaRoutine extends GraphRoutine {
-    readonly isMeta: boolean;
-}
-
 declare class GraphAsyncRun extends GraphRunStrategy {
     constructor();
     run(): Promise<void>;
@@ -695,14 +722,21 @@ interface TaskOptions {
     concurrency?: number;
     timeout?: number;
     register?: boolean;
+    isUnique?: boolean;
+    isMeta?: boolean;
+    getTagCallback?: ThrottleTagGetter;
+    inputSchema?: SchemaDefinition;
+    validateInputContext?: boolean;
+    outputSchema?: SchemaDefinition;
+    validateOutputContext?: boolean;
 }
 declare class Cadenza {
     static broker: SignalBroker;
     static runner: GraphRunner;
     static metaRunner: GraphRunner;
     static registry: GraphRegistry;
-    private static isBootstrapped;
-    private static bootstrap;
+    protected static isBootstrapped: boolean;
+    protected static bootstrap(): void;
     static get runStrategy(): {
         PARALLEL: GraphAsyncRun;
         SEQUENTIAL: GraphStandardRun;
@@ -712,7 +746,7 @@ declare class Cadenza {
      * @param name The name to validate.
      * @throws Error if invalid.
      */
-    private static validateName;
+    protected static validateName(name: string): void;
     /**
      * Creates a standard Task and registers it in the GraphRegistry.
      * @param name Unique identifier for the task.
@@ -733,7 +767,7 @@ declare class Cadenza {
      * @returns The created MetaTask instance.
      * @throws Error if name invalid or duplicate.
      */
-    static createMetaTask(name: string, func: TaskFunction, description?: string, options?: TaskOptions): MetaTask;
+    static createMetaTask(name: string, func: TaskFunction, description?: string, options?: TaskOptions): Task;
     /**
      * Creates a UniqueTask (executes once per execution ID, merging parents) and registers it.
      * Use for fan-in/joins after parallel branches.
@@ -744,7 +778,7 @@ declare class Cadenza {
      * @returns The created UniqueTask.
      * @throws Error if invalid.
      */
-    static createUniqueTask(name: string, func: TaskFunction, description?: string, options?: TaskOptions): UniqueTask;
+    static createUniqueTask(name: string, func: TaskFunction, description?: string, options?: TaskOptions): Task;
     /**
      * Creates a UniqueMetaTask for meta-layer joins.
      * @param name Unique identifier.
@@ -753,7 +787,7 @@ declare class Cadenza {
      * @param options Optional task options.
      * @returns The created UniqueMetaTask.
      */
-    static createUniqueMetaTask(name: string, func: TaskFunction, description?: string, options?: TaskOptions): UniqueMetaTask;
+    static createUniqueMetaTask(name: string, func: TaskFunction, description?: string, options?: TaskOptions): Task;
     /**
      * Creates a ThrottledTask (rate-limited by concurrency or custom groups) and registers it.
      * @param name Unique identifier.
@@ -764,7 +798,7 @@ declare class Cadenza {
      * @returns The created ThrottledTask.
      * @edge If no getter, throttles per task ID; use for resource protection.
      */
-    static createThrottledTask(name: string, func: TaskFunction, throttledIdGetter?: ThrottleTagGetter, description?: string, options?: TaskOptions): ThrottledTask;
+    static createThrottledTask(name: string, func: TaskFunction, throttledIdGetter?: ThrottleTagGetter, description?: string, options?: TaskOptions): Task;
     /**
      * Creates a ThrottledMetaTask for meta-layer throttling.
      * @param name Identifier.
@@ -774,7 +808,7 @@ declare class Cadenza {
      * @param options Optional task options.
      * @returns The created ThrottledMetaTask.
      */
-    static createThrottledMetaTask(name: string, func: TaskFunction, throttledIdGetter?: ThrottleTagGetter, description?: string, options?: TaskOptions): ThrottledMetaTask;
+    static createThrottledMetaTask(name: string, func: TaskFunction, throttledIdGetter: ThrottleTagGetter, description?: string, options?: TaskOptions): Task;
     /**
      * Creates a DebounceTask (delays exec until quiet period) and registers it.
      * @param name Identifier.
@@ -795,7 +829,7 @@ declare class Cadenza {
      * @param options Optional task options plus optional debounce config (e.g., leading/trailing).
      * @returns The created DebouncedMetaTask.
      */
-    static createDebounceMetaTask(name: string, func: TaskFunction, description?: string, debounceTime?: number, options?: TaskOptions & DebounceOptions): DebouncedMetaTask;
+    static createDebounceMetaTask(name: string, func: TaskFunction, description?: string, debounceTime?: number, options?: TaskOptions & DebounceOptions): DebounceTask;
     /**
      * Creates an EphemeralTask (self-destructs after exec or condition) without default registration.
      * Useful for transients; optionally register if needed.
@@ -819,7 +853,7 @@ declare class Cadenza {
      * @param options Optional task options.
      * @returns The created EphemeralMetaTask.
      */
-    static createEphemeralMetaTask(name: string, func: TaskFunction, description?: string, once?: boolean, destroyCondition?: (context: any) => boolean, options?: TaskOptions): EphemeralMetaTask;
+    static createEphemeralMetaTask(name: string, func: TaskFunction, description?: string, once?: boolean, destroyCondition?: (context: any) => boolean, options?: TaskOptions): EphemeralTask;
     /**
      * Creates a GraphRoutine (named entry to starting tasks) and registers it.
      * @param name Unique identifier.
@@ -836,7 +870,7 @@ declare class Cadenza {
      * @param description Optional.
      * @returns The created MetaRoutine.
      */
-    static createMetaRoutine(name: string, tasks: Task[], description?: string): MetaRoutine;
+    static createMetaRoutine(name: string, tasks: Task[], description?: string): GraphRoutine;
     static reset(): void;
 }
 
@@ -844,8 +878,4 @@ declare class SignalTask extends Task {
     constructor(signal: string, description?: string);
 }
 
-declare class SignalMetaTask extends SignalTask {
-    readonly isMeta = true;
-}
-
-export { type AnyObject, DebounceTask, DebouncedMetaTask, EphemeralMetaTask, EphemeralTask, GraphContext, GraphRegistry, GraphRoutine, GraphRun, MetaRoutine, MetaTask, SignalEmitter, SignalMetaTask, SignalParticipant, SignalTask, Task, type TaskResult, ThrottledMetaTask, ThrottledTask, UniqueMetaTask, UniqueTask, Cadenza as default };
+export { type AnyObject, DebounceTask, EphemeralTask, GraphContext, GraphRegistry, GraphRoutine, GraphRun, SignalEmitter, SignalParticipant, SignalTask, Task, type TaskOptions, type TaskResult, Cadenza as default };