time

dates, durations, date math, relative text

Example results generated on 2026-10-08. Ones using now, today or randomness will differ when you run them: press Run on any example to run it in your browser, after editing it if you like.

types

# date
date("2026-12-25 18:30")
# → 2026-12-25 18:30:00 -06:00
# time of day: today at that time
9:30 + 45 min
# → 2026-10-08 10:15:00 -05:00
# duration
1h30m
# → 90 min

names

# now today tomorrow yesterday

pretty

# long date: time always shown
pretty(date("2026-12-25"))
# → "Friday, December 25, 2026 at 12:00 AM"
# short date
pretty(date("2026-12-25 18:30"), "short")
# → "Dec 25, 2026, 6:30 PM"
# other zones add theirs
pretty(date("2026-12-25 18:30") to "Asia/Tokyo")
# → "Saturday, December 26, 2026 at 9:30 AM JST"
# long duration: up to 3 of d h min s
pretty(5000 s)
# → "1 h 23 min 20 s"
# short duration: up to 2
pretty(5000 s, "short")
# → "1 h 23 min"

operators

# date ± time
date("2026-01-31") + 1 mo
# → 2026-02-28
# date - date
date("2027-01-01") - date("2026-12-25")
# → 7 d
# "time" - "time"
"17:00" - "08:45"
# → 8.25 h
# date < date
yesterday < now
# → true

conversions

# to unix, to unix_ms
date("2026-12-25") to unix
# → 1798178400
# to date
"2026-12-25" to date
# → 2026-12-25

Submodules

Functions

date

date(s: str) / date(s: str, fmt: str) / date(y: int, m: int, d: int, h?: int, min?: int, s?: int) / date(unix: int): parse ISO, US (12/25/2026), written (Dec 25 2026) or natural language dates

date("2026-12-25")
# → 2026-12-25
date("next friday at 5pm")
# → 2026-10-09 17:00:00 -05:00
date("3 days ago")
# → 2026-10-05 00:29:18 -05:00
date("25.12.2026", "%d.%m.%Y")
# → 2026-12-25
date(2026, 12, 25, 18, 30)
# → 2026-12-25 18:30:00 -06:00
date(0)
# → 1969-12-31 18:00:00 -06:00

See also: format, with, start_of

year

year(d: date): year of a date

now.year
# → 2026

See also: month, day

month

month(d: date): month of a date (1-12)

now.month
# → 10

See also: year, day

day

day(d: date): day of the month

now.day
# → 8

See also: month, weekday

hour

hour(d: date): hour of a date

now.hour
# → 0

See also: minute, second

minute

minute(d: date): minute of a date

now.minute
# → 29

See also: hour, second

second

second(d: date): second of a date

now.second
# → 18

See also: hour, minute

weekday

weekday(d: date): day name

date("2026-12-25").weekday
# → "Friday"

See also: day, format

format

format(d: date, fmt: str) / format(fmt: str, args?: any, ...): format a date with strftime codes, or numbers printf-style

now.format("%B %d, %Y")
# → "October 08, 2026"
now.format("%H:%M")
# → "00:29"
format("%5.2f%%", 12.345)
# → "12.35%"

See also: date, fixed

with

with(d: date, fields: map): same date with fields replaced: year month day hour minute second

today.with({day: 1})
# → 2026-10-01
now.with({hour: 9, minute: 0})
# → 2026-10-08 09:00:18 -05:00

See also: start_of, date

is_weekend

is_weekend(d: date): Saturday or Sunday

date("2026-10-10").is_weekend
# → true

See also: is_weekday, add_workdays

is_weekday

is_weekday(d: date): Monday through Friday

today.is_weekday
# → true

See also: is_weekend

is_today

is_today(d: date): same calendar day as now

now.is_today
# → true
tomorrow.is_today
# → false

See also: is_past

is_past

is_past(d: date): before now

yesterday.is_past
# → true

See also: is_future, is_today

is_future

is_future(d: date): after now

tomorrow.is_future
# → true

See also: is_past

age

age(d: date): whole years since d

date("1990-06-15").age
# → 36

See also: diff

diff

diff(a: date, b: date): calendar difference from a to b

diff(date("2025-08-03"), date("2026-10-06 04:00"))
# → "1 yr 2 mo 3 d 4 h"

See also: age, relative, parts

relative

relative(d: date): “in 3 days”, “2 hours ago”

date("2026-12-25").relative
# → "in 3 months"
(now - 3 h).relative
# → "3 hours ago"

See also: diff, parts

parts

parts(duration: quantity): duration in up to three of d, h, min, s; or to d h min for chosen units

(date("2026-12-25") - date("2026-10-06 14:24")).parts
# → "79 d 10 h 36 min"
5000 s.parts
# → "1 h 23 min 20 s"

See also: relative, diff

unix

unix(d: date): seconds since 1970-01-01 UTC; same as d to unix

date(0).unix
# → 0
date(86400) to unix
# → 86400

See also: date, unix_ms

unix_ms

unix_ms(d: date): milliseconds since 1970-01-01 UTC; same as d to unix_ms

date(1).unix_ms
# → 1000

See also: date_ms, unix

date_ms

date_ms(ms: int): the date from Unix milliseconds, as JavaScript and Java give them

date_ms(1798178400000) == date(1798178400)
# → true

See also: unix_ms, date

timeit

timeit(f: fn): how long calling f takes

timeit(|| (1..1000).sum) < 1 s
# → true

See also: stopwatch

stopwatch

stopwatch(): time since the last stopwatch() call (0 s the first time)

stopwatch() >= 0 s
# → true

See also: timeit

More examples

time

# day of the week
date("2026-12-25").weekday
# → "Friday"
# month math clamps to the end
date("2026-01-31") + 1 mo
# → 2026-02-28
# plain-English dates
date("next friday")
# → 2026-10-09
# countdown
(date("2027-01-01") - now).parts
# → "85 d 31 min"
# relative time
(now - 3 h).relative
# → "3 hours ago"
# first of next month
(today + 1 mo).with({day: 1})
# → 2026-11-01
# months with a Friday the 13th
(1..=12).filter(|m| date(2026, m, 13).weekday == "Friday")
# → [2, 3, 11]
# from a Unix timestamp
date(1798178400)
# → 2026-12-25
# compact durations
1h30m + 2d4h
# → 3210 min
# hours worked
17:00 - 8:45
# → 8.25 h