Date operations

ZEN provides the d() function for comprehensive date handling with timezone support, arithmetic, comparisons, and formatting.

Creating dates

From string

d("2024-01-15")                    // 2024-01-15T00:00:00Z
d("2024-01-15 14:30")              // 2024-01-15T14:30:00Z
d("2024-01-15 14:30:45")           // 2024-01-15T14:30:45Z

With timezone

d("2024-01-15", "America/New_York")       // 2024-01-15T00:00:00-05:00
d("2024-01-15", "Europe/London")          // 2024-01-15T00:00:00Z
d("2024-01-15 14:30", "Asia/Tokyo")       // 2024-01-15T14:30:00+09:00

Current date/time

d()                               // Current date and time
d("America/Los_Angeles")          // Current time in LA timezone

Date components

Getters

Method	Example	Result
`.year()`	`d("2024-01-15").year()`	`2024`
`.month()`	`d("2024-01-15").month()`	`1`
`.day()`	`d("2024-01-15").day()`	`15`
`.weekday()`	`d("2024-01-15").weekday()`	`1` (Monday)
`.hour()`	`d("2024-01-15 14:30").hour()`	`14`
`.minute()`	`d("2024-01-15 14:30").minute()`	`30`
`.second()`	`d("2024-01-15 14:30:45").second()`	`45`
`.dayOfYear()`	`d("2024-01-15").dayOfYear()`	`15`
`.quarter()`	`d("2024-01-15").quarter()`	`1`
`.timestamp()`	`d("2024-01-15").timestamp()`	`1705276800000`

Setters

d("2024-01-15").set("year", 2025)      // 2025-01-15
d("2024-01-15").set("month", 6)        // 2024-06-15
d("2024-01-15").set("day", 20)         // 2024-01-20

Date arithmetic

Adding time

d("2024-01-15").add("1d")              // 2024-01-16
d("2024-01-15").add("1w")              // 2024-01-22
d("2024-01-15").add("1M")              // 2024-02-15
d("2024-01-15").add("1y")              // 2025-01-15
d("2024-01-15").add("2d 5h")           // 2024-01-17T05:00:00

// Alternative syntax
d("2024-01-15").add(1, "d")            // 2024-01-16
d("2024-01-15").add(3, "M")            // 2024-04-15

Subtracting time

d("2024-01-15").sub("7d")              // 2024-01-08
d("2024-01-15").sub("1M")              // 2023-12-15
d("2024-01-15").sub(1, "y")            // 2023-01-15

Duration units

Unit	Aliases
Year	`y`, `year`, `years`
Month	`M`, `month`, `months`
Week	`w`, `week`, `weeks`
Day	`d`, `day`, `days`
Hour	`h`, `hour`, `hours`
Minute	`m`, `minute`, `minutes`
Second	`s`, `second`, `seconds`

Date comparisons

Comparison methods

d("2024-01-15").isBefore(d("2024-01-20"))         // true
d("2024-01-15").isAfter(d("2024-01-10"))          // true
d("2024-01-15").isSame(d("2024-01-15"))           // true
d("2024-01-15").isSameOrBefore(d("2024-01-15"))   // true
d("2024-01-15").isSameOrAfter(d("2024-01-15"))    // true

Comparison with granularity

d("2024-01-15").isSame(d("2024-01-20"), "month")    // true (same month)
d("2024-01-15").isSame(d("2024-06-15"), "year")     // true (same year)
d("2024-01-15").isBefore(d("2024-02-01"), "month")  // true

Comparison operators

d("2024-01-15") == d("2024-01-15")    // true
d("2024-01-15") != d("2024-01-20")    // true
d("2024-01-15") < d("2024-01-20")     // true
d("2024-01-15") > d("2024-01-10")     // true
d("2024-01-15") <= d("2024-01-15")    // true
d("2024-01-15") >= d("2024-01-15")    // true

Range checks

d("2024-01-15") in [d("2024-01-01")..d("2024-01-31")]     // true
d("2024-01-15") in (d("2024-01-01")..d("2024-01-31"))     // true
d("2024-02-15") not in [d("2024-01-01")..d("2024-01-31")] // true

Calculating differences

d("2024-01-15").diff("2024-01-10", "day")       // 5
d("2024-01-15").diff("2024-01-01", "week")      // 2
d("2024-06-15").diff("2024-01-15", "month")     // 5
d("2025-01-15").diff("2024-01-15", "year")      // 1

Negative differences when the first date is earlier:

d("2024-01-10").diff("2024-01-15", "day")       // -5

Start and end of periods

