@cadenza.io/core 1.4.0 → 1.5.1

package/dist/index.d.mts

@@ -361,8 +361,32 @@ 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;
@@ -375,6 +399,10 @@ declare class Task extends SignalParticipant implements Graph {
     readonly isSignal: 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;
@@ -392,14 +420,45 @@ declare class Task extends SignalParticipant implements Graph {
      * @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, isUnique?: boolean, isMeta?: 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;
@@ -521,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.
@@ -620,12 +679,6 @@ declare class GraphRegistry {
     reset(): void;
 }
 
-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, isUnique?: boolean, isMeta?: boolean);
-}
-
 interface DebounceOptions {
     leading?: boolean;
     trailing?: boolean;
@@ -639,7 +692,7 @@ 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, isUnique?: boolean, isMeta?: 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;
@@ -649,7 +702,7 @@ 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, isUnique?: boolean, isMeta?: 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;
 }
 
@@ -671,6 +724,11 @@ interface TaskOptions {
     register?: boolean;
     isUnique?: boolean;
     isMeta?: boolean;
+    getTagCallback?: ThrottleTagGetter;
+    inputSchema?: SchemaDefinition;
+    validateInputContext?: boolean;
+    outputSchema?: SchemaDefinition;
+    validateOutputContext?: boolean;
 }
 declare class Cadenza {
     static broker: SignalBroker;
@@ -740,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.
@@ -750,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): ThrottledTask;
+    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.
@@ -820,8 +878,4 @@ declare class SignalTask extends Task {
     constructor(signal: string, description?: string);
 }
 
-declare class UniqueTask extends Task {
-    readonly isUnique: boolean;
-}
-
-export { type AnyObject, DebounceTask, EphemeralTask, GraphContext, GraphRegistry, GraphRoutine, GraphRun, SignalEmitter, SignalParticipant, SignalTask, Task, type TaskOptions, type TaskResult, ThrottledTask, UniqueTask, Cadenza as default };
+export { type AnyObject, DebounceTask, EphemeralTask, GraphContext, GraphRegistry, GraphRoutine, GraphRun, type SchemaConstraints, type SchemaDefinition, type SchemaType, SignalEmitter, SignalParticipant, SignalTask, Task, type TaskOptions, type TaskResult, type ThrottleTagGetter, Cadenza as default };

package/dist/index.d.ts

@@ -361,8 +361,32 @@ 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;
@@ -375,6 +399,10 @@ declare class Task extends SignalParticipant implements Graph {
     readonly isSignal: 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;
@@ -392,14 +420,45 @@ declare class Task extends SignalParticipant implements Graph {
      * @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, isUnique?: boolean, isMeta?: 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;
@@ -521,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.
@@ -620,12 +679,6 @@ declare class GraphRegistry {
     reset(): void;
 }
 
-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, isUnique?: boolean, isMeta?: boolean);
-}
-
 interface DebounceOptions {
     leading?: boolean;
     trailing?: boolean;
@@ -639,7 +692,7 @@ 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, isUnique?: boolean, isMeta?: 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;
@@ -649,7 +702,7 @@ 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, isUnique?: boolean, isMeta?: 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;
 }
 
@@ -671,6 +724,11 @@ interface TaskOptions {
     register?: boolean;
     isUnique?: boolean;
     isMeta?: boolean;
+    getTagCallback?: ThrottleTagGetter;
+    inputSchema?: SchemaDefinition;
+    validateInputContext?: boolean;
+    outputSchema?: SchemaDefinition;
+    validateOutputContext?: boolean;
 }
 declare class Cadenza {
     static broker: SignalBroker;
@@ -740,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.
@@ -750,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): ThrottledTask;
+    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.
@@ -820,8 +878,4 @@ declare class SignalTask extends Task {
     constructor(signal: string, description?: string);
 }
 
-declare class UniqueTask extends Task {
-    readonly isUnique: boolean;
-}
-
-export { type AnyObject, DebounceTask, EphemeralTask, GraphContext, GraphRegistry, GraphRoutine, GraphRun, SignalEmitter, SignalParticipant, SignalTask, Task, type TaskOptions, type TaskResult, ThrottledTask, UniqueTask, Cadenza as default };
+export { type AnyObject, DebounceTask, EphemeralTask, GraphContext, GraphRegistry, GraphRoutine, GraphRun, type SchemaConstraints, type SchemaDefinition, type SchemaType, SignalEmitter, SignalParticipant, SignalTask, Task, type TaskOptions, type TaskResult, type ThrottleTagGetter, Cadenza as default };