gem-hunter

This library adds additional types for Zod to parse and validate dates, times and durations as Temporal types. This library has support for both zod/v4 and zod/v4/mini.

Install via your favorite package manager:

npm install zod-temporal
# or
pnpm add zod-temporal
# or
yarn add zod-temporal

Import the schema types from this package. You can either import individual types or import all types via a convenience method:

import { zt } from 'zod-temporal';

For zod/v4/mini, import from the mini sub-path:

import { zt } from 'zod-temporal/mini';

This library supplies the following types:

• zt.duration()
• zt.plainDate()
• zt.plainDateTime()
• zt.plainTime()
• zt.plainYearMonth()
• zt.plainMonthDay()
• zt.instant()
• zt.zonedDateTime()

zt.instant() parses any offset date time (e.g. 2020-01-01T14:00:00+01:00) to a Temporal.Instant, while zt.zonedDateTime() expects timezone information (e.g. 2020-01-01T14:00:00+01:00[Europe/Berlin]) and preserves it.

The temporal schemas are implemented as codecs. This allows you to not only parse temporal values from their ISO string representation but also to encode them back:

const schema = zt.plainTime();
const value = schema.encode(Temporal.PlainTime.from('12:34:56.789'));