@vertesia/workflow 1.2.0 → 1.3.0-dev.20260620.091720Z

package/src/dsl/vars.ts

@@ -1,18 +1,23 @@
-import { ImportSpec } from "@vertesia/common";
-import { matchCondition } from "./conditions.js";
-import { ObjectKey, ObjectVisitor, ObjectWalker } from "./walk.js";
+import type { ImportSpec } from '@vertesia/common';
+import { matchCondition } from './conditions.js';
+import { type ObjectKey, type ObjectVisitor, ObjectWalker } from './walk.js';
 
-const FALLBACK_VALUE_SEP = "??";
+const FALLBACK_VALUE_SEP = '??';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
 
 function decodeLiteralValue(value: string) {
     if (value.startsWith("'") && value.endsWith("'")) {
-        value = '"' + value.slice(1, -1).replace(/(?<!\\)"/g, '\\"') + '"'
+        value = `"${value.slice(1, -1).replace(/(?<!\\)"/g, '\\"')}"`;
     }
     return JSON.parse(value);
 }
 
 export function splitPath(path: string) {
-    if (path.indexOf('[') > -1) { // support array like paths
+    if (path.indexOf('[') > -1) {
+        // support array like paths
         path = path.replace(/\[(\d+)\]/g, '.$1');
     }
     return path.split('.');
@@ -26,36 +31,36 @@ export function splitPath(path: string) {
  * @param name the name of the property.
  * @returns the property value
  */
-function _prop(object: any, name: string) {
+function _prop(object: unknown, name: string) {
     if (object === undefined) {
         return undefined;
     }
     object = _valueOf(object); // resolve Value objects
     if (Array.isArray(object)) {
         const index = +name;
-        if (isNaN(index)) {
+        if (Number.isNaN(index)) {
             // map array to property
-            return object.map(item => item[name]);
+            return object.map((item) => (isRecord(item) ? item[name] : undefined));
         } else {
             return _valueOf(object[index]);
         }
-    } else {
+    } else if (isRecord(object)) {
         return _valueOf(object[name]);
     }
-
+    return undefined;
 }
 
-function _valueOf(value: any) {
+function _valueOf(value: unknown) {
     return value instanceof Value ? value.value : value;
 }
 
-export function resolveField(object: any, path: string[]) {
-    let p = object as any;
+export function resolveField(object: unknown, path: string[]) {
+    let p = object as unknown;
     if (!p) return p;
     if (!path.length) return _valueOf(p);
     const last = path.length - 1;
     for (let i = 0; i < last; i++) {
-        p = _prop(p, path[i])
+        p = _prop(p, path[i]);
         if (!p) {
             return undefined;
         }
@@ -63,11 +68,11 @@ export function resolveField(object: any, path: string[]) {
     return _prop(p, path[last]);
 }
 
-abstract class Value<T = any> {
+abstract class Value<T = unknown> {
     abstract value: T;
     abstract stringify(): string;
 }
-class LiteralValue<T = any> extends Value<T> {
+class LiteralValue<T = unknown> extends Value<T> {
     constructor(public value: T) {
         super();
     }
@@ -77,7 +82,11 @@ class LiteralValue<T = any> extends Value<T> {
 }
 
 class RefValue extends Value {
-    constructor(public vars: Vars, public path: string[], public defaultValue?: any) {
+    constructor(
+        public vars: Vars,
+        public path: string[],
+        public defaultValue?: unknown,
+    ) {
         super();
     }
     get value() {
@@ -94,12 +103,15 @@ class RefValue extends Value {
     }
 
     stringify() {
-        return "${" + this.path.join('.') + "}";
+        return `\${${this.path.join('.')}}`;
     }
 }
 
 class ExprValue extends Value {
-    constructor(public vars: Vars, public parts: Value[]) {
+    constructor(
+        public vars: Vars,
+        public parts: Value[],
+    ) {
         super();
     }
     get value() {
@@ -118,14 +130,12 @@ class ExprValue extends Value {
         for (const seg of this.parts) {
             out.push(seg.stringify());
         }
-        return "${" + out.join('') + "}";
+        return `\${${out.join('')}}`;
     }
-
 }
 
-
 export class Vars {
-    map: Record<string, any>;
+    map: Record<string, unknown>;
     /**
      * This property is used when resolving params. It contains the list of references that should not be resolved to their value
      * but instead they need to return the string representation of the expression to be able to regenerate another Vars instance with the same expression
@@ -133,12 +143,12 @@ export class Vars {
     //TODO this feature is no more used - it was replaced by importVars so we can now delete `preserveRefs`
     preserveRefs: Set<string> | undefined;
 
-    constructor(vars?: Record<string, any>) {
+    constructor(vars?: Record<string, unknown>) {
         this.map = vars ? this.parse(vars) : {};
     }
 
-    parse(vars: Record<string, any>): Record<string, any> {
-        return new ObjectWalker().map(vars, (_key, value) => {
+    parse(vars: Record<string, unknown>): Record<string, unknown> {
+        return new ObjectWalker().map<Record<string, unknown>>(vars, (_key, value) => {
             if (typeof value === 'string') {
                 return this.createValue(this, value);
             } else {
@@ -147,7 +157,7 @@ export class Vars {
         });
     }
 
-    load(vars: Record<string, any>) {
+    load(vars: Record<string, unknown>) {
         const toAppend = this.parse(vars);
         this.map = Object.assign(this.map, toAppend);
         return this;
@@ -159,7 +169,7 @@ export class Vars {
      * @param name
      * @param value
      */
-    setValue(name: string, value: any) {
+    setValue(name: string, value: unknown) {
         this.map[name] = value;
     }
 
@@ -175,7 +185,7 @@ export class Vars {
         return this.map[name] !== undefined;
     }
 
-    match(match: Record<string, any>) {
+    match(match: Record<string, unknown>) {
         for (const name of Object.keys(match)) {
             const value = this.getValue(name);
             if (!matchCondition(value, match[name])) {
@@ -185,12 +195,12 @@ export class Vars {
         return true;
     }
 
-    resolveParams(params: Record<string, any>, preserveRefs?: Set<string>) {
+    resolveParams(params: Record<string, unknown>, preserveRefs?: Set<string>) {
         this.preserveRefs = preserveRefs;
         try {
-            return new ObjectWalker().map(params, (_key, value) => {
+            return new ObjectWalker().map<Record<string, unknown>>(params, (_key, value) => {
                 if (typeof value === 'string') {
-                    const v = this.createValue(this, value)
+                    const v = this.createValue(this, value);
                     return v instanceof Value ? v.value : v;
                 } else {
                     return value;
@@ -201,26 +211,26 @@ export class Vars {
         }
     }
 
-    resolve(preserveRefs?: Set<string>): Record<string, any> {
-        function map(_key: ObjectKey, value: any) {
+    resolve(preserveRefs?: Set<string>): Record<string, unknown> {
+        function map(_key: ObjectKey, value: unknown) {
             if (value instanceof Value) {
                 const v = value.value;
                 if (v && typeof v === 'object') {
                     if (Array.isArray(v) || v.constructor === Object) {
                         // an array or plain object - recurse into the
                         // value to find other nested Ref values if any...
-                        return new ObjectWalker().map(v, map);
+                        return new ObjectWalker().map<Record<string, unknown> | unknown[]>(v, map);
                     }
                 } else {
                     return v;
                 }
             } else {
-                return value
+                return value;
             }
         }
         try {
             this.preserveRefs = preserveRefs;
-            return new ObjectWalker().map(this.map, map);
+            return new ObjectWalker().map<Record<string, unknown>>(this.map, map);
         } finally {
             this.preserveRefs = undefined;
         }
@@ -228,18 +238,18 @@ export class Vars {
 
     createRefValue(ref: string) {
         const index = ref.indexOf(FALLBACK_VALUE_SEP);
-        let defaultValue: any;
+        let defaultValue: unknown;
         if (index > -1) {
             defaultValue = decodeLiteralValue(ref.substring(index + FALLBACK_VALUE_SEP.length).trim());
             ref = ref.substring(0, index).trim();
         }
         if (ref === '.' || ref.indexOf('..') > -1) {
-            throw new Error("Invalid variable reference: " + ref)
+            throw new Error(`Invalid variable reference: ${ref}`);
         }
         return new RefValue(this, splitPath(ref), defaultValue);
     }
 
-    createValue(vars: Vars, obj: any) {
+    createValue(vars: Vars, obj: unknown) {
         if (!obj) {
             return obj;
         }
@@ -276,10 +286,10 @@ export class Vars {
         if (!importSpec || importSpec.length === 0) {
             return {};
         }
-        const result: Record<string, any> = {};
+        const result: Record<string, unknown> = {};
 
         for (const importVar of importSpec) {
-            if (typeof importVar === "string") {
+            if (typeof importVar === 'string') {
                 addImportVar(importVar, undefined, this, result);
             } else {
                 for (const key of Object.keys(importVar)) {
@@ -290,37 +300,34 @@ export class Vars {
         return result;
     }
 
-    getUnknownReferences(obj: any) {
+    getUnknownReferences(obj: unknown) {
         const visitor = new UnknownReferencesVisitor(this);
         new ObjectWalker().walk(obj, visitor);
         return visitor.result;
     }
 }
 
-function addImportVar(varPath: string, asName: string | undefined, vars: Vars, result: Record<string, any>) {
+function addImportVar(varPath: string, asName: string | undefined, vars: Vars, result: Record<string, unknown>) {
     let isRequired = false;
-    if (varPath.endsWith("!")) {
+    if (varPath.endsWith('!')) {
         isRequired = true;
         varPath = varPath.slice(0, -1);
     }
-    let value = vars.getValue(varPath);
+    const value = vars.getValue(varPath);
     if (value === undefined && isRequired) {
         throw new Error(`Import variable ${varPath} is required but not found`);
     }
     result[asName || varPath] = value;
 }
 
-
 class UnknownReferencesVisitor implements ObjectVisitor {
+    result: { name: string; expression: string }[] = [];
 
-    result: { name: string, expression: string }[] = [];
-
-    constructor(public vars: Vars) {
-    }
+    constructor(public vars: Vars) {}
 
-    onValue(_key: ObjectKey, value: any) {
+    onValue(_key: ObjectKey, value: unknown) {
         const vars = this.vars;
-        if (typeof value === "string") {
+        if (typeof value === 'string') {
             const v = vars.createValue(vars, value);
             if (v instanceof ExprValue) {
                 for (const p of v.parts) {

package/src/dsl/walk.test.ts

@@ -1,81 +1,86 @@
-import { describe, expect, test } from "vitest";
-import { ObjectWalker } from "./walk.ts";
+import { describe, expect, test } from 'vitest';
+import { ObjectWalker } from './walk.js';
 
-describe('walk object', () => {
+/** Permissive recursive type for navigating untyped walker results in test assertions. */
+type Tree = { readonly [key: string]: Tree };
 
-    test('find string values', () => {
+describe('walk object', () => {
+    test('should find string values', () => {
         const obj = {
-            name: "foo",
+            name: 'foo',
             age: 42,
-            children: [{
-                name: "bar",
-                age: 12,
-            },
-            {
-                name: "baz",
-                age: 15,
-            }],
+            children: [
+                {
+                    name: 'bar',
+                    age: 12,
+                },
+                {
+                    name: 'baz',
+                    age: 15,
+                },
+            ],
             folder: {
                 subfolder: {
-                    name: "file",
-                }
-            }
-        }
-        const values = ["foo", "bar", "baz", "file"].sort().join(',');
+                    name: 'file',
+                },
+            },
+        };
+        const values = ['foo', 'bar', 'baz', 'file'].sort().join(',');
         const found: string[] = [];
         new ObjectWalker().walk(obj, {
-            onValue(key, value) {
-                if (typeof value === "string") {
+            onValue(_key, value) {
+                if (typeof value === 'string') {
                     found.push(value);
                 }
-            }
-        })
+            },
+        });
         expect(found.sort().join(',')).toBe(values);
-    })
+    });
 
-    test('map numbers to string values', () => {
+    test('should map numbers to string values', () => {
         const obj = {
-            name: "foo",
+            name: 'foo',
             age: 42,
-            children: [{
-                name: "bar",
-                age: 12,
-            },
-            {
-                name: "baz",
-                age: 15,
-            }],
+            children: [
+                {
+                    name: 'bar',
+                    age: 12,
+                },
+                {
+                    name: 'baz',
+                    age: 15,
+                },
+            ],
             folder: {
                 subfolder: {
                     name: 123,
-                }
-            }
-        }
+                },
+            },
+        };
         const r = new ObjectWalker().map(obj, (_key, value) => {
-            if (typeof value === "number") {
-                return String(value)
+            if (typeof value === 'number') {
+                return String(value);
             }
             return value;
-        });
-        expect(r.age).toBe("42");
-        expect(r.children[0].age).toBe("12");
-        expect(r.children[1].age).toBe("15");
-        expect(r.folder.subfolder.name).toBe("123");
-    })
+        }) as Tree;
+        expect(r.age).toBe('42');
+        expect(r.children[0].age).toBe('12');
+        expect(r.children[1].age).toBe('15');
+        expect(r.folder.subfolder.name).toBe('123');
+    });
 
-    test('map numbers in an array to string values', () => {
-        const obj = [123, { x: 1 }, { y: 2 }, { z: 3 }]
+    test('should map numbers in an array to string values', () => {
+        const obj = [123, { x: 1 }, { y: 2 }, { z: 3 }];
         const r = new ObjectWalker().map(obj, (_key, value) => {
-            if (typeof value === "number") {
-                return String(value)
+            if (typeof value === 'number') {
+                return String(value);
             }
             return value;
-        });
+        }) as unknown as Tree;
         expect(r.length).toBe(4);
-        expect(r[0]).toBe("123");
-        expect(r[1].x).toBe("1");
-        expect(r[2].y).toBe("2");
-        expect(r[3].z).toBe("3");
-    })
-
-})
+        expect(r[0]).toBe('123');
+        expect(r[1].x).toBe('1');
+        expect(r[2].y).toBe('2');
+        expect(r[3].z).toBe('3');
+    });
+});

package/src/dsl/walk.ts

@@ -1,11 +1,33 @@
-
 export type ObjectKey = string | number | undefined;
 export interface ObjectVisitor {
-    onStartObject?: (key: ObjectKey, value: any) => void;
-    onEndObject?: (key: ObjectKey, value: any) => void;
-    onStartIteration?: (key: ObjectKey, value: Iterable<any>) => void;
-    onEndIteration?: (key: ObjectKey, value: Iterable<any>) => void;
-    onValue?: (key: ObjectKey, value: any) => void;
+    onStartObject?: (key: ObjectKey, value: unknown) => void;
+    onEndObject?: (key: ObjectKey, value: unknown) => void;
+    onStartIteration?: (key: ObjectKey, value: Iterable<unknown>) => void;
+    onEndIteration?: (key: ObjectKey, value: Iterable<unknown>) => void;
+    onValue?: (key: ObjectKey, value: unknown) => void;
+}
+
+type MutableContainer = Record<string, unknown> | unknown[];
+
+function isIterable(value: unknown): value is Iterable<unknown> {
+    return (
+        !!value && typeof value === 'object' && Symbol.iterator in value && typeof value[Symbol.iterator] === 'function'
+    );
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+    return !!value && typeof value === 'object' && value.constructor === Object;
+}
+
+function setValue(target: MutableContainer | undefined, key: ObjectKey, value: unknown) {
+    if (!target || key === undefined) {
+        return;
+    }
+    if (Array.isArray(target) && typeof key === 'number') {
+        target[key] = value;
+    } else if (!Array.isArray(target) && typeof key === 'string') {
+        target[key] = value;
+    }
 }
 
 export class ObjectWalker {
@@ -13,62 +35,65 @@ export class ObjectWalker {
     constructor(supportIterators = false) {
         this.supportIterators = supportIterators;
     }
-    walk(obj: any, visitor: ObjectVisitor) {
+    walk(obj: unknown, visitor: ObjectVisitor) {
         this._walk(undefined, obj, visitor);
     }
-    _walk(key: ObjectKey, obj: any, visitor: ObjectVisitor) {
+    _walk(key: ObjectKey, obj: unknown, visitor: ObjectVisitor) {
         const type = typeof obj;
         if (!obj || type !== 'object' || obj instanceof Date) {
-            visitor.onValue && visitor.onValue(key, obj);
+            visitor.onValue?.(key, obj);
         } else if (Array.isArray(obj)) {
             this._walkIterable(key, obj, visitor);
-        } else if (this.supportIterators && obj[Symbol.iterator] === 'function') {
+        } else if (this.supportIterators && isIterable(obj)) {
             this._walkIterable(key, obj, visitor);
-        } else if (obj.constructor === Object) { // a plain object
+        } else if (isPlainRecord(obj)) {
+            // a plain object
             this._walkObject(key, obj, visitor);
-        } else { // a random object - we treat it as a value
-            visitor.onValue && visitor.onValue(key, obj);
+        } else {
+            // a random object - we treat it as a value
+            visitor.onValue?.(key, obj);
         }
     }
 
-    _walkIterable(key: ObjectKey, obj: any, visitor: ObjectVisitor) {
-        visitor.onStartIteration && visitor.onStartIteration(key, obj);
+    _walkIterable(key: ObjectKey, obj: Iterable<unknown>, visitor: ObjectVisitor) {
+        visitor.onStartIteration?.(key, obj);
         let i = 0;
         for (const value of obj) {
             this._walk(i++, value, visitor);
         }
-        visitor.onEndIteration && visitor.onEndIteration(key, obj);
+        visitor.onEndIteration?.(key, obj);
     }
 
-    _walkObject(key: ObjectKey, obj: any, visitor: ObjectVisitor) {
-        visitor.onStartObject && visitor.onStartObject(key, obj);
+    _walkObject(key: ObjectKey, obj: Record<string, unknown>, visitor: ObjectVisitor) {
+        visitor.onStartObject?.(key, obj);
         for (const k of Object.keys(obj)) {
             this._walk(k, obj[k], visitor);
         }
-        visitor.onEndObject && visitor.onEndObject(key, obj);
+        visitor.onEndObject?.(key, obj);
     }
 
-    map(obj: any, mapFn: (key: ObjectKey, value: any) => any) {
+    map<T = unknown>(obj: unknown, mapFn: (key: ObjectKey, value: unknown) => unknown): T {
         const visitor = new MapVisitor(mapFn);
         this.walk(obj, visitor);
-        return visitor.result;
+        return visitor.result as T;
     }
 }
 
 class MapVisitor implements ObjectVisitor {
-    result: any;
-    current: any;
-    stack: any[] = [];
-    constructor(private mapFn: (key: ObjectKey, value: any) => any) { }
+    result: unknown;
+    current: MutableContainer | undefined;
+    stack: (MutableContainer | undefined)[] = [];
+    constructor(private mapFn: (key: ObjectKey, value: unknown) => unknown) {}
 
     onStartObject(key: ObjectKey) {
         if (key === undefined) {
-            this.result = {};
-            this.current = this.result;
+            const obj: Record<string, unknown> = {};
+            this.result = obj;
+            this.current = obj;
         } else {
             this.stack.push(this.current);
-            const obj = {};
-            this.current[key] = obj;
+            const obj: Record<string, unknown> = {};
+            setValue(this.current, key, obj);
             this.current = obj;
         }
     }
@@ -78,12 +103,13 @@ class MapVisitor implements ObjectVisitor {
 
     onStartIteration(key: ObjectKey) {
         if (key === undefined) {
-            this.result = [];
-            this.current = this.result;
+            const ar: unknown[] = [];
+            this.result = ar;
+            this.current = ar;
         } else {
             this.stack.push(this.current);
-            const ar: any[] = [];
-            this.current[key] = ar;
+            const ar: unknown[] = [];
+            setValue(this.current, key, ar);
             this.current = ar;
         }
     }
@@ -92,12 +118,12 @@ class MapVisitor implements ObjectVisitor {
         this.current = this.stack.pop();
     }
 
-    onValue(key: ObjectKey, value: any) {
+    onValue(key: ObjectKey, value: unknown) {
         const r = this.mapFn(key, value);
         if (key === undefined) {
             this.result = r;
         } else if (r !== undefined) {
-            this.current[key] = r;
+            setValue(this.current, key, r);
         }
     }
 }