@telorun/templating 0.4.1 → 0.6.0

package/src/cel/catalog.ts

@@ -0,0 +1,540 @@
+import { v1, v3, v4, v5, v6, v7, validate as uuidValidate, version as uuidVersion } from "uuid";
+
+/** Host-injected functions that need platform APIs the templating package must
+ *  not import directly (Node `crypto` / `Buffer`), keeping it browser-safe. The
+ *  kernel supplies real implementations; the analyzer omits them (the stubs
+ *  throw, since static analysis never executes these). */
+export interface CelHandlers {
+  sha256: (s: string) => string;
+  md5: (s: string) => string;
+  sha1: (s: string) => string;
+  sha512: (s: string) => string;
+  hmac: (algorithm: string, key: string, message: string) => string;
+  base64Encode: (s: string) => string;
+  base64Decode: (s: string) => string;
+  json: (value: unknown) => string;
+}
+
+export type CelFunctionCategory =
+  | "conversion"
+  | "time"
+  | "uuid"
+  | "string"
+  | "math"
+  | "collection"
+  | "json"
+  | "encoding"
+  | "hashing"
+  | "null";
+
+/** One entry in the CEL standard library — the single source of truth that both
+ *  registers the function (`build`) and documents it (everything else). `telo
+ *  cel functions` and `celFunctionCatalog()` read the metadata; `buildCelEnvironment`
+ *  calls `build`. */
+export interface CelFunctionDoc {
+  /** Bare function name (`nowIso`, `uuidv4`). */
+  readonly name: string;
+  /** Human-facing signature for docs (`nowIso(tz?): string`). May use `?` for
+   *  optional args even though cel-js itself has no optional syntax. */
+  readonly signature: string;
+  /** Actual cel-js signatures to register — one per arity for an overloaded
+   *  function. Defaults to `[signature]` when omitted (the common single-arity
+   *  case, where `signature` is itself a valid cel-js signature). */
+  readonly register?: readonly string[];
+  readonly category: CelFunctionCategory;
+  readonly summary: string;
+  /** False → re-evaluates per call; in an `x-telo-eval: compile` field it bakes
+   *  once at load. */
+  readonly deterministic: boolean;
+  /** Needs a `CelHandlers` implementation (Node `crypto` / `Buffer`); the
+   *  analyzer's stub throws if such a function is actually evaluated. */
+  readonly hostBacked: boolean;
+  readonly build: (h: CelHandlers) => (...args: any[]) => unknown;
+}
+
+/** Public, build-free view of a catalog entry (for `--json` / docs). */
+export type CelFunctionInfo = Omit<CelFunctionDoc, "build">;
+
+const num = (x: unknown): number => Number(x);
+
+const minMax = (list: unknown[], isMin: boolean): unknown => {
+  if (!Array.isArray(list) || list.length === 0) return null;
+  let best = list[0];
+  let bestN = num(best);
+  for (const x of list) {
+    const n = num(x);
+    if (isMin ? n < bestN : n > bestN) {
+      best = x;
+      bestN = n;
+    }
+  }
+  return best;
+};
+
+const sortList = (list: unknown[]): unknown[] =>
+  [...list].sort((a, b) => {
+    if (typeof a === "number" || typeof a === "bigint") {
+      const d = num(a) - num(b);
+      return d < 0 ? -1 : d > 0 ? 1 : 0;
+    }
+    return String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0;
+  });
+
+/** `Intl.DateTimeFormat` is an ECMA-402 global in Node (full ICU) and browsers,
+ *  so timezone handling needs no Node-only API and stays browser-safe. */
+const zoneParts = (date: Date, tz: string, opts: Intl.DateTimeFormatOptions): Record<string, string> => {
+  const parts: Record<string, string> = {};
+  for (const p of new Intl.DateTimeFormat("en-US", { timeZone: tz, ...opts }).formatToParts(date)) {
+    parts[p.type] = p.value;
+  }
+  return parts;
+};
+
+/** Current instant as ISO-8601 in `tz`: UTC `…Z` for "UTC", else the zone's
+ *  offset (e.g. `2026-06-06T18:30:00.000-05:00`). Uses only standard Intl
+ *  fields and derives the offset arithmetically, so it needs no newer Intl
+ *  type-lib features and stays portable. */
+const isoInZone = (tz: string): string => {
+  const now = new Date();
+  if (tz === "UTC" || tz === "Z") return now.toISOString();
+  const p = zoneParts(now, tz, {
+    hourCycle: "h23",
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+  });
+  // Sub-second is timezone-independent; read it off the instant directly.
+  const ms = String(now.getUTCMilliseconds()).padStart(3, "0");
+  // Offset = the zone's wall-clock read as UTC, minus the real instant.
+  const asUtc = Date.UTC(+p.year, +p.month - 1, +p.day, +p.hour, +p.minute, +p.second);
+  const offsetMin = Math.round((asUtc - now.getTime()) / 60000);
+  const offset =
+    offsetMin === 0
+      ? "Z"
+      : `${offsetMin > 0 ? "+" : "-"}${String(Math.floor(Math.abs(offsetMin) / 60)).padStart(2, "0")}:${String(Math.abs(offsetMin) % 60).padStart(2, "0")}`;
+  return `${p.year}-${p.month}-${p.day}T${p.hour}:${p.minute}:${p.second}.${ms}${offset}`;
+};
+
+/** Current calendar date (`YYYY-MM-DD`) in `tz`. */
+const dateInZone = (tz: string): string => {
+  const now = new Date();
+  if (tz === "UTC" || tz === "Z") return now.toISOString().slice(0, 10);
+  const p = zoneParts(now, tz, { year: "numeric", month: "2-digit", day: "2-digit" });
+  return `${p.year}-${p.month}-${p.day}`;
+};
+
+export const CEL_FUNCTIONS: readonly CelFunctionDoc[] = [
+  // Collections
+  {
+    name: "join",
+    signature: "join(list, string): string",
+    category: "collection",
+    summary: "Join list elements into a string with a separator.",
+    deterministic: true,
+    hostBacked: false,
+    build: () => (list: unknown[], sep: string) => list.map(String).join(sep),
+  },
+  {
+    name: "keys",
+    signature: "keys(map): list",
+    category: "collection",
+    summary: "List a map's keys.",
+    deterministic: true,
+    hostBacked: false,
+    build: () => (map: unknown) =>
+      map instanceof Map ? [...map.keys()] : Object.keys(map as Record<string, unknown>),
+  },
+  {
+    name: "values",
+    signature: "values(map): list",
+    category: "collection",
+    summary: "List a map's values.",
+    deterministic: true,
+    hostBacked: false,
+    build: () => (map: unknown) =>
+      map instanceof Map ? [...map.values()] : Object.values(map as Record<string, unknown>),
+  },
+  {
+    name: "distinct",
+    signature: "distinct(list): list",
+    category: "collection",
+    summary: "Remove duplicate elements, preserving order.",
+    deterministic: true,
+    hostBacked: false,
+    build: () => (list: unknown[]) => [...new Set(list)],
+  },
+  {
+    name: "reverse",
+    signature: "reverse(list): list",
+    category: "collection",
+    summary: "Reverse a list (copy; never mutates the input).",
+    deterministic: true,
+    hostBacked: false,
+    build: () => (list: unknown[]) => [...list].reverse(),
+  },
+  {
+    name: "flatten",
+    signature: "flatten(list): list",
+    category: "collection",
+    summary: "Flatten one level of nested lists.",
+    deterministic: true,
+    hostBacked: false,
+    build: () => (list: unknown[]) => list.flat(),
+  },
+  {
+    name: "sort",
+    signature: "sort(list): list",
+    category: "collection",
+    summary: "Sort a list numerically (numbers) or lexicographically; copy.",
+    deterministic: true,
+    hostBacked: false,
+    build: () => (list: unknown[]) => sortList(list),
+  },
+  // Strings
+  {
+    name: "lower",
+    signature: "lower(string): string",
+    category: "string",
+    summary: "Lowercase a string.",
+    deterministic: true,
+    hostBacked: false,
+    build: () => (s: string) => s.toLowerCase(),
+  },
+  {
+    name: "upper",
+    signature: "upper(string): string",
+    category: "string",
+    summary: "Uppercase a string.",
+    deterministic: true,
+    hostBacked: false,
+    build: () => (s: string) => s.toUpperCase(),
+  },
+  {
+    name: "trim",
+    signature: "trim(string): string",
+    category: "string",
+    summary: "Strip leading/trailing whitespace.",
+    deterministic: true,
+    hostBacked: false,
+    build: () => (s: string) => s.trim(),
+  },
+  {
+    name: "replace",
+    signature: "replace(string, string, string): string",
+    category: "string",
+    summary: "Replace all occurrences of a substring.",
+    deterministic: true,
+    hostBacked: false,
+    build: () => (s: string, a: string, b: string) => s.split(a).join(b),
+  },
+  {
+    name: "split",
+    signature: "split(string, string): list",
+    category: "string",
+    summary: "Split a string on a separator into a list.",
+    deterministic: true,
+    hostBacked: false,
+    build: () => (s: string, sep: string) => s.split(sep),
+  },
+  // Math
+  {
+    name: "abs",
+    signature: "abs(dyn): double",
+    category: "math",
+    summary: "Absolute value.",
+    deterministic: true,
+    hostBacked: false,
+    build: () => (x: unknown) => Math.abs(num(x)),
+  },
+  {
+    name: "floor",
+    signature: "floor(dyn): double",
+    category: "math",
+    summary: "Round down to an integer.",
+    deterministic: true,
+    hostBacked: false,
+    build: () => (x: unknown) => Math.floor(num(x)),
+  },
+  {
+    name: "ceil",
+    signature: "ceil(dyn): double",
+    category: "math",
+    summary: "Round up to an integer.",
+    deterministic: true,
+    hostBacked: false,
+    build: () => (x: unknown) => Math.ceil(num(x)),
+  },
+  {
+    name: "round",
+    signature: "round(dyn): double",
+    category: "math",
+    summary: "Round to the nearest integer.",
+    deterministic: true,
+    hostBacked: false,
+    build: () => (x: unknown) => Math.round(num(x)),
+  },
+  {
+    name: "min",
+    signature: "min(list): dyn",
+    category: "math",
+    summary: "Smallest element (by numeric value); null for an empty list.",
+    deterministic: true,
+    hostBacked: false,
+    build: () => (list: unknown[]) => minMax(list, true),
+  },
+  {
+    name: "max",
+    signature: "max(list): dyn",
+    category: "math",
+    summary: "Largest element (by numeric value); null for an empty list.",
+    deterministic: true,
+    hostBacked: false,
+    build: () => (list: unknown[]) => minMax(list, false),
+  },
+  // JSON
+  {
+    name: "json",
+    signature: "json(dyn): string",
+    category: "json",
+    summary: "Serialize any value to a JSON string.",
+    deterministic: true,
+    hostBacked: true,
+    build: (h) => (value: unknown) => h.json(value),
+  },
+  {
+    name: "parseJson",
+    signature: "parseJson(string): dyn",
+    category: "json",
+    summary: "Parse a JSON string into a value (numbers come back as doubles).",
+    deterministic: true,
+    hostBacked: false,
+    build: () => (s: string) => JSON.parse(s),
+  },
+  // Encoding
+  {
+    name: "base64Encode",
+    signature: "base64Encode(string): string",
+    category: "encoding",
+    summary: "Encode a UTF-8 string as base64.",
+    deterministic: true,
+    hostBacked: true,
+    build: (h) => (s: string) => h.base64Encode(s),
+  },
+  {
+    name: "base64Decode",
+    signature: "base64Decode(string): string",
+    category: "encoding",
+    summary: "Decode a base64 string to UTF-8.",
+    deterministic: true,
+    hostBacked: true,
+    build: (h) => (s: string) => h.base64Decode(s),
+  },
+  {
+    name: "urlEncode",
+    signature: "urlEncode(string): string",
+    category: "encoding",
+    summary: "Percent-encode a URI component.",
+    deterministic: true,
+    hostBacked: false,
+    build: () => (s: string) => encodeURIComponent(s),
+  },
+  {
+    name: "urlDecode",
+    signature: "urlDecode(string): string",
+    category: "encoding",
+    summary: "Decode a percent-encoded URI component.",
+    deterministic: true,
+    hostBacked: false,
+    build: () => (s: string) => decodeURIComponent(s),
+  },
+  // Hashing
+  {
+    name: "sha256",
+    signature: "sha256(string): string",
+    category: "hashing",
+    summary: "SHA-256 hash, hex-encoded.",
+    deterministic: true,
+    hostBacked: true,
+    build: (h) => (s: string) => h.sha256(s),
+  },
+  {
+    name: "md5",
+    signature: "md5(string): string",
+    category: "hashing",
+    summary: "MD5 hash, hex-encoded.",
+    deterministic: true,
+    hostBacked: true,
+    build: (h) => (s: string) => h.md5(s),
+  },
+  {
+    name: "sha1",
+    signature: "sha1(string): string",
+    category: "hashing",
+    summary: "SHA-1 hash, hex-encoded.",
+    deterministic: true,
+    hostBacked: true,
+    build: (h) => (s: string) => h.sha1(s),
+  },
+  {
+    name: "sha512",
+    signature: "sha512(string): string",
+    category: "hashing",
+    summary: "SHA-512 hash, hex-encoded.",
+    deterministic: true,
+    hostBacked: true,
+    build: (h) => (s: string) => h.sha512(s),
+  },
+  {
+    name: "hmac",
+    signature: "hmac(string, string, string): string",
+    category: "hashing",
+    summary: "HMAC of message under key for an algorithm (e.g. 'sha256'), hex.",
+    deterministic: true,
+    hostBacked: true,
+    build: (h) => (algo: string, key: string, msg: string) => h.hmac(algo, key, msg),
+  },
+  // Null handling
+  {
+    name: "default",
+    signature: "default(dyn, dyn): dyn",
+    category: "null",
+    summary: "Return the value, or the fallback when it is null.",
+    deterministic: true,
+    hostBacked: false,
+    build: () => (v: unknown, fallback: unknown) =>
+      v === null || v === undefined ? fallback : v,
+  },
+  {
+    name: "coalesce",
+    signature: "coalesce(list): dyn",
+    category: "null",
+    summary: "First non-null element of a list, or null.",
+    deterministic: true,
+    hostBacked: false,
+    build: () => (list: unknown[]) => {
+      const found = list.find((x) => x !== null && x !== undefined);
+      return found === undefined ? null : found;
+    },
+  },
+  // Time (non-deterministic). `nowIso`/`today` take an optional IANA timezone
+  // (default "UTC"); epoch values are absolute and take none.
+  {
+    name: "nowIso",
+    signature: "nowIso(tz?): string",
+    register: ["nowIso(): string", "nowIso(string): string"],
+    category: "time",
+    summary: "Current time as ISO-8601; UTC by default, or in the given IANA timezone.",
+    deterministic: false,
+    hostBacked: false,
+    build: () => (tz?: string) => isoInZone(tz ?? "UTC"),
+  },
+  {
+    name: "today",
+    signature: "today(tz?): string",
+    register: ["today(): string", "today(string): string"],
+    category: "time",
+    summary: "Current calendar date (YYYY-MM-DD); UTC by default, or in the given IANA timezone.",
+    deterministic: false,
+    hostBacked: false,
+    build: () => (tz?: string) => dateInZone(tz ?? "UTC"),
+  },
+  {
+    name: "nowMillis",
+    signature: "nowMillis(): int",
+    category: "time",
+    summary: "Current time as epoch milliseconds (absolute; timezone-independent).",
+    deterministic: false,
+    hostBacked: false,
+    build: () => () => BigInt(Date.now()),
+  },
+  {
+    name: "nowSeconds",
+    signature: "nowSeconds(): int",
+    category: "time",
+    summary: "Current time as epoch seconds (absolute; timezone-independent).",
+    deterministic: false,
+    hostBacked: false,
+    build: () => () => BigInt(Math.floor(Date.now() / 1000)),
+  },
+  // UUID
+  {
+    name: "uuidv1",
+    signature: "uuidv1(): string",
+    category: "uuid",
+    summary: "Time-based UUID (v1).",
+    deterministic: false,
+    hostBacked: false,
+    build: () => () => v1(),
+  },
+  {
+    name: "uuidv4",
+    signature: "uuidv4(): string",
+    category: "uuid",
+    summary: "Random UUID (v4).",
+    deterministic: false,
+    hostBacked: false,
+    build: () => () => v4(),
+  },
+  {
+    name: "uuidv6",
+    signature: "uuidv6(): string",
+    category: "uuid",
+    summary: "Time-ordered UUID (v6).",
+    deterministic: false,
+    hostBacked: false,
+    build: () => () => v6(),
+  },
+  {
+    name: "uuidv7",
+    signature: "uuidv7(): string",
+    category: "uuid",
+    summary: "Time-ordered UUID (v7).",
+    deterministic: false,
+    hostBacked: false,
+    build: () => () => v7(),
+  },
+  {
+    name: "uuidv3",
+    signature: "uuidv3(string, string): string",
+    category: "uuid",
+    summary: "Name-based UUID (v3, MD5) under a namespace UUID.",
+    deterministic: true,
+    hostBacked: false,
+    build: () => (name: string, ns: string) => v3(name, ns),
+  },
+  {
+    name: "uuidv5",
+    signature: "uuidv5(string, string): string",
+    category: "uuid",
+    summary: "Name-based UUID (v5, SHA-1) under a namespace UUID.",
+    deterministic: true,
+    hostBacked: false,
+    build: () => (name: string, ns: string) => v5(name, ns),
+  },
+  {
+    name: "uuidValidate",
+    signature: "uuidValidate(string): bool",
+    category: "uuid",
+    summary: "True if the string is a valid UUID.",
+    deterministic: true,
+    hostBacked: false,
+    build: () => (s: string) => uuidValidate(s),
+  },
+  {
+    name: "uuidVersion",
+    signature: "uuidVersion(string): int",
+    category: "uuid",
+    summary: "The version number of a UUID.",
+    deterministic: true,
+    hostBacked: false,
+    build: () => (s: string) => BigInt(uuidVersion(s)),
+  },
+];
+
+/** Build-free catalog for the CLI / docs (`telo cel functions`). */
+export function celFunctionCatalog(): CelFunctionInfo[] {
+  return CEL_FUNCTIONS.map(({ build: _build, ...info }) => info);
+}

