@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/hkp-node/src/services/expression.ts

@@ -0,0 +1,417 @@
+/**
+ * Expression evaluation for services that let a board author write small
+ * dynamic terms — a Map template's `key=` rows, for example.
+ *
+ * An expression is parsed to an AST and interpreted against a scope holding
+ * the incoming data as `params` and the helper functions below. It is not
+ * JavaScript: the grammar is jsep's, so there are no statements, no
+ * assignment, no function or arrow expressions, no object literals and no
+ * template strings — array literals, member access, calls, `||`/`&&` and the
+ * ternary are the whole of it.
+ *
+ * **Nothing outside the scope is reachable, and that is the point.** A term
+ * naming `process` or `require` evaluates to `undefined` rather than to the
+ * real thing, and reaching a constructor through a value that *is* in scope
+ * (`x.constructor.constructor("…")()`, the usual way out of an interpreter
+ * like this) is refused by the evaluator. Compiling these terms with
+ * `new Function` — which is what this module used to do — made every
+ * expression a board contained arbitrary code in the runtime's own process.
+ * The evaluator is a boundary, so keep it one: no helper below may hand back
+ * a constructor, a module, or a way to reach either.
+ *
+ * The browser runtime evaluates the same sources through the same library, so
+ * one template behaves the same whichever runtime hosts the service and the
+ * shared Map UI can validate for both. The helper set is kept aligned for the
+ * same reason; helpers that need a browser (DOM, vault, AudioContext) have no
+ * counterpart here and are left out.
+ */
+import { randomUUID } from "node:crypto";
+
+import { OnMissing, evaluate as evaluateAst, parse } from "../expressionEval";
+
+/**
+ * A compiled term. `onMissing` hears about every read that found nothing
+ * (expressionEval.ts); `parseError` says why a source that did not parse
+ * will throw, so a caller can report it before the term ever runs.
+ */
+export type CompiledExpression = ((params: unknown, onMissing?: OnMissing) => unknown) & {
+  parseError?: string;
+};
+
+const MONTHS = [
+  "January",
+  "February",
+  "March",
+  "April",
+  "May",
+  "June",
+  "July",
+  "August",
+  "September",
+  "October",
+  "November",
+  "December",
+];
+
+const WEEKDAYS = [
+  "Sunday",
+  "Monday",
+  "Tuesday",
+  "Wednesday",
+  "Thursday",
+  "Friday",
+  "Saturday",
+];
+
+// Format tokens understood by formatDate/parseDate, longest first so that
+// e.g. "MMMM" is matched before "MM".
+const TOKEN_PATTERN =
+  /\[([^\]]*)\]|YYYY|YY|MMMM|MMM|MM|M|DD|D|dddd|ddd|HH|H|hh|h|mm|m|ss|s|A|a/g;
+
+function pad(value: number, length = 2): string {
+  return String(value).padStart(length, "0");
+}
+
+function formatDate(date: Date, format: string): string {
+  if (Number.isNaN(date.getTime())) {
+    return "";
+  }
+
+  return format.replace(TOKEN_PATTERN, (token, escaped?: string) => {
+    if (escaped !== undefined) {
+      return escaped;
+    }
+
+    const hours12 = date.getHours() % 12 || 12;
+    switch (token) {
+      case "YYYY":
+        return String(date.getFullYear());
+      case "YY":
+        return pad(date.getFullYear() % 100);
+      case "MMMM":
+        return MONTHS[date.getMonth()];
+      case "MMM":
+        return MONTHS[date.getMonth()].slice(0, 3);
+      case "MM":
+        return pad(date.getMonth() + 1);
+      case "M":
+        return String(date.getMonth() + 1);
+      case "DD":
+        return pad(date.getDate());
+      case "D":
+        return String(date.getDate());
+      case "dddd":
+        return WEEKDAYS[date.getDay()];
+      case "ddd":
+        return WEEKDAYS[date.getDay()].slice(0, 3);
+      case "HH":
+        return pad(date.getHours());
+      case "H":
+        return String(date.getHours());
+      case "hh":
+        return pad(hours12);
+      case "h":
+        return String(hours12);
+      case "mm":
+        return pad(date.getMinutes());
+      case "m":
+        return String(date.getMinutes());
+      case "ss":
+        return pad(date.getSeconds());
+      case "s":
+        return String(date.getSeconds());
+      case "A":
+        return date.getHours() < 12 ? "AM" : "PM";
+      case "a":
+        return date.getHours() < 12 ? "am" : "pm";
+      default:
+        return token;
+    }
+  });
+}
+
+// Reads `value` according to the same token subset formatDate writes. Falls
+// back to Date's own parsing (ISO strings, epoch millis) when the format
+// describes nothing this understands.
+function parseDate(value: string, format: string): Date {
+  const captured: string[] = [];
+  let pattern = "";
+  let lastIndex = 0;
+
+  const escapeLiteral = (text: string) =>
+    text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+  for (const match of format.matchAll(TOKEN_PATTERN)) {
+    const start = match.index ?? 0;
+    pattern += escapeLiteral(format.slice(lastIndex, start));
+    lastIndex = start + match[0].length;
+
+    if (match[1] !== undefined) {
+      pattern += escapeLiteral(match[1]);
+      continue;
+    }
+
+    const token = match[0];
+    captured.push(token);
+    switch (token) {
+      case "YYYY":
+        pattern += "(\\d{4})";
+        break;
+      case "MMMM":
+      case "MMM":
+      case "dddd":
+      case "ddd":
+        pattern += "([A-Za-z]+)";
+        break;
+      case "A":
+      case "a":
+        pattern += "([AaPp][Mm])";
+        break;
+      default:
+        pattern += "(\\d{1,2})";
+        break;
+    }
+  }
+  pattern += escapeLiteral(format.slice(lastIndex));
+
+  if (captured.length === 0) {
+    return new Date(value);
+  }
+
+  const match = new RegExp(`^${pattern}$`).exec(String(value).trim());
+  if (!match) {
+    return new Date(value);
+  }
+
+  const parts = {
+    year: 1970,
+    month: 0,
+    day: 1,
+    hours: 0,
+    minutes: 0,
+    seconds: 0,
+    pm: false,
+    hours12: false,
+  };
+
+  captured.forEach((token, idx) => {
+    const raw = match[idx + 1];
+    switch (token) {
+      case "YYYY":
+        parts.year = Number(raw);
+        break;
+      case "YY":
+        parts.year = 2000 + Number(raw);
+        break;
+      case "MMMM":
+      case "MMM": {
+        const month = MONTHS.findIndex((name) =>
+          name.toLowerCase().startsWith(raw.toLowerCase()),
+        );
+        if (month >= 0) {
+          parts.month = month;
+        }
+        break;
+      }
+      case "MM":
+      case "M":
+        parts.month = Number(raw) - 1;
+        break;
+      case "DD":
+      case "D":
+        parts.day = Number(raw);
+        break;
+      case "HH":
+      case "H":
+        parts.hours = Number(raw);
+        break;
+      case "hh":
+      case "h":
+        parts.hours = Number(raw);
+        parts.hours12 = true;
+        break;
+      case "mm":
+      case "m":
+        parts.minutes = Number(raw);
+        break;
+      case "ss":
+      case "s":
+        parts.seconds = Number(raw);
+        break;
+      case "A":
+      case "a":
+        parts.pm = raw.toLowerCase() === "pm";
+        break;
+      default:
+        break;
+    }
+  });
+
+  if (parts.hours12) {
+    parts.hours = (parts.hours % 12) + (parts.pm ? 12 : 0);
+  }
+
+  return new Date(
+    parts.year,
+    parts.month,
+    parts.day,
+    parts.hours,
+    parts.minutes,
+    parts.seconds,
+  );
+}
+
+function uuidV7(): string {
+  const bytes = new Uint8Array(16);
+  for (let i = 0; i < bytes.length; i += 1) {
+    bytes[i] = Math.floor(Math.random() * 256);
+  }
+
+  const timestamp = Date.now();
+  bytes[0] = (timestamp / 2 ** 40) & 0xff;
+  bytes[1] = (timestamp / 2 ** 32) & 0xff;
+  bytes[2] = (timestamp / 2 ** 24) & 0xff;
+  bytes[3] = (timestamp / 2 ** 16) & 0xff;
+  bytes[4] = (timestamp / 2 ** 8) & 0xff;
+  bytes[5] = timestamp & 0xff;
+  bytes[6] = (bytes[6] & 0x0f) | 0x70; // version 7
+  bytes[8] = (bytes[8] & 0x3f) | 0x80; // variant
+
+  const hex = [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+// A predicate for find/filter is itself an expression string. It is parsed
+// once per call and evaluated per element with `item`/`index` in scope, since
+// the expression dialect has no lambdas. `params` is deliberately not in
+// scope: the browser's predicate does not bind it either, and a predicate that
+// works in one runtime and not the other is worse than one that is merely
+// narrow.
+function itemPredicate(predicate: string) {
+  const ast = parse(predicate);
+  return (item: unknown, index: number) =>
+    !!evaluateAst(ast, { item, index, ...globalScope });
+}
+
+export const globalScope: Record<string, unknown> = {
+  print: console.log,
+  log: console.log,
+  round: Math.round,
+  sin: Math.sin,
+  min: Math.min,
+  max: Math.max,
+  rand: Math.random,
+  number: (x: string | number) => Number(x),
+  string: (x: number | string) => `${x}`,
+  stringify: JSON.stringify,
+  parse: (x: string | undefined) =>
+    x !== undefined ? JSON.parse(x) : "<parse undefined>",
+  concat: (...args: string[]) => args.join(""),
+  // An array's elements as one text, e.g. the parts a gather collected:
+  // join(params.items, ''). An empty element is nothing, as Array.join has it.
+  join: (arr: unknown, separator?: string) =>
+    Array.isArray(arr)
+      ? arr.join(separator ?? "")
+      : arr === null || arr === undefined
+        ? ""
+        : `${arr}`,
+  reformatDate: (date: string, inputFormat: string, outputFormat: string) =>
+    formatDate(parseDate(date, inputFormat), outputFormat),
+  formatNow: (format: string) => formatDate(new Date(), format),
+  find: (arr: unknown, predicate: string) =>
+    Array.isArray(arr) ? arr.find(itemPredicate(predicate)) : undefined,
+  filter: (arr: unknown, predicate: string) =>
+    Array.isArray(arr) ? arr.filter(itemPredicate(predicate)) : [],
+  isFuture: (ts: string | number | null | undefined) =>
+    ts != null && new Date(ts).getTime() >= Date.now(),
+  isPast: (ts: string | number | null | undefined) =>
+    ts != null && new Date(ts).getTime() < Date.now(),
+  encodeURI,
+  slice: (arr: unknown[], offset: number, step: number, end: number) =>
+    arr.slice(offset, end).filter((_, i) => i % step === 0),
+  sum: (x: number[]) => (x && x.reduce ? x.reduce((acc, v) => acc + v, 0) : x),
+  flatSum: (x: unknown[]) =>
+    x && x.flat
+      ? (x.flat() as number[]).reduce((acc: number, v: number) => acc + v, 0)
+      : 0,
+  at: (arr: unknown[], i: number) => arr[Math.abs(Math.round(i)) % arr.length],
+  now: () => Date.now(),
+  range: (n: number) =>
+    Array.from({ length: Math.max(0, Math.round(n)) }, (_, i) => i),
+  avg: (x: number[]) =>
+    x && x.reduce ? x.reduce((acc, v) => acc + v, 0) / x.length : x,
+  slug: (x: string | number) =>
+    String(x)
+      .toLowerCase()
+      .replace(/[^a-z0-9_-]/g, ""),
+  withoutUrls: (x: unknown) => withoutUrls(x),
+  uuid: {
+    v4: randomUUID,
+    v7: uuidV7,
+  },
+};
+
+/**
+ * A web address in running text, with whatever label introduced it.
+ *
+ * The label goes because it is only there to introduce the address: "Article
+ * URL:" with nothing after it says less than nothing. Bounded to a short run of
+ * words so it cannot swallow a sentence.
+ */
+const URL_IN_TEXT = /(?:[A-Za-z][\w ]{0,30}:[ \t]*)?(?:https?:\/\/|www\.)\S+/gi;
+
+/**
+ * Text with the web addresses taken out of it.
+ *
+ * Feeds are written for programs as much as for people, and some of them are
+ * mostly machinery: a summary that reads "Article URL: https://… Comments URL:
+ * https://… Points: 48" is a fine thing for a reader to show as a link and a
+ * miserable thing to hear read aloud, where an address becomes a minute of
+ * punctuation. This is for text on its way to something that speaks or
+ * summarises it — never for what a board stores or publishes, where the address
+ * is the useful part.
+ */
+export function withoutUrls(value: unknown): string {
+  return String(value ?? "")
+    .replace(URL_IN_TEXT, " ")
+    // What removal leaves behind: doubled spaces, and punctuation adrift from
+    // the word it belonged to.
+    .replace(/[ \t]{2,}/g, " ")
+    .replace(/\s+([.,;:!?])/g, "$1")
+    .trim();
+}
+
+/**
+ * Compiles an expression source into a callable. Non-string sources are
+ * constants and are returned as-is; a source that does not parse throws when
+ * called and carries `parseError`, so the caller decides how a broken term is
+ * reported.
+ *
+ * Parsing happens once, evaluation once per pass — the same split the old
+ * `new Function` had, so a template still costs one compile and not one per
+ * input.
+ */
+export function compileExpression(source: unknown): CompiledExpression {
+  if (typeof source !== "string") {
+    return () => source;
+  }
+
+  let ast: ReturnType<typeof parse>;
+  try {
+    ast = parse(source);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const parseError = `invalid expression '${source}': ${message}`;
+    return Object.assign(
+      () => {
+        throw new Error(parseError);
+      },
+      { parseError },
+    );
+  }
+
+  // `params` names the input, and the helpers sit beside it — the same scope
+  // the browser builds, so the same term resolves the same names.
+  return (params: unknown, onMissing?: OnMissing) =>
+    evaluateAst(ast, { params, ...globalScope }, onMissing);
+}