@objectstack/formula 9.7.0 → 9.9.0

package/src/skill-catalog-sync.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+import { CEL_STDLIB_FUNCTIONS } from './validate';
+
+/**
+ * Drift-guard (#1928 follow-up): the objectstack-formula authoring skill is what
+ * the AI author reads to know which CEL functions exist. It MUST stay in sync
+ * with the runtime catalog — a function advertised in the catalog but missing
+ * from the skill means the AI never reaches for it; one in the skill but not the
+ * catalog means the AI calls a function that faults the build. This pins the
+ * skill ↔ `CEL_STDLIB_FUNCTIONS` mapping so neither drifts silently again
+ * (mirrors the runtime drift-guard in cel-engine.test.ts).
+ */
+describe('objectstack-formula skill ↔ CEL_STDLIB_FUNCTIONS', () => {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const skillPath = resolve(here, '../../../skills/objectstack-formula/SKILL.md');
+  const skill = readFileSync(skillPath, 'utf8');
+
+  it('documents every advertised stdlib function', () => {
+    // A function is "documented" if its name appears as `` `name(` `` (a call
+    // form) anywhere in the skill — robust to table layout / grouping changes.
+    const missing = CEL_STDLIB_FUNCTIONS.filter((fn) => !skill.includes(`\`${fn}(`));
+    expect(
+      missing,
+      `These CEL_STDLIB_FUNCTIONS are not documented in skills/objectstack-formula/SKILL.md:\n` +
+        `${missing.join(', ')}\nAdd them to the stdlib table so AI authors know they exist.`,
+    ).toEqual([]);
+  });
+});

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());
@@ -22,6 +56,16 @@ function startOfDayUtc(d: Date): Date {
   return out;
 }
 
+/** Coerce a CEL value (Date | ISO string | epoch number) to a Date. */
+function toDate(v: unknown): Date {
+  if (v instanceof Date) return v;
+  if (typeof v === 'number' || typeof v === 'bigint') return new Date(Number(v));
+  return new Date(String(v));
+}
+
+/** One UTC day in milliseconds. */
+const MS_PER_DAY = 86_400_000;
+
 /** Add `n` days to a Date in UTC; returns a new Date. */
 function addDaysUtc(d: Date, n: number): Date {
   const out = new Date(d.getTime());
@@ -40,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.
@@ -101,9 +150,58 @@ export function registerStdLib(
         }
         return parts.join(separator);
       },
+    )
+    // ── Dates ────────────────────────────────────────────────────────────
+    // Whole days from `a` to `b` (negative if `b` is before `a`). The common
+    // shape is `daysBetween(today(), record.due)` for "days remaining". Args are
+    // coerced (Date | ISO string | epoch) so a `Field.date` that arrives as a
+    // string still works without the caller hydrating it.
+    .registerFunction(
+      'daysBetween(dyn, dyn): int',
+      (a: unknown, b: unknown) =>
+        BigInt(Math.round((toDate(b).getTime() - toDate(a).getTime()) / MS_PER_DAY)),
+    )
+    // Parse an ISO date / date-time string to a Timestamp. `date` and `datetime`
+    // are aliases — both accept either form (the field's own type decides the
+    // intent); kept distinct because authors reach for whichever reads clearer.
+    .registerFunction('date(dyn): google.protobuf.Timestamp', (s: unknown) => toDate(s))
+    .registerFunction('datetime(dyn): google.protobuf.Timestamp', (s: unknown) => toDate(s))
+    // ── Numbers ──────────────────────────────────────────────────────────
+    .registerFunction('abs(dyn): double', (x: unknown) => Math.abs(Number(x)))
+    .registerFunction('round(dyn): int', (x: unknown) => BigInt(Math.round(Number(x))))
+    // min/max return the smaller/larger operand verbatim (type preserved) rather
+    // than a coerced copy, so `min(record.a, record.b)` keeps int-ness when both
+    // are ints. Comparison is numeric.
+    .registerFunction('min(dyn, dyn): dyn', (a: unknown, b: unknown) => (Number(a) <= Number(b) ? a : b))
+    .registerFunction('max(dyn, dyn): dyn', (a: unknown, b: unknown) => (Number(a) >= Number(b) ? a : b))
+    // ── Strings ──────────────────────────────────────────────────────────
+    // Free-function forms of the common string ops. CEL also exposes some as
+    // receiver methods (`s.contains(x)`), but the authoring catalog advertises
+    // the bare-call form, so register it to match what authors are told to use.
+    .registerFunction('upper(dyn): string', (s: unknown) => String(s ?? '').toUpperCase())
+    .registerFunction('lower(dyn): string', (s: unknown) => String(s ?? '').toLowerCase())
+    .registerFunction('contains(dyn, dyn): bool', (s: unknown, sub: unknown) => String(s ?? '').includes(String(sub ?? '')))
+    .registerFunction('startsWith(dyn, dyn): bool', (s: unknown, p: unknown) => String(s ?? '').startsWith(String(p ?? '')))
+    .registerFunction('endsWith(dyn, dyn): bool', (s: unknown, p: unknown) => String(s ?? '').endsWith(String(p ?? '')))
+    .registerFunction('matches(dyn, dyn): bool', (s: unknown, re: unknown) => new RegExp(String(re ?? '')).test(String(s ?? '')))
+    // ── Collections ──────────────────────────────────────────────────────
+    // `len` mirrors CEL's built-in `size()` for strings/lists/maps; `isEmpty` is
+    // the inverse-of-non-empty companion to `isBlank` (true for null, '', []).
+    .registerFunction('len(dyn): int', (v: unknown) => BigInt(lengthOf(v)))
+    .registerFunction(
+      'isEmpty(dyn): bool',
+      (v: unknown) => v === null || v === undefined || lengthOf(v) === 0,
     );
 }
 
+/** Length of a string / list / map (0 for scalars and null). */
+function lengthOf(v: unknown): number {
+  if (v === null || v === undefined) return 0;
+  if (typeof v === 'string' || Array.isArray(v)) return v.length;
+  if (typeof v === 'object') return Object.keys(v as Record<string, unknown>).length;
+  return 0;
+}
+
 /**
  * Register mixed `double <op> int` / `int <op> double` arithmetic overloads.
  *

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;

package/src/validate.ts

@@ -256,10 +256,21 @@ export function introspectScope(role: FieldRole, schema?: ExprSchemaHint): {
   };
 }
 
-/** 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).
+ */
 export const CEL_STDLIB_FUNCTIONS: string[] = [
-  'now', 'today', 'daysFromNow', 'daysBetween', 'date', 'datetime', 'timestamp',
-  'isBlank', 'isEmpty', 'coalesce', 'len', 'size', 'int', 'float', 'string', 'bool',
-  'upper', 'lower', 'trim', 'contains', 'startsWith', 'endsWith', 'matches',
-  'has', 'min', 'max', 'abs', 'round',
+  // Dates (registered stdlib)
+  'now', 'today', 'daysFromNow', 'daysAgo', 'daysBetween', 'date', 'datetime',
+  // Numbers (registered stdlib)
+  'abs', 'round', 'min', 'max',
+  // Strings (registered stdlib)
+  'upper', 'lower', 'trim', 'contains', 'startsWith', 'endsWith', 'matches', 'joinNonEmpty',
+  // Collections / null-ish (registered stdlib)
+  'isBlank', 'isEmpty', 'coalesce', 'len',
+  // cel-js built-ins (verified to resolve)
+  'size', 'has', 'int', 'string', 'bool', 'double', 'timestamp', 'duration',
 ];