@objectstack/formula 9.8.0 → 9.9.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/formula@9.8.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     29.77 KB
-CJS dist/index.js.map 78.89 KB
-CJS ⚡️ Build success in 123ms
-ESM dist/index.mjs     28.04 KB
-ESM dist/index.mjs.map 77.53 KB
-ESM ⚡️ Build success in 124ms
+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 4371ms
-DTS dist/index.d.mts 15.71 KB
-DTS dist/index.d.ts  15.71 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,39 @@
 # @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

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.
@@ -372,4 +393,4 @@ declare function introspectScope(role: FieldRole, schema?: ExprSchemaHint): {
  */
 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.
@@ -372,4 +393,4 @@ declare function introspectScope(role: FieldRole, schema?: ExprSchemaHint): {
  */
 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,6 +47,26 @@ 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);
@@ -62,16 +83,16 @@ function addDaysUtc(d, n) {
   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) => {
@@ -153,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",
@@ -305,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);
@@ -445,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);
@@ -453,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
@@ -485,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();
@@ -570,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);
     });
@@ -919,6 +951,7 @@ var CEL_STDLIB_FUNCTIONS = [
   celEngine,
   cronEngine,
   expectedDialect,
+  formatValue,
   getEngine,
   hasDialect,
   introspectScope,