durationLast updated on
Last updated on
Build and validate ISO 8601 durations
Build and validate time durations in ISO 8601 format. The Duration primitive represents spans of time like "1 year, 6 months" or "2 hours, 30 minutes".
Examples
Creating durations
// Direct validation
const period = open.duration('P1Y6M') // 1 year, 6 months
const hours = open.duration('PT2H30M') // 2 hours, 30 minutesParsing external data
// Parse unknown input (throws on error)
const period = open.duration.parse(jsonData)
// Safe parsing (returns result object)
const result = open.duration.safeParse(jsonData)
if (result.success) {
console.log(`Duration: ${result.data}`)
} else {
console.error(result.error.message)
}Using with forms
const form = open.form({
name: 'subscription',
fields: {
term: { type: 'duration', label: 'Subscription Term' }
}
})
const filled = form.fill({
fields: {
term: open.duration('P1Y') // 1 year
}
})API
Direct Call
open.duration(input: Duration): DurationPass a duration string for validation. Returns the validated string or throws on error.
const period = open.duration('P6M') // 6 monthsStatic Methods
parse: (input: unknown) => Duration
Parse unknown input (throws on error)
safeParse: (input: unknown) => Result<Duration>
Parse unknown input (returns result object)
Format
The Duration primitive uses ISO 8601 duration format:
P[n]Y[n]M[n]DT[n]H[n]M[n]S| Component | Description | Example |
|---|---|---|
P | Period designator (required) | P |
[n]Y | Years | 1Y |
[n]M | Months | 6M |
[n]D | Days | 15D |
T | Time designator | T |
[n]H | Hours | 2H |
[n]M | Minutes | 30M |
[n]S | Seconds | 45S |
Common Examples
| Duration | Meaning |
|---|---|
P1Y | 1 year |
P6M | 6 months |
P1Y6M | 1 year, 6 months |
P30D | 30 days |
PT2H | 2 hours |
PT30M | 30 minutes |
PT2H30M | 2 hours, 30 minutes |
P1DT12H | 1 day, 12 hours |
Validation
The Duration primitive validates:
- String must start with
P - At least one component must be specified
- Components must be in correct order (Y, M, D, then T, H, M, S)
- Time components must follow
Tdesignator
// Valid
open.duration('P1Y')
open.duration('P1Y6M')
open.duration('P1Y6M15D')
open.duration('PT2H30M')
open.duration('P1DT12H')
open.duration('P0D') // Zero duration
// Invalid - throws Error
open.duration('1Y')
// Error: Invalid Duration: must start with P
open.duration('P')
// Error: Invalid Duration: must specify at least one component
open.duration('P2H')
// Error: Invalid Duration: time components must follow T
open.duration('PT1Y')
// Error: Invalid Duration: years cannot follow T designatorRelated
- Primitives Overview - All available primitives
- Date - Date values
- Duration Field - Duration field type
- Duration Schema - JSON Schema definition