Time

Timestamps and durations. Calendar functions take an optional IANA time zone as their last argument and default to UTC. The examples on this page run with the clock fixed at 2026-01-15T10:30:00.000Z, so now() returns that instant.

Every function can be called as f(x, ...) or as a method, x.f(...). In the signatures, T and U stand for any type, T[] is a list, ? marks an optional parameter, and (T, number) => boolean is a lambda parameter.

Function	Description
now	The current time, fixed for one evaluation.
timestamp	Parses ISO-8601 text or epoch milliseconds into a timestamp.
duration	Parses ISO-8601 duration text in weeks, days, hours, minutes, and seconds (e.g. "PT1H30M", "-P2DT0.5S"), the text a duration renders as.
weeks	A duration of n weeks.
days	A duration of n days (24 hours each).
hours	A duration of n hours.
minutes	A duration of n minutes.
seconds	A duration of n seconds.
milliseconds	A duration of n milliseconds. Durations are whole milliseconds: a fraction rounds to the nearest one, halves away from zero.
inDays	A duration as a (fractional) number of days.
inHours	A duration as a number of hours.
inMinutes	A duration as a number of minutes.
inSeconds	A duration as a number of seconds.
inMilliseconds	A duration as a number of milliseconds.
year	The calendar year, in a time zone (default UTC).
month	The month 1-12, in a time zone (default UTC).
day	The day of the month, in a time zone (default UTC).
hour	The hour 0-23, in a time zone (default UTC).
minute	The minute, in a time zone (default UTC).
second	The second, in a time zone (default UTC).
dayOfWeek	The ISO weekday (Monday 1 to Sunday 7), in a time zone (default UTC).
startOfDay	Midnight at the start of the day, in a time zone (default UTC).
startOfMonth	Midnight on the first of the month, in a time zone (default UTC).
startOfYear	Midnight on January 1, in a time zone (default UTC).
addDays	Adds calendar days (keeps the wall-clock time across DST), in a time zone.
addMonths	Adds calendar months, clamping the day to the month length.
addYears	Adds calendar years (Feb 29 becomes Feb 28).
formatDate	Formats a timestamp in a time zone (default UTC). Tokens: yyyy yy MMMM MMM MM M dd d EEEE EEE HH H hh h a mm m ss s SSS; quote literal text.
abs	Absolute value.
sum	The sum of the numbers in a list (nulls are skipped), added left to right as a + b + c is.

now

The current time, fixed for one evaluation.

• now(): timestamp

now() // => 2026-01-15T10:30:00.000Z

timestamp

Parses ISO-8601 text or epoch milliseconds into a timestamp.

• timestamp(string): timestamp
• timestamp(number): timestamp
• timestamp(timestamp): timestamp

timestamp("2026-03-01T12:00:00Z") // => 2026-03-01T12:00:00.000Z
timestamp("2026-03-01") // => 2026-03-01T00:00:00.000Z
timestamp("2026-03-01T12:00:00+02:00") // => 2026-03-01T10:00:00.000Z
timestamp(0) // => 1970-01-01T00:00:00.000Z

duration

Parses ISO-8601 duration text in weeks, days, hours, minutes, and seconds (e.g. "PT1H30M", "-P2DT0.5S"), the text a duration renders as.

• duration(string): duration
• duration(duration): duration

duration("PT1H30M") // => PT1H30M
duration("-P2DT0.5S") // => -P2DT0.5S
duration("P1W") == weeks(1) // => true

weeks

A duration of n weeks.

• weeks(number): duration

weeks(2) // => P14D

days

A duration of n days (24 hours each).

• days(number): duration

days(3) // => P3D
now() + days(30) // => 2026-02-14T10:30:00.000Z

hours

A duration of n hours.

• hours(number): duration

hours(1.5) // => PT1H30M

minutes

A duration of n minutes.

• minutes(number): duration

minutes(90) // => PT1H30M

seconds

A duration of n seconds.

• seconds(number): duration

seconds(0.5) // => PT0.5S

milliseconds

A duration of n milliseconds. Durations are whole milliseconds: a fraction rounds to the nearest one, halves away from zero.

