@objectstack/formula 7.5.0 → 7.7.0

package/dist/index.js

@@ -20,20 +20,25 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  CEL_STDLIB_FUNCTIONS: () => CEL_STDLIB_FUNCTIONS,
   DEFAULT_LIMITS: () => DEFAULT_LIMITS,
   ExpressionEngine: () => ExpressionEngine,
+  TEMPLATE_FORMATTERS: () => TEMPLATE_FORMATTERS,
   buildScope: () => buildScope,
   celEngine: () => celEngine,
   cronEngine: () => cronEngine,
+  expectedDialect: () => expectedDialect,
   getEngine: () => getEngine,
   hasDialect: () => hasDialect,
+  introspectScope: () => introspectScope,
   normalizeExpression: () => normalizeExpression,
   normalizeExpressionTree: () => normalizeExpressionTree,
   register: () => register,
   registerStdLib: () => registerStdLib,
   resolveSeed: () => resolveSeed,
   resolveSeedRecord: () => resolveSeedRecord,
-  templateEngine: () => templateEngine
+  templateEngine: () => templateEngine,
+  validateExpression: () => validateExpression
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -138,6 +143,28 @@ function coerce(value) {
   }
   return value;
 }
+var NUMERIC_STRING_RE = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
+function isNumericOverloadError(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  return /no such overload/i.test(message);
+}
+function hydrateNumericStrings(value) {
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (trimmed.length > 0 && NUMERIC_STRING_RE.test(trimmed)) {
+      const n = Number(trimmed);
+      if (Number.isFinite(n)) return n;
+    }
+    return value;
+  }
+  if (Array.isArray(value)) return value.map(hydrateNumericStrings);
+  if (value && typeof value === "object" && !(value instanceof Date)) {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = hydrateNumericStrings(v);
+    return out;
+  }
+  return value;
+}
 function classifyError(err) {
   const message = err instanceof Error ? err.message : String(err);
   let kind = "runtime";
@@ -182,8 +209,19 @@ var celEngine = {
     try {
       const env = buildEnv(now);
       const scope = buildScope(ctx);
-      const raw = env.evaluate(source, scope);
-      return { ok: true, value: coerce(raw) };
+      try {
+        const raw = env.evaluate(source, scope);
+        return { ok: true, value: coerce(raw) };
+      } catch (err) {
+        if (!isNumericOverloadError(err)) throw err;
+        const hydrated = hydrateNumericStrings(scope);
+        try {
+          const raw = env.evaluate(source, hydrated);
+          return { ok: true, value: coerce(raw) };
+        } catch {
+          throw err;
+        }
+      }
     } catch (err) {
       return classifyError(err);
     }
@@ -260,18 +298,96 @@ var cronEngine = {
 };
 
 // src/template-engine.ts
-var PATH_RE = /\{\{\s*([\w.[\]]+?)\s*\}\}/g;
-function resolvePath(scope, path) {
-  const normalized = path.replace(/\[(\w+)\]/g, ".$1");
-  const segments = normalized.split(".").filter(Boolean);
-  let cursor = scope;
-  for (const seg of segments) {
-    if (cursor == null || typeof cursor !== "object") return void 0;
-    cursor = cursor[seg];
+var HOLE_RE = /\{\{([^}]*)\}\}/g;
+function asNumber(v) {
+  if (typeof v === "number") return v;
+  if (typeof v === "bigint") return Number(v);
+  if (typeof v === "string" && v.trim() !== "" && !Number.isNaN(Number(v))) return Number(v);
+  return void 0;
+}
+function asDate(v) {
+  if (v instanceof Date) return v;
+  if (typeof v === "number") return new Date(v);
+  if (typeof v === "string") {
+    const d = new Date(v);
+    if (!Number.isNaN(d.getTime())) return d;
   }
-  return cursor;
+  return void 0;
 }
-function stringify(value) {
+var FORMATTERS = {
+  upper: (v) => baseString(v).toUpperCase(),
+  lower: (v) => baseString(v).toLowerCase(),
+  trim: (v) => baseString(v).trim(),
+  // number | number:2  → grouped, optional fixed decimals
+  number: (v, arg, locale) => {
+    const n = asNumber(v);
+    if (n === void 0) return baseString(v);
+    const digits = arg !== void 0 ? Number(arg) : void 0;
+    return new Intl.NumberFormat(locale, digits !== void 0 && !Number.isNaN(digits) ? { minimumFractionDigits: digits, maximumFractionDigits: digits } : {}).format(n);
+  },
+  // currency | currency:EUR  → defaults to USD
+  currency: (v, arg, locale) => {
+    const n = asNumber(v);
+    if (n === void 0) return baseString(v);
+    const code = arg && arg.trim() || "USD";
+    try {
+      return new Intl.NumberFormat(locale, { style: "currency", currency: code }).format(n);
+    } catch {
+      return new Intl.NumberFormat(locale, { style: "currency", currency: "USD" }).format(n);
+    }
+  },
+  // percent | percent:1  → 0.42 → "42%" (value is a 0..1 ratio)
+  percent: (v, arg, locale) => {
+    const n = asNumber(v);
+    if (n === void 0) return baseString(v);
+    const digits = arg !== void 0 ? Number(arg) : 0;
+    return new Intl.NumberFormat(locale, {
+      style: "percent",
+      minimumFractionDigits: Number.isNaN(digits) ? 0 : digits,
+      maximumFractionDigits: Number.isNaN(digits) ? 0 : digits
+    }).format(n);
+  },
+  // date | date:long | date:iso  → date-only
+  date: (v, arg, locale) => {
+    const d = asDate(v);
+    if (!d) return baseString(v);
+    if (arg === "iso") return d.toISOString().slice(0, 10);
+    const style = arg === "long" ? "long" : arg === "medium" ? "medium" : "short";
+    return new Intl.DateTimeFormat(locale, { dateStyle: style }).format(d);
+  },
+  // datetime | datetime:long | datetime:iso
+  datetime: (v, arg, locale) => {
+    const d = asDate(v);
+    if (!d) return baseString(v);
+    if (arg === "iso") return d.toISOString();
+    const style = arg === "long" ? "long" : arg === "medium" ? "medium" : "short";
+    return new Intl.DateTimeFormat(locale, {
+      dateStyle: style,
+      timeStyle: style
+    }).format(d);
+  },
+  // truncate:80  → cut with an ellipsis
+  truncate: (v, arg) => {
+    const s = baseString(v);
+    const len = arg !== void 0 ? Number(arg) : 80;
+    if (Number.isNaN(len) || s.length <= len) return s;
+    return s.slice(0, Math.max(0, len - 1)) + "\u2026";
+  },
+  // default:'N/A'  → fallback when the value is null/undefined/empty
+  default: (v, arg) => {
+    const s = baseString(v);
+    return s === "" ? arg ?? "" : s;
+  },
+  json: (v) => {
+    try {
+      return JSON.stringify(v);
+    } catch {
+      return String(v);
+    }
+  }
+};
+var TEMPLATE_FORMATTERS = Object.keys(FORMATTERS);
+function baseString(value) {
   if (value === null || value === void 0) return "";
   if (value instanceof Date) return value.toISOString();
   if (typeof value === "string") return value;
@@ -283,21 +399,59 @@ function stringify(value) {
     return String(value);
   }
 }
+function resolvePath(scope, path) {
+  const normalized = path.replace(/\[(\w+)\]/g, ".$1");
+  const segments = normalized.split(".").filter(Boolean);
+  let cursor = scope;
+  for (const seg of segments) {
+    if (cursor == null || typeof cursor !== "object") return void 0;
+    cursor = cursor[seg];
+  }
+  return cursor;
+}
+var PATH_ONLY_RE = /^[\w.[\]]+$/;
+function parseHole(inner) {
+  const pipe = inner.indexOf("|");
+  if (pipe === -1) {
+    const path2 = inner.trim();
+    return PATH_ONLY_RE.test(path2) ? { path: path2 } : null;
+  }
+  const path = inner.slice(0, pipe).trim();
+  if (!PATH_ONLY_RE.test(path)) return null;
+  const filterPart = inner.slice(pipe + 1).trim();
+  const colon = filterPart.indexOf(":");
+  let name = filterPart;
+  let arg;
+  if (colon !== -1) {
+    name = filterPart.slice(0, colon).trim();
+    arg = filterPart.slice(colon + 1).trim().replace(/^['"]|['"]$/g, "");
+  }
+  if (!FORMATTERS[name]) return null;
+  return { path, filter: { name, arg } };
+}
 function compileTemplate(source) {
-  const matches = source.match(/\{\{|\}\}/g) ?? [];
-  if (matches.length % 2 !== 0) {
-    return {
-      ok: false,
-      error: { kind: "parse", message: "template has unbalanced {{ }} delimiters" }
-    };
+  const open = (source.match(/\{\{/g) ?? []).length;
+  const close = (source.match(/\}\}/g) ?? []).length;
+  if (open !== close) {
+    return { ok: false, error: { kind: "parse", message: "template has unbalanced {{ }} delimiters" } };
   }
-  const refs = [];
+  const holes = [];
   let m;
-  PATH_RE.lastIndex = 0;
-  while ((m = PATH_RE.exec(source)) !== null) {
-    refs.push(m[1]);
+  HOLE_RE.lastIndex = 0;
+  while ((m = HOLE_RE.exec(source)) !== null) {
+    const parsed = parseHole(m[1]);
+    if (!parsed) {
+      return {
+        ok: false,
+        error: {
+          kind: "parse",
+          message: `invalid template hole \`{{ ${m[1]} }}\` \u2014 holes are a field path with an optional formatter (\`{{ record.amount | currency }}\`), not arbitrary logic. Move logic into a CEL field. Known formatters: ${TEMPLATE_FORMATTERS.join(", ")}.`
+        }
+      };
+    }
+    holes.push(parsed);
   }
-  return { ok: true, value: refs };
+  return { ok: true, value: holes };
 }
 var templateEngine = {
   dialect: "template",
@@ -312,16 +466,20 @@ var templateEngine = {
       };
     }
     if (typeof expr.source !== "string") {
-      return {
-        ok: false,
-        error: { kind: "parse", message: "template Expression.source required" }
-      };
+      return { ok: false, error: { kind: "parse", message: "template Expression.source required" } };
     }
     const check = compileTemplate(expr.source);
     if (!check.ok) return check;
     const scope = buildScope(ctx);
-    const out = expr.source.replace(PATH_RE, (_match, path) => {
-      return stringify(resolvePath(scope, path));
+    const locale = ctx.extra && typeof ctx.extra.locale === "string" && ctx.extra.locale || typeof ctx.locale === "string" && ctx.locale || "en-US";
+    const out = expr.source.replace(HOLE_RE, (_match, inner) => {
+      const parsed = parseHole(String(inner));
+      if (!parsed) return _match;
+      const value = resolvePath(scope, parsed.path);
+      if (parsed.filter) {
+        return FORMATTERS[parsed.filter.name](value, parsed.filter.arg, locale);
+      }
+      return baseString(value);
     });
     return { ok: true, value: out };
   }
@@ -487,21 +645,163 @@ function looksLikeExpression(value) {
   if (typeof v.dialect !== "string") return false;
   return import_spec2.ExpressionSchema.safeParse(v).success;
 }
+
+// src/validate.ts
+var SINGLE_BRACE_RE = /(?:^|[^{])\{\s*([A-Za-z_$][\w.$]*)\s*\}(?!\})/;
+var RECORD_REF_RE = /\b(?:record|previous)\.([A-Za-z_$][\w$]*)/g;
+function expectedDialect(role) {
+  return role === "template" ? "template" : "cel";
+}
+function toSource(input) {
+  if (input == null) return { source: "" };
+  if (typeof input === "string") return { source: input };
+  return { dialect: input.dialect, source: input.source ?? "" };
+}
+function bracesHint(source) {
+  const m = SINGLE_BRACE_RE.exec(source);
+  if (!m) return null;
+  const ref = m[1];
+  return `it looks like a \`{${ref}}\` template brace was used inside a CEL expression \u2014 \`{\u2026}\` parses as a CEL map literal and fails. Write the bare reference instead, e.g. \`${ref}\`.`;
+}
+function checkFieldExistence(source, schema, errors) {
+  if (!schema?.fields || schema.fields.length === 0) return;
+  const known = new Set(schema.fields);
+  const seen = /* @__PURE__ */ new Set();
+  let m;
+  RECORD_REF_RE.lastIndex = 0;
+  while ((m = RECORD_REF_RE.exec(source)) !== null) {
+    const field = m[1];
+    if (seen.has(field) || known.has(field)) continue;
+    seen.add(field);
+    const suggestion = nearest(field, schema.fields);
+    errors.push({
+      source,
+      message: `unknown field \`${field}\`${schema.objectName ? ` on \`${schema.objectName}\`` : ""}` + (suggestion ? ` \u2014 did you mean \`${suggestion}\`?` : "")
+    });
+  }
+}
+function nearest(name, candidates) {
+  let best;
+  let bestD = Infinity;
+  for (const c of candidates) {
+    const d = levenshtein(name, c);
+    if (d < bestD) {
+      bestD = d;
+      best = c;
+    }
+  }
+  return bestD <= Math.max(2, Math.floor(name.length / 3)) ? best : void 0;
+}
+function levenshtein(a, b) {
+  const m = a.length, n = b.length;
+  const dp = Array.from({ length: m + 1 }, (_, i) => i);
+  for (let j = 1; j <= n; j++) {
+    let prev = dp[0];
+    dp[0] = j;
+    for (let i = 1; i <= m; i++) {
+      const tmp = dp[i];
+      dp[i] = Math.min(dp[i] + 1, dp[i - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+      prev = tmp;
+    }
+  }
+  return dp[m];
+}
+function validateExpression(role, input, schema) {
+  const { dialect, source } = toSource(input);
+  const errors = [];
+  if (!source.trim()) return { ok: true, errors };
+  if (role === "template") {
+    if (dialect && dialect !== "template") {
+      errors.push({ source, message: `expected a text template but got a \`${dialect}\` expression.` });
+      return { ok: false, errors };
+    }
+    const compiled2 = templateEngine.compile(source);
+    if (!compiled2.ok) {
+      errors.push({ source, message: `invalid template: ${compiled2.error.message} (holes use \`{{ path }}\`).` });
+    }
+    const hint = SINGLE_BRACE_RE.test(source) ? bracesHintForTemplate(source) : null;
+    if (hint) errors.push({ source, message: hint });
+    return { ok: errors.length === 0, errors };
+  }
+  if (dialect && dialect !== "cel") {
+    errors.push({ source, message: `expected a CEL expression but got a \`${dialect}\` dialect.` });
+    return { ok: false, errors };
+  }
+  const compiled = celEngine.compile(source);
+  if (!compiled.ok) {
+    const hint = bracesHint(source);
+    errors.push({
+      source,
+      message: `invalid CEL ${role}: ${compiled.error.message}` + (hint ? ` \u2014 ${hint}` : ` \u2014 ${role}s are bare CEL (e.g. \`record.rating >= 4\`).`)
+    });
+  } else {
+    checkFieldExistence(source, schema, errors);
+  }
+  return { ok: errors.length === 0, errors };
+}
+function bracesHintForTemplate(source) {
+  const m = SINGLE_BRACE_RE.exec(source);
+  const ref = m?.[1] ?? "field";
+  return `single-brace \`{${ref}}\` is not a valid template hole \u2014 use double braces: \`{{ ${ref} }}\`.`;
+}
+function introspectScope(role, schema) {
+  return {
+    dialect: expectedDialect(role),
+    fields: [...schema?.fields ?? []],
+    roots: ["record", "previous", "input", "os", "vars"],
+    functions: CEL_STDLIB_FUNCTIONS
+  };
+}
+var CEL_STDLIB_FUNCTIONS = [
+  "now",
+  "today",
+  "daysFromNow",
+  "daysBetween",
+  "date",
+  "datetime",
+  "timestamp",
+  "isBlank",
+  "isEmpty",
+  "coalesce",
+  "len",
+  "size",
+  "int",
+  "float",
+  "string",
+  "bool",
+  "upper",
+  "lower",
+  "trim",
+  "contains",
+  "startsWith",
+  "endsWith",
+  "matches",
+  "has",
+  "min",
+  "max",
+  "abs",
+  "round"
+];
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CEL_STDLIB_FUNCTIONS,
   DEFAULT_LIMITS,
   ExpressionEngine,
+  TEMPLATE_FORMATTERS,
   buildScope,
   celEngine,
   cronEngine,
+  expectedDialect,
   getEngine,
   hasDialect,
+  introspectScope,
   normalizeExpression,
   normalizeExpressionTree,
   register,
   registerStdLib,
   resolveSeed,
   resolveSeedRecord,
-  templateEngine
+  templateEngine,
+  validateExpression
 });
 //# sourceMappingURL=index.js.map