evals-lab 0.1.2

package/lab/flows/wdl.mjs

@@ -0,0 +1,373 @@
+// Power Automate's expressions -- the Workflow Definition Language -- as a
+// Power Automate step's request template holds them (docs/power-automate.md
+// § The HTTP Request step). The lab evaluates a template against a record's
+// scope to rebuild the request a flow would send with new words, so the
+// evaluator has to write a value the way Power Automate does: the fidelity
+// check (a record's request, rebuilt and compared byte for byte) is what
+// holds it to that, on real runs.
+//
+// A string that begins `@` is one expression and its value is whatever the
+// expression gives; `@{…}` inside a string writes each value into the text;
+// `@@` at the start is a literal @. Function names are case-insensitive.
+// A function the lab does not evaluate is refused by name rather than
+// guessed at.
+
+/** What an expression reads: a record's scope (flows/record.ts). */
+                           
+                                                                  
+                                                                    
+                                      
+                                  
+ 
+
+                             
+                  
+                                                                    
+                       
+                                                                          
+                                                           
+                      
+                                              
+                                       
+ 
+
+export class WdlError extends Error {}
+
+const isObj = (v         )                               => v != null && typeof v === "object" && !Array.isArray(v);
+
+// ---- reading an expression ------------------------------------------------
+
+           
+                            
+                                             
+                                                     
+
+                                                        
+
+function tokens(src        )        {
+  const out        = [];
+  let i = 0;
+  while (i < src.length) {
+    const c = src[i] ;
+    if (/\s/.test(c)) { i++; continue; }
+    if (c === "'") {
+      let s = "";
+      i++;
+      for (;;) {
+        if (i >= src.length) throw new WdlError("a quoted string is never closed");
+        if (src[i] === "'") {
+          if (src[i + 1] === "'") { s += "'"; i += 2; continue; }
+          i++;
+          break;
+        }
+        s += src[i++];
+      }
+      out.push({ t: "str", v: s });
+      continue;
+    }
+    const num = /^-?\d+(\.\d+)?([eE][-+]?\d+)?/.exec(src.slice(i));
+    if (num && (c === "-" ? /\d/.test(src[i + 1] ?? "") : true) && /[-\d]/.test(c)) {
+      out.push({ t: "num", v: num[0] });
+      i += num[0].length;
+      continue;
+    }
+    const id = /^[A-Za-z_$][\w$]*/.exec(src.slice(i));
+    if (id) { out.push({ t: "id", v: id[0] }); i += id[0].length; continue; }
+    if ("()[],.?".includes(c)) { out.push({ t: "p", v: c }); i++; continue; }
+    throw new WdlError(`"${c}" cannot start anything in an expression`);
+  }
+  return out;
+}
+
+function parse(src        )       {
+  const ts = tokens(src);
+  let at = 0;
+  const peek = (v         ) => (v == null ? ts[at] : ts[at]?.t === "p" && ts[at]?.v === v ? ts[at] : undefined);
+  const want = (v        ) => {
+    if (!peek(v)) throw new WdlError(`expected "${v}" in ${src}`);
+    at++;
+  };
+  const expr = ()       => {
+    const tok = ts[at++];
+    if (!tok) throw new WdlError(`${src} ends too soon`);
+    let node      ;
+    if (tok.t === "str") node = { k: "lit", v: tok.v };
+    else if (tok.t === "num") node = { k: "lit", v: Number(tok.v) };
+    else if (tok.t === "id") {
+      const low = tok.v.toLowerCase();
+      if (!peek("(") && (low === "true" || low === "false" || low === "null")) {
+        node = { k: "lit", v: low === "null" ? null : low === "true" };
+      } else {
+        want("(");
+        const args         = [];
+        if (!peek(")")) {
+          args.push(expr());
+          while (peek(",")) { at++; args.push(expr()); }
+        }
+        want(")");
+        node = { k: "call", name: low, args };
+      }
+    } else throw new WdlError(`"${tok.v}" cannot start an expression`);
+    // Property access: ['x'], ?['x'], .x, ?.x
+    for (;;) {
+      const safe = !!peek("?");
+      if (safe) at++;
+      if (peek("[")) {
+        at++;
+        const key = expr();
+        want("]");
+        node = { k: "get", of: node, key, safe };
+      } else if (peek(".")) {
+        at++;
+        const name = ts[at++];
+        if (name?.t !== "id") throw new WdlError(`a property name is wanted after "." in ${src}`);
+        node = { k: "get", of: node, key: { k: "lit", v: name.v }, safe };
+      } else {
+        if (safe) throw new WdlError(`"?" has to be followed by [ or . in ${src}`);
+        return node;
+      }
+    }
+  };
+  const node = expr();
+  if (at < ts.length) throw new WdlError(`${src} goes on after its expression ends`);
+  return node;
+}
+
+// ---- writing a value -------------------------------------------------------
+
+/** A value as Power Automate writes it into text: an array or object as
+    compact JSON -- measured on the spike's run -- a boolean as True or
+    False, null as nothing. */
+export function asText(v         )         {
+  if (v == null) return "";
+  if (typeof v === "string") return v;
+  if (typeof v === "boolean") return v ? "True" : "False";
+  if (typeof v === "number") return String(v);
+  return JSON.stringify(v);
+}
+
+// ---- functions ---------------------------------------------------------------
+
+                                                        
+
+const str = (v         )         => asText(v);
+const num = (v         , fn        )         => {
+  const n = typeof v === "number" ? v : typeof v === "string" && v.trim() !== "" ? Number(v) : NaN;
+  if (Number.isNaN(n)) throw new WdlError(`${fn}() wants a number, and was given ${JSON.stringify(v)}`);
+  return n;
+};
+const list = (v         , fn        )            => {
+  if (Array.isArray(v)) return v;
+  throw new WdlError(`${fn}() wants an array, and was given ${JSON.stringify(v)}`);
+};
+const equal = (a         , b         )          => JSON.stringify(a) === JSON.stringify(b);
+const got =     (v               , what        )    => {
+  if (v === undefined) throw new WdlError(`${what} is not in the record`);
+  return v;
+};
+const name = (args           , fn        )         => {
+  if (typeof args[0] !== "string") throw new WdlError(`${fn}() names what it reads`);
+  return args[0];
+};
+
+/** A date as ISO 8601 with milliseconds and a Z, as utcNow() writes one. */
+const iso = (d      ) => d.toISOString().replace(/\.(\d{3})Z$/, ".$10000Z");
+const date = (v         , fn        )       => {
+  const d = new Date(str(v));
+  if (Number.isNaN(d.getTime())) throw new WdlError(`${fn}() wants a time, and was given ${JSON.stringify(v)}`);
+  return d;
+};
+/** .NET's custom date format, the tokens flows use. */
+function formatDate(d      , fmt                    )         {
+  if (!fmt || fmt === "o") return iso(d);
+  const p = (n        , w = 2) => String(n).padStart(w, "0");
+  const parts                         = {
+    yyyy: String(d.getUTCFullYear()), yy: p(d.getUTCFullYear() % 100), MM: p(d.getUTCMonth() + 1),
+    M: String(d.getUTCMonth() + 1), dd: p(d.getUTCDate()), d: String(d.getUTCDate()), HH: p(d.getUTCHours()),
+    H: String(d.getUTCHours()), mm: p(d.getUTCMinutes()), ss: p(d.getUTCSeconds()), fff: p(d.getUTCMilliseconds(), 3),
+  };
+  return fmt.replace(/yyyy|yy|MM|M|dd|d|HH|H|mm|ss|fff/g, (t) => parts[t] );
+}
+const shift = (unit        )     => ([ts, n, fmt]) =>
+  formatDate(new Date(date(ts, "add").getTime() + num(n, "add") * unit), fmt                      );
+
+const FUNCTIONS                     = {
+  // What the flow read.
+  triggerbody: (_, c) => c.scope.trigger?.body ?? null,
+  triggeroutputs: (_, c) => ({ body: c.scope.trigger?.body ?? null, headers: c.scope.trigger?.headers ?? {} }),
+  trigger: (_, c) => ({ outputs: { body: c.scope.trigger?.body ?? null, headers: c.scope.trigger?.headers ?? {} } }),
+  body: (a, c) => got(c.scope.actions?.[name(a, "body")], `body('${a[0]}')`).body ?? null,
+  actionbody: (a, c) => got(c.scope.actions?.[name(a, "actionBody")], `body('${a[0]}')`).body ?? null,
+  outputs: (a, c) => got(c.scope.actions?.[name(a, "outputs")], `outputs('${a[0]}')`),
+  actionoutputs: (a, c) => got(c.scope.actions?.[name(a, "actionOutputs")], `outputs('${a[0]}')`),
+  actions: (a, c) => ({ outputs: got(c.scope.actions?.[name(a, "actions")], `actions('${a[0]}')`) }),
+  variables: (a, c) => got(c.scope.variables?.[name(a, "variables")], `variables('${a[0]}')`),
+  items: (a, c) => got(c.scope.items?.[name(a, "items")], `items('${a[0]}')`),
+  item: (_, c) => {
+    if (!c.loop) throw new WdlError("item() is only inside a loop");
+    return got(c.scope.items?.[c.loop], "item()");
+  },
+  parameters: (a, c) => got(c.parameters?.[name(a, "parameters")], `parameters('${a[0]}')`),
+  utcnow: ([fmt], c) => {
+    if (!c.now) throw new WdlError("utcNow() needs the time of the call, and this record has none");
+    return formatDate(new Date(c.now), fmt                      );
+  },
+  // Text.
+  concat: (a) => a.map(str).join(""),
+  substring: ([s, start, len]) => {
+    const t = str(s), b = num(start, "substring");
+    return len == null ? t.slice(b) : t.slice(b, b + num(len, "substring"));
+  },
+  slice: ([s, start, end]) => str(s).slice(num(start, "slice"), end == null ? undefined : num(end, "slice")),
+  replace: ([s, from, to]) => str(s).split(str(from)).join(str(to)),
+  tolower: ([s]) => str(s).toLowerCase(),
+  toupper: ([s]) => str(s).toUpperCase(),
+  trim: ([s]) => str(s).trim(),
+  indexof: ([s, t]) => str(s).toLowerCase().indexOf(str(t).toLowerCase()),
+  lastindexof: ([s, t]) => str(s).toLowerCase().lastIndexOf(str(t).toLowerCase()),
+  startswith: ([s, t]) => str(s).toLowerCase().startsWith(str(t).toLowerCase()),
+  endswith: ([s, t]) => str(s).toLowerCase().endsWith(str(t).toLowerCase()),
+  split: ([s, sep]) => str(s).split(str(sep)),
+  // Collections, and text as one.
+  contains: ([c, v]) => typeof c === "string" ? c.includes(str(v))
+    : Array.isArray(c) ? c.some((x) => equal(x, v)) : isObj(c) ? str(v) in c : false,
+  empty: ([v]) => v == null || (typeof v === "string" || Array.isArray(v) ? v.length === 0 : isObj(v) && !Object.keys(v).length),
+  first: ([v]) => (typeof v === "string" ? v[0] ?? "" : list(v, "first")[0] ?? null),
+  last: ([v]) => (typeof v === "string" ? v.at(-1) ?? "" : list(v, "last").at(-1) ?? null),
+  length: ([v]) => (typeof v === "string" ? v.length : list(v, "length").length),
+  join: ([v, sep]) => list(v, "join").map(str).join(str(sep)),
+  take: ([v, n]) => (typeof v === "string" ? v.slice(0, num(n, "take")) : list(v, "take").slice(0, num(n, "take"))),
+  skip: ([v, n]) => (typeof v === "string" ? v.slice(num(n, "skip")) : list(v, "skip").slice(num(n, "skip"))),
+  union: (a) => Array.isArray(a[0]) ? a.flatMap((x) => list(x, "union")).filter((x, i, all) => all.findIndex((y) => equal(x, y)) === i)
+    : Object.assign({}, ...a),
+  intersection: (a) => list(a[0], "intersection").filter((x) => a.slice(1).every((o) => list(o, "intersection").some((y) => equal(x, y)))),
+  createarray: (a) => a,
+  reverse: ([v]) => [...list(v, "reverse")].reverse(),
+  range: ([s, n]) => Array.from({ length: num(n, "range") }, (_, i) => num(s, "range") + i),
+  // Logic.
+  equals: ([a, b]) => equal(a, b),
+  and: (a) => a.every(Boolean),
+  or: (a) => a.some(Boolean),
+  not: ([v]) => !v,
+  if: ([c, a, b]) => (c ? a : b),
+  greater: ([a, b]) => (a          ) > (b          ),
+  greaterorequals: ([a, b]) => (a          ) >= (b          ),
+  less: ([a, b]) => (a          ) < (b          ),
+  lessorequals: ([a, b]) => (a          ) <= (b          ),
+  coalesce: (a) => a.find((v) => v != null) ?? null,
+  // Conversion.
+  string: ([v]) => str(v),
+  int: ([v]) => Math.trunc(num(v, "int")),
+  float: ([v]) => num(v, "float"),
+  bool: ([v]) => (typeof v === "string" ? v.toLowerCase() === "true" : !!v),
+  json: ([v]) => {
+    if (typeof v !== "string") return v;
+    try { return JSON.parse(v); } catch { throw new WdlError(`json() could not read ${JSON.stringify(v.slice(0, 40))}`); }
+  },
+  array: ([v]) => [v],
+  base64: ([v]) => Bytes.from(str(v), "utf8").toString("base64"),
+  base64tostring: ([v]) => Bytes.from(str(v), "base64").toString("utf8"),
+  decodebase64: ([v]) => Bytes.from(str(v), "base64").toString("utf8"),
+  encodeuricomponent: ([v]) => encodeURIComponent(str(v)),
+  uricomponent: ([v]) => encodeURIComponent(str(v)),
+  uricomponenttostring: ([v]) => decodeURIComponent(str(v)),
+  decodeuricomponent: ([v]) => decodeURIComponent(str(v)),
+  // Numbers.
+  add: ([a, b]) => num(a, "add") + num(b, "add"),
+  sub: ([a, b]) => num(a, "sub") - num(b, "sub"),
+  mul: ([a, b]) => num(a, "mul") * num(b, "mul"),
+  div: ([a, b]) => {
+    const x = num(a, "div"), y = num(b, "div");
+    return Number.isInteger(x) && Number.isInteger(y) ? Math.trunc(x / y) : x / y;
+  },
+  mod: ([a, b]) => num(a, "mod") % num(b, "mod"),
+  min: (a) => Math.min(...(Array.isArray(a[0]) ? a[0] : a).map((v) => num(v, "min"))),
+  max: (a) => Math.max(...(Array.isArray(a[0]) ? a[0] : a).map((v) => num(v, "max"))),
+  // Times.
+  formatdatetime: ([ts, fmt]) => formatDate(date(ts, "formatDateTime"), fmt                      ),
+  adddays: shift(86_400_000),
+  addhours: shift(3_600_000),
+  addminutes: shift(60_000),
+  addseconds: shift(1_000),
+  // Objects.
+  addproperty: ([o, k, v]) => ({ ...(o          ), [str(k)]: v }),
+  setproperty: ([o, k, v]) => ({ ...(o          ), [str(k)]: v }),
+  removeproperty: ([o, k]) => {
+    const { [str(k)]: _gone, ...rest } = o                           ;
+    return rest;
+  },
+};
+
+// Bytes is Node's; the page has btoa. One path each, so the core's
+// evaluator runs in both.
+const Bytes = (globalThis                                                                                   ).Bytes ?? {
+  from: (s        , enc        ) => ({
+    toString: (to        ) => enc === "utf8" && to === "base64"
+      ? btoa(String.fromCharCode(...new TextEncoder().encode(s)))
+      : new TextDecoder().decode(Uint8Array.from(atob(s), (ch) => ch.charCodeAt(0))),
+  }),
+};
+
+function run(node      , ctx            )          {
+  if (node.k === "lit") return node.v;
+  if (node.k === "get") {
+    const of = run(node.of, ctx);
+    const key = run(node.key, ctx);
+    if (of == null) {
+      if (node.safe) return null;
+      throw new WdlError(`property ${JSON.stringify(key)} cannot be read from null`);
+    }
+    const v = Array.isArray(of) && typeof key === "number" ? of[key]
+      : isObj(of) ? Object.entries(of).find(([k]) => k.toLowerCase() === str(key).toLowerCase())?.[1]
+      : undefined;
+    if (v === undefined && !node.safe) throw new WdlError(`property ${JSON.stringify(key)} is not there`);
+    return v ?? null;
+  }
+  const fn = FUNCTIONS[node.name];
+  if (!fn) throw new WdlError(`${node.name}() is not an expression function this lab evaluates`);
+  return fn(node.args.map((a) => run(a, ctx)), ctx);
+}
+
+/** One expression's value: `triggerBody()?['text']`, without its `@`. */
+export function evaluateExpression(src        , ctx            )          {
+  return run(parse(src), ctx);
+}
+
+/** A string's value: an expression's own value for a string that is one,
+    text with each `@{…}` written in otherwise. */
+function evaluateString(s        , ctx            )          {
+  if (s.startsWith("@@")) return s.slice(1);
+  if (s.startsWith("@") && !s.startsWith("@{")) return evaluateExpression(s.slice(1), ctx);
+  if (!s.includes("@{")) return s;
+  let out = "";
+  let i = 0;
+  while (i < s.length) {
+    const open = s.indexOf("@{", i);
+    if (open < 0) { out += s.slice(i); break; }
+    out += s.slice(i, open);
+    const close = endOf(s, open + 2);
+    out += asText(evaluateExpression(s.slice(open + 2, close), ctx));
+    i = close + 1;
+  }
+  return out;
+}
+
+/** Where the `}` that closes an `@{` is: braces inside quoted strings do not count. */
+function endOf(s        , from        )         {
+  let quoted = false;
+  for (let i = from; i < s.length; i++) {
+    const c = s[i];
+    if (c === "'") quoted = !quoted;
+    else if (c === "}" && !quoted) return i;
+  }
+  throw new WdlError("an @{ is never closed");
+}
+
+/** [template] with every expression in it evaluated: each string that is
+    one, or holds one, wherever it sits in objects and arrays. */
+export function evaluate(template         , ctx            )          {
+  if (typeof template === "string") return evaluateString(template, ctx);
+  if (Array.isArray(template)) return template.map((v) => evaluate(v, ctx));
+  if (isObj(template)) return Object.fromEntries(Object.entries(template).map(([k, v]) => [k, evaluate(v, ctx)]));
+  return template;
+}