ts-workflow-engine-lite 2.1.0

package/dist/src/engine/SchemaValidator.d.ts

@@ -0,0 +1,30 @@
+import type { TaskType, WorkflowDefinition } from "../model/Workflow.js";
+export interface ValidationError {
+    path: string;
+    message: string;
+    code: string;
+}
+export interface ValidationWarning {
+    path: string;
+    message: string;
+    code: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+}
+export declare class SchemaValidator {
+    private registeredNodeTypes;
+    constructor(registeredNodeTypes?: TaskType[]);
+    registerNodeType(nodeType: TaskType): void;
+    validate(definition: WorkflowDefinition): ValidationResult;
+    private validateNodeConfigs;
+    private validateSchema;
+    private validateNodeTypes;
+    private validateNodeIdUniqueness;
+    private validateNodeReferences;
+    private validateExpressions;
+    private detectCircularDependencies;
+    private detectUnreachableNodes;
+}

package/dist/src/engine/SchemaValidator.js

@@ -0,0 +1,630 @@
+import { validateExpression } from "./ExpressionEvaluator.js";
+export class SchemaValidator {
+    registeredNodeTypes;
+    constructor(registeredNodeTypes) {
+        this.registeredNodeTypes = new Set(registeredNodeTypes || [
+            "action",
+            "wait",
+            "event",
+            "rollback",
+            "subworkflow",
+            "http",
+            "sql",
+            "queue",
+            "condition",
+            "router",
+            "loop",
+            "approval",
+            "notification",
+            "join",
+            "transform",
+        ]);
+    }
+    registerNodeType(nodeType) {
+        this.registeredNodeTypes.add(nodeType);
+    }
+    validate(definition) {
+        const errors = [];
+        const warnings = [];
+        errors.push(...this.validateSchema(definition));
+        errors.push(...this.validateNodeTypes(definition));
+        errors.push(...this.validateNodeIdUniqueness(definition));
+        errors.push(...this.validateNodeReferences(definition));
+        errors.push(...this.validateExpressions(definition));
+        errors.push(...this.detectCircularDependencies(definition));
+        warnings.push(...this.detectUnreachableNodes(definition));
+        errors.push(...this.validateNodeConfigs(definition));
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings,
+        };
+    }
+    validateNodeConfigs(definition) {
+        const errors = [];
+        if (!definition.nodes || typeof definition.nodes !== "object") {
+            return errors;
+        }
+        Object.entries(definition.nodes).forEach(([nodeId, node]) => {
+            const config = node.config;
+            const pathPrefix = `nodes.${nodeId}`;
+            switch (node.type) {
+                case "wait":
+                    if (node.timeout === undefined &&
+                        config?.durationMs === undefined &&
+                        !config?.until) {
+                        errors.push({
+                            path: `${pathPrefix}.timeout`,
+                            message: "Wait node requires a timeout, config.durationMs, or config.until",
+                            code: "MISSING_REQUIRED_FIELD",
+                        });
+                    }
+                    break;
+                case "event":
+                    if (!node.onEvent) {
+                        errors.push({
+                            path: `${pathPrefix}.onEvent`,
+                            message: "Event node requires an onEvent",
+                            code: "MISSING_REQUIRED_FIELD",
+                        });
+                    }
+                    break;
+                case "http":
+                    if (config) {
+                        if (!config.url) {
+                            errors.push({
+                                path: `${pathPrefix}.config.url`,
+                                message: "HTTP node requires a url",
+                                code: "MISSING_REQUIRED_FIELD",
+                            });
+                        }
+                        if (!config.method) {
+                            errors.push({
+                                path: `${pathPrefix}.config.method`,
+                                message: "HTTP node requires a method",
+                                code: "MISSING_REQUIRED_FIELD",
+                            });
+                        }
+                    }
+                    break;
+                case "sql":
+                    if (config && !config.query) {
+                        errors.push({
+                            path: `${pathPrefix}.config.query`,
+                            message: "SQL node requires a query",
+                            code: "MISSING_REQUIRED_FIELD",
+                        });
+                    }
+                    break;
+                case "notification":
+                    if (!config) {
+                        errors.push({
+                            path: `${pathPrefix}.config`,
+                            message: "Notification node requires config",
+                            code: "MISSING_REQUIRED_FIELD",
+                        });
+                        break;
+                    }
+                    if (!config.channel) {
+                        errors.push({
+                            path: `${pathPrefix}.config.channel`,
+                            message: "Notification node requires a channel",
+                            code: "MISSING_REQUIRED_FIELD",
+                        });
+                    }
+                    if (!config.target) {
+                        errors.push({
+                            path: `${pathPrefix}.config.target`,
+                            message: "Notification node requires a target",
+                            code: "MISSING_REQUIRED_FIELD",
+                        });
+                    }
+                    if (!config.template) {
+                        errors.push({
+                            path: `${pathPrefix}.config.template`,
+                            message: "Notification node requires a template",
+                            code: "MISSING_REQUIRED_FIELD",
+                        });
+                    }
+                    break;
+                case "loop":
+                    if (config) {
+                        if (!config.collection) {
+                            errors.push({
+                                path: `${pathPrefix}.config.collection`,
+                                message: "Loop node requires a collection expression",
+                                code: "MISSING_REQUIRED_FIELD",
+                            });
+                        }
+                        if (!config.itemVariable) {
+                            errors.push({
+                                path: `${pathPrefix}.config.itemVariable`,
+                                message: "Loop node requires an itemVariable",
+                                code: "MISSING_REQUIRED_FIELD",
+                            });
+                        }
+                        if (!config.body) {
+                            errors.push({
+                                path: `${pathPrefix}.config.body`,
+                                message: "Loop node requires a body node ID",
+                                code: "MISSING_REQUIRED_FIELD",
+                            });
+                        }
+                    }
+                    break;
+                case "subworkflow":
+                    if (!node.subworkflowId) {
+                        errors.push({
+                            path: `${pathPrefix}.subworkflowId`,
+                            message: "Subworkflow node requires a subworkflowId",
+                            code: "MISSING_REQUIRED_FIELD",
+                        });
+                    }
+                    break;
+                case "join":
+                    if (!config) {
+                        errors.push({
+                            path: `${pathPrefix}.config`,
+                            message: "Join node requires config",
+                            code: "MISSING_REQUIRED_FIELD",
+                        });
+                        break;
+                    }
+                    if (!Array.isArray(config.waitFor) ||
+                        config.waitFor.length === 0) {
+                        errors.push({
+                            path: `${pathPrefix}.config.waitFor`,
+                            message: "Join node requires a non-empty config.waitFor array",
+                            code: "MISSING_REQUIRED_FIELD",
+                        });
+                    }
+                    break;
+                case "transform":
+                    if (!config) {
+                        errors.push({
+                            path: `${pathPrefix}.config`,
+                            message: "Transform node requires config",
+                            code: "MISSING_REQUIRED_FIELD",
+                        });
+                        break;
+                    }
+                    if (!config.output ||
+                        typeof config.output !== "object" ||
+                        Array.isArray(config.output)) {
+                        errors.push({
+                            path: `${pathPrefix}.config.output`,
+                            message: "Transform node requires config.output to be an object",
+                            code: "MISSING_REQUIRED_FIELD",
+                        });
+                    }
+                    break;
+            }
+        });
+        return errors;
+    }
+    validateSchema(definition) {
+        const errors = [];
+        if (!definition.id || typeof definition.id !== "string") {
+            errors.push({
+                path: "id",
+                message: "Workflow ID is required and must be a string",
+                code: "MISSING_REQUIRED_FIELD",
+            });
+        }
+        if (!definition.name || typeof definition.name !== "string") {
+            errors.push({
+                path: "name",
+                message: "Workflow name is required and must be a string",
+                code: "MISSING_REQUIRED_FIELD",
+            });
+        }
+        if (!definition.nodes || typeof definition.nodes !== "object") {
+            errors.push({
+                path: "nodes",
+                message: "Workflow nodes are required and must be an object",
+                code: "MISSING_REQUIRED_FIELD",
+            });
+            return errors;
+        }
+        if (!definition.startNode || typeof definition.startNode !== "string") {
+            errors.push({
+                path: "startNode",
+                message: "Start node is required and must be a string",
+                code: "MISSING_REQUIRED_FIELD",
+            });
+        }
+        if (definition.version !== undefined &&
+            typeof definition.version !== "string") {
+            errors.push({
+                path: "version",
+                message: "Version must be a string",
+                code: "INVALID_TYPE",
+            });
+        }
+        if (definition.description !== undefined &&
+            typeof definition.description !== "string") {
+            errors.push({
+                path: "description",
+                message: "Description must be a string",
+                code: "INVALID_TYPE",
+            });
+        }
+        if (definition.cron !== undefined && typeof definition.cron !== "string") {
+            errors.push({
+                path: "cron",
+                message: "Cron expression must be a string",
+                code: "INVALID_TYPE",
+            });
+        }
+        if (definition.triggerEvents !== undefined) {
+            if (!Array.isArray(definition.triggerEvents)) {
+                errors.push({
+                    path: "triggerEvents",
+                    message: "Trigger events must be an array",
+                    code: "INVALID_TYPE",
+                });
+            }
+            else {
+                definition.triggerEvents.forEach((event, index) => {
+                    if (typeof event !== "string") {
+                        errors.push({
+                            path: `triggerEvents[${index}]`,
+                            message: "Trigger event must be a string",
+                            code: "INVALID_TYPE",
+                        });
+                    }
+                });
+            }
+        }
+        Object.entries(definition.nodes).forEach(([nodeId, node]) => {
+            if (!node.id || typeof node.id !== "string") {
+                errors.push({
+                    path: `nodes.${nodeId}.id`,
+                    message: "Node ID is required and must be a string",
+                    code: "MISSING_REQUIRED_FIELD",
+                });
+            }
+            if (!node.type || typeof node.type !== "string") {
+                errors.push({
+                    path: `nodes.${nodeId}.type`,
+                    message: "Node type is required and must be a string",
+                    code: "MISSING_REQUIRED_FIELD",
+                });
+            }
+            if (node.next !== undefined && !Array.isArray(node.next)) {
+                errors.push({
+                    path: `nodes.${nodeId}.next`,
+                    message: "Node next must be an array",
+                    code: "INVALID_TYPE",
+                });
+            }
+            if (node.failureNext !== undefined && !Array.isArray(node.failureNext)) {
+                errors.push({
+                    path: `nodes.${nodeId}.failureNext`,
+                    message: "Node failureNext must be an array",
+                    code: "INVALID_TYPE",
+                });
+            }
+            if (node.conditionalNext !== undefined) {
+                if (!Array.isArray(node.conditionalNext)) {
+                    errors.push({
+                        path: `nodes.${nodeId}.conditionalNext`,
+                        message: "Node conditionalNext must be an array",
+                        code: "INVALID_TYPE",
+                    });
+                }
+                else {
+                    node.conditionalNext.forEach((branch, index) => {
+                        if (!branch.condition || typeof branch.condition !== "string") {
+                            errors.push({
+                                path: `nodes.${nodeId}.conditionalNext[${index}].condition`,
+                                message: "Conditional branch condition is required and must be a string",
+                                code: "MISSING_REQUIRED_FIELD",
+                            });
+                        }
+                        if (!branch.target || typeof branch.target !== "string") {
+                            errors.push({
+                                path: `nodes.${nodeId}.conditionalNext[${index}].target`,
+                                message: "Conditional branch target is required and must be a string",
+                                code: "MISSING_REQUIRED_FIELD",
+                            });
+                        }
+                    });
+                }
+            }
+        });
+        return errors;
+    }
+    validateNodeTypes(definition) {
+        const errors = [];
+        if (!definition.nodes || typeof definition.nodes !== "object") {
+            return errors;
+        }
+        Object.entries(definition.nodes).forEach(([nodeId, node]) => {
+            if (node.type && !this.registeredNodeTypes.has(node.type)) {
+                errors.push({
+                    path: `nodes.${nodeId}.type`,
+                    message: `Unknown node type: ${node.type}. Registered types: ${Array.from(this.registeredNodeTypes).join(", ")}`,
+                    code: "UNKNOWN_NODE_TYPE",
+                });
+            }
+        });
+        return errors;
+    }
+    validateNodeIdUniqueness(definition) {
+        const errors = [];
+        if (!definition.nodes || typeof definition.nodes !== "object") {
+            return errors;
+        }
+        const nodeIds = new Set();
+        const duplicates = new Set();
+        Object.entries(definition.nodes).forEach(([_nodeId, node]) => {
+            if (nodeIds.has(node.id)) {
+                duplicates.add(node.id);
+            }
+            nodeIds.add(node.id);
+        });
+        duplicates.forEach((nodeId) => {
+            errors.push({
+                path: `nodes.${nodeId}`,
+                message: `Duplicate node ID: ${nodeId}`,
+                code: "DUPLICATE_NODE_ID",
+            });
+        });
+        return errors;
+    }
+    validateNodeReferences(definition) {
+        const errors = [];
+        if (!definition.nodes || typeof definition.nodes !== "object") {
+            return errors;
+        }
+        const nodeIds = new Set(Object.keys(definition.nodes));
+        if (definition.startNode && !nodeIds.has(definition.startNode)) {
+            errors.push({
+                path: "startNode",
+                message: `Start node references non-existent node: ${definition.startNode}`,
+                code: "INVALID_NODE_REFERENCE",
+            });
+        }
+        Object.entries(definition.nodes).forEach(([nodeId, node]) => {
+            if (node.next) {
+                node.next.forEach((nextId, index) => {
+                    if (!nodeIds.has(nextId)) {
+                        errors.push({
+                            path: `nodes.${nodeId}.next[${index}]`,
+                            message: `Node references non-existent node: ${nextId}`,
+                            code: "INVALID_NODE_REFERENCE",
+                        });
+                    }
+                });
+            }
+            if (node.failureNext) {
+                node.failureNext.forEach((nextId, index) => {
+                    if (!nodeIds.has(nextId)) {
+                        errors.push({
+                            path: `nodes.${nodeId}.failureNext[${index}]`,
+                            message: `Node references non-existent node: ${nextId}`,
+                            code: "INVALID_NODE_REFERENCE",
+                        });
+                    }
+                });
+            }
+            if (node.conditionalNext) {
+                node.conditionalNext.forEach((branch, index) => {
+                    if (branch.target && !nodeIds.has(branch.target)) {
+                        errors.push({
+                            path: `nodes.${nodeId}.conditionalNext[${index}].target`,
+                            message: `Conditional branch references non-existent node: ${branch.target}`,
+                            code: "INVALID_NODE_REFERENCE",
+                        });
+                    }
+                });
+            }
+            if (node.defaultNext && !nodeIds.has(node.defaultNext)) {
+                errors.push({
+                    path: `nodes.${nodeId}.defaultNext`,
+                    message: `Default branch references non-existent node: ${node.defaultNext}`,
+                    code: "INVALID_NODE_REFERENCE",
+                });
+            }
+            if (node.rollbackTo && !nodeIds.has(node.rollbackTo)) {
+                errors.push({
+                    path: `nodes.${nodeId}.rollbackTo`,
+                    message: `Rollback references non-existent node: ${node.rollbackTo}`,
+                    code: "INVALID_NODE_REFERENCE",
+                });
+            }
+            const approvalConfig = node.config;
+            if (node.type === "approval" &&
+                approvalConfig?.approvedTarget &&
+                !nodeIds.has(approvalConfig.approvedTarget)) {
+                errors.push({
+                    path: `nodes.${nodeId}.config.approvedTarget`,
+                    message: `Approval approvedTarget references non-existent node: ${approvalConfig.approvedTarget}`,
+                    code: "INVALID_NODE_REFERENCE",
+                });
+            }
+            if (node.type === "approval" &&
+                approvalConfig?.rejectedTarget &&
+                !nodeIds.has(approvalConfig.rejectedTarget)) {
+                errors.push({
+                    path: `nodes.${nodeId}.config.rejectedTarget`,
+                    message: `Approval rejectedTarget references non-existent node: ${approvalConfig.rejectedTarget}`,
+                    code: "INVALID_NODE_REFERENCE",
+                });
+            }
+            if (node.type === "join") {
+                const joinConfig = node.config;
+                if (Array.isArray(joinConfig?.waitFor)) {
+                    joinConfig.waitFor.forEach((waitForId, index) => {
+                        if (typeof waitForId === "string" && !nodeIds.has(waitForId)) {
+                            errors.push({
+                                path: `nodes.${nodeId}.config.waitFor[${index}]`,
+                                message: `Join waitFor references non-existent node: ${waitForId}`,
+                                code: "INVALID_NODE_REFERENCE",
+                            });
+                        }
+                    });
+                }
+            }
+        });
+        return errors;
+    }
+    validateExpressions(definition) {
+        const errors = [];
+        if (!definition.nodes || typeof definition.nodes !== "object") {
+            return errors;
+        }
+        Object.entries(definition.nodes).forEach(([nodeId, node]) => {
+            if (node.conditionalNext) {
+                node.conditionalNext.forEach((branch, index) => {
+                    if (branch.condition) {
+                        const result = validateExpression(branch.condition);
+                        if (!result.valid) {
+                            errors.push({
+                                path: `nodes.${nodeId}.conditionalNext[${index}].condition`,
+                                message: `Invalid expression syntax: ${result.error}`,
+                                code: "INVALID_EXPRESSION",
+                            });
+                        }
+                    }
+                });
+            }
+            if (node.type === "transform") {
+                const transformConfig = node.config;
+                if (transformConfig?.output &&
+                    typeof transformConfig.output === "object") {
+                    Object.entries(transformConfig.output).forEach(([field, expr]) => {
+                        if (typeof expr !== "string")
+                            return;
+                        const unwrapped = expr.trim().startsWith("${") && expr.trim().endsWith("}")
+                            ? expr.trim().slice(2, -1)
+                            : expr.trim();
+                        const result = validateExpression(unwrapped);
+                        if (!result.valid) {
+                            errors.push({
+                                path: `nodes.${nodeId}.config.output.${field}`,
+                                message: `Invalid expression syntax: ${result.error}`,
+                                code: "INVALID_EXPRESSION",
+                            });
+                        }
+                    });
+                }
+            }
+        });
+        return errors;
+    }
+    detectCircularDependencies(definition) {
+        const errors = [];
+        if (!definition.nodes || typeof definition.nodes !== "object") {
+            return errors;
+        }
+        const nodeIds = Object.keys(definition.nodes);
+        const inDegree = new Map();
+        const adjacencyList = new Map();
+        nodeIds.forEach((nodeId) => {
+            inDegree.set(nodeId, 0);
+            adjacencyList.set(nodeId, []);
+        });
+        Object.entries(definition.nodes).forEach(([nodeId, node]) => {
+            const edges = [];
+            if (node.next) {
+                edges.push(...node.next);
+            }
+            if (node.failureNext) {
+                edges.push(...node.failureNext);
+            }
+            if (node.conditionalNext) {
+                edges.push(...node.conditionalNext.map((b) => b.target));
+            }
+            if (node.defaultNext) {
+                edges.push(node.defaultNext);
+            }
+            if (node.type === "approval") {
+                const approvalConfig = node.config;
+                if (approvalConfig?.approvedTarget) {
+                    edges.push(approvalConfig.approvedTarget);
+                }
+                if (approvalConfig?.rejectedTarget) {
+                    edges.push(approvalConfig.rejectedTarget);
+                }
+            }
+            edges.forEach((targetId) => {
+                if (inDegree.has(targetId)) {
+                    adjacencyList.get(nodeId)?.push(targetId);
+                    inDegree.set(targetId, (inDegree.get(targetId) || 0) + 1);
+                }
+            });
+        });
+        const queue = [];
+        const visited = new Set();
+        inDegree.forEach((degree, nodeId) => {
+            if (degree === 0) {
+                queue.push(nodeId);
+            }
+        });
+        while (queue.length > 0) {
+            const current = queue.shift();
+            visited.add(current);
+            const neighbors = adjacencyList.get(current) || [];
+            neighbors.forEach((neighbor) => {
+                const newDegree = (inDegree.get(neighbor) || 0) - 1;
+                inDegree.set(neighbor, newDegree);
+                if (newDegree === 0) {
+                    queue.push(neighbor);
+                }
+            });
+        }
+        if (visited.size < nodeIds.length) {
+            const unvisited = nodeIds.filter((id) => !visited.has(id));
+            errors.push({
+                path: "nodes",
+                message: `Circular dependency detected involving nodes: ${unvisited.join(", ")}`,
+                code: "CIRCULAR_DEPENDENCY",
+            });
+        }
+        return errors;
+    }
+    detectUnreachableNodes(definition) {
+        const warnings = [];
+        if (!definition.nodes || typeof definition.nodes !== "object") {
+            return warnings;
+        }
+        const reachable = new Set();
+        const queue = [definition.startNode];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            if (reachable.has(current)) {
+                continue;
+            }
+            reachable.add(current);
+            const node = definition.nodes[current];
+            if (!node) {
+                continue;
+            }
+            if (node.next) {
+                queue.push(...node.next);
+            }
+            if (node.failureNext) {
+                queue.push(...node.failureNext);
+            }
+            if (node.conditionalNext) {
+                queue.push(...node.conditionalNext.map((b) => b.target));
+            }
+            if (node.defaultNext) {
+                queue.push(node.defaultNext);
+            }
+        }
+        const allNodeIds = Object.keys(definition.nodes);
+        const unreachable = allNodeIds.filter((id) => !reachable.has(id));
+        unreachable.forEach((nodeId) => {
+            warnings.push({
+                path: `nodes.${nodeId}`,
+                message: `Node is unreachable from start node: ${nodeId}`,
+                code: "UNREACHABLE_NODE",
+            });
+        });
+        return warnings;
+    }
+}
+//# sourceMappingURL=SchemaValidator.js.map