> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gorules.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Date operations

> Working with dates and times in ZEN expressions.

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
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.