feat: add support for Temporal.Instant

Author: DASPRiD

src/core.ts

@@ -68,6 +68,15 @@ export const zonedDateTimeConfig: TransformConfig<Temporal.ZonedDateTime> = {
     example: "2020-01-01T14:00:00+01:00[Europe/Berlin]",
 };
 
+export const instantConfig: TransformConfig<Temporal.Instant> = {
+    parse: (input) => Temporal.Instant.from(input),
+    encode: (input) => input.toString(),
+    instanceType: Temporal.Instant,
+    invalidMessage: "Invalid instant",
+    schemaFormat: "date-time",
+    example: "2020-01-01T14:00:00Z",
+};
+
 export const plainYearMonthConfig: TransformConfig<Temporal.PlainYearMonth> = {
     parse: (input) => Temporal.PlainYearMonth.from(input),
     encode: (input) => input.toString(),

src/index.ts

@@ -2,6 +2,7 @@ import { z } from "zod/v4";
 import {
     type CoreParams,
     durationConfig,
+    instantConfig,
     offsetDateTimeConfig,
     plainDateConfig,
     plainDateTimeConfig,
@@ -58,6 +59,7 @@ export const plainDate = createCodecConstructor(plainDateConfig);
 export const plainDateTime = createCodecConstructor(plainDateTimeConfig);
 export const plainTime = createCodecConstructor(plainTimeConfig);
 export const offsetDateTime = createCodecConstructor(offsetDateTimeConfig);
+export const instant = createCodecConstructor(instantConfig);
 export const zonedDateTime = createCodecConstructor(zonedDateTimeConfig);
 export const plainYearMonth = createCodecConstructor(plainYearMonthConfig);
 export const plainMonthDay = createCodecConstructor(plainMonthDayConfig);
@@ -68,6 +70,7 @@ export const zt = {
     plainDateTime,
     plainTime,
     offsetDateTime,
+    instant,
     zonedDateTime,
     plainYearMonth,
     plainMonthDay,

src/mini.ts

@@ -2,6 +2,7 @@ import { z } from "zod/v4/mini";
 import {
     type CoreParams,
     durationConfig,
+    instantConfig,
     offsetDateTimeConfig,
     plainDateConfig,
     plainDateTimeConfig,
@@ -58,6 +59,7 @@ export const plainDate = createCodecConstructor(plainDateConfig);
 export const plainDateTime = createCodecConstructor(plainDateTimeConfig);
 export const plainTime = createCodecConstructor(plainTimeConfig);
 export const offsetDateTime = createCodecConstructor(offsetDateTimeConfig);
+export const instant = createCodecConstructor(instantConfig);
 export const zonedDateTime = createCodecConstructor(zonedDateTimeConfig);
 export const plainYearMonth = createCodecConstructor(plainYearMonthConfig);
 export const plainMonthDay = createCodecConstructor(plainMonthDayConfig);
@@ -68,6 +70,7 @@ export const zt = {
     plainDateTime,
     plainTime,
     offsetDateTime,
+    instant,
     zonedDateTime,
     plainYearMonth,
     plainMonthDay,

test/Instant.test.ts

@@ -0,0 +1,56 @@
+import assert from "node:assert/strict";
+import { it } from "node:test";
+import { toJSONSchema } from "zod/v4/core";
+import { describeMatrix } from "./matrix.js";
+
+describeMatrix("OffsetDateTime", (zt, z) => {
+    it("should allow ISO offset date time value", () => {
+        const schema = zt.instant();
+        const instant = Temporal.Instant.from("2021-01-01T20:00:00Z");
+        const result = schema.parse("2021-01-01T20:00:00Z");
+        assert(result.equals(instant));
+    });
+
+    it("should report invalid date", () => {
+        const schema = zt.instant();
+        assert.throws(() => schema.parse("foo"));
+    });
+
+    it("should report invalid type", () => {
+        const schema = zt.instant();
+        assert.throws(() => schema.parse(1));
+    });
+
+    it("should allow error override", () => {
+        const schema = zt.instant({ error: "whoops" });
+        const result = schema.safeParse("a");
+        assert(!result.success);
+        assert.deepEqual(result.error.issues[0].message, "whoops");
+    });
+
+    it("should create a standard JSON schema", () => {
+        const schema = zt.instant();
+        const jsonSchema = toJSONSchema(schema, { io: "input" });
+        assert.partialDeepStrictEqual(jsonSchema, {
+            type: "string",
+            format: "date-time",
+            example: "2020-01-01T14:00:00Z",
+        });
+    });
+
+    it("should encode to ISO offset date time", () => {
+        const schema = zt.instant();
+        const result = z.encode(schema, Temporal.Instant.from("2021-01-01T20:00:00Z"));
+        assert.equal(result, "2021-01-01T20:00:00Z");
+    });
+
+    it("should preserve JSON schema over refine", () => {
+        const schema = zt.instant().check(z.refine(() => true));
+        const jsonSchema = toJSONSchema(schema, { io: "input" });
+        assert.partialDeepStrictEqual(jsonSchema, {
+            type: "string",
+            format: "date-time",
+            example: "2020-01-01T14:00:00Z",
+        });
+    });
+});