d("2024-01-15").startOf("day")      // 2024-01-15T00:00:00
d("2024-01-15").endOf("day")        // 2024-01-15T23:59:59
d("2024-01-15").startOf("month")    // 2024-01-01T00:00:00
d("2024-01-15").endOf("month")      // 2024-01-31T23:59:59
d("2024-01-15").startOf("year")     // 2024-01-01T00:00:00
d("2024-01-15").endOf("year")       // 2024-12-31T23:59:59
d("2024-01-15").startOf("week")     // 2024-01-15T00:00:00 (Monday)
d("2024-01-15").endOf("week")       // 2024-01-21T23:59:59 (Sunday)
d("2024-05-15").startOf("quarter")  // 2024-04-01T00:00:00
d("2024-05-15").endOf("quarter")    // 2024-06-30T23:59:59

Timezone conversion

d("2024-01-15T12:00:00Z").tz("America/New_York")    // 2024-01-15T07:00:00-05:00
d("2024-01-15T12:00:00Z").tz("Europe/London")       // 2024-01-15T12:00:00Z
d("2024-01-15T12:00:00Z").tz("Asia/Tokyo")          // 2024-01-15T21:00:00+09:00

Get timezone name:

d("2024-01-15", "America/New_York").offsetName()    // "America/New_York"

Relative dates

d().isToday()          // true if today
d().sub(1, "d").isYesterday()    // true
d().add(1, "d").isTomorrow()     // true

Validation

d("2024-01-15").isValid()         // true
d("invalid").isValid()            // false
d("2024-02-30").isValid()         // false (invalid date)
d(null).isValid()                 // false

Leap years

d("2024-01-15").isLeapYear()      // true
d("2023-01-15").isLeapYear()      // false
d("2000-01-15").isLeapYear()      // true
d("1900-01-15").isLeapYear()      // false

Formatting

d("2024-01-15").format("%Y-%m-%d")                    // "2024-01-15"
d("2024-01-15").format("%Y/%m/%d")                    // "2024/01/15"
d("2024-01-15T14:30:45Z").format("%A, %B %d %Y")      // "Monday, January 15 2024"
d("2024-01-15T14:30:45Z").format("%H:%M:%S")          // "14:30:45"

Format codes

Code	Description	Example
`%Y`	4-digit year	`2024`
`%m`	Month (01-12)	`01`
`%d`	Day (01-31)	`15`
`%H`	Hour (00-23)	`14`
`%M`	Minute (00-59)	`30`
`%S`	Second (00-59)	`45`
`%A`	Full weekday	`Monday`
`%a`	Abbreviated weekday	`Mon`
`%B`	Full month	`January`
`%b`	Abbreviated month	`Jan`
`%j`	Day of year	`015`

Min/max with dates

min([d("2024-01-15"), d("2024-03-20"), d("2024-02-10")])    // 2024-01-15
max([d("2024-01-15"), d("2024-03-20"), d("2024-02-10")])    // 2024-03-20

Common patterns

Age calculation

d().diff(birthDate, "year")

Days until expiration

d(expirationDate).diff(d(), "day")

Is within last 30 days

d(eventDate).isAfter(d().sub(30, "d"))

Business days check

d(orderDate).weekday() in [1..5]    // 1=Monday, 5=Friday

Getting Started

Authoring

ZEN Language

Tutorials

Creating dates

From string

With timezone

Current date/time

Date components

Getters

Setters

Date arithmetic

Adding time

Subtracting time

Duration units

Date comparisons

Comparison methods

Comparison with granularity

Comparison operators

Range checks

Calculating differences

Start and end of periods

Timezone conversion

Relative dates

Validation

Leap years

Formatting

Format codes

Min/max with dates

Common patterns

Age calculation

Days until expiration

Is within last 30 days

Business days check

Getting Started

Authoring

ZEN Language

Tutorials

​Creating dates

​From string

​With timezone

​Current date/time

​Date components

​Getters

​Setters

​Date arithmetic

​Adding time

​Subtracting time

​Duration units

​Date comparisons

​Comparison methods

​Comparison with granularity

​Comparison operators

​Range checks

​Calculating differences

​Start and end of periods

​Timezone conversion

​Relative dates

​Validation

​Leap years

​Formatting

​Format codes

​Min/max with dates

​Common patterns

​Age calculation

​Days until expiration

​Is within last 30 days

​Business days check

Creating dates

From string

With timezone

Current date/time

Date components

Getters

Setters

Date arithmetic

Adding time

Subtracting time

Duration units

Date comparisons

Comparison methods

Comparison with granularity

Comparison operators

Range checks

Calculating differences

Start and end of periods

Timezone conversion

Relative dates

Validation

Leap years

Formatting

Format codes

Min/max with dates

Common patterns

Age calculation

Days until expiration

Is within last 30 days

Business days check