@objectstack/formula 9.8.0 → 9.9.0

package/src/stdlib.ts

@@ -15,6 +15,40 @@ import type { Environment } from '@marcbachmann/cel-js';
 
 import type { EvalContext } from './types';
 
+/**
+ * Calendar-day parts (y/m/d) of an instant *as seen in a timezone*
+ * (ADR-0053 Phase 2). Uses `Intl.DateTimeFormat` so DST transitions are
+ * handled correctly — never hand-rolled offset math. An unknown zone throws,
+ * which the caller treats as a fall-through to UTC.
+ */
+function partsInTz(d: Date, tz: string): { y: number; m: number; day: number } {
+  const parts = new Intl.DateTimeFormat('en-US', {
+    timeZone: tz, year: 'numeric', month: '2-digit', day: '2-digit',
+  }).formatToParts(d);
+  const get = (t: string) => Number(parts.find((p) => p.type === t)?.value);
+  return { y: get('year'), m: get('month'), day: get('day') };
+}
+
+/**
+ * The calendar day of an instant *in a reference timezone*, expressed as a
+ * UTC-midnight `Date` (ADR-0053 Phase 2, decision D1). This is the one
+ * representation consistent with how `Field.date` strings hydrate (UTC
+ * midnight), how the SQL driver normalizes date filters, and how Phase 1
+ * stores dates — so `record.date == today()` compares cleanly. Falls back to
+ * the UTC calendar day for `UTC` or an invalid zone.
+ */
+function calendarDayUtc(d: Date, tz: string): Date {
+  if (tz && tz !== 'UTC') {
+    try {
+      const { y, m, day } = partsInTz(d, tz);
+      return new Date(Date.UTC(y, m - 1, day));
+    } catch {
+      // unknown zone → fall through to UTC
+    }
+  }
+  return startOfDayUtc(d);
+}
+
 /** Truncate a Date to start-of-day in UTC. */
 function startOfDayUtc(d: Date): Date {
   const out = new Date(d.getTime());
@@ -50,20 +84,25 @@ function addDaysUtc(d: Date, n: number): Date {
 export function registerStdLib(
   env: Environment,
   now: () => Date,
+  timezone = 'UTC',
 ): Environment {
+  // `today()` / `daysFromNow()` / `daysAgo()` are calendar-day functions: they
+  // resolve to the reference-tz calendar day expressed as a UTC-midnight Date
+  // (ADR-0053 Phase 2 D1), never an instant carrying wall-clock time. For a
+  // genuine sub-day offset use `now() + duration("Nh")`.
   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: bigint | number) => addDaysUtc(now(), Number(n)),
+      (n: bigint | number) => addDaysUtc(calendarDayUtc(now(), timezone), Number(n)),
     )
     .registerFunction(
       'daysAgo(int): google.protobuf.Timestamp',
-      (n: bigint | number) => addDaysUtc(now(), -Number(n)),
+      (n: bigint | number) => addDaysUtc(calendarDayUtc(now(), timezone), -Number(n)),
     )
     // Returns true when `value` is null, undefined, empty string, or empty list.
     // Matches the intent of legacy `ISBLANK()` while staying CEL-idiomatic.

package/src/template-engine.ts

@@ -32,7 +32,12 @@ const HOLE_RE = /\{\{([^}]*)\}\}/g;
 
 // ───────────────────────── formatter whitelist (ADR-0032 §3) ──────────────
 