package/src/cel/compile.ts

@@ -1,4 +1,4 @@
-import type { CompiledValue } from "@telorun/sdk";
+import { isCompiledValue, type CompiledValue } from "@telorun/sdk";
 import type { Environment } from "@marcbachmann/cel-js";
 
 export const TEMPLATE_REGEX = /\$\{\{\s*([^}]+?)\s*\}\}/g;
@@ -41,7 +41,45 @@ export function compileString(s: string, env: Environment): unknown {
   return {
     __compiled: true,
     source: s,
+    parts,
     call: (ctx: Record<string, unknown>) =>
       parts.map((p) => (typeof p === "string" ? p : String(p.call(ctx) ?? ""))).join(""),
   } satisfies CompiledValue;
 }
+
+/** Split an interpolated value into literal fragments and the evaluated values
+ *  of its embedded expressions, instead of joining them into one string. Lets a
+ *  consumer emit its own placeholders between fragments and bind the values
+ *  separately (e.g. parameterized SQL). The invariant
+ *  `fragments.length === values.length + 1` always holds.
+ *
+ *  - plain string (no `${{ }}`)        → `{ fragments: [s], values: [] }`
+ *  - bare single expression `${{ x }}` → `{ fragments: ["", ""], values: [x] }`
+ *  - interpolated `"a ${{ x }} b"`     → `{ fragments: ["a ", " b"], values: [x] }`
+ */
+export function toParameterized(
+  value: unknown,
+  ctx: Record<string, unknown>,
+): { fragments: string[]; values: unknown[] } {
+  if (typeof value === "string") return { fragments: [value], values: [] };
+  if (!isCompiledValue(value)) {
+    throw new Error("toParameterized expects a string or CompiledValue");
+  }
+  if (!value.parts) {
+    return { fragments: ["", ""], values: [value.call(ctx)] };
+  }
+  const fragments: string[] = [];
+  const values: unknown[] = [];
+  let current = "";
+  for (const p of value.parts) {
+    if (typeof p === "string") {
+      current += p;
+    } else {
+      fragments.push(current);
+      current = "";
+      values.push(p.call(ctx));
+    }
+  }
+  fragments.push(current);
+  return { fragments, values };
+}

