@vertesia/workflow 0.42.2

package/src/dsl/validation.test.ts

@@ -0,0 +1,257 @@
+import { describe, expect, test } from "vitest";
+import { validateWorkflow } from "./validation.ts";
+
+describe('workflow validation', () => {
+
+    test('empty object is not a valid workflow', () => {
+        const workflow: any = {
+        }
+        const errors = validateWorkflow(workflow);
+        expect(errors.length).toBe(2);
+    })
+
+    test('activities is required', () => {
+        const workflow: any = {
+            name: "test",
+        }
+        const errors = validateWorkflow(workflow);
+        expect(errors.length).toBe(1);
+    })
+
+    test('activities shpuld be an array', () => {
+        const workflow: any = {
+            name: "test",
+            activities: {}
+        }
+        const errors = validateWorkflow(workflow);
+        expect(errors.length).toBe(1);
+    })
+
+    test('activities array should have at least one item', () => {
+        const workflow: any = {
+            name: "test",
+            activities: []
+        }
+        const errors = validateWorkflow(workflow);
+        expect(errors.length).toBe(1);
+    })
+
+    test('activity should have a name', () => {
+        const workflow: any = {
+            name: "test",
+            activities: [{}]
+        }
+        const errors = validateWorkflow(workflow);
+        expect(errors.length).toBe(1);
+    })
+
+    test('allow empty activity', () => {
+        const workflow: any = {
+            name: "test",
+            activities: [{ name: "test" }]
+        }
+        const errors = validateWorkflow(workflow);
+        expect(errors.length).toBe(0);
+    })
+
+    test('import undeclared var', () => {
+        const workflow: any = {
+            name: "test",
+            vars: { "foo": true },
+            activities: [{
+                name: "test",
+                import: ["foo", "bar"]
+            }]
+        }
+        const errors = validateWorkflow(workflow);
+        expect(errors.length).toBe(1);
+    })
+
+
+    test('import declared vars', () => {
+        const workflow: any = {
+            name: "test",
+            vars: { "foo": true, "bar": true },
+            activities: [{
+                name: "test",
+                import: ["foo", "bar"]
+            }]
+        }
+        const errors = validateWorkflow(workflow);
+        expect(errors.length).toBe(0);
+    })
+
+    test('import unknown imorted var through expressions', () => {
+        const workflow: any = {
+            name: "test",
+            vars: { "foo": true },
+            activities: [{
+                name: "test",
+                import: [{ "foo": "foo", "barLen": "bar.length" }]
+            }]
+        }
+        const errors = validateWorkflow(workflow);
+        expect(errors.length).toBe(1);
+    })
+
+    test('import declared vars through expressions', () => {
+        const workflow: any = {
+            name: "test",
+            vars: { "foo": true, "bar": "true" },
+            activities: [{
+                name: "test",
+                import: [{ "foo": "foo", "barLen": "bar.length" }]
+            }]
+        }
+        const errors = validateWorkflow(workflow);
+        expect(errors.length).toBe(0);
+    })
+
+    test('detect self references', () => {
+        const workflow: any = {
+            name: "test",
+            vars: { "object_type": "thetype" },
+            activities: [{
+                name: "test",
+                import: ["object_type"],
+                params: {
+                    "object_type": "${object_type}"
+                }
+            }]
+        }
+        const errors = validateWorkflow(workflow);
+        expect(errors.length).toBe(1);
+        expect(errors[0].includes("Self referencing parameter")).toBe(true);
+    })
+
+    test('reference known vars in fetch', () => {
+        const workflow: any = {
+            name: "test",
+            vars: { "foo": true, "bar": "true" },
+            activities: [{
+                name: "test",
+                import: [{ "foo": "foo", "barLen": "bar.length" }],
+                fetch: {
+                    doc: {
+                        query: {
+                            foo: "${foo}",
+                            barLen: "${barLen}"
+                        }
+                    }
+                }
+            }]
+        }
+        const errors = validateWorkflow(workflow);
+        console.log('##############errors', errors);
+
+        expect(errors.length).toBe(0);
+    })
+
+    test('reference unknown vars in fetch', () => {
+        const workflow: any = {
+            name: "test",
+            vars: { "foo": true, "bar": "true" },
+            activities: [{
+                name: "test",
+                import: [],
+                fetch: {
+                    doc: {
+                        query: {
+                            foo: "${foo}",
+                            barLen: "${barLen}"
+                        }
+                    }
+                }
+            }]
+        }
+        const errors = validateWorkflow(workflow);
+        expect(errors.length).toBe(2);
+    })
+
+    test('reference one unknown and one known var in fetch', () => {
+        const workflow: any = {
+            name: "test",
+            vars: { "foo": true, "bar": "true" },
+            activities: [{
+                name: "test",
+                import: ["foo"],
+                fetch: {
+                    doc: {
+                        query: {
+                            foo: "${foo}",
+                            barLen: "${barLen}"
+                        }
+                    }
+                }
+            }]
+        }
+        const errors = validateWorkflow(workflow);
+        expect(errors.length).toBe(1);
+    })
+
+    test('reference 2 unknown vars in params', () => {
+        const workflow: any = {
+            name: "test",
+            vars: { "foo": true, "bar": "true" },
+            activities: [{
+                name: "test",
+                import: ["foo"],
+                params: {
+                    barLength: "${barLen}",
+                    doc: "${doc.text}"
+                }
+            }]
+        }
+        const errors = validateWorkflow(workflow);
+        expect(errors.length).toBe(2);
+    })
+
+    test('reference 1 unknown vars in params', () => {
+        const workflow: any = {
+            name: "test",
+            vars: { "foo": true, "bar": "true" },
+            activities: [{
+                name: "test",
+                import: ["foo", { "barLen": "bar.length" }],
+                params: {
+                    barLength: "${barLen}",
+                    doc: "${doc.text}"
+                }
+            }]
+        }
+        const errors = validateWorkflow(workflow);
+        expect(errors.length).toBe(1);
+    })
+
+    test('reference known vars in params', () => {
+        const workflow: any = {
+            name: "test",
+            vars: { "foo": true, "bar": "true" },
+            activities: [
+                {
+                    name: "test0",
+                    output: "previousResult"
+                }, {
+                    name: "test",
+                    import: ["foo", { "barLen": "bar.length" }, "previousResult"],
+                    fetch: {
+                        doc: {
+                            query: {
+                                foo: "${foo}",
+                                barLen: "${barLen}"
+                            }
+                        }
+                    },
+                    params: {
+                        fooParam: "${foo}",
+                        barLenParam: "${barLen}",
+                        doc: "${doc.text}",
+                        prev: "${previousResult}"
+                    }
+                }]
+        }
+        const errors = validateWorkflow(workflow);
+        expect(errors.length).toBe(0);
+    })
+
+})

