Dates & Times

The Dates & Times category holds functions for building temporal values and truncating them to a boundary. They operate on TransformScript's first-class temporal types — Date, DateTime, LocalDateTime, and LocalTime/Time — never on strings that merely look like dates.

Each is callable in prefix form fn(x) or postfix/UFCS form x fn().

Where the Duration Math Lives. Adding or subtracting time uses a Period and the + / - operators (|2021-03-02T10:39:59| - |P1D| → |2021-03-01T10:39:59|), not a function in this category. Period constructors and between are documented in Periods.

Reading the Examples. Temporal literals are written between pipes — |2024-05-01|, |2024-05-15T13:45:30-07:00|. The results are rendered with as String, which formats each temporal type as ISO-8601; in a real script you would keep the temporal value and do further math on it. The now-style functions (today, tomorrow, yesterday) depend on the current date, so their outputs below are representative.

Reference Time Zone

The reference zone is the default time zone used when a script runs. TransformScript uses UTC consistently in Transform File, Automations v2 templates, conditions, and Transform nodes, and both modes of Expectation Content Validation. This keeps a script's date calculations consistent when you test it in one context and use it in another.

UTC determines the calendar date returned by today(), tomorrow(), and yesterday(), the zone of now(), and how dateTime interprets components when you omit timeZone. Numeric timestamps converted to Date or DateTime also use UTC unless you supply a timeZone option.

The reference zone is fixed. The site's Default Timezone, a user's display time zone, and the time zone of an Automation or Expectation schedule do not change it. A schedule's time zone determines when the work runs; the reference zone determines the date and time used by these functions during execution.

The calendar date changes at midnight UTC. At 2024-05-01T02:00:00Z, today() returns |2024-05-01| even though it is still April 30 in US Eastern time. For a business date that must use a particular zone, select it explicitly as shown under today / tomorrow / yesterday.

Constructors

Each constructor takes a single Object whose keys supply the components — there is no positional date(2024, 5, 1) form. Keys are read by name, missing required keys raise, and every supplied component must be an integer (a non-integer like 1.5 raises).

Notes that apply across the constructors:

• time is an alias for localTime — same underlying LocalTime/Time type, same arguments.
• Time components default to 0 when omitted, so dateTime and localDateTime need only the date keys; localTime/time need only hour.
• Component ranges are validated: hour 0–23, minute/second 0–59, millisecond 0–999. Out-of-range values raise (e.g. localTime({ hour: 25 }) → "localTime expects hour between 0 and 23").
• dateTime interprets its components in the zone given by timeZone (or timezone); with no zone it uses the UTC reference zone. Setting timeZone affects that value only; it does not change the reference zone for other calls. localDateTime, localTime, and time carry no zone.

date

Builds a calendar Date (no time, no zone).

date({ year: 2024, month: 5, day: 1 }) as String
// "2024-05-01"

dateTime

Builds a zoned DateTime. Time components default to 0; an optional timeZone sets the zone the components are read in.

dateTime({ year: 2024, month: 5, day: 1, hour: 13, minute: 30 }) as String
// "2024-05-01T13:30:00Z"

dateTime({ year: 2024, month: 5, day: 1, hour: 13, timeZone: "America/New_York" }) as String
// "2024-05-01T13:00:00-04:00"

localDateTime

Builds a LocalDateTime — a date and time of day with no zone.

localDateTime({ year: 2024, month: 5, day: 1, hour: 13, minute: 30, second: 45 }) as String
// "2024-05-01T13:30:45"

localTime

Builds a LocalTime (wall-clock time of day). hour is required; a millisecond becomes a fractional second.

localTime({ hour: 13, minute: 30, second: 45 }) as String
// "13:30:45"

localTime({ hour: 9, minute: 5, second: 1, millisecond: 250 }) as String
// "09:05:01.25"

time

Alias for localTime — identical arguments and result type.

time({ hour: 9, minute: 5 }) as String
// "09:05:00"

today / tomorrow / yesterday

These take no arguments and return today's, tomorrow's, or yesterday's calendar Date in the reference zone. The date changes at midnight in that zone. A returned Date contains no time or zone; the reference zone determines which calendar day it represents.

today()      // a Date, e.g. |2026-06-30|
tomorrow()   // a Date, e.g. |2026-07-01|
yesterday()  // a Date, e.g. |2026-06-29|

To calculate these dates for a particular business time zone, convert now() to that zone with toDateTime, then extract its date with toDate. Use a named zone such as America/New_York so daylight saving changes are applied. Add or subtract a one-day Period to obtain the adjacent dates:

%files 1.0
output json
var businessDate = toDate(toDateTime(now(), "America/New_York"))
---
{
  today: businessDate,
  tomorrow: businessDate + |P1D|,
  yesterday: businessDate - |P1D|
}

At 2024-05-01T02:00:00Z, this script produces "2024-04-30", "2024-05-01", and "2024-04-29" respectively in all three execution contexts.

Truncation (atBeginningOf…)

The atBeginningOf… helpers round a temporal down to the start of a day, hour, month, week, or year, returning the same type they were given. They accept a DateTime, a LocalDateTime, or (where a time-of-day component would be meaningless) a Date.

• Weeks start on Monday — atBeginningOfWeek of a Wednesday returns the preceding Monday.
• atBeginningOfDay and atBeginningOfHour need a time of day, so they raise on a bare Date. The month/week/year helpers accept a Date and return a Date.
• A DateTime keeps its zone; a Date/LocalDateTime result stays zoneless.

On a DateTime (here |2024-05-15T13:45:30-07:00|, a Wednesday):

|2024-05-15T13:45:30-07:00| atBeginningOfDay()   as String  // "2024-05-15T00:00:00-07:00"
|2024-05-15T13:45:30-07:00| atBeginningOfHour()  as String  // "2024-05-15T13:00:00-07:00"
|2024-05-15T13:45:30-07:00| atBeginningOfMonth() as String  // "2024-05-01T00:00:00-07:00"
|2024-05-15T13:45:30-07:00| atBeginningOfWeek()  as String  // "2024-05-13T00:00:00-07:00"
|2024-05-15T13:45:30-07:00| atBeginningOfYear()  as String  // "2024-01-01T00:00:00-07:00"

On a bare Date (the month/week/year helpers return a Date):

|2024-05-15| atBeginningOfMonth() as String  // "2024-05-01"
|2024-05-15| atBeginningOfWeek()  as String  // "2024-05-13"
|2024-05-15| atBeginningOfYear()  as String  // "2024-01-01"

Prefix and UFCS forms are equivalent:

atBeginningOfMonth(|2024-05-15|) as String   // "2024-05-01"
|2024-05-15| atBeginningOfMonth() as String  // "2024-05-01"

Related

• Periods — duration constructors and between; Periods apply to these temporals via + and -.
• Coercions — toDate, toDateTime, toLocalDateTime, toTime, and toString.
• Types & Coercion — the temporal types and how as String { format: … } formats them.
• Function Library — all categories.