@objectstack/formula 9.11.0 → 10.0.0

package/dist/index.js

@@ -26,12 +26,16 @@ __export(index_exports, {
   TEMPLATE_FORMATTERS: () => TEMPLATE_FORMATTERS,
   buildScope: () => buildScope,
   celEngine: () => celEngine,
+  compileCelToFilter: () => compileCelToFilter,
   cronEngine: () => cronEngine,
   expectedDialect: () => expectedDialect,
   formatValue: () => formatValue,
   getEngine: () => getEngine,
   hasDialect: () => hasDialect,
   introspectScope: () => introspectScope,
+  isPushdownableCel: () => isPushdownableCel,
+  lowerCelAst: () => lowerCelAst,
+  matchesFilterCondition: () => matchesFilterCondition,
   normalizeExpression: () => normalizeExpression,
   normalizeExpressionTree: () => normalizeExpressionTree,
   register: () => register,
@@ -219,7 +223,14 @@ var SCOPE_ROOTS = [
   "data",
   "params",
   "config",
-  "settings"
+  "settings",
+  // UI action / predicate context (ActionEngine, renderers): the current
+  // record plus ambient globals exposed to `visible`/`disabled` predicates.
+  "ctx",
+  "features",
+  // Master-detail inline grids inject the header record as `parent` for a
+  // child field's `readonlyWhen`/`requiredWhen` predicate (ADR-0036, #1581).
+  "parent"
 ];
 function buildScopedEnv(knownFields) {
   const env = new import_cel_js.Environment({
@@ -791,13 +802,364 @@ function looksLikeExpression(value) {
   return import_spec2.ExpressionSchema.safeParse(v).success;
 }
 
+// src/cel-to-filter.ts
+var import_cel_js2 = require("@marcbachmann/cel-js");
+var SHAPE_VALUE = /* @__PURE__ */ Symbol("cel-filter-shape-placeholder");
+var CompileError = class extends Error {
+  constructor(reason, message) {
+    super(message);
+    this.reason = reason;
+    this.name = "CelFilterCompileError";
+  }
+};
+var parseEnv;
+function getParseEnv() {
+  if (!parseEnv) {
+    parseEnv = new import_cel_js2.Environment({ unlistedVariablesAreDyn: true, enableOptionalTypes: true });
+  }
+  return parseEnv;
+}
+function toSource(input) {
+  if (typeof input === "string") return input.trim() || null;
+  if (input && typeof input === "object" && typeof input.source === "string") {
+    return input.source.trim() || null;
+  }
+  return null;
+}
+function compileCelToFilter(input, opts = {}) {
+  const source = toSource(input);
+  if (!source) return { ok: false, reason: "parse-error", detail: "empty expression" };
+  let ast;
+  try {
+    ast = getParseEnv().parse(source).ast;
+  } catch (err) {
+    return { ok: false, reason: "parse-error", detail: err.message?.split("\n")[0] ?? "parse error" };
+  }
+  return lowerCelAst(ast, opts, "value");
+}
+function isPushdownableCel(input, opts = {}) {
+  const source = toSource(input);
+  if (!source) return { ok: false, reason: "parse-error", detail: "empty expression" };
+  let ast;
+  try {
+    ast = getParseEnv().parse(source).ast;
+  } catch (err) {
+    return { ok: false, reason: "parse-error", detail: err.message?.split("\n")[0] ?? "parse error" };
+  }
+  const res = lowerCelAst(ast, opts, "shape");
+  return res.ok ? { ok: true } : { ok: false, reason: res.reason, detail: res.detail };
+}
+function lowerCelAst(ast, opts = {}, mode = "value") {
+  const ctx = {
+    fieldRoots: new Set(opts.fieldRoots ?? ["record"]),
+    variableRoots: new Set(opts.variableRoots ?? ["current_user"]),
+    variables: opts.variables ?? {},
+    mode
+  };
+  try {
+    return { ok: true, filter: lowerCondition(ast, ctx) };
+  } catch (err) {
+    if (err instanceof CompileError) return { ok: false, reason: err.reason, detail: err.message };
+    return { ok: false, reason: "unsupported", detail: err.message ?? "compile error" };
+  }
+}
+var FLIP = { ">": "<", "<": ">", ">=": "<=", "<=": ">=", "==": "==", "!=": "!=" };
+var CMP_OP = { ">": "$gt", ">=": "$gte", "<": "$lt", "<=": "$lte" };
+var STRING_METHOD = { startsWith: "$startsWith", endsWith: "$endsWith", contains: "$contains" };
+function lowerCondition(node, ctx) {
+  const op = node.op;
+  const args = node.args;
+  switch (op) {
+    case "&&":
+      return combine("$and", node, ctx);
+    case "||":
+      return combine("$or", node, ctx);
+    case "!_":
+      return { $not: lowerCondition(args, ctx) };
+    case "==":
+    case "!=":
+    case ">":
+    case ">=":
+    case "<":
+    case "<=":
+      return lowerComparison(op, args[0], args[1], ctx);
+    case "in":
+      return lowerMembership(args[0], args[1], ctx);
+    case "rcall":
+      return lowerStringMethod(args, ctx);
+    case "value": {
+      const v = coerceLiteral(args);
+      if (v === true) return {};
+      throw new CompileError("unsupported", `constant non-true predicate (${String(v)})`);
+    }
+    default:
+      throw new CompileError("unsupported", `unsupported operator "${String(op)}"`);
+  }
+}
+function combine(key, node, ctx) {
+  const [l, r] = node.args;
+  const parts = [];
+  for (const child of [lowerCondition(l, ctx), lowerCondition(r, ctx)]) {
+    const nested = child[key];
+    if (Array.isArray(nested) && Object.keys(child).length === 1) parts.push(...nested);
+    else parts.push(child);
+  }
+  return { [key]: parts };
+}
+function lowerComparison(op, lNode, rNode, ctx) {
+  const L = classify(lNode, ctx);
+  const R = classify(rNode, ctx);
+  const lField = L.kind === "field";
+  const rField = R.kind === "field";
+  if (lField && rField) {
+    return emit(L.path, op, { $field: R.path }, true);
+  }
+  if (lField) return emit(L.path, op, resolveValue(R, ctx), false);
+  if (rField) return emit(R.path, FLIP[op] ?? op, resolveValue(L, ctx), false);
+  const lv = resolveValue(L, ctx);
+  const rv = resolveValue(R, ctx);
+  if (ctx.mode === "shape") return {};
+  const truth = constFold(op, lv, rv);
+  if (truth === true) return {};
+  throw new CompileError("unsupported", `constant ${op} predicate that is not always-true`);
+}
+function lowerMembership(elemNode, containerNode, ctx) {
+  const elem = classify(elemNode, ctx);
+  if (elem.kind !== "field") {
+    throw new CompileError("unsupported", `\`in\` requires a field on the left (got ${elem.kind})`);
+  }
+  const container = classify(containerNode, ctx);
+  const value = resolveValue(container, ctx);
+  if (value !== SHAPE_VALUE && !Array.isArray(value)) {
+    throw new CompileError("unsupported", `\`in\` requires an array/list on the right`);
+  }
+  return { [elem.path]: { $in: value } };
+}
+function lowerStringMethod(args, ctx) {
+  const [method, receiver, callArgs] = args;
+  const mapped = STRING_METHOD[method];
+  if (!mapped) throw new CompileError("unsupported", `unsupported method "${method}()"`);
+  const recv = classify(receiver, ctx);
+  if (recv.kind !== "field") throw new CompileError("unsupported", `"${method}()" must be called on a field`);
+  if (!Array.isArray(callArgs) || callArgs.length !== 1) {
+    throw new CompileError("unsupported", `"${method}()" takes exactly one argument`);
+  }
+  const arg = resolveValue(classify(callArgs[0], ctx), ctx);
+  if (arg !== SHAPE_VALUE && typeof arg !== "string") {
+    throw new CompileError("unsupported", `"${method}()" argument must be a string literal`);
+  }
+  return { [recv.path]: { [mapped]: arg } };
+}
+function emit(field, op, value, isRef) {
+  if (op === "==") {
+    if (!isRef && value === null) return { [field]: { $null: true } };
+    if (isRef) return { [field]: { $eq: value } };
+    return { [field]: value };
+  }
+  if (op === "!=") {
+    if (!isRef && value === null) return { [field]: { $null: false } };
+    return { [field]: { $ne: value } };
+  }
+  const cmp = CMP_OP[op];
+  if (cmp) return { [field]: { [cmp]: value } };
+  throw new CompileError("unsupported", `unsupported comparison "${op}"`);
+}
+function classify(node, ctx) {
+  switch (node.op) {
+    case "value":
+      return { kind: "literal", value: coerceLiteral(node.args) };
+    case "list": {
+      const items = node.args.map((n) => {
+        const leaf = classify(n, ctx);
+        if (leaf.kind !== "literal") {
+          throw new CompileError("unsupported", "list elements must be literals");
+        }
+        return leaf.value;
+      });
+      return { kind: "literal", value: items };
+    }
+    case "id": {
+      const name = node.args;
+      if (ctx.variableRoots.has(name)) return { kind: "var", path: [name] };
+      return { kind: "field", path: name };
+    }
+    case ".":
+    case ".?": {
+      const [recv, field] = node.args;
+      const chain = memberChain(recv, field);
+      if (!chain) throw new CompileError("unsupported", "unsupported member-access expression");
+      const [root, ...rest] = chain;
+      if (ctx.variableRoots.has(root)) return { kind: "var", path: chain };
+      if (ctx.fieldRoots.has(root)) {
+        if (rest.length !== 1) {
+          throw new CompileError("unsupported", `cross-object/nested field path "${chain.join(".")}" is not pushdown-able`);
+        }
+        return { kind: "field", path: rest[0] };
+      }
+      throw new CompileError("unsupported", `cross-object field path "${chain.join(".")}" is not pushdown-able`);
+    }
+    default:
+      throw new CompileError("unsupported", `unsupported operand "${String(node.op)}"`);
+  }
+}
+function memberChain(recv, field) {
+  if (recv.op === "id") return [recv.args, field];
+  if (recv.op === "." || recv.op === ".?") {
+    const [innerRecv, innerField] = recv.args;
+    const inner = memberChain(innerRecv, innerField);
+    return inner ? [...inner, field] : null;
+  }
+  return null;
+}
+function resolveValue(leaf, ctx) {
+  if (leaf.kind === "literal") return leaf.value;
+  if (leaf.kind === "field") {
+    throw new CompileError("unsupported", `expected a value but got field "${leaf.path}"`);
+  }
+  if (ctx.mode === "shape") return SHAPE_VALUE;
+  let cur = ctx.variables;
+  for (const seg of leaf.path) {
+    if (cur == null || typeof cur !== "object") {
+      throw new CompileError("unresolved-variable", `variable "${leaf.path.join(".")}" is not resolvable`);
+    }
+    cur = cur[seg];
+  }
+  if (cur === void 0 || cur === null) {
+    throw new CompileError("unresolved-variable", `variable "${leaf.path.join(".")}" is ${String(cur)}`);
+  }
+  return cur;
+}
+function coerceLiteral(v) {
+  if (typeof v === "bigint") return Number(v);
+  if (v === null || typeof v === "string" || typeof v === "number" || typeof v === "boolean") return v;
+  if (typeof v === "object" && typeof v.valueOf === "function") {
+    const prim = v.valueOf();
+    if (typeof prim === "bigint") return Number(prim);
+    if (typeof prim === "number" || typeof prim === "string" || typeof prim === "boolean") return prim;
+  }
+  throw new CompileError("unsupported", `unsupported literal type "${typeof v}"`);
+}
+function constFold(op, l, r) {
+  switch (op) {
+    case "==":
+      return l === r;
+    case "!=":
+      return l !== r;
+    case ">":
+      return l > r;
+    case ">=":
+      return l >= r;
+    case "<":
+      return l < r;
+    case "<=":
+      return l <= r;
+    default:
+      return void 0;
+  }
+}
+
+// src/matches-filter.ts
+function matchesFilterCondition(record, filter) {
+  if (filter == null) return true;
+  if (typeof filter !== "object" || Array.isArray(filter)) return false;
+  return evalNode(record, filter);
+}
+function evalNode(record, node) {
+  for (const [key, val] of Object.entries(node)) {
+    if (key === "$and") {
+      if (!Array.isArray(val) || !val.every((c) => evalNode(record, c))) return false;
+    } else if (key === "$or") {
+      if (!Array.isArray(val) || val.length === 0 || !val.some((c) => evalNode(record, c))) return false;
+    } else if (key === "$not") {
+      if (val == null || typeof val !== "object") return false;
+      if (evalNode(record, val)) return false;
+    } else if (key.startsWith("$")) {
+      return false;
+    } else {
+      if (!evalField(record, key, val)) return false;
+    }
+  }
+  return true;
+}
+function evalField(record, field, spec) {
+  const actual = getPath(record, field);
+  if (spec === null) return actual == null;
+  if (typeof spec !== "object" || spec instanceof Date) return looseEq(actual, spec);
+  if (Array.isArray(spec)) return false;
+  const ops = spec;
+  const keys = Object.keys(ops);
+  if (keys.length === 0 || keys.some((k) => !k.startsWith("$"))) return false;
+  for (const op of keys) {
+    if (!evalOp(actual, op, ops[op], record)) return false;
+  }
+  return true;
+}
+function evalOp(actual, op, raw, record) {
+  const v = resolveValue2(raw, record);
+  switch (op) {
+    case "$eq":
+      return v === null ? actual == null : looseEq(actual, v);
+    case "$ne":
+      return v === null ? actual != null : !looseEq(actual, v);
+    case "$gt":
+      return actual != null && v != null && actual > v;
+    case "$gte":
+      return actual != null && v != null && actual >= v;
+    case "$lt":
+      return actual != null && v != null && actual < v;
+    case "$lte":
+      return actual != null && v != null && actual <= v;
+    case "$in":
+      return Array.isArray(v) && v.some((x) => looseEq(actual, x));
+    case "$nin":
+      return Array.isArray(v) && !v.some((x) => looseEq(actual, x));
+    case "$between":
+      return Array.isArray(v) && v.length === 2 && actual != null && actual >= v[0] && actual <= v[1];
+    case "$contains":
+      return typeof actual === "string" && typeof v === "string" && actual.includes(v);
+    case "$notContains":
+      return !(typeof actual === "string" && typeof v === "string" && actual.includes(v));
+    case "$startsWith":
+      return typeof actual === "string" && typeof v === "string" && actual.startsWith(v);
+    case "$endsWith":
+      return typeof actual === "string" && typeof v === "string" && actual.endsWith(v);
+    case "$null":
+      return v === true ? actual == null : actual != null;
+    case "$exists":
+      return v === true ? actual !== void 0 : actual === void 0;
+    default:
+      return false;
+  }
+}
+function resolveValue2(raw, record) {
+  if (raw && typeof raw === "object" && !Array.isArray(raw) && "$field" in raw) {
+    return getPath(record, String(raw.$field));
+  }
+  return raw;
+}
+function getPath(record, path) {
+  if (!path.includes(".")) return record[path];
+  let cur = record;
+  for (const seg of path.split(".")) {
+    if (cur == null || typeof cur !== "object") return void 0;
+    cur = cur[seg];
+  }
+  return cur;
+}
+function looseEq(a, b) {
+  if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
+  if (a instanceof Date && (typeof b === "string" || typeof b === "number")) return a.getTime() === new Date(b).getTime();
+  if (b instanceof Date && (typeof a === "string" || typeof a === "number")) return new Date(a).getTime() === b.getTime();
+  return a === b;
+}
+
 // 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) {
+function toSource2(input) {
   if (input == null) return { source: "" };
   if (typeof input === "string") return { source: input };
   return { dialect: input.dialect, source: input.source ?? "" };
@@ -852,7 +1214,7 @@ function levenshtein(a, b) {
   return dp[m];
 }
 function validateExpression(role, input, schema) {
-  const { dialect, source } = toSource(input);
+  const { dialect, source } = toSource2(input);
   const errors = [];
   const warnings = [];
   if (!source.trim()) return { ok: true, errors, warnings };
@@ -966,12 +1328,16 @@ var CEL_STDLIB_FUNCTIONS = [
   TEMPLATE_FORMATTERS,
   buildScope,
   celEngine,
+  compileCelToFilter,
   cronEngine,
   expectedDialect,
   formatValue,
   getEngine,
   hasDialect,
   introspectScope,
+  isPushdownableCel,
+  lowerCelAst,
+  matchesFilterCondition,
   normalizeExpression,
   normalizeExpressionTree,
   register,