# time

Validate time strings

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

Validate time strings in ISO 8601 format (HH:mm:ss). The Time primitive ensures times are properly formatted and represent valid clock times.

## Examples

### Creating times

```ts
// Direct validation
const time = p.time('14:30:00')

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

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

// Check validity without throwing
if (p.time.isValid('23:59:59')) {
  console.log('Valid time')
}
```

### Parsing external data

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

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

### Using with forms

```ts
const form = p.form({
  name: 'schedule',
  fields: {
    startTime: { type: 'time', label: 'Start Time' },
    endTime: { type: 'time', label: 'End Time' }
  }
})

const filled = form.fill({
  fields: {
    startTime: p.time('09:00:00'),
    endTime: p.time('17:00:00')
  }
})
```

## API

### Direct Call

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

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

```ts
const time = p.time('14:30:00')
```

### 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 time |
| `now()` | `string` | Get current local wall-clock time as HH:mm:ss |

## Format

The Time primitive expects and returns strings in ISO 8601 time format:

```
HH:mm:ss
HH:mm:ss[.fraction]
```

| Component   | Description                                       | Range |
| ----------- | ------------------------------------------------- | ----- |
| `HH`        | Hours (24-hour)                                   | 00-23 |
| `mm`        | Minutes                                           | 00-59 |
| `ss`        | Seconds                                           | 00-59 |
| `.fraction` | Fractional seconds, one or more digits (optional) | .123  |

## Common Times

| Time       | Description |
| ---------- | ----------- |
| `00:00:00` | Midnight    |
| `06:00:00` | 6:00 AM     |
| `12:00:00` | Noon        |
| `13:00:00` | 1:00 PM     |
| `18:00:00` | 6:00 PM     |
| `23:59:59` | End of day  |

## Validation

The Time primitive validates:

* String must match `HH:mm:ss` or `HH:mm:ss[.fraction]` format
* Hours must be 00-23
* Minutes must be 00-59
* Seconds must be 00-59

```ts
// Valid
p.time('00:00:00')
p.time('12:30:00')
p.time('23:59:59')
p.time('14:30:00.123')

// Invalid - throws Error
p.time('24:00:00')

p.time('12:60:00')

p.time('14:30')

p.time('2:30:00')

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

## Related

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