package/src/cel/environment.ts

@@ -1,10 +1,8 @@
 import { Environment } from "@marcbachmann/cel-js";
 import { Stream } from "@telorun/sdk";
+import { CEL_FUNCTIONS, type CelHandlers } from "./catalog.js";
 
-export interface CelHandlers {
-  sha256: (s: string) => string;
-  json: (value: unknown) => string;
-}
+export type { CelHandlers } from "./catalog.js";
 
 const stub = (name: string) => () => {
   throw new Error(
@@ -15,13 +13,22 @@ const stub = (name: string) => () => {
 
 const STUB_HANDLERS: CelHandlers = {
   sha256: stub("sha256"),
+  md5: stub("md5"),
+  sha1: stub("sha1"),
+  sha512: stub("sha512"),
+  hmac: stub("hmac"),
+  base64Encode: stub("base64Encode"),
+  base64Decode: stub("base64Decode"),
   json: stub("json"),
 };
 
-/** Build a CEL `Environment` with Telo's stdlib of functions. Always registers the
- *  same function signatures (so `env.check()` succeeds for type-inference) — the
- *  handlers govern what the function does when called at runtime. Analyzer-only
- *  callers can omit handlers; runtime callers (kernel) must supply real ones.
+/** Build a CEL `Environment` with Telo's stdlib. Every function comes from the
+ *  single-source catalog (`CEL_FUNCTIONS`), so registration and the documented
+ *  surface (`telo cel functions`) can never drift. Always registers the same
+ *  signatures (so `env.check()` succeeds for type-inference); the host-injected
+ *  handlers govern what `hostBacked` functions do at runtime. Analyzer-only
+ *  callers can omit handlers (the stubs throw if such a function is evaluated);
+ *  runtime callers (kernel) supply real ones.
  *
  *  Also registers the `Stream` object type, backed by the `Stream` class from
  *  `@telorun/sdk`. CEL's type-checker rejects values whose constructor isn't
@@ -31,20 +38,16 @@ const STUB_HANDLERS: CelHandlers = {
  *  no fields, so terminal access (passing the value through CEL) succeeds but
  *  member access raises a CEL error at runtime — matching the analyzer's
  *  static check on `x-telo-stream`-marked properties. */
-export function buildCelEnvironment(handlers: CelHandlers = STUB_HANDLERS): Environment {
-  return new Environment({ unlistedVariablesAreDyn: true, enableOptionalTypes: true })
-    .registerFunction("join(list, string): string", (list: unknown[], sep: string) =>
-      list.map(String).join(sep),
-    )
-    .registerFunction("keys(map): list", (map: unknown) => {
-      if (map instanceof Map) return [...map.keys()];
-      return Object.keys(map as Record<string, unknown>);
-    })
-    .registerFunction("values(map): list", (map: unknown) => {
-      if (map instanceof Map) return [...map.values()];
-      return Object.values(map as Record<string, unknown>);
-    })
-    .registerFunction("sha256(string): string", (s: string) => handlers.sha256(s))
-    .registerFunction("json(dyn): string", (value: unknown) => handlers.json(value))
-    .registerType("Stream", Stream as unknown as new (...args: unknown[]) => unknown);
+export function buildCelEnvironment(handlers: Partial<CelHandlers> = {}): Environment {
+  const h: CelHandlers = { ...STUB_HANDLERS, ...handlers };
+  let env = new Environment({ unlistedVariablesAreDyn: true, enableOptionalTypes: true });
+  for (const fn of CEL_FUNCTIONS) {
+    const impl = fn.build(h);
+    // `register` lists one cel-js signature per arity (overloaded functions);
+    // it falls back to `signature` for the single-arity common case.
+    for (const sig of fn.register ?? [fn.signature]) {
+      env = env.registerFunction(sig, impl);
+    }
+  }
+  return env.registerType("Stream", Stream as unknown as new (...args: unknown[]) => unknown);
 }