@objectstack/formula 10.3.0 → 11.0.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/formula@10.3.0 build /home/runner/work/framework/framework/packages/formula
+> @objectstack/formula@11.0.0 build /home/runner/work/framework/framework/packages/formula
 > tsup --config ../../tsup.config.ts
 
 CLI Building entry: src/index.ts
@@ -10,13 +10,13 @@
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-ESM dist/index.mjs     43.08 KB
-ESM dist/index.mjs.map 118.46 KB
-ESM ⚡️ Build success in 124ms
-CJS dist/index.js     45.02 KB
-CJS dist/index.js.map 120.34 KB
-CJS ⚡️ Build success in 130ms
+CJS dist/index.js     48.18 KB
+CJS dist/index.js.map 130.43 KB
+CJS ⚡️ Build success in 114ms
+ESM dist/index.mjs     46.17 KB
+ESM dist/index.mjs.map 128.47 KB
+ESM ⚡️ Build success in 115ms
 DTS Build start
-DTS ⚡️ Build success in 4555ms
-DTS dist/index.d.mts 20.19 KB
-DTS dist/index.d.ts  20.19 KB
+DTS ⚡️ Build success in 4697ms
+DTS dist/index.d.mts 22.39 KB
+DTS dist/index.d.ts  22.39 KB

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @objectstack/formula
 
+## 11.0.0
+
+### Minor Changes
+
+- ef3ed67: Formula field typing: `inferExpressionType()` + a declared `returnType`.
+
+  - `@objectstack/formula`: new `inferExpressionType()` (and lower-level `inferCelType()`) surfaces the cel-js type-checker's result for a CEL value/formula expression, mapped to `number | text | boolean | date | unknown`. Conservative — two `dyn` operands stay `unknown`; typed literals/stdlib returns pin a concrete type.
+  - `@objectstack/spec`: `FieldSchema` gains an optional `returnType` (`number|text|boolean|date`) so a formula field can carry its declared value type (the way Salesforce/Airtable do), letting consumers (dataset measures, formatting, validation) read a declared type instead of re-parsing the expression.
+
+### Patch Changes
+
+- Updated dependencies [ab5718a]
+- Updated dependencies [4845c12]
+- Updated dependencies [c1a754a]
+- Updated dependencies [6fbe91f]
+- Updated dependencies [715d667]
+- Updated dependencies [5eef4cf]
+- Updated dependencies [72759e1]
+- Updated dependencies [6c4fbd9]
+- Updated dependencies [ef3ed67]
+- Updated dependencies [cd51229]
+- Updated dependencies [7697a0e]
+- Updated dependencies [e7e04f1]
+- Updated dependencies [cfd5ac4]
+- Updated dependencies [2be5c1f]
+- Updated dependencies [ad143ce]
+- Updated dependencies [5c4a8c8]
+- Updated dependencies [3afaeed]
+- Updated dependencies [8801c02]
+- Updated dependencies [3d04e06]
+- Updated dependencies [4a84c98]
+- Updated dependencies [d980f0d]
+- Updated dependencies [a658523]
+- Updated dependencies [82ff91c]
+- Updated dependencies [638f472]
+  - @objectstack/spec@11.0.0
+
 ## 10.3.0
 
 ### Patch Changes

package/dist/index.d.mts

