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

# Dates & time

> Date creation, formatting, comparison, and arithmetic in penscript

penscript provides operators for creating, formatting, comparing, and manipulating dates. These are used for deadline calculations, age-based eligibility rules, contract expiration checks, and time-sensitive automations.

## Date Creation: `:date`

Creates a date from a string or retrieves the current date/time.

```json theme={null}
{ ":date": "now" }
// Result: "2026-01-27T16:34:54.757Z"

{ ":date": "2000-11-20" }
// Result: "2000-11-20T00:00:00.000Z"
```

Strings in ISO 8601 format (`"2024-01-15T00:00:00.000Z"`) and `YYYY-MM-DD` format (`"2024-01-15"`) are automatically parsed as dates.

The system variable `{$today}` is also available in inline expressions for the current date.

## Date Formatting: `:format-date`

Formats a date according to a pattern string.

```json theme={null}
{
  ":format-date": { ":date": "now" },
  ":pattern": "Y"
}
// Result: "2026"

{
  ":format-date": { ":date": "now" },
  ":pattern": "Y-M-D"
}
// Result: "2026-01-27"

{
  ":format-date": { ":date": "now" },
  ":pattern": "D/M/Y"
}
// Result: "27/01/2026"
```

### Pattern Characters

| Character | Description                   |
| --------- | ----------------------------- |
| `Y`       | Year, 4 digits                |
| `y`       | Year, 2–4 digits              |
| `M`       | Month, 2 digits (zero-padded) |
| `m`       | Month, 1–2 digits             |
| `D`       | Day, 2 digits (zero-padded)   |
| `d`       | Day, 1–2 digits               |
| `x`       | Any non-digit separator       |

### Inline Formatting with Pipes

For quick formatting inside strings, use the `formatDdMmYyyy` pipe:

```json theme={null}
"{$today | formatDdMmYyyy}"
// → "27/01/2026"

"{data.created_at | formatDdMmYyyy}"
// Scope: { "data": { "created_at": "2015-10-20" } }
// → "20/10/2015"
```

## Date Comparison

### Using `:cmp`

Combine `:cmp` with dates and the `| age` pipe for age-based conditions:

```json theme={null}
{
  ":if": [
    {
      ":cmp": "{data.birthdate | age}",
      ":gte": 18,
      ":lte": 65
    }
  ],
  ":then": "Eligible",
  ":else": "Not eligible"
}
```

All standard comparison modifiers work: `:eq`, `:neq`, `:gt`, `:gte`/`:ge`, `:lt`, `:lte`/`:le`.

### Inline Date Comparisons

Simple date comparisons can be expressed directly inside strings:

```json theme={null}
{
  ":if": "{{ myDate > now }}",
  ":then": "Future date",
  ":else": "Past or current date"
}
```

Direct inline comparison patterns:

```json theme={null}
"{ my_date > $today }"
// → true if my_date is after today

"{ my_date == $today }"
// → equality check with today

"{ data.birthdate | age >= 18 }"
// → age check

"{ my_date > $today ? 'Future' : 'Past' }"
// → ternary
```

Combined conditions:

```json theme={null}
"{ my_date != $today | my_date < $today }"
// → true if my_date is not today or is in the past
```

## Date Difference: `:diff`

Calculates the difference between two dates in a specified unit.

```json theme={null}
{
  ":diff": [
    "{data.date1}",
    "{data.date2}",
    {
      ":comparator": "day"
    }
  ]
}

// Scope: { "data": { "date1": "2024-01-01", "date2": "2024-02-04" } }
// Result: 34
```

### Available Comparators

| Comparator | Returns                          |
| ---------- | -------------------------------- |
| `"day"`    | Number of days between the dates |
| `"hour"`   | Number of hours                  |
| `"minute"` | Number of minutes                |
| `"second"` | Number of seconds                |

## Age Calculation: `| age`

Calculates the age in years from a date value. Available as an inline pipe.

```json theme={null}
"{data.birthdate | age}"

// Scope: { "data": { "birthdate": "2007-01-01" } }
// Result: 18
```

Commonly combined with `:cmp` for eligibility rules:

```json theme={null}
{
  ":if": [
    { ":cmp": "{data.birthdate | age}", ":gte": 18 }
  ],
  ":then": "Adult",
  ":else": "Minor"
}
```

## Date Arithmetic: `:sum` with Dates

Add or subtract time from dates using duration strings.

**Single duration:**

```json theme={null}
{
  ":format-date": {
    ":sum": ["{$today}", "2d"]
  }
}
// Result: Current date + 2 days
```

**Multiple durations combined:**

```json theme={null}
{
  ":format-date": {
    ":sum": ["{$today}", "2d", "3d", "72h", "2y"]
  }
}
// Result: Current date + 2 days + 3 days + 72 hours + 2 years
```

### Supported Duration Units

| Unit  | Example        | Description |
| ----- | -------------- | ----------- |
| Days  | `"2d"`, `"3d"` | Add days    |
| Hours | `"72h"`        | Add hours   |
| Years | `"2y"`         | Add years   |

### Raw Numbers and Strings

* **Raw numbers** are treated as **milliseconds**. Negative numbers subtract time.
* **Numeric strings** (e.g., `"+86400"`) are treated as **seconds**.

```json theme={null}
{
  ":format-date": {
    ":sum": [
      { ":date": "now" },
      -8640000000
    ],
    ":pattern": "D-M-Y"
  }
}
// Result: Current date minus 100 days
```

### Building Deadlines

A common pattern — calculate a deadline and format it for display:

```json theme={null}
{
  ":format-date": {
    ":sum": ["{$today}", "30d"]
  },
  ":pattern": "D/M/Y"
}
// → "13/03/2026" (30 days from today)
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Variables & scope" icon="brackets-curly" href="/penscript/variables">
    \$today and inline pipes
  </Card>

  <Card title="Logic & comparisons" icon="code-branch" href="/penscript/logic">
    Date-based conditions with :cmp
  </Card>

  <Card title="Numbers & calculations" icon="calculator" href="/penscript/numbers">
    :sum for date arithmetic
  </Card>

  <Card title="How penscript works" icon="gears" href="/penscript/how_it_works">
    Date examples in automations
  </Card>
</CardGroup>