@objectstack/formula 9.7.0 → 9.9.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/formula@9.7.0 build /home/runner/work/framework/framework/packages/formula
+> @objectstack/formula@9.9.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
-CJS dist/index.js     27.85 KB
-CJS dist/index.js.map 73.20 KB
-CJS ⚡️ Build success in 103ms
-ESM dist/index.mjs     26.12 KB
-ESM dist/index.mjs.map 71.83 KB
-ESM ⚡️ Build success in 104ms
+CJS dist/index.js     31.13 KB
+CJS dist/index.js.map 83.10 KB
+CJS ⚡️ Build success in 67ms
+ESM dist/index.mjs     29.37 KB
+ESM dist/index.mjs.map 81.72 KB
+ESM ⚡️ Build success in 84ms
 DTS Build start
-DTS ⚡️ Build success in 5303ms
-DTS dist/index.d.mts 15.44 KB
-DTS dist/index.d.ts  15.44 KB
+DTS ⚡️ Build success in 4303ms
+DTS dist/index.d.mts 16.79 KB
+DTS dist/index.d.ts  16.79 KB

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # @objectstack/formula
 
+## 9.9.0
+
+### Minor Changes
+
+- d99a75a: feat(formula): timezone-aware `today()` / `daysFromNow()` / `daysAgo()` (ADR-0053 Phase 2)
+
+  These are now **calendar-day** functions resolved in a reference timezone, threaded from `ExecutionContext.timezone` (#1978) through `EvalContext.timezone` into the CEL stdlib. Each returns the reference-tz calendar day expressed as a **UTC-midnight `Date`** (ADR-0053 decision D1) — the one representation consistent with how `Field.date` strings hydrate, how the SQL driver normalizes date filters, and how Phase 1 stores dates. So `record.close_date == daysFromNow(30)` now matches in-memory too, not just at the storage boundary. The timezone calculation uses `Intl.DateTimeFormat` (DST-safe; no hand-rolled offset math).
+
+  **⚠️ Behavior change:** `daysFromNow(n)` / `daysAgo(n)` previously kept the wall-clock time of `now` (e.g. `daysFromNow(30)` at `10:00Z` → `…T10:00:00Z`). They now drop the time and return the calendar day at **midnight** (`…T00:00:00Z`) — the ADR-0053 "defect #3" fix. `today()` is unchanged at UTC (it already truncated to start-of-day). For a genuine sub-day offset use the documented escape hatch `now() + duration("Nh")`.
+
+  With no reference timezone configured the zone resolves to `UTC`, so `today()` is byte-for-byte unchanged; only the `daysFromNow`/`daysAgo` midnight-truncation differs from before. `objectql` threads `execCtx.timezone` into read-time formula evaluation (`applyFormulaPlan`) and default-value expressions (`applyFieldDefaults`).
+
+  Part of #1980. (Consuming a non-UTC reference timezone end-to-end also needs the `localization` settings manifest noted in #1978.)
+
+- 575448d: feat(formula,email): render `datetime` in a reference timezone (ADR-0053 Phase 2)
+
+  `datetime` template holes now render in a reference timezone's wall-clock when one is supplied, at the presentation boundary — storage stays UTC.
+
+  - **Formula template engine** — the `datetime` formatter takes the reference timezone from `EvalContext.timezone` (threaded in #1980) and passes it to `Intl.DateTimeFormat`. `{{ ts | datetime }}` renders in that zone; `{{ ts | datetime:iso }}` stays UTC (machine-readable). Calendar-day `date` rendering is intentionally **unchanged** (tz-naive — a `Field.date` has no zone). New exported `formatValue(name, value, arg, { locale, timeZone })` makes the whitelisted formatters reusable outside the full CEL template engine.
+  - **Email pipeline** — `plugin-email`'s renderer previously bypassed the formatter pipeline (`String()` only), so a datetime went out as raw ISO. Email holes now accept the shared formula formatters — `{{ order.total | currency }}`, `{{ ts | datetime }}` — reusing `formatValue` (single source of truth), while keeping the engine's HTML-escaping and `{{{ }}}` raw-output semantics. `SendTemplateInput.timezone` (mirroring the existing `locale`) flows into rendering so an email's datetime shows the recipient's wall-clock.
+
+### Patch Changes
+
+- Updated dependencies [84249a4]
+- Updated dependencies [11af299]
+- Updated dependencies [d5774b5]
+- Updated dependencies [134043a]
+- Updated dependencies [90108e0]
+- Updated dependencies [9afeb2d]
+- Updated dependencies [6bec07e]
+- Updated dependencies [601cc11]
+- Updated dependencies [575448d]
+  - @objectstack/spec@9.9.0
+
+## 9.8.0
+
+### Minor Changes
+
+- c17d2c8: feat(formula): register the CEL functions the authoring catalog advertises (daysBetween, abs, round, min, max, upper, lower, contains, startsWith, endsWith, matches, len, isEmpty, date, datetime)
+
+  `introspectScope` / `CEL_STDLIB_FUNCTIONS` advertised 25 functions to authors
+  (incl. AI), but only 8 were registered — 14 faulted at runtime (`daysBetween`,
+  `abs`, `round`, `min`, `max`, `upper`, `lower`, `len`, `isEmpty`, `contains`,
+  `startsWith`, `endsWith`, `matches`, plus `date`/`datetime`). Authors were told
+  to call functions that don't exist (e.g. `daysBetween` for "days remaining").
+
+  Register the genuinely-useful set in `registerStdLib` with dyn-lenient signatures
+  (so a `Field.date` arriving as a string still works) and internal coercion, and
+  reconcile the catalog so every advertised entry resolves — guarded by a test that
+  evaluates every `CEL_STDLIB_FUNCTIONS` entry. Pure additions; no behavior change
+  to existing expressions.
+
+### Patch Changes
+
+- Updated dependencies [97c55b3]
+- Updated dependencies [1b1f490]
+  - @objectstack/spec@9.8.0
+
 ## 9.7.0
 
 ### Minor Changes

package/dist/index.d.mts

@@ -24,6 +24,13 @@ import { Environment } from '@marcbachmann/cel-js';
 interface EvalContext {
     /** Logical "now" snapshot — pinned per evaluation run for determinism. */
     now?: Date;
+    /**
+     * Reference timezone (IANA name, e.g. `America/New_York`) for calendar-day
+     * functions `today()` / `daysFromNow()` / `daysAgo()` and for rendering
+     * `datetime` template holes in that zone's wall-clock (ADR-0053 Phase 2).
+     * Defaults to `UTC` when unset. Calendar-day `date` rendering stays tz-naive.
+     */
+    timezone?: string;
     /** Current authenticated subject (hook / action / view contexts). */
     user?: {
         id: string;
@@ -198,6 +205,20 @@ declare const cronEngine: DialectEngine;
 
 /** Public list of whitelisted template formatters (for introspection/docs). */
 declare const TEMPLATE_FORMATTERS: string[];
+/**
+ * Apply a whitelisted formatter to a value, the single source of truth for
+ * value→string semantics across dialects. Returns `undefined` for an unknown
+ * formatter name so callers can decide how to handle it (the template engine
+ * rejects at compile time; other consumers may pass the raw value through).
+ *
+ * Exported so renderers that don't run the full CEL template engine — notably
+ * the email pipeline (ADR-0053 Phase 2 slice 4) — format dates, money, etc.
+ * identically to in-app templates, including reference-timezone `datetime`.
+ */
+declare function formatValue(name: string, value: unknown, arg: string | undefined, opts?: {
+    locale?: string;
+    timeZone?: string;
+}): string | undefined;
 declare const templateEngine: DialectEngine;
 
 /**
@@ -221,7 +242,7 @@ declare const templateEngine: DialectEngine;
  * and dependency-free — they're the contract surface for AI authors and must
  * stay legible.
  */
-declare function registerStdLib(env: Environment, now: () => Date): Environment;
+declare function registerStdLib(env: Environment, now: () => Date, timezone?: string): Environment;
 /**
  * Build the variable scope for a single evaluation. Absent fields are simply
  * not bound — CEL macros (`has(record.foo)`) handle missing-key safely.
@@ -364,7 +385,12 @@ declare function introspectScope(role: FieldRole, schema?: ExprSchemaHint): {
     roots: string[];
     functions: string[];
 };
-/** Public catalog of CEL stdlib functions available in expressions. */
+/**
+ * Public catalog of CEL functions available in expressions — what `introspectScope`
+ * advertises to authors (incl. AI). Every entry MUST actually resolve at runtime:
+ * either registered in `registerStdLib` or a verified cel-js built-in. Drifting this
+ * list ahead of the runtime tells the author to call functions that fault (#1928).
+ */
 declare const CEL_STDLIB_FUNCTIONS: string[];
 
-export { CEL_STDLIB_FUNCTIONS, 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, cronEngine, expectedDialect, getEngine, hasDialect, introspectScope, normalizeExpression, normalizeExpressionTree, register, registerStdLib, resolveSeed, resolveSeedRecord, templateEngine, validateExpression };
+export { CEL_STDLIB_FUNCTIONS, 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, cronEngine, expectedDialect, formatValue, getEngine, hasDialect, introspectScope, normalizeExpression, normalizeExpressionTree, register, registerStdLib, resolveSeed, resolveSeedRecord, templateEngine, validateExpression };

package/dist/index.d.ts

@@ -24,6 +24,13 @@ import { Environment } from '@marcbachmann/cel-js';
 interface EvalContext {
     /** Logical "now" snapshot — pinned per evaluation run for determinism. */
     now?: Date;
+    /**
+     * Reference timezone (IANA name, e.g. `America/New_York`) for calendar-day
+     * functions `today()` / `daysFromNow()` / `daysAgo()` and for rendering
+     * `datetime` template holes in that zone's wall-clock (ADR-0053 Phase 2).
+     * Defaults to `UTC` when unset. Calendar-day `date` rendering stays tz-naive.
+     */
+    timezone?: string;
     /** Current authenticated subject (hook / action / view contexts). */
     user?: {
         id: string;
@@ -198,6 +205,20 @@ declare const cronEngine: DialectEngine;
 
 /** Public list of whitelisted template formatters (for introspection/docs). */
 declare const TEMPLATE_FORMATTERS: string[];
+/**
+ * Apply a whitelisted formatter to a value, the single source of truth for
+ * value→string semantics across dialects. Returns `undefined` for an unknown
+ * formatter name so callers can decide how to handle it (the template engine
+ * rejects at compile time; other consumers may pass the raw value through).
+ *
+ * Exported so renderers that don't run the full CEL template engine — notably
+ * the email pipeline (ADR-0053 Phase 2 slice 4) — format dates, money, etc.
+ * identically to in-app templates, including reference-timezone `datetime`.
+ */
+declare function formatValue(name: string, value: unknown, arg: string | undefined, opts?: {
+    locale?: string;
+    timeZone?: string;
+}): string | undefined;
 declare const templateEngine: DialectEngine;
 
 /**
@@ -221,7 +242,7 @@ declare const templateEngine: DialectEngine;
  * and dependency-free — they're the contract surface for AI authors and must
  * stay legible.
  */
-declare function registerStdLib(env: Environment, now: () => Date): Environment;
+declare function registerStdLib(env: Environment, now: () => Date, timezone?: string): Environment;
 /**
  * Build the variable scope for a single evaluation. Absent fields are simply
  * not bound — CEL macros (`has(record.foo)`) handle missing-key safely.
@@ -364,7 +385,12 @@ declare function introspectScope(role: FieldRole, schema?: ExprSchemaHint): {
     roots: string[];
     functions: string[];
 };
-/** Public catalog of CEL stdlib functions available in expressions. */
+/**
+ * Public catalog of CEL functions available in expressions — what `introspectScope`
+ * advertises to authors (incl. AI). Every entry MUST actually resolve at runtime:
+ * either registered in `registerStdLib` or a verified cel-js built-in. Drifting this
+ * list ahead of the runtime tells the author to call functions that fault (#1928).
+ */
 declare const CEL_STDLIB_FUNCTIONS: string[];
 
-export { CEL_STDLIB_FUNCTIONS, 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, cronEngine, expectedDialect, getEngine, hasDialect, introspectScope, normalizeExpression, normalizeExpressionTree, register, registerStdLib, resolveSeed, resolveSeedRecord, templateEngine, validateExpression };
+export { CEL_STDLIB_FUNCTIONS, 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, cronEngine, expectedDialect, formatValue, getEngine, hasDialect, introspectScope, normalizeExpression, normalizeExpressionTree, register, registerStdLib, resolveSeed, resolveSeedRecord, templateEngine, validateExpression };

package/dist/index.js

@@ -28,6 +28,7 @@ __export(index_exports, {
   celEngine: () => celEngine,
   cronEngine: () => cronEngine,
   expectedDialect: () => expectedDialect,
+  formatValue: () => formatValue,
   getEngine: () => getEngine,
   hasDialect: () => hasDialect,
   introspectScope: () => introspectScope,
@@ -46,26 +47,52 @@ module.exports = __toCommonJS(index_exports);
 var import_cel_js = require("@marcbachmann/cel-js");
 
 // src/stdlib.ts
+function partsInTz(d, tz) {
+  const parts = new Intl.DateTimeFormat("en-US", {
+    timeZone: tz,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit"
+  }).formatToParts(d);
+  const get = (t) => Number(parts.find((p) => p.type === t)?.value);
+  return { y: get("year"), m: get("month"), day: get("day") };
+}
+function calendarDayUtc(d, tz) {
+  if (tz && tz !== "UTC") {
+    try {
+      const { y, m, day } = partsInTz(d, tz);
+      return new Date(Date.UTC(y, m - 1, day));
+    } catch {
+    }
+  }
+  return startOfDayUtc(d);
+}
 function startOfDayUtc(d) {
   const out = new Date(d.getTime());
   out.setUTCHours(0, 0, 0, 0);
   return out;
 }
+function toDate(v) {
+  if (v instanceof Date) return v;
+  if (typeof v === "number" || typeof v === "bigint") return new Date(Number(v));
+  return new Date(String(v));
+}
+var MS_PER_DAY = 864e5;
 function addDaysUtc(d, n) {
   const out = new Date(d.getTime());
   out.setUTCDate(out.getUTCDate() + n);
   return out;
 }
-function registerStdLib(env, now) {
+function registerStdLib(env, now, timezone = "UTC") {
   return env.registerFunction("now(): google.protobuf.Timestamp", () => now()).registerFunction(
     "today(): google.protobuf.Timestamp",
-    () => startOfDayUtc(now())
+    () => calendarDayUtc(now(), timezone)
   ).registerFunction(
     "daysFromNow(int): google.protobuf.Timestamp",
-    (n) => addDaysUtc(now(), Number(n))
+    (n) => addDaysUtc(calendarDayUtc(now(), timezone), Number(n))
   ).registerFunction(
     "daysAgo(int): google.protobuf.Timestamp",
-    (n) => addDaysUtc(now(), -Number(n))
+    (n) => addDaysUtc(calendarDayUtc(now(), timezone), -Number(n))
   ).registerFunction(
     "isBlank(dyn): bool",
     (value) => {
@@ -96,8 +123,20 @@ function registerStdLib(env, now) {
       }
       return parts.join(separator);
     }
+  ).registerFunction(
+    "daysBetween(dyn, dyn): int",
+    (a, b) => BigInt(Math.round((toDate(b).getTime() - toDate(a).getTime()) / MS_PER_DAY))
+  ).registerFunction("date(dyn): google.protobuf.Timestamp", (s) => toDate(s)).registerFunction("datetime(dyn): google.protobuf.Timestamp", (s) => toDate(s)).registerFunction("abs(dyn): double", (x) => Math.abs(Number(x))).registerFunction("round(dyn): int", (x) => BigInt(Math.round(Number(x)))).registerFunction("min(dyn, dyn): dyn", (a, b) => Number(a) <= Number(b) ? a : b).registerFunction("max(dyn, dyn): dyn", (a, b) => Number(a) >= Number(b) ? a : b).registerFunction("upper(dyn): string", (s) => String(s ?? "").toUpperCase()).registerFunction("lower(dyn): string", (s) => String(s ?? "").toLowerCase()).registerFunction("contains(dyn, dyn): bool", (s, sub) => String(s ?? "").includes(String(sub ?? ""))).registerFunction("startsWith(dyn, dyn): bool", (s, p) => String(s ?? "").startsWith(String(p ?? ""))).registerFunction("endsWith(dyn, dyn): bool", (s, p) => String(s ?? "").endsWith(String(p ?? ""))).registerFunction("matches(dyn, dyn): bool", (s, re) => new RegExp(String(re ?? "")).test(String(s ?? ""))).registerFunction("len(dyn): int", (v) => BigInt(lengthOf(v))).registerFunction(
+    "isEmpty(dyn): bool",
+    (v) => v === null || v === void 0 || lengthOf(v) === 0
   );
 }
+function lengthOf(v) {
+  if (v === null || v === void 0) return 0;
+  if (typeof v === "string" || Array.isArray(v)) return v.length;
+  if (typeof v === "object") return Object.keys(v).length;
+  return 0;
+}
 function registerNumericCoercions(env) {
   const ops = {
     "+": (a, b) => a + b,
@@ -135,13 +174,13 @@ var DEFAULT_LIMITS = {
   maxMapEntries: 64,
   maxCallArguments: 16
 };
-function buildEnv(now) {
+function buildEnv(now, timezone = "UTC") {
   const env = new import_cel_js.Environment({
     unlistedVariablesAreDyn: true,
     enableOptionalTypes: true,
     limits: DEFAULT_LIMITS
   });
-  return registerNumericCoercions(registerStdLib(env, now));
+  return registerNumericCoercions(registerStdLib(env, now, timezone));
 }
 var SCOPE_ROOTS = [
   "record",
@@ -287,7 +326,7 @@ var celEngine = {
     }
     const now = () => ctx.now ?? /* @__PURE__ */ new Date();
     try {
-      const env = buildEnv(now);
+      const env = buildEnv(now, ctx.timezone ?? "UTC");
       const scope = buildScope(ctx);
       try {
         const raw = env.evaluate(source, scope);
@@ -427,7 +466,9 @@ var FORMATTERS = {
       maximumFractionDigits: Number.isNaN(digits) ? 0 : digits
     }).format(n);
   },
-  // date | date:long | date:iso  → date-only
+  // date | date:long | date:iso  → date-only. Intentionally tz-naive
+  // (ADR-0053): a `Field.date` is a calendar day with no zone, so rendering
+  // never applies a reference timezone — that would shift the day.
   date: (v, arg, locale) => {
     const d = asDate(v);
     if (!d) return baseString(v);
@@ -435,15 +476,18 @@ var FORMATTERS = {
     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) => {
+  // datetime | datetime:long | datetime:iso. A `datetime` is a UTC instant;
+  // when a reference `timeZone` is supplied (ADR-0053 Phase 2) the wall-clock
+  // styles render in that zone. `iso` stays UTC (machine-readable, unambiguous).
+  datetime: (v, arg, locale, timeZone) => {
     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
+      timeStyle: style,
+      ...timeZone ? { timeZone } : {}
     }).format(d);
   },
   // truncate:80  → cut with an ellipsis
@@ -467,6 +511,11 @@ var FORMATTERS = {
   }
 };
 var TEMPLATE_FORMATTERS = Object.keys(FORMATTERS);
+function formatValue(name, value, arg, opts = {}) {
+  const fmt = FORMATTERS[name];
+  if (!fmt) return void 0;
+  return fmt(value, arg, opts.locale ?? "en-US", opts.timeZone);
+}
 function baseString(value) {
   if (value === null || value === void 0) return "";
   if (value instanceof Date) return value.toISOString();
@@ -552,12 +601,13 @@ var templateEngine = {
     if (!check.ok) return check;
     const scope = buildScope(ctx);
     const locale = ctx.extra && typeof ctx.extra.locale === "string" && ctx.extra.locale || typeof ctx.locale === "string" && ctx.locale || "en-US";
+    const timeZone = typeof ctx.timezone === "string" ? ctx.timezone : void 0;
     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 FORMATTERS[parsed.filter.name](value, parsed.filter.arg, locale, timeZone);
       }
       return baseString(value);
     });
@@ -854,22 +904,20 @@ function introspectScope(role, schema) {
   };
 }
 var CEL_STDLIB_FUNCTIONS = [
+  // Dates (registered stdlib)
   "now",
   "today",
   "daysFromNow",
+  "daysAgo",
   "daysBetween",
   "date",
   "datetime",
-  "timestamp",
-  "isBlank",
-  "isEmpty",
-  "coalesce",
-  "len",
-  "size",
-  "int",
-  "float",
-  "string",
-  "bool",
+  // Numbers (registered stdlib)
+  "abs",
+  "round",
+  "min",
+  "max",
+  // Strings (registered stdlib)
   "upper",
   "lower",
   "trim",
@@ -877,11 +925,21 @@ var CEL_STDLIB_FUNCTIONS = [
   "startsWith",
   "endsWith",
   "matches",
+  "joinNonEmpty",
+  // Collections / null-ish (registered stdlib)
+  "isBlank",
+  "isEmpty",
+  "coalesce",
+  "len",
+  // cel-js built-ins (verified to resolve)
+  "size",
   "has",
-  "min",
-  "max",
-  "abs",
-  "round"
+  "int",
+  "string",
+  "bool",
+  "double",
+  "timestamp",
+  "duration"
 ];
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -893,6 +951,7 @@ var CEL_STDLIB_FUNCTIONS = [
   celEngine,
   cronEngine,
   expectedDialect,
+  formatValue,
   getEngine,
   hasDialect,
   introspectScope,