@@ -32,9 +32,22 @@ interface EvalContext {
      * Defaults to `UTC` when unset. Calendar-day `date` rendering stays tz-naive.
      */
     timezone?: string;
-    /** Current authenticated subject (hook / action / view contexts). */
+    /**
+     * Current authenticated subject (hook / action / view contexts).
+     *
+     * ADR-0068: the canonical user contract is {@link EvalUser} from
+     * `@objectstack/spec`, surfaced to predicates as `current_user` (aliases
+     * `user`, `ctx.user`). `roles: string[]` is the only canonical role field;
+     * the singular `role` is deprecated (its "overwritten to 'admin' on
+     * promotion" behavior is the footgun ADR-0068 eliminates).
+     */
     user?: {
         id: string;
+        /** CANONICAL (ADR-0068). Scope-resolved role names assigned to the user. */
+        roles?: string[];
+        /** Active organization ID (null = platform / unscoped). */
+        organizationId?: string | null;
+        /** @deprecated ADR-0068 — use {@link roles}. Retained for back-compat only. */
         role?: string;
         email?: string;
         [key: string]: unknown;
@@ -424,6 +437,14 @@ interface ExprSchemaHint {
      *                    did-you-mean *warning*. (Default.)
      */
     scope?: 'record' | 'flattened';
+    /**
+     * ADR-0068 D4 — the closed catalog of valid role names (built-in + declared).
+     * When supplied, a role-membership predicate testing a role NOT in this set
+     * (e.g. `'org_admni' in current_user.roles`) is flagged as an error. Closes
+     * the AI-hallucination hole where a model invents a plausible-but-nonexistent
+     * role that then silently never matches. Absent => role checks are skipped.
+     */
+    roleCatalog?: readonly string[];
 }
 interface ExprValidationError {
     /** Self-correcting message: what is wrong + the correct form. */
@@ -459,8 +480,27 @@ declare function introspectScope(role: FieldRole, schema?: ExprSchemaHint): {
     dialect: 'cel' | 'template';
     fields: string[];
     roots: string[];
+    roles: string[];
     functions: string[];
 };
+/**
+ * Coarse value categories a `value`/formula expression can compute. `'unknown'`
+ * means cel-js could not prove a concrete type — either a `dyn` result (an
+ * ambiguous expression over untyped operands) or one that does not type-check.
+ */
+type InferredValueType = 'number' | 'text' | 'boolean' | 'date' | 'unknown';
+/**
+ * Infer the coarse value type a `value`/formula expression computes — `'number'`,
+ * `'text'`, `'boolean'`, `'date'`, or `'unknown'` when cel-js cannot prove a
+ * concrete type. `schema.fields` (the host object's field names) are declared so
+ * a bare `<field>` reference resolves the same as `record.<field>`.
+ *
+ * The motivating use is measure-eligibility: a dataset derives a SUM measure for
+ * a `formula` field ONLY when this returns `'number'`, so an ambiguous or
+ * non-numeric formula never yields an incoherent measure. Conservative by
+ * construction — see {@link inferCelType}.
+ */
+declare function inferExpressionType(input: ExprInput, schema?: ExprSchemaHint): InferredValueType;
 /**
  * Public catalog of CEL functions available in expressions — what `introspectScope`
  * advertises to authors (incl. AI). Every entry MUST actually resolve at runtime:
@@ -469,4 +509,4 @@ declare function introspectScope(role: FieldRole, schema?: ExprSchemaHint): {
  */
 declare const CEL_STDLIB_FUNCTIONS: string[];
 
-export { CEL_STDLIB_FUNCTIONS, type CelFilterCompileOptions, type CelFilterCompileResult, type CelFilterFailReason, DEFAULT_LIMITS, type DialectEngine, type EvalContext, type EvalError, type EvalResult, type ExprSchemaHint, type ExprValidationError, type ExprValidationResult, ExpressionEngine, type FieldRole, type SeedPrimitive, type SeedValue, TEMPLATE_FORMATTERS, buildScope, celEngine, compileCelToFilter, cronEngine, expectedDialect, formatValue, getEngine, hasDialect, introspectScope, isPushdownableCel, lowerCelAst, matchesFilterCondition, normalizeExpression, normalizeExpressionTree, register, registerStdLib, resolveSeed, resolveSeedRecord, templateEngine, validateExpression };
+export { CEL_STDLIB_FUNCTIONS, type CelFilterCompileOptions, type CelFilterCompileResult, type CelFilterFailReason, DEFAULT_LIMITS, type DialectEngine, type EvalContext, type EvalError, type EvalResult, type ExprInput, type ExprSchemaHint, type ExprValidationError, type ExprValidationResult, ExpressionEngine, type FieldRole, type InferredValueType, type SeedPrimitive, type SeedValue, TEMPLATE_FORMATTERS, buildScope, celEngine, compileCelToFilter, cronEngine, expectedDialect, formatValue, getEngine, hasDialect, inferExpressionType, introspectScope, isPushdownableCel, lowerCelAst, matchesFilterCondition, normalizeExpression, normalizeExpressionTree, register, registerStdLib, resolveSeed, resolveSeedRecord, templateEngine, validateExpression };

package/dist/index.d.ts

@@ -32,9 +32,22 @@ interface EvalContext {
      * Defaults to `UTC` when unset. Calendar-day `date` rendering stays tz-naive.
      */
     timezone?: string;
-    /** Current authenticated subject (hook / action / view contexts). */
+    /**
+     * Current authenticated subject (hook / action / view contexts).
+     *
+     * ADR-0068: the canonical user contract is {@link EvalUser} from
+     * `@objectstack/spec`, surfaced to predicates as `current_user` (aliases
+     * `user`, `ctx.user`). `roles: string[]` is the only canonical role field;
+     * the singular `role` is deprecated (its "overwritten to 'admin' on
+     * promotion" behavior is the footgun ADR-0068 eliminates).
+     */
     user?: {
         id: string;
+        /** CANONICAL (ADR-0068). Scope-resolved role names assigned to the user. */
+        roles?: string[];
+        /** Active organization ID (null = platform / unscoped). */
+        organizationId?: string | null;
+        /** @deprecated ADR-0068 — use {@link roles}. Retained for back-compat only. */
         role?: string;
         email?: string;
         [key: string]: unknown;
@@ -424,6 +437,14 @@ interface ExprSchemaHint {
      *                    did-you-mean *warning*. (Default.)
      */
     scope?: 'record' | 'flattened';
+    /**
+     * ADR-0068 D4 — the closed catalog of valid role names (built-in + declared).
+     * When supplied, a role-membership predicate testing a role NOT in this set
+     * (e.g. `'org_admni' in current_user.roles`) is flagged as an error. Closes
+     * the AI-hallucination hole where a model invents a plausible-but-nonexistent
+     * role that then silently never matches. Absent => role checks are skipped.
+     */
+    roleCatalog?: readonly string[];
 }
 interface ExprValidationError {
     /** Self-correcting message: what is wrong + the correct form. */
@@ -459,8 +480,27 @@ declare function introspectScope(role: FieldRole, schema?: ExprSchemaHint): {
     dialect: 'cel' | 'template';
     fields: string[];
     roots: string[];
+    roles: string[];
     functions: string[];
 };
+/**
+ * Coarse value categories a `value`/formula expression can compute. `'unknown'`
+ * means cel-js could not prove a concrete type — either a `dyn` result (an
+ * ambiguous expression over untyped operands) or one that does not type-check.
+ */
+type InferredValueType = 'number' | 'text' | 'boolean' | 'date' | 'unknown';
+/**
+ * Infer the coarse value type a `value`/formula expression computes — `'number'`,
+ * `'text'`, `'boolean'`, `'date'`, or `'unknown'` when cel-js cannot prove a
+ * concrete type. `schema.fields` (the host object's field names) are declared so
+ * a bare `<field>` reference resolves the same as `record.<field>`.
+ *
+ * The motivating use is measure-eligibility: a dataset derives a SUM measure for
+ * a `formula` field ONLY when this returns `'number'`, so an ambiguous or
+ * non-numeric formula never yields an incoherent measure. Conservative by
+ * construction — see {@link inferCelType}.
+ */
+declare function inferExpressionType(input: ExprInput, schema?: ExprSchemaHint): InferredValueType;
 /**
  * Public catalog of CEL functions available in expressions — what `introspectScope`
  * advertises to authors (incl. AI). Every entry MUST actually resolve at runtime:
@@ -469,4 +509,4 @@ declare function introspectScope(role: FieldRole, schema?: ExprSchemaHint): {
  */
 declare const CEL_STDLIB_FUNCTIONS: string[];
 
-export { CEL_STDLIB_FUNCTIONS, type CelFilterCompileOptions, type CelFilterCompileResult, type CelFilterFailReason, DEFAULT_LIMITS, type DialectEngine, type EvalContext, type EvalError, type EvalResult, type ExprSchemaHint, type ExprValidationError, type ExprValidationResult, ExpressionEngine, type FieldRole, type SeedPrimitive, type SeedValue, TEMPLATE_FORMATTERS, buildScope, celEngine, compileCelToFilter, cronEngine, expectedDialect, formatValue, getEngine, hasDialect, introspectScope, isPushdownableCel, lowerCelAst, matchesFilterCondition, normalizeExpression, normalizeExpressionTree, register, registerStdLib, resolveSeed, resolveSeedRecord, templateEngine, validateExpression };
+export { CEL_STDLIB_FUNCTIONS, type CelFilterCompileOptions, type CelFilterCompileResult, type CelFilterFailReason, DEFAULT_LIMITS, type DialectEngine, type EvalContext, type EvalError, type EvalResult, type ExprInput, type ExprSchemaHint, type ExprValidationError, type ExprValidationResult, ExpressionEngine, type FieldRole, type InferredValueType, type SeedPrimitive, type SeedValue, TEMPLATE_FORMATTERS, buildScope, celEngine, compileCelToFilter, cronEngine, expectedDialect, formatValue, getEngine, hasDialect, inferExpressionType, introspectScope, isPushdownableCel, lowerCelAst, matchesFilterCondition, normalizeExpression, normalizeExpressionTree, register, registerStdLib, resolveSeed, resolveSeedRecord, templateEngine, validateExpression };

package/dist/index.js

@@ -32,6 +32,7 @@ __export(index_exports, {
   formatValue: () => formatValue,
   getEngine: () => getEngine,
   hasDialect: () => hasDialect,
+  inferExpressionType: () => inferExpressionType,
   introspectScope: () => introspectScope,
   isPushdownableCel: () => isPushdownableCel,
   lowerCelAst: () => lowerCelAst,
@@ -51,6 +52,7 @@ module.exports = __toCommonJS(index_exports);
 var import_cel_js = require("@marcbachmann/cel-js");
 
 // src/stdlib.ts
+var import_spec = require("@objectstack/spec");
 function partsInTz(d, tz) {
   const parts = new Intl.DateTimeFormat("en-US", {
     timeZone: tz,
@@ -171,13 +173,37 @@ function registerNumericCoercions(env) {
   }
   return env;
 }
+function toEvalUser(u) {
+  const legacyRole = typeof u.role === "string" && u.role ? [u.role] : [];
+  const roles = Array.isArray(u.roles) ? u.roles : [];
+  const canonical = (0, import_spec.createEvalUser)({
+    id: u.id,
+    name: typeof u.name === "string" ? u.name : void 0,
+    email: typeof u.email === "string" ? u.email : void 0,
+    roles: [...roles, ...legacyRole],
+    organizationId: typeof u.organizationId === "string" || u.organizationId === null ? u.organizationId : void 0
+  });
+  if (typeof u.role === "string" && u.role) {
+    canonical.role = u.role;
+  }
+  return canonical;
+}
 function buildScope(ctx) {
   const scope = {};
   if (ctx.record !== void 0) scope.record = ctx.record;
   if (ctx.previous !== void 0) scope.previous = ctx.previous;
   if (ctx.input !== void 0) scope.input = ctx.input;
   const os = {};
-  if (ctx.user !== void 0) os.user = ctx.user;
+  if (ctx.user !== void 0) {
+    const currentUser = toEvalUser(ctx.user);
+    scope.current_user = currentUser;
+    scope.user = currentUser;
+    scope.ctx = {
+      ...typeof scope.ctx === "object" && scope.ctx !== null ? scope.ctx : {},
+      user: currentUser
+    };
+    os.user = currentUser;
+  }
   if (ctx.org !== void 0) os.org = ctx.org;
   if (ctx.env !== void 0) os.env = ctx.env;
   if (Object.keys(os).length > 0) scope.os = os;
@@ -267,6 +293,17 @@ function firstUndeclaredReference(source, knownFields = []) {
   }
   return null;
 }
+function inferCelType(source, knownFields = []) {
+  if (typeof source !== "string" || !source.trim()) return null;
+  try {
+    const env = knownFields.length === 0 ? recordScopeEnv ?? (recordScopeEnv = buildScopedEnv([])) : buildScopedEnv(knownFields);
+    const result = env.parse(source).check?.();
+    if (!result || result.valid === false) return null;
+    return typeof result.type === "string" ? result.type : null;
+  } catch {
+    return null;
+  }
+}
 function coerce(value) {
   if (typeof value === "bigint") {
     if (value >= BigInt(Number.MIN_SAFE_INTEGER) && value <= BigInt(Number.MAX_SAFE_INTEGER)) {
@@ -704,12 +741,12 @@ var ExpressionEngine = {
 };
 
 // src/seed-eval.ts
-var import_spec = require("@objectstack/spec");
+var import_spec2 = require("@objectstack/spec");
 function isExpressionLike(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
   const v = value;
   if (typeof v.dialect !== "string") return false;
-  return import_spec.ExpressionSchema.safeParse(v).success;
+  return import_spec2.ExpressionSchema.safeParse(v).success;
 }
 function resolveSeed(value, ctx) {
   if (value === null || value === void 0) {
@@ -749,9 +786,9 @@ function resolveSeedRecord(record, ctx) {
 }
 
 // src/normalize.ts
-var import_spec2 = require("@objectstack/spec");
+var import_spec3 = require("@objectstack/spec");
 function normalizeExpression(input) {
-  const parsed = import_spec2.ExpressionInputSchema.safeParse(input);
+  const parsed = import_spec3.ExpressionInputSchema.safeParse(input);
   if (!parsed.success) {
     return {
       ok: false,
@@ -799,7 +836,7 @@ function looksLikeExpression(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
   const v = value;
   if (typeof v.dialect !== "string") return false;
-  return import_spec2.ExpressionSchema.safeParse(v).success;
+  return import_spec3.ExpressionSchema.safeParse(v).success;
 }
 
 // src/cel-to-filter.ts
@@ -1213,6 +1250,30 @@ function levenshtein(a, b) {
   }
   return dp[m];
 }
+var ROLE_IN_RE = /(['"])([a-z0-9_]+)\1\s+in\s+(?:current_user|user|ctx\.user)\.roles\b/g;
+var ROLE_CONTAINS_RE = /(?:current_user|user|ctx\.user)\.roles\s*\.\s*contains\(\s*(['"])([a-z0-9_]+)\1\s*\)/g;
+var ROLE_EXISTS_RE = /(?:current_user|user|ctx\.user)\.roles\s*\.\s*exists\s*\([^,)]{0,64},[^)=]{0,128}==\s*(['"])([a-z0-9_]+)\1/g;
+var ROLE_EQ_RE = /(?:current_user|user|ctx\.user)\.role\s*==\s*(['"])([a-z0-9_]+)\1/g;
+function checkRoleCatalog(source, schema, errors) {
+  const catalog = schema?.roleCatalog;
+  if (!catalog || catalog.length === 0) return;
+  const known = new Set(catalog);
+  const seen = /* @__PURE__ */ new Set();
+  for (const re of [ROLE_IN_RE, ROLE_CONTAINS_RE, ROLE_EXISTS_RE, ROLE_EQ_RE]) {
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(source)) !== null) {
+      const name = m[2];
+      if (known.has(name) || seen.has(name)) continue;
+      seen.add(name);
+      const suggestion = nearest(name, catalog);
+      errors.push({
+        source,
+        message: `unknown role \`${name}\` \u2014 not a defined role` + (suggestion ? `; did you mean \`${suggestion}\`?` : ".") + ` Valid roles: ${catalog.join(", ")}.`
+      });
+    }
+  }
+}
 function validateExpression(role, input, schema) {
   const { dialect, source } = toSource2(input);
   const errors = [];
@@ -1244,6 +1305,7 @@ function validateExpression(role, input, schema) {
     });
   } else {
     checkFieldExistence(source, schema, errors);
+    checkRoleCatalog(source, schema, errors);
     if (schema?.scope === "record") {
       const bare = firstUndeclaredReference(source);
       if (bare) {
@@ -1276,10 +1338,32 @@ function introspectScope(role, schema) {
   return {
     dialect: expectedDialect(role),
     fields: [...schema?.fields ?? []],
-    roots: ["record", "previous", "input", "os", "vars"],
+    roots: ["record", "previous", "input", "os", "current_user", "user", "vars"],
+    roles: [...schema?.roleCatalog ?? []],
     functions: CEL_STDLIB_FUNCTIONS
   };
 }
+function celTypeToValueType(celType) {
+  switch (celType) {
+    case "int":
+    case "uint":
+    case "double":
+      return "number";
+    case "string":
+      return "text";
+    case "bool":
+      return "boolean";
+    case "google.protobuf.Timestamp":
+      return "date";
+    default:
+      return "unknown";
+  }
+}
+function inferExpressionType(input, schema) {
+  const { source } = toSource2(input);
+  if (!source.trim()) return "unknown";
+  return celTypeToValueType(inferCelType(source, schema?.fields));
+}
 var CEL_STDLIB_FUNCTIONS = [
   // Dates (registered stdlib)
   "now",
@@ -1334,6 +1418,7 @@ var CEL_STDLIB_FUNCTIONS = [
   formatValue,
   getEngine,
   hasDialect,
+  inferExpressionType,
   introspectScope,
   isPushdownableCel,
   lowerCelAst,