package/src/dsl/validation.ts

@@ -0,0 +1,125 @@
+import { DSLActivitySpec, DSLWorkflowSpec, DSLWorkflowStep } from "@vertesia/common";
+import { Vars, splitPath } from "./vars.js";
+
+export function validateWorkflow(workflow: DSLWorkflowSpec, vars: string[] = []) {
+    const errors: string[] = [];
+    const workflowVars = new Set(vars);
+    workflowVars.add("objectId");
+    workflowVars.add("objectIds");
+    if (workflow.vars) {
+        for (const v of Object.keys(workflow.vars)) {
+            workflowVars.add(v);
+        }
+    }
+    if (!workflow.name) {
+        errors.push("Workflow 'name' property is required");
+    }
+    if (workflow.steps && workflow.activities) {
+        errors.push("You must use either 'steps' or 'activities'. You cannot use both. Prefer using steps.");
+        return errors;
+    }
+    if (!workflow.steps && !workflow.activities) {
+        errors.push("The workflow requires one of 'steps' or 'activities' properties. Neither is present.");
+        return errors;
+    }
+    const stepsPropName = workflow.steps ? "steps" : "activities";
+    const steps = workflow.steps || workflow.activities;
+    if (!steps || !Array.isArray(steps)) {
+        errors.push(`Workflow '${stepsPropName}' property is required`);
+        return errors;
+    }
+    if (!steps || !Array.isArray(steps)) {
+        errors.push(`Workflow '${stepsPropName}' should be an array`);
+        return errors;
+    }
+    if (!steps.length) {
+        errors.push("Workflow should have at least one step or activity");
+    }
+
+    const activities: DSLActivitySpec[] = stepsPropName === "steps" ? (steps as DSLWorkflowStep[]).filter(s => s.type === "activity") : steps;
+    for (const activity of activities) {
+        const activityErrors = validateActivity(activity, workflowVars);
+        if (activityErrors.length > 0) {
+            for (const err of activityErrors) {
+                errors.push(`Activity "${activity.name}": ${err}`);
+            }
+        }
+        if (activity.output) {
+            workflowVars.add(activity.output);
+        }
+    }
+
+    return errors;
+}
+
+export function validateActivity(activity: DSLActivitySpec, workflowVars: Set<string>): string[] {
+    const errors: string[] = [];
+    if (!activity.name) {
+        errors.push("Activity name is required");
+    }
+    const importedVars = activity.import;
+    const localVars: Record<string, boolean> = {};
+    if (importedVars && importedVars.length > 0) {
+        for (const entry of importedVars) {
+            if (typeof entry === 'string') {
+                pushLocalVar(entry, localVars, errors);
+                if (!workflowVars.has(entry)) {
+                    errors.push(`Unknown workflow variable "${entry}" in import declaration`);
+                }
+            } else {
+                for (const key of Object.keys(entry)) {
+                    pushLocalVar(key, localVars, errors);
+                    const wfExpr = entry[key];
+                    const wfVar = splitPath(wfExpr)[0];
+                    if (!workflowVars.has(wfVar)) {
+                        errors.push(`Unknown workflow variable "${wfExpr}" in import declaration`);
+                    }
+                }
+            }
+        }
+    }
+
+    // collect fetch vars and check expressions in fetch declarations
+    const fetch = activity.fetch;
+    if (fetch) {
+        const keys = Object.keys(fetch);
+        for (const key of keys) {
+            const query = fetch[key].query;
+            // check expressions in query
+            validateExpressions(query, localVars, errors);
+        }
+        for (const key of keys) {
+            pushLocalVar(key, localVars, errors);
+        }
+    }
+    // check expressions in activity params
+    if (activity.params) {
+        validateExpressions(activity.params, localVars, errors, true);
+    }
+    return errors;
+}
+
+
+function validateExpressions(target: Record<string, any>, localVars: Record<string, boolean>, errors: string[], checkSelfReference = false) {
+    const vars = new Vars(localVars);
+    const refs = vars.getUnknownReferences(target);
+    for (const ref of refs) {
+        errors.push(`Unknown variable "${ref.name}" in expression "${ref.expression}"`)
+    }
+    if (checkSelfReference) {
+        // check for self references like `"object_type": "${object_type}"`.
+        for (const key of Object.keys(target)) {
+            const value = target[key];
+            if (typeof value === 'string' && value.includes("${" + key + "}")) {
+                errors.push(`Self referencing parameter "${key}" in expression "${value}"`);
+            }
+        }
+    }
+}
+
+function pushLocalVar(v: string, localVars: Record<string, boolean>, errors: string[]) {
+    if (localVars[v] === true) {
+        errors.push(`Duplicate variable "${v}"`);
+    }
+    localVars[v] = true;
+}