-type Formatter = (value: unknown, arg: string | undefined, locale: string) => string;
+type Formatter = (
+  value: unknown,
+  arg: string | undefined,
+  locale: string,
+  timeZone?: string,
+) => string;
 
 function asNumber(v: unknown): number | undefined {
   if (typeof v === 'number') return v;
@@ -85,7 +90,9 @@ const FORMATTERS: Record<string, Formatter> = {
       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);
@@ -93,8 +100,10 @@ const FORMATTERS: Record<string, Formatter> = {
     const style = arg === 'long' ? 'long' : arg === 'medium' ? 'medium' : 'short';
     return new Intl.DateTimeFormat(locale, { dateStyle: style as 'short' | 'medium' | 'long' }).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();
@@ -102,6 +111,7 @@ const FORMATTERS: Record<string, Formatter> = {
     return new Intl.DateTimeFormat(locale, {
       dateStyle: style as 'short' | 'medium' | 'long',
       timeStyle: style as 'short' | 'medium' | 'long',
+      ...(timeZone ? { timeZone } : {}),
     }).format(d);
   },
   // truncate:80  → cut with an ellipsis
@@ -124,6 +134,27 @@ const FORMATTERS: Record<string, Formatter> = {
 /** Public list of whitelisted template formatters (for introspection/docs). */
 export const TEMPLATE_FORMATTERS: string[] = Object.keys(FORMATTERS);
 
+/**
+ * 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`.
+ */
+export function formatValue(
+  name: string,
+  value: unknown,
+  arg: string | undefined,
+  opts: { locale?: string; timeZone?: string } = {},
+): string | undefined {
+  const fmt = FORMATTERS[name];
+  if (!fmt) return undefined;
+  return fmt(value, arg, opts.locale ?? 'en-US', opts.timeZone);
+}
+
 function baseString(value: unknown): string {
   if (value === null || value === undefined) return '';
   if (value instanceof Date) return value.toISOString();
@@ -234,13 +265,16 @@ export const templateEngine: DialectEngine = {
       (ctx.extra && typeof ctx.extra.locale === 'string' && ctx.extra.locale) ||
       (typeof (ctx as { locale?: string }).locale === 'string' && (ctx as { locale?: string }).locale) ||
       'en-US';
+    // Reference timezone for `datetime` rendering (ADR-0053 Phase 2). Unset →
+    // Intl uses the runtime zone, matching pre-Phase-2 behavior.
+    const timeZone = typeof ctx.timezone === 'string' ? ctx.timezone : undefined;
 
     const out = expr.source.replace(HOLE_RE, (_match, inner) => {
       const parsed = parseHole(String(inner));
       if (!parsed) return _match; // compile already validated; defensive
       const value = resolvePath(scope, parsed.path);
       if (parsed.filter) {
-        return FORMATTERS[parsed.filter.name](value, parsed.filter.arg, locale as string);
+        return FORMATTERS[parsed.filter.name](value, parsed.filter.arg, locale as string, timeZone);
       }
       return baseString(value);
     });

package/src/template-formatters.test.ts

@@ -1,8 +1,11 @@
 import { describe, it, expect } from 'vitest';
-import { templateEngine, TEMPLATE_FORMATTERS } from './template-engine';
+import { templateEngine, TEMPLATE_FORMATTERS, formatValue } from './template-engine';
 
-function render(source: string, record: Record<string, unknown>): string {
-  const r = templateEngine.evaluate<string>({ dialect: 'template', source }, { record, extra: { locale: 'en-US' } });
+function render(source: string, record: Record<string, unknown>, timezone?: string): string {
+  const r = templateEngine.evaluate<string>(
+    { dialect: 'template', source },
+    { record, extra: { locale: 'en-US' }, ...(timezone ? { timezone } : {}) },
+  );
   if (!r.ok) throw new Error(r.error.message);
   return r.value;
 }
@@ -30,6 +33,36 @@ describe('template formatters (ADR-0032 §3)', () => {
     expect(render('{{ record.d | date:iso }}', { d: '2026-06-02T10:00:00Z' })).toBe('2026-06-02');
   });
 
+  // ADR-0053 Phase 2: datetime renders in the reference timezone.
+  describe('datetime in a reference timezone', () => {
+    // 2026-06-02T01:30Z is 2026-06-01 21:30 in America/New_York (EDT, -4).
+    const ts = '2026-06-02T01:30:00Z';
+
+    it('renders the wall-clock of the reference zone for styled output', () => {
+      const ny = render('{{ record.t | datetime }}', { t: ts }, 'America/New_York');
+      expect(ny).toContain('6/1/26'); // shifted back a day in NY
+      const utc = render('{{ record.t | datetime }}', { t: ts }, 'UTC');
+      expect(utc).toContain('6/2/26'); // same instant, UTC calendar day
+    });
+
+    it('keeps `iso` machine-readable (always UTC) regardless of zone', () => {
+      expect(render('{{ record.t | datetime:iso }}', { t: ts }, 'America/New_York'))
+        .toBe('2026-06-02T01:30:00.000Z');
+    });
+
+    it('leaves calendar-day `date` tz-naive (criterion 3)', () => {
+      // date:iso is UTC-sliced and must not move under a negative-offset zone.
+      expect(render('{{ record.d | date:iso }}', { d: '2026-06-02' }, 'America/New_York'))
+        .toBe('2026-06-02');
+    });
+
+    it('formatValue is reusable with an explicit timeZone (email pipeline path)', () => {
+      const out = formatValue('datetime', ts, undefined, { locale: 'en-US', timeZone: 'UTC' });
+      expect(out).toContain('6/2/26');
+      expect(formatValue('bogus', ts, undefined, {})).toBeUndefined();
+    });
+  });
+
   it('truncate + upper + default', () => {
     expect(render('{{ record.s | truncate:5 }}', { s: 'abcdefgh' })).toBe('abcd…');
     expect(render('{{ record.s | upper }}', { s: 'hi' })).toBe('HI');

package/src/types.ts

@@ -23,6 +23,13 @@ import type { Expression } from '@objectstack/spec';
 export 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;