Time builtins

11 builtins of Soma 3.2.4 in the category Time, with their exact signatures, as soma describe --builtins --json prints them.

• parse_date
• add_days
• add_months
• days_between
• months_between
• days_in_month
• now
• now_ms
• today
• format_date
• sleep

parse_date

parse_date(s: "YYYY-MM-DD") -> {year, month, day, weekday, epoch_day}

Strict ISO date to its parts (weekday 1 = Monday); raises kind "date" otherwise.

deterministic · replay: pure

add_days

add_days(date: String, n: Int) -> String

The ISO date n days later (negative n goes back), across month and year ends.

deterministic · replay: pure

add_months

add_months(date: String, n: Int) -> String

Same day n months later, clamped to the month's length (Ruby's Date >> n): add_months("2026-01-31", 1) = "2026-02-28".

deterministic · replay: pure

days_between

days_between(a: String, b: String) -> Int

Days from a to b (negative when b is earlier).

deterministic · replay: pure

months_between

months_between(a: String, b: String) -> Int

Whole months from a to b ("YYYY-MM-DD"), day-of-month aware like java.time MONTHS.between: 2026-01-15 → 2026-04-14 is 2, → 2026-04-20 is 3.

deterministic · replay: pure

days_in_month

days_in_month(year: Int, month: Int) -> Int

28–31, leap years included.

deterministic · replay: pure

now

now() -> Int

Current Unix timestamp in seconds.

not deterministic · replay: nondeterministic: replay reports it as a divergence source

Used in verified programs:

• web/guestbook, line 19: let entry = map("name", escape_html(name), "message", escape_html(message), "at", now())

now_ms

now_ms() -> Int

Current Unix timestamp in milliseconds.

not deterministic · replay: nondeterministic: replay reports it as a divergence source

today

today() -> String

Today's date as "YYYY-MM-DD" (UTC).

not deterministic · replay: nondeterministic: replay reports it as a divergence source

Used in verified programs:

• services/refund_agent, line 58: on paid_today() { return paid_by_day.get(today()) ?? 0 }

format_date

format_date(ts: Int) -> String

Format a Unix-seconds timestamp as "YYYY-MM-DD" (UTC).

deterministic · replay: pure

sleep

sleep(ms: Int) -> ()

Block the current handler for ms milliseconds. Requires one Int (other types raise kind type); values outside 0 to 86400000 raise kind range. Under serve it holds the handler lock the whole time.

deterministic · replay: pure