@bpmnkit/feel 0.0.21 → 1.0.0

package/dist/evaluator.d.ts

@@ -6,7 +6,10 @@ export interface EvalContext {
     input?: FeelValue;
 }
 export declare function evaluate(node: FeelNode, ctx: EvalContext): FeelValue;
-/** Evaluate a unary test against an input value. Returns boolean. */
+/**
+ * Evaluates a unary test against an input value. A decision table's rule
+ * either matches or it does not, so an unknown answer is not a match.
+ */
 export declare function evaluateUnaryTest(node: FeelNode, input: FeelValue, ctx: EvalContext): boolean;
 /** Evaluate a full unary-test node (the root returned by parseUnaryTests). */
 export declare function evaluateUnaryTests(node: FeelNode, input: FeelValue, ctx: EvalContext): boolean;

package/dist/evaluator.js

@@ -1,5 +1,5 @@
-import { compareValues, getBuiltin, parseTemporal } from "./builtins.js";
-import { getProperty, isFeelContext, isFeelDate, isFeelDateTime, isFeelDayTimeDuration, isFeelList, isFeelRange, isFeelTime, isFeelYearsMonthsDuration, } from "./types.js";
+import { compareValues, getBuiltin, orderNamedArgs, parseTemporal } from "./builtins.js";
+import { getProperty, isFeelContext, isFeelDate, isFeelDateTime, isFeelDayTimeDuration, isFeelFunction, isFeelList, isFeelRange, isFeelTime, isFeelYearsMonthsDuration, } from "./types.js";
 function lookupVar(ctx, name) {
     if (name === "?")
         return ctx.input ?? null;
@@ -13,16 +13,63 @@ function lookupVar(ctx, name) {
 function childCtx(parent, vars = {}) {
     return { vars, parent, input: parent.input };
 }
+/**
+ * The scope a filter condition runs in. The element is bound to `item`, and
+ * when it is a context its entries are in scope directly, so a list of
+ * records filters on their fields: `[{a: 1}, {a: 2}][a >= 2]`. An entry
+ * called `item` is the element's own, not the element.
+ */
+function filterCtx(parent, item) {
+    const vars = { item };
+    if (isFeelContext(item))
+        Object.assign(vars, item);
+    return childCtx(parent, vars);
+}
+/**
+ * Expands the domain of a `for`/`some`/`every` binding into the values to
+ * iterate. A numeric or date range yields its whole span, counting down when
+ * it runs backwards; anything else iterates as a single-element list. A range
+ * over values that cannot be stepped through has no iteration, which is null.
+ */
+function iterationValues(domain) {
+    if (isFeelList(domain))
+        return domain;
+    if (!isFeelRange(domain))
+        return [domain];
+    const { start, end } = domain;
+    if (typeof start === "number" && typeof end === "number") {
+        return span(start, end).map((n) => n);
+    }
+    if (isFeelDate(start) && isFeelDate(end)) {
+        return span(dateToEpochDays(start), dateToEpochDays(end)).map((d) => epochDaysToDate(d));
+    }
+    return null;
+}
+/** Every integer from `from` to `to`, in whichever direction that runs. */
+function span(from, to) {
+    const step = from <= to ? 1 : -1;
+    const values = [];
+    for (let v = from; step > 0 ? v <= to : v >= to; v += step)
+        values.push(v);
+    return values;
+}
 // -------------------------------------------------------------------------
 // Arithmetic helpers for temporal types
 // -------------------------------------------------------------------------
+/**
+ * Shifts a date by whole months. The day is clamped to the length of the
+ * month it lands in, so 2020-01-31 plus P1M is 2020-02-29 rather than a
+ * February 31st that no calendar has.
+ */
+function shiftMonths(date, months) {
+    const total = date.month + months;
+    const year = date.year + Math.floor((total - 1) / 12);
+    const month = ((((total - 1) % 12) + 12) % 12) + 1;
+    return { type: "date", year, month, day: Math.min(date.day, DAYS_IN_MONTH_TABLE(year, month)) };
+}
 function addDuration(date, dur) {
     if (isFeelDate(date) && isFeelYearsMonthsDuration(dur)) {
-        let m = date.month + dur.months;
-        let y = date.year;
-        y += Math.floor((m - 1) / 12);
-        m = ((m - 1 + 1200) % 12) + 1;
-        return { type: "date", year: y, month: m, day: date.day };
+        return shiftMonths(date, dur.months);
     }
     if (isFeelDate(date) && isFeelDayTimeDuration(dur)) {
         const EPOCH = dateToEpochDays(date);
@@ -34,16 +81,7 @@ function addDuration(date, dur) {
         return epochSecondsToDateTime(totalSec, date.time.offsetSeconds, date.time.timezone);
     }
     if (isFeelDateTime(date) && isFeelYearsMonthsDuration(dur)) {
-        const d = date.date;
-        let m = d.month + dur.months;
-        let y = d.year;
-        y += Math.floor((m - 1) / 12);
-        m = ((m - 1 + 1200) % 12) + 1;
-        return {
-            type: "date-time",
-            date: { type: "date", year: y, month: m, day: d.day },
-            time: date.time,
-        };
+        return { type: "date-time", date: shiftMonths(date.date, dur.months), time: date.time };
     }
     if (isFeelDayTimeDuration(date) && isFeelDayTimeDuration(dur)) {
         return { type: "days-time-duration", seconds: date.seconds + dur.seconds };
@@ -178,9 +216,16 @@ export function evaluate(node, ctx) {
         case "list":
             return node.items.map((item) => evaluate(item, ctx));
         case "context": {
+            // Entries are evaluated in order in a scope that already holds the
+            // preceding ones, so `{a: 1, b: a + 1}` resolves `a` in `b`.
             const result = {};
+            const entryCtx = childCtx(ctx, result);
             for (const entry of node.entries) {
-                result[entry.key] = evaluate(entry.value, ctx);
+                // A key given twice names two different values, which is not a
+                // context at all.
+                if (entry.key in result)
+                    return null;
+                result[entry.key] = evaluate(entry.value, entryCtx);
             }
             return result;
         }
@@ -206,71 +251,53 @@ export function evaluate(node, ctx) {
             return getProperty(base, node.key);
         }
         case "filter": {
-            const base = evaluate(node.base, ctx);
-            if (!isFeelList(base)) {
-                if (base === null)
-                    return [];
-                // single value
-                const result = evaluate(node.condition, childCtx(ctx, { item: base }));
-                return typeof result === "number" ? [base] : result ? [base] : [];
-            }
+            const value = evaluate(node.base, ctx);
+            if (value === null)
+                return [];
+            // A value that is not a list is filtered as a list holding just it,
+            // so `true[1]` is true and `true[0]` is null.
+            const base = isFeelList(value) ? value : [value];
             // Numeric index filter
-            const first = evaluate(node.condition, childCtx(ctx, { item: base[0] ?? null }));
+            const first = evaluate(node.condition, filterCtx(ctx, base[0] ?? null));
             if (typeof first === "number") {
                 const idx = first > 0 ? first - 1 : base.length + first;
                 const val = base[Math.floor(idx)];
                 return val !== undefined ? val : null;
             }
-            return base.filter((item) => {
-                const r = evaluate(node.condition, childCtx(ctx, { item }));
-                return r === true || (r !== false && r !== null);
-            });
+            return base.filter((item) => evaluate(node.condition, filterCtx(ctx, item)) === true);
         }
         case "call":
             return evalCall(node.callee, node.args, ctx);
+        case "call-expr": {
+            const target = evaluate(node.target, ctx);
+            if (!isFeelFunction(target))
+                return null;
+            return target.call(node.args.map((a) => evaluate(a, ctx)));
+        }
         case "call-named": {
+            const argNames = node.args.map((a) => a.name);
+            const values = node.args.map((a) => evaluate(a.value, ctx));
             const builtin = getBuiltin(node.callee);
-            if (!builtin) {
-                const fn = lookupVar(ctx, node.callee);
-                if (fn === null || typeof fn !== "object" || !("call" in fn))
+            if (builtin) {
+                const order = orderNamedArgs(node.callee, argNames);
+                if (order === null)
                     return null;
-                const args = node.args.map((a) => evaluate(a.value, ctx));
-                return fn.call(args);
+                return builtin.call(order.map((idx) => values[idx] ?? null));
             }
-            // Map named args to positional (built-ins don't declare param names in registry)
-            const args = node.args.map((a) => evaluate(a.value, ctx));
-            return builtin.call(args);
+            const fn = lookupVar(ctx, node.callee);
+            if (!isFeelFunction(fn))
+                return null;
+            return fn.call(orderArgs(fn.paramNames, argNames, values));
         }
         case "if": {
             const cond = evaluate(node.condition, ctx);
             return cond === true ? evaluate(node.then, ctx) : evaluate(node.else, ctx);
         }
-        case "for": {
-            const domains = [];
-            for (const binding of node.bindings) {
-                const d = evaluate(binding.domain, ctx);
-                domains.push(isFeelList(d) ? d : [d]);
-            }
-            const partial = [];
-            const results = evalCartesian(node.bindings, domains, 0, ctx, node, partial);
-            return results;
-        }
-        case "some": {
-            const domains = [];
-            for (const binding of node.bindings) {
-                const d = evaluate(binding.domain, ctx);
-                domains.push(isFeelList(d) ? d : [d]);
-            }
-            return evalQuantifier("some", node.bindings, domains, 0, ctx, node.satisfies);
-        }
-        case "every": {
-            const domains = [];
-            for (const binding of node.bindings) {
-                const d = evaluate(binding.domain, ctx);
-                domains.push(isFeelList(d) ? d : [d]);
-            }
-            return evalQuantifier("every", node.bindings, domains, 0, ctx, node.satisfies);
-        }
+        case "for":
+            return evalFor(node.bindings, node.body, ctx);
+        case "some":
+        case "every":
+            return evalQuantifier(node.kind, node.bindings, node.satisfies, ctx);
         case "between": {
             const val = evaluate(node.value, ctx);
             const low = evaluate(node.low, ctx);
@@ -281,11 +308,11 @@ export function evaluate(node, ctx) {
                 return null;
             return cmpLow >= 0 && cmpHigh <= 0;
         }
-        case "in-test": {
-            const val = evaluate(node.value, ctx);
-            const test = evaluate(node.test, ctx);
-            return testIncludes(test, val);
-        }
+        case "in-test":
+            // The right-hand side is a unary test, evaluated with the left-hand
+            // value as its implicit input. Unlike a decision table's test, this
+            // one keeps an unknown answer unknown.
+            return unaryTestValue(node.test, evaluate(node.value, ctx), ctx);
         case "instance-of": {
             const val = evaluate(node.value, ctx);
             return checkInstanceOf(val, node.typeName);
@@ -333,9 +360,8 @@ function evalBinary(op, leftNode, rightNode, ctx) {
         const r = evaluate(rightNode, ctx);
         if (r === false)
             return false;
-        if (l === null || r === null)
-            return null;
-        return true;
+        // Anything that is not a boolean leaves the result unknown.
+        return l === true && r === true ? true : null;
     }
     if (op === "or") {
         const l = evaluate(leftNode, ctx);
@@ -344,16 +370,21 @@ function evalBinary(op, leftNode, rightNode, ctx) {
         const r = evaluate(rightNode, ctx);
         if (r === true)
             return true;
-        if (l === null || r === null)
-            return null;
-        return false;
+        return l === false && r === false ? false : null;
     }
     const left = evaluate(leftNode, ctx);
     const right = evaluate(rightNode, ctx);
-    if (op === "=")
-        return deepEqual(left, right);
-    if (op === "!=")
-        return !deepEqual(left, right);
+    if (op === "=" || op === "!=") {
+        // Comparing values of different types says nothing, so it is null
+        // rather than false. Comparing against null stays a real answer.
+        if (left !== null && right !== null && typeTag(left) !== typeTag(right))
+            return null;
+        // Temporal values are equal when they name the same point, however
+        // each was written: 12:00-01:00 and 17:00+04:00 are one instant.
+        const instant = isTemporal(left) ? compareValues(left, right) : null;
+        const equal = instant !== null ? instant === 0 : deepEqual(left, right);
+        return op === "=" ? equal : !equal;
+    }
     if (left === null || right === null)
         return null;
     if (op === "+" || op === "-") {
@@ -409,6 +440,19 @@ function evalBinary(op, leftNode, rightNode, ctx) {
         return cmp >= 0;
     return null;
 }
+/**
+ * Orders the arguments of a named invocation of a user-defined function. A
+ * function that declares no parameter names, or that is handed a name it does
+ * not declare, gets nulls rather than a silently mis-ordered argument list.
+ */
+function orderArgs(paramNames, argNames, values) {
+    if (!paramNames)
+        return [];
+    return paramNames.map((param) => {
+        const idx = argNames.indexOf(param);
+        return idx >= 0 ? (values[idx] ?? null) : null;
+    });
+}
 function evalCall(callee, argNodes, ctx) {
     const builtin = getBuiltin(callee);
     if (builtin) {
@@ -421,63 +465,100 @@ function evalCall(callee, argNodes, ctx) {
     const args = argNodes.map((a) => evaluate(a, ctx));
     return fn.call(args);
 }
-function evalCartesian(bindings, domains, idx, ctx, forNode, partial) {
-    if (idx === bindings.length) {
-        const vars = { partial: [...partial] };
-        const binding = bindings[idx - 1];
-        if (binding)
-            vars[binding.name] = partial[partial.length - 1] ?? null;
-        const result = evaluate(forNode.body, childCtx(ctx, vars));
-        partial.push(result);
-        return [result];
-    }
-    const binding = bindings[idx];
-    if (!binding)
-        return [];
-    const domain = domains[idx] ?? [];
+/**
+ * Evaluates a `for`. Each binding's domain is evaluated with the bindings to
+ * its left already in scope, so `for x in xs, y in x` works, and the body sees
+ * the results produced so far as `partial`.
+ */
+function evalFor(bindings, body, ctx) {
     const results = [];
-    for (const val of domain) {
-        const vars = { partial: [...partial] };
-        vars[binding.name] = val;
-        // Propagate earlier bindings too
-        for (let i = 0; i < idx; i++) {
-            const b = bindings[i];
-            if (b)
-                vars[b.name] = partial[i] ?? null;
+    let failed = false;
+    const iterate = (idx, scope) => {
+        if (failed)
+            return;
+        if (idx === bindings.length) {
+            results.push(evaluate(body, childCtx(scope, { partial: [...results] })));
+            return;
         }
-        const sub = evalCartesian(bindings, domains, idx + 1, childCtx(ctx, vars), forNode, [
-            ...partial,
-            val,
-        ]);
-        results.push(...sub);
-    }
-    return results;
+        const binding = bindings[idx];
+        if (!binding)
+            return;
+        const domain = iterationValues(evaluate(binding.domain, scope));
+        if (domain === null) {
+            failed = true;
+            return;
+        }
+        for (const value of domain) {
+            iterate(idx + 1, childCtx(scope, { [binding.name]: value }));
+        }
+    };
+    iterate(0, ctx);
+    return failed ? null : results;
 }
-function evalQuantifier(kind, bindings, domains, idx, ctx, satisfies) {
-    if (idx === bindings.length) {
-        return evaluate(satisfies, ctx);
-    }
-    const binding = bindings[idx];
-    if (!binding)
-        return kind === "every";
-    const domain = domains[idx] ?? [];
-    if (domain.length === 0)
-        return kind === "every";
-    let hasNull = false;
-    for (const val of domain) {
-        const vars = {};
-        vars[binding.name] = val;
-        const r = evalQuantifier(kind, bindings, domains, idx + 1, childCtx(ctx, vars), satisfies);
-        if (kind === "some" && r === true)
-            return true;
-        if (kind === "every" && r === false)
-            return false;
-        if (r === null)
-            hasNull = true;
-    }
+/**
+ * Evaluates `some`/`every`. A definite answer wins over an unknown one: one
+ * true satisfies `some` whatever else the domain holds, and one false settles
+ * `every`. Otherwise an unknown anywhere makes the whole answer unknown.
+ */
+function evalQuantifier(kind, bindings, satisfies, ctx) {
+    let sawTrue = false;
+    let sawFalse = false;
+    let sawUnknown = false;
+    let failed = false;
+    const visit = (idx, scope) => {
+        if (failed)
+            return;
+        if (idx === bindings.length) {
+            const result = asBoolean(evaluate(satisfies, scope));
+            if (result === true)
+                sawTrue = true;
+            else if (result === false)
+                sawFalse = true;
+            else
+                sawUnknown = true;
+            return;
+        }
+        const binding = bindings[idx];
+        if (!binding)
+            return;
+        const domain = iterationValues(evaluate(binding.domain, scope));
+        if (domain === null) {
+            failed = true;
+            return;
+        }
+        for (const value of domain) {
+            visit(idx + 1, childCtx(scope, { [binding.name]: value }));
+        }
+    };
+    visit(0, ctx);
+    if (failed)
+        return null;
     if (kind === "some")
-        return hasNull ? null : false;
-    return hasNull ? null : true;
+        return sawTrue ? true : sawUnknown ? null : false;
+    return sawFalse ? false : sawUnknown ? null : true;
+}
+function asBoolean(v) {
+    return typeof v === "boolean" ? v : null;
+}
+/** True for the values that name a point in time or a length of it. */
+function isTemporal(v) {
+    return (isFeelDate(v) ||
+        isFeelTime(v) ||
+        isFeelDateTime(v) ||
+        isFeelDayTimeDuration(v) ||
+        isFeelYearsMonthsDuration(v));
+}
+/** The FEEL type of a value, for deciding whether two values are comparable. */
+function typeTag(v) {
+    if (v === null)
+        return "null";
+    if (Array.isArray(v))
+        return "list";
+    const t = typeof v;
+    if (t !== "object")
+        return t;
+    const tagged = v.type;
+    return typeof tagged === "string" ? tagged : "context";
 }
 function deepEqual(a, b) {
     if (a === b)
@@ -511,6 +592,10 @@ function deepEqual(a, b) {
     return false;
 }
 function testIncludes(test, val) {
+    // Two lists are compared, not searched: [1,2,3] is a member of
+    // [[1,2,3,4], [1,2,3]] rather than of its elements.
+    if (isFeelList(test) && isFeelList(val))
+        return deepEqual(test, val);
     if (isFeelRange(test)) {
         const cmpStart = compareValues(val, test.start);
         const cmpEnd = compareValues(val, test.end);
@@ -531,6 +616,10 @@ function testIncludes(test, val) {
     return deepEqual(val, test);
 }
 function checkInstanceOf(val, typeName) {
+    // null is not an instance of anything, Any included: it is the absence of
+    // a value rather than a value of some type.
+    if (val === null)
+        return typeName === "null" || typeName === "Null";
     switch (typeName) {
         case "number":
             return typeof val === "number";
@@ -545,8 +634,10 @@ function checkInstanceOf(val, typeName) {
         case "date and time":
             return isFeelDateTime(val);
         case "days and time duration":
+        case "dayTimeDuration":
             return isFeelDayTimeDuration(val);
         case "years and months duration":
+        case "yearMonthDuration":
             return isFeelYearsMonthsDuration(val);
         case "list":
             return Array.isArray(val);
@@ -555,25 +646,39 @@ function checkInstanceOf(val, typeName) {
         case "function":
             return typeof val === "object" && val !== null && "call" in val;
         case "Any":
+        case "any":
             return true;
         case "null":
-            return val === null;
+        case "Null":
+            return false;
         default:
             return false;
     }
 }
-/** Evaluate a unary test against an input value. Returns boolean. */
-export function evaluateUnaryTest(node, input, ctx) {
+/**
+ * Evaluates a unary test, keeping an unknown answer unknown. A range whose
+ * bound is null, or an input of null, says nothing about membership.
+ */
+function unaryTestValue(node, input, ctx) {
     const withInput = { ...ctx, input };
     const result = evaluate(node, withInput);
     if (typeof result === "boolean")
         return result;
     // Range result in unary-test context → membership test
     if (isFeelRange(result))
-        return testIncludes(result, input) === true;
+        return testIncludes(result, input);
     // List result → any element matches
-    if (isFeelList(result))
-        return result.some((r) => testIncludes(r, input) === true);
+    if (isFeelList(result)) {
+        let unknown = false;
+        for (const item of result) {
+            const match = testIncludes(item, input);
+            if (match === true)
+                return true;
+            if (match === null)
+                unknown = true;
+        }
+        return unknown ? null : false;
+    }
     // A plain expression in unary test mode is an equality test.
     // When the result is null: only match if the node itself is the null literal
     // (null arithmetic in comparisons also yields null but must not match anything).
@@ -581,6 +686,13 @@ export function evaluateUnaryTest(node, input, ctx) {
         return deepEqual(result, input);
     return node.kind === "null" ? input === null : false;
 }
+/**
+ * Evaluates a unary test against an input value. A decision table's rule
+ * either matches or it does not, so an unknown answer is not a match.
+ */
+export function evaluateUnaryTest(node, input, ctx) {
+    return unaryTestValue(node, input, ctx) === true;
+}
 /** Evaluate a full unary-test node (the root returned by parseUnaryTests). */
 export function evaluateUnaryTests(node, input, ctx) {
     return evaluateUnaryTest(node, input, ctx);

package/dist/formatter.js

@@ -6,6 +6,17 @@ export function formatFeel(node, opts) {
     const o = { ...DEFAULTS, ...opts };
     return fmt(node, o, 0);
 }
+const STRING_ESCAPES = {
+    "\\": "\\\\",
+    '"': '\\"',
+    "\n": "\\n",
+    "\r": "\\r",
+    "\t": "\\t",
+};
+/** Re-escapes a string literal's value, which the parser stores decoded. */
+function escapeString(value) {
+    return value.replace(/[\\"\n\r\t]/g, (c) => STRING_ESCAPES[c] ?? c);
+}
 function fmt(node, o, depth) {
     const ind = o.indent.repeat(depth);
     const ind1 = o.indent.repeat(depth + 1);
@@ -17,7 +28,7 @@ function fmt(node, o, depth) {
         case "number":
             return String(node.value);
         case "string":
-            return `"${node.value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+            return `"${escapeString(node.value)}"`;
         case "temporal":
             return node.raw;
         case "name":
@@ -64,6 +75,10 @@ function fmt(node, o, depth) {
             const args = node.args.map((a) => fmt(a, o, depth)).join(", ");
             return `${node.callee}(${args})`;
         }
+        case "call-expr": {
+            const args = node.args.map((a) => fmt(a, o, depth)).join(", ");
+            return `${fmt(node.target, o, depth)}(${args})`;
+        }
         case "call-named": {
             const args = node.args.map((a) => `${a.name}: ${fmt(a.value, o, depth)}`).join(", ");
             return `${node.callee}(${args})`;

package/dist/index.d.ts

@@ -4,11 +4,12 @@ export { tokenize } from "./lexer.js";
 export type { FeelToken, FeelTokenKind } from "./lexer.js";
 export type { FeelNode, BinaryOp } from "./ast.js";
 export { parseExpression, parseUnaryTests } from "./parser.js";
-export type { ParseResult, ParseError } from "./parser.js";
+export type { ParseResult, ParseError, ParseOptions } from "./parser.js";
 export { evaluate, evaluateUnaryTests, evaluateUnaryTest } from "./evaluator.js";
 export type { EvalContext } from "./evaluator.js";
 export { formatFeel } from "./formatter.js";
 export type { FormatOptions } from "./formatter.js";
+export { builtinNames, getBuiltin } from "./builtins.js";
 export { annotate, highlightToHtml, highlightFeel } from "./highlighter.js";
 export type { AnnotatedToken, HighlightKind } from "./highlighter.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -7,6 +7,8 @@ export { parseExpression, parseUnaryTests } from "./parser.js";
 export { evaluate, evaluateUnaryTests, evaluateUnaryTest } from "./evaluator.js";
 // Formatter
 export { formatFeel } from "./formatter.js";
+// Built-ins
+export { builtinNames, getBuiltin } from "./builtins.js";
 // Highlighter
 export { annotate, highlightToHtml, highlightFeel } from "./highlighter.js";
 //# sourceMappingURL=index.js.map

package/dist/lexer.d.ts

@@ -6,4 +6,11 @@ export interface FeelToken {
     end: number;
 }
 export declare function tokenize(input: string): FeelToken[];
+/**
+ * Decodes the escape sequences of a FEEL string literal body (the text between
+ * the quotes). Recognizes \' \" \\ \n \r \t, \uXXXX and the extended
+ * \UXXXXXX form; an unrecognized sequence is left as written, since dropping
+ * the backslash would silently alter the author's data.
+ */
+export declare function unescapeString(body: string): string;
 //# sourceMappingURL=lexer.d.ts.map