• milliseconds(number): duration

milliseconds(1500) // => PT1.5S
milliseconds(0.5) == milliseconds(1) // => true

inDays

A duration as a (fractional) number of days.

• inDays(duration): number

inDays(hours(36)) // => 1.5
inDays(now() - timestamp("2026-01-01T00:00:00Z")) // => 14.4375

inHours

A duration as a number of hours.

• inHours(duration): number

days(2).inHours() // => 48

inMinutes

A duration as a number of minutes.

• inMinutes(duration): number

hours(1).inMinutes() // => 60

inSeconds

A duration as a number of seconds.

• inSeconds(duration): number

minutes(2).inSeconds() // => 120

inMilliseconds

A duration as a number of milliseconds.

• inMilliseconds(duration): number

seconds(1).inMilliseconds() // => 1000

year

The calendar year, in a time zone (default UTC).

• year(timestamp, string?): number

year(now()) // => 2026

month

The month 1-12, in a time zone (default UTC).

• month(timestamp, string?): number

month(now()) // => 1

day

The day of the month, in a time zone (default UTC).

• day(timestamp, string?): number

day(now()) // => 15

hour

The hour 0-23, in a time zone (default UTC).

• hour(timestamp, string?): number

hour(now()) // => 10
hour(now(), "America/New_York") // => 5
now().hour("Asia/Tokyo") // => 19

minute

The minute, in a time zone (default UTC).

• minute(timestamp, string?): number

minute(now()) // => 30

second

The second, in a time zone (default UTC).

• second(timestamp, string?): number

second(now()) // => 0

dayOfWeek

The ISO weekday (Monday 1 to Sunday 7), in a time zone (default UTC).

• dayOfWeek(timestamp, string?): number

dayOfWeek(now()) // => 4

startOfDay

Midnight at the start of the day, in a time zone (default UTC).

• startOfDay(timestamp, string?): timestamp

startOfDay(now()) // => 2026-01-15T00:00:00.000Z
startOfDay(now(), "Europe/Berlin") // => 2026-01-14T23:00:00.000Z

startOfMonth

Midnight on the first of the month, in a time zone (default UTC).

• startOfMonth(timestamp, string?): timestamp

startOfMonth(now()) // => 2026-01-01T00:00:00.000Z

startOfYear

Midnight on January 1, in a time zone (default UTC).

• startOfYear(timestamp, string?): timestamp

startOfYear(now()) // => 2026-01-01T00:00:00.000Z

addDays

Adds calendar days (keeps the wall-clock time across DST), in a time zone.

• addDays(timestamp, number, string?): timestamp

addDays(timestamp("2026-03-28T12:00:00Z"), 2, "Europe/Berlin") // => 2026-03-30T11:00:00.000Z
timestamp("2026-03-28T12:00:00Z") + days(2) // => 2026-03-30T12:00:00.000Z

addMonths

Adds calendar months, clamping the day to the month length.

• addMonths(timestamp, number, string?): timestamp

addMonths(timestamp("2026-01-31T00:00:00Z"), 1) // => 2026-02-28T00:00:00.000Z

addYears

Adds calendar years (Feb 29 becomes Feb 28).

• addYears(timestamp, number, string?): timestamp

addYears(timestamp("2024-02-29T00:00:00Z"), 1) // => 2025-02-28T00:00:00.000Z

formatDate

Formats a timestamp in a time zone (default UTC). Tokens: yyyy yy MMMM MMM MM M dd d EEEE EEE HH H hh h a mm m ss s SSS; quote literal text.

• formatDate(timestamp, string, string?): string

formatDate(now(), "yyyy-MM-dd HH:mm") // => "2026-01-15 10:30"
now().formatDate("dd/MM/yyyy HH:mm", "Asia/Tokyo") // => "15/01/2026 19:30"

abs

Absolute value.

• abs(duration): duration

abs(hours(-2)) // => PT2H

sum

The sum of the numbers in a list (nulls are skipped), added left to right as a + b + c is.

• sum((duration | null)[]): duration

[hours(1), minutes(30)].sum() // => PT1H30M