# datetime

Validate datetime strings

Canonical URL: https://docs.paradoc.dev/sdk/primitives/datetime/

Validate datetime strings in ISO 8601 format. The Datetime primitive ensures timestamps are properly formatted with date, time, and timezone information.

## Examples

### Creating datetimes

```ts
// Direct validation
const dt = p.datetime('2024-01-15T10:30:00Z')

// Parse unknown input
const dt = p.datetime.parse(jsonData)

// Get current datetime
const now = p.datetime.now()

// Convert from Date object
const dt = p.datetime.fromDate(new Date())

// Check validity without throwing
if (p.datetime.isValid('2024-01-15T10:30:00Z')) {
  console.log('Valid datetime')
}
```

### Parsing external data

```ts
// Parse unknown input (throws on error)
const dt = p.datetime.parse(userInput)

// Safe parsing (returns result object)
const result = p.datetime.safeParse(userInput)
if (result.success) {
  console.log(`Datetime: ${result.data}`)
} else {
  console.error(result.error.message)
}
```

### Using with forms

```ts
const form = p.form({
  name: 'appointment',
  fields: {
    scheduledAt: { type: 'datetime', label: 'Appointment Time' }
  }
})

const filled = form.fill({
  fields: {
    scheduledAt: p.datetime('2024-06-15T14:30:00Z')
  }
})
```

## API

### Direct Call

```ts
p.datetime(input: string): string
```

Pass a datetime string for validation. Returns the validated string or throws on error.

```ts
const dt = p.datetime('2024-01-15T10:30:00Z')
```

### Static Methods

| Method | Returns | Description |
| --- | --- | --- |
| `parse(input: unknown)` | `string` | Parse unknown input (throws on error) |
| `safeParse(input: unknown)` | `Result<string>` | Parse unknown input (returns result object) |
| `isValid(input: string)` | `boolean` | Check if a string is a valid datetime |
| `fromDate(date: Date)` | `string` | Convert a JavaScript Date to ISO datetime string |
| `now()` | `string` | Get current UTC datetime with a Z suffix |

## Format

The Datetime primitive expects and returns strings in ISO 8601 datetime format:

```
YYYY-MM-DDTHH:mm:ssZ
YYYY-MM-DDTHH:mm:ss[.fraction]Z
YYYY-MM-DDTHH:mm:ss±HH:mm
```

| Component    | Description                                       | Example    |
| ------------ | ------------------------------------------------- | ---------- |
| `YYYY-MM-DD` | Date portion                                      | 2024-01-15 |
| `T`          | Separator                                         | T          |
| `HH:mm:ss`   | Time (24-hour)                                    | 10:30:00   |
| `.fraction`  | Fractional seconds, one or more digits (optional) | .123       |
| `Z`          | UTC timezone                                      | Z          |
| `±HH:mm`     | Timezone offset                                   | +05:30     |

## Validation

The Datetime primitive validates:

* String must be a valid ISO 8601 datetime format
* Date portion must be valid (see [date](/sdk/primitives/date))
* Time portion must be valid (see [time](/sdk/primitives/time))
* Timezone must be specified (Z or offset)

```ts
// Valid
p.datetime('2024-01-15T10:30:00Z')
p.datetime('2024-01-15T10:30:00.123Z')
p.datetime('2024-01-15T10:30:00+05:30')
p.datetime('2024-01-15T10:30:00-08:00')

// Invalid - throws Error
p.datetime('2024-01-15')

p.datetime('2024-01-15T10:30:00')

p.datetime('2024-01-15 10:30:00Z')

p.datetime('not-a-datetime')
```

## Related

* [Primitives Overview](/sdk/primitives) - All available primitives
* [Date](/sdk/primitives/date) - Date only
* [Time](/sdk/primitives/time) - Time only
* [Datetime Field](/sdk/artifacts/form/field#date--datetime--timetime) - Datetime field type