Date Module

The std/date module provides date manipulation utilities including date creation, arithmetic (add/subtract days, months, years), comparisons, boundary calculations, and human-readable relative time. It complements the std/time module — use Time for timestamps, formatting, and sleep; use Date for date arithmetic and comparisons.

All timestamps are in milliseconds since the Unix epoch.

Import

import { date } from "std/date"

Creating Dates

`date.create(year: int, month: int, day: int, hour?: int, minute?: int, second?: int): int`

Creates a timestamp from date components. Hour, minute, and second default to 0.

const ts = date.create(2025, 6, 15)           // June 15, 2025 at midnight
const ts2 = date.create(2025, 6, 15, 14, 30)  // June 15, 2025 at 2:30 PM

`date.today(): int`

Returns today’s date at midnight (start of day) in milliseconds.

const today = date.today()

Date Arithmetic

`date.addDays(ms: int, days: int): int`

Adds (or subtracts) days to a timestamp. Use negative values to subtract.

const tomorrow = date.addDays(today, 1)
const yesterday = date.addDays(today, -1)

`date.addMonths(ms: int, months: int): int`

Adds (or subtracts) months to a timestamp.

const nextMonth = date.addMonths(today, 1)
const lastMonth = date.addMonths(today, -1)

`date.addYears(ms: int, years: int): int`

Adds (or subtracts) years to a timestamp.

const nextYear = date.addYears(today, 1)

`date.addHours(ms: int, hours: int): int`

Adds (or subtracts) hours to a timestamp.

const inTwoHours = date.addHours(now, 2)

`date.addMinutes(ms: int, minutes: int): int`

Adds (or subtracts) minutes to a timestamp.

const inThirtyMin = date.addMinutes(now, 30)

`date.addSeconds(ms: int, seconds: int): int`

Adds (or subtracts) seconds to a timestamp.

const inTenSec = date.addSeconds(now, 10)

Difference

`date.diff(ms1: int, ms2: int): any`

Returns the difference between two timestamps as a map with days, hours, minutes, seconds, milliseconds, and totalMilliseconds.

const today = date.today()
const nextWeek = date.addDays(today, 7)
const d: any = date.diff(today, nextWeek)
println(string(d["days"]))    // 7
println(string(d["hours"]))   // 0

Comparisons

`date.isBefore(ms1: int, ms2: int): bool`

Returns true if the first timestamp is before the second.

const today = date.today()
const tomorrow = date.addDays(today, 1)
println(date.isBefore(today, tomorrow))  // true

`date.isAfter(ms1: int, ms2: int): bool`

Returns true if the first timestamp is after the second.

println(date.isAfter(tomorrow, today))  // true

`date.isEqual(ms1: int, ms2: int): bool`

Returns true if both timestamps are equal.

println(date.isEqual(today, today))  // true

Boundaries

`date.startOfDay(ms: int): int`

Returns the start of the day (midnight) for the given timestamp.

const start = date.startOfDay(time.now())

`date.endOfDay(ms: int): int`

Returns the end of the day (23:59:59.999) for the given timestamp.

const end = date.endOfDay(time.now())

`date.startOfMonth(ms: int): int`

Returns the first day of the month at midnight.

const monthStart = date.startOfMonth(time.now())

`date.endOfMonth(ms: int): int`

Returns the last day of the month at 23:59:59.999.

const monthEnd = date.endOfMonth(time.now())

`date.startOfYear(ms: int): int`

Returns January 1st at midnight for the given year.

const yearStart = date.startOfYear(time.now())

`date.endOfYear(ms: int): int`

Returns December 31st at 23:59:59.999 for the given year.

const yearEnd = date.endOfYear(time.now())

Day Info

`date.dayOfWeek(ms: int): int`

Returns the day of the week (0 = Sunday, 1 = Monday, …, 6 = Saturday).

const dow = date.dayOfWeek(time.now())
println(string(dow))  // e.g. 5 (Friday)

`date.dayOfYear(ms: int): int`

Returns the day of the year (1–366).

const doy = date.dayOfYear(time.now())
println(string(doy))  // e.g. 166

Calendar Helpers

`date.isLeapYear(year: int): bool`

Returns true if the given year is a leap year.

println(date.isLeapYear(2024))  // true
println(date.isLeapYear(2025))  // false

`date.daysInMonth(year: int, month: int): int`

Returns the number of days in a given month of a given year.

println(string(date.daysInMonth(2024, 2)))  // 29 (leap year)
println(string(date.daysInMonth(2025, 2)))  // 28

Relative Time

`date.relative(ms: int): string`

Returns a human-readable relative time string like “just now”, “5 minutes ago”, or “in 3 days”.

import { time } from "std/time"

const fiveMinAgo = date.addMinutes(time.now(), -5)
println(date.relative(fiveMinAgo))  // "5 minutes ago"

const inTwoDays = date.addDays(time.now(), 2)
println(date.relative(inTwoDays))   // "in 2 days"

Function Reference

Function	Returns	Description
`date.create(y, m, d, ...)`	`int`	Create timestamp from components
`date.today()`	`int`	Today at midnight
`date.addDays(ms, n)`	`int`	Add/subtract days
`date.addMonths(ms, n)`	`int`	Add/subtract months
`date.addYears(ms, n)`	`int`	Add/subtract years
`date.addHours(ms, n)`	`int`	Add/subtract hours
`date.addMinutes(ms, n)`	`int`	Add/subtract minutes
`date.addSeconds(ms, n)`	`int`	Add/subtract seconds
`date.diff(ms1, ms2)`	`any`	Difference as map (days, hours, etc.)
`date.isBefore(ms1, ms2)`	`bool`	True if ms1 < ms2
`date.isAfter(ms1, ms2)`	`bool`	True if ms1 > ms2
`date.isEqual(ms1, ms2)`	`bool`	True if ms1 == ms2
`date.startOfDay(ms)`	`int`	Midnight of the given day
`date.endOfDay(ms)`	`int`	23:59:59.999 of the given day
`date.startOfMonth(ms)`	`int`	First day of month at midnight
`date.endOfMonth(ms)`	`int`	Last day of month at 23:59:59.999
`date.startOfYear(ms)`	`int`	Jan 1 at midnight
`date.endOfYear(ms)`	`int`	Dec 31 at 23:59:59.999
`date.dayOfWeek(ms)`	`int`	Day of week (0=Sun, 6=Sat)
`date.dayOfYear(ms)`	`int`	Day of year (1–366)
`date.isLeapYear(year)`	`bool`	True if leap year
`date.daysInMonth(y, m)`	`int`	Days in given month
`date.relative(ms)`	`string`	Human-readable relative time

Complete Example

import { date } from "std/date"
import { time } from "std/time"

function main() {
    const now: int = time.now();
    const today: int = date.today();

    // Date arithmetic
    const nextWeek: int = date.addDays(today, 7);
    const nextMonth: int = date.addMonths(today, 1);

    // Difference
    const d: any = date.diff(today, nextWeek);
    println("Days until next week: " + string(d["days"]));

    // Boundaries
    const monthStart: int = date.startOfMonth(now);
    const monthEnd: int = date.endOfMonth(now);
    println("Month start: " + time.format(monthStart));
    println("Month end: " + time.format(monthEnd));

    // Calendar info
    println("Leap year 2024: " + string(date.isLeapYear(2024)));
    println("Days in Feb 2024: " + string(date.daysInMonth(2024, 2)));

    // Relative time
    const created: int = date.addDays(now, -3);
    println("Created: " + date.relative(created));  // "3 days ago"
}