package/src/dsl/vars.test.ts

@@ -0,0 +1,245 @@
+import { describe, expect, test } from "vitest";
+import { Vars } from "./vars.ts";
+
+describe('Workflow vars', () => {
+
+    test('access initial variables', () => {
+        const vars = new Vars({
+            objectId: "123",
+            timestamp: 123456,
+        });
+        expect(vars.getValue("objectId")).toBe("123");
+        expect(vars.getValue("timestamp")).toBe(123456);
+        expect(vars.getValue("foo")).toBeUndefined();
+    })
+
+    test('set and access variables', () => {
+        const vars = new Vars({
+            objectId: "123",
+            timestamp: 123456,
+        });
+        expect(vars.getValue("objectId")).toBe("123");
+        vars.setValue("objectId", "456");
+        expect(vars.getValue("objectId")).toBe("456");
+    })
+
+    test('access and modify ref variables', () => {
+        const vars = new Vars({
+            objectId: "123",
+            config: {
+                name: "foo",
+            },
+            objectIdAlias: "${objectId}",
+            configNameAlias: "${config.name}",
+        });
+        expect(vars.getValue("objectIdAlias")).toBe("123");
+        expect(vars.getValue("configNameAlias")).toBe("foo");
+        vars.setValue("objectId", "456");
+        vars.getValue("config").name = "bar";
+        expect(vars.getValue("objectIdAlias")).toBe("456");
+        expect(vars.getValue("configNameAlias")).toBe("bar");
+    })
+
+    test('replace literal with ref', () => {
+        const vars = new Vars({
+            objectId: "123",
+            otherId: "1234",
+        });
+        expect(vars.getValue("objectId")).toBe("123");
+        expect(vars.getValue("otherId")).toBe("1234");
+        vars.setValue("objectId", "456");
+        vars.load({ "otherId": "${objectId}" });
+        expect(vars.getValue("objectId")).toBe("456");
+        expect(vars.getValue("otherId")).toBe("456");
+    });
+
+    test("undefined ref variable", () => {
+        const vars = new Vars({
+            otherId: "${objectId}",
+        });
+        expect(vars.getValue("otherId")).toBeUndefined();
+    })
+
+    test("default values", () => {
+        const vars = new Vars({
+            squote: "${objectId ?? '123'}",
+            dquote: "${objectId ?? \"123\"}",
+            number: "${objectId ?? 123}",
+            boolean: "${objectId ?? true}",
+            array: "${objectId ?? [1,2]}",
+        });
+        // object valus and path expression are not supported
+        expect(vars.getValue("squote")).toBe("123");
+        expect(vars.getValue("dquote")).toBe("123");
+        expect(vars.getValue("number")).toBe(123);
+        expect(vars.getValue("boolean")).toBe(true);
+        expect(vars.getValue("array")).toEqual([1, 2]);
+    })
+
+    test("array map", () => {
+        const vars = new Vars({
+            docs: [{ text: "hello" }, { text: "world" }],
+        });
+        // object valus and path expression are not supported
+        expect(vars.getValue("docs.text").join(' ')).toBe("hello world");
+    })
+
+    test("resolveParams", () => {
+        const vars = new Vars({
+            objectIds: ["123", "456"],
+            objectId: "123",
+            data: { message: "hello" },
+        });
+        const params = {
+            query: {
+                _id: "${objectId}",
+                data: "${data}",
+            },
+            secondDocId: "${objectIds.1}",
+            secondDocIdByBracket: "${objectIds[1]}",
+        }
+        const resolved = vars.resolveParams(params);
+        expect(Object.keys(resolved).length).toBe(3);
+        expect(resolved.query).toBeTypeOf("object");
+        expect(resolved.query._id).toBe("123");
+        expect(resolved.query.data).toBeTypeOf("object");
+        expect(resolved.query.data.message).toBe("hello");
+        expect(resolved.secondDocId).toBe("456");
+        expect(resolved.secondDocIdByBracket).toBe("456");
+
+    });
+
+    test("resolve", () => {
+        const vars = new Vars({
+            objectId: "123",
+            message: "hello",
+            prompt_data: { message: "${message}" },
+            data2: "${prompt_data}",
+            unknown: "${notdefined}"
+        });
+        const resolved = vars.resolve();
+        console.log('@@@@@@@@@@@@@@@@@@@', resolved);
+        expect(Object.keys(resolved).length).toBe(4); // since unknown will be undefined it will not be included
+        expect(resolved.objectId).toBe("123");
+        expect(resolved.prompt_data).toBeTypeOf("object");
+        expect(resolved.prompt_data.message).toBe("hello");
+        expect(resolved.data2).toBeTypeOf("object");
+        expect(resolved.data2.message).toBe("hello");
+        expect(resolved.unnown).toBeUndefined();
+    });
+
+
+    test("createImportVars", () => {
+        const vars = new Vars({
+            person: { name: "John", age: 30 },
+            objectId: "123",
+            data: { message: "hello" },
+            data2: "${data}",
+        });
+        const params = vars.createImportVars(["data2", { "name": "person.name", "age": "person.age" }, { message: "data.message" }]);
+        expect(Object.keys(params).length).toBe(4);
+        expect(params.name).toBe("John");
+        expect(params.age).toBe(30);
+        expect(params.message).toBe("hello");
+        expect(params.data2).toStrictEqual({ message: "hello" });
+    });
+
+    test("evaluate null and exists conditions", () => {
+        const vars = new Vars({
+            objectId: "123",
+            docType: {
+                id: "bla",
+                idNull: null,
+            }
+        });
+        expect(vars.match({ objectId: { $exists: true } })).toBe(true);
+        expect(vars.match({ objectId: { $exists: false } })).toBe(false);
+        expect(vars.match({ objectIds: { $exists: true } })).toBe(false);
+        expect(vars.match({ objectIds: { $exists: false } })).toBe(true);
+        expect(vars.match({ "docType.id": { $exists: true } })).toBe(true);
+        expect(vars.match({ "docType.idNull": { $exists: true } })).toBe(true);
+
+        expect(vars.match({ objectId: { $null: true } })).toBe(false);
+        expect(vars.match({ objectId: { $null: false } })).toBe(true);
+        expect(vars.match({ objectIds: { $null: false } })).toBe(false);
+        expect(vars.match({ objectIds: { $null: true } })).toBe(true);
+        expect(vars.match({ "docType.id": { $null: true } })).toBe(false);
+        expect(vars.match({ "docType.idNull": { $null: true } })).toBe(true);
+    });
+
+    test("evaluate $eq conditions", () => {
+        const vars = new Vars({
+            objectId: "123",
+            otherId: "${objectId}",
+            config: {
+                name: { foo: "bar" },
+                tags: ["a", "b", "c"]
+            }
+        });
+        expect(vars.match({ objectId: { $eq: "123" } })).toBe(true);
+        expect(vars.match({ objectId: { $eq: "456" } })).toBe(false);
+        expect(vars.match({ objectId: { $ne: "123" } })).toBe(false);
+        expect(vars.match({ objectId: { $ne: "456" } })).toBe(true);
+
+        expect(vars.match({ otherId: { $eq: "123" } })).toBe(true);
+        expect(vars.match({ otherId: { $eq: "456" } })).toBe(false);
+        expect(vars.match({ otherId: { $ne: "123" } })).toBe(false);
+        expect(vars.match({ otherId: { $ne: "456" } })).toBe(true);
+
+        expect(vars.match({ "config": { $eq: { name: { foo: "bar" }, tags: ["a", "b", "c"] } } })).toBe(true);
+    });
+
+    test("evaluate $regexp conditions", () => {
+        const vars = new Vars({
+            expr: "a=2",
+        });
+        expect(vars.match({ expr: { $regexp: "^.*\\s*=\\s*.*$" } })).toBe(true);
+    });
+
+    test("evaluate string compare conditions", () => {
+        const vars = new Vars({
+            expr: "<tag />",
+        });
+        expect(vars.match({ expr: { $startsWith: "<" } })).toBe(true);
+        expect(vars.match({ expr: { $contains: "tag" } })).toBe(true);
+        expect(vars.match({ expr: { $endsWith: "/>" } })).toBe(true);
+    });
+
+    test("evaluate $in conditions", () => {
+        const vars = new Vars({
+            name: "foo",
+        });
+        expect(vars.match({ name: { $in: ["foo", "bar"] } })).toBe(true);
+        expect(vars.match({ name: { $nin: ["hello", "world"] } })).toBe(true);
+    });
+
+    test("evaluate $lt, $gt conditions", () => {
+        const vars = new Vars({
+            value: 5,
+        });
+        expect(vars.match({ value: { $lt: 6 } })).toBe(true);
+        expect(vars.match({ value: { $gt: 4 } })).toBe(true);
+        expect(vars.match({ value: { $lte: 5 } })).toBe(true);
+        expect(vars.match({ value: { $gte: 5 } })).toBe(true);
+    });
+
+    test("evaluate $or conditions", () => {
+        const vars = new Vars({
+            value: 5,
+            name: "foo"
+        });
+        expect(vars.match({ value: { $or: [{ $lt: 4 }, { $gt: 6 }] } })).toBe(false);
+        expect(vars.match({ name: { $or: [{ $eq: "bar" }, { $eq: "foo" }] } })).toBe(true);
+        expect(vars.match({ name: { $or: [{ $eq: "bar" }, { $eq: "fooo" }] } })).toBe(false);
+    });
+
+    test("evaluate nested conditions", () => {
+        const vars = new Vars({
+            config: {
+                name: "foo",
+            },
+        });
+        expect(vars.match({ "config.name": { $eq: "foo" } })).toBe(true);
+    });
+
+});