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|. Because the pipe character breaks Markdown tables, every example below is shown in a fenced code block. 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.

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).

Function	Signature	Required keys	Optional keys
`date`	`(:object)`	`year`, `month`, `day`	—
`dateTime`	`(:object)`	`year`, `month`, `day`	`hour`, `minute`, `second`/`seconds`, `millisecond`, `timeZone`/`timezone`
`localDateTime`	`(:object)`	`year`, `month`, `day`	`hour`, `minute`, `second`/`seconds`, `millisecond`
`localTime`	`(:object)`	`hour`	`minute`, `second`/`seconds`, `millisecond`
`time`	`(:object)`	`hour`	`minute`, `second`/`seconds`, `millisecond`

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 configured reference zone (UTC in these examples). 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. Their output depends on the current date.

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

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.

Function	Signature	Truncates to	Accepts
`atBeginningOfDay`	`(:any)`	midnight (`00:00:00`) of the same day	`DateTime`, `LocalDateTime`
`atBeginningOfHour`	`(:any)`	the top of the hour (`:00:00`)	`DateTime`, `LocalDateTime`
`atBeginningOfMonth`	`(:any)`	the 1st of the month at midnight	`DateTime`, `LocalDateTime`, `Date`
`atBeginningOfWeek`	`(:any)`	Monday of that week at midnight	`DateTime`, `LocalDateTime`, `Date`
`atBeginningOfYear`	`(:any)`	January 1 at midnight	`DateTime`, `LocalDateTime`, `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"

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.