zod 4.2.0-canary.20250824T204911 → 4.2.0-canary.20250825T230433

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zod",
-  "version": "4.2.0-canary.20250824T204911",
+  "version": "4.2.0-canary.20250825T230433",
   "type": "module",
   "license": "MIT",
   "author": "Colin McDonnell <zod@colinhacks.com>",

package/src/v4/classic/external.ts

@@ -27,6 +27,7 @@ export {
   flattenError,
   toJSONSchema,
   TimePrecision,
+  util,
   NEVER,
 } from "../core/index.js";
 

package/src/v4/classic/tests/codec-examples.test.ts

@@ -2,7 +2,7 @@ import { expect, test } from "vitest";
 import * as z from "zod/v4";
 
 // ============================================================================
-// Number/BigInt Codecs
+// stringToNumber
 // ============================================================================
 
 const stringToNumber = () =>
@@ -11,128 +11,6 @@ const stringToNumber = () =>
     encode: (num) => num.toString(),
   });
 
-const stringToInt = () =>
-  z.codec(z.string(), z.int(), {
-    decode: (str) => Number.parseInt(str, 10),
-    encode: (num) => num.toString(),
-  });
-
-const stringToBigInt = () =>
-  z.codec(z.string(), z.bigint(), {
-    decode: (str) => BigInt(str),
-    encode: (bigint) => bigint.toString(),
-  });
-
-const numberToBigInt = () =>
-  z.codec(z.int(), z.bigint(), {
-    decode: (num) => BigInt(num),
-    encode: (bigint) => Number(bigint),
-  });
-
-// ============================================================================
-// Date/Duration Codecs
-// ============================================================================
-
-const isoDatetimeToDate = () =>
-  z.codec(z.iso.datetime(), z.date(), {
-    decode: (isoString) => new Date(isoString),
-    encode: (date) => date.toISOString(),
-  });
-
-const epochSecondsToDate = () =>
-  z.codec(z.int().min(0), z.date(), {
-    decode: (seconds) => new Date(seconds * 1000),
-    encode: (date) => Math.floor(date.getTime() / 1000),
-  });
-
-const epochMillisToDate = () =>
-  z.codec(z.int().min(0), z.date(), {
-    decode: (millis) => new Date(millis),
-    encode: (date) => date.getTime(),
-  });
-
-// ============================================================================
-// JSON Codec
-// ============================================================================
-
-const json = <T extends z.ZodTypeAny>(schema: T) =>
-  z.codec(z.string(), schema, {
-    decode: (jsonString) => JSON.parse(jsonString),
-    encode: (value) => JSON.stringify(value),
-  });
-
-// ============================================================================
-// Text/Bytes Codecs
-// ============================================================================
-
-const utf8ToBytes = () =>
-  z.codec(z.string(), z.instanceof(Uint8Array), {
-    decode: (str) => new TextEncoder().encode(str),
-    encode: (bytes) => new TextDecoder().decode(bytes),
-  });
-
-const bytesToUtf8 = () =>
-  z.codec(z.instanceof(Uint8Array), z.string(), {
-    decode: (bytes) => new TextDecoder().decode(bytes),
-    encode: (str) => new TextEncoder().encode(str),
-  });
-
-// ============================================================================
-// Binary-to-text Codecs
-// ============================================================================
-
-// Using utility functions from z.core.util
-
-const base64 = () =>
-  z.codec(z.base64(), z.instanceof(Uint8Array), {
-    decode: (base64String) => z.core.util.base64ToUint8Array(base64String),
-    encode: (bytes) => z.core.util.uint8ArrayToBase64(bytes),
-  });
-
-const base64urlToBytes = () =>
-  z.codec(z.base64url(), z.instanceof(Uint8Array), {
-    decode: (base64urlString) => z.core.util.base64urlToUint8Array(base64urlString),
-    encode: (bytes) => z.core.util.uint8ArrayToBase64url(bytes),
-  });
-
-const hexToBytes = () =>
-  z.codec(z.hex(), z.instanceof(Uint8Array), {
-    decode: (hexString) => z.core.util.hexToUint8Array(hexString),
-    encode: (bytes) => z.core.util.uint8ArrayToHex(bytes),
-  });
-
-// ============================================================================
-// URL Codecs
-// ============================================================================
-
-const stringToURL = () =>
-  z.codec(z.url(), z.instanceof(URL), {
-    decode: (urlString) => new URL(urlString),
-    encode: (url) => url.href,
-  });
-
-const stringToHttpURL = () =>
-  z.codec(z.httpUrl(), z.instanceof(URL), {
-    decode: (urlString) => new URL(urlString),
-    encode: (url) => url.href,
-  });
-
-const uriComponent = () =>
-  z.codec(z.string(), z.string(), {
-    decode: (encodedString) => decodeURIComponent(encodedString),
-    encode: (decodedString) => encodeURIComponent(decodedString),
-  });
-
-// ============================================================================
-// Boolean Codec
-// ============================================================================
-
-const stringToBoolean = (options?: { truthy?: string[]; falsy?: string[] }) => z.stringbool(options);
-
-// ============================================================================
-// Tests
-// ============================================================================
-
 test("stringToNumber codec", () => {
   const codec = stringToNumber();
 
@@ -152,6 +30,16 @@ test("stringToNumber codec", () => {
   expect(roundTrip).toBe("3.14159");
 });
 
+// ============================================================================
+// stringToInt
+// ============================================================================
+
+const stringToInt = () =>
+  z.codec(z.string(), z.int(), {
+    decode: (str) => Number.parseInt(str, 10),
+    encode: (num) => num.toString(),
+  });
+
 test("stringToInt codec", () => {
   const codec = stringToInt();
 
@@ -171,6 +59,16 @@ test("stringToInt codec", () => {
   expect(roundTrip).toBe("999");
 });
 
+// ============================================================================
+// stringToBigInt
+// ============================================================================
+
+const stringToBigInt = () =>
+  z.codec(z.string(), z.bigint(), {
+    decode: (str) => BigInt(str),
+    encode: (bigint) => bigint.toString(),
+  });
+
 test("stringToBigInt codec", () => {
   const codec = stringToBigInt();
 
@@ -190,6 +88,16 @@ test("stringToBigInt codec", () => {
   expect(roundTrip).toBe("987654321098765432109876543210");
 });
 
+// ============================================================================
+// numberToBigInt
+// ============================================================================
+
+const numberToBigInt = () =>
+  z.codec(z.int(), z.bigint(), {
+    decode: (num) => BigInt(num),
+    encode: (bigint) => Number(bigint),
+  });
+
 test("numberToBigInt codec", () => {
   const codec = numberToBigInt();
 
@@ -209,6 +117,16 @@ test("numberToBigInt codec", () => {
   expect(roundTrip).toBe(999);
 });
 
+// ============================================================================
+// isoDatetimeToDate
+// ============================================================================
+
+const isoDatetimeToDate = () =>
+  z.codec(z.iso.datetime(), z.date(), {
+    decode: (isoString) => new Date(isoString),
+    encode: (date) => date.toISOString(),
+  });
+
 test("isoDatetimeToDate codec", () => {
   const codec = isoDatetimeToDate();
 
@@ -227,6 +145,16 @@ test("isoDatetimeToDate codec", () => {
   expect(roundTrip).toBe("2024-12-25T15:45:30.123Z");
 });
 
+// ============================================================================
+// epochSecondsToDate
+// ============================================================================
+
+const epochSecondsToDate = () =>
+  z.codec(z.int().min(0), z.date(), {
+    decode: (seconds) => new Date(seconds * 1000),
+    encode: (date) => Math.floor(date.getTime() / 1000),
+  });
+
 test("epochSecondsToDate codec", () => {
   const codec = epochSecondsToDate();
 
@@ -245,6 +173,16 @@ test("epochSecondsToDate codec", () => {
   expect(roundTrip).toBe(1640995200);
 });
 
+// ============================================================================
+// epochMillisToDate
+// ============================================================================
+
+const epochMillisToDate = () =>
+  z.codec(z.int().min(0), z.date(), {
+    decode: (millis) => new Date(millis),
+    encode: (date) => date.getTime(),
+  });
+
 test("epochMillisToDate codec", () => {
   const codec = epochMillisToDate();
 
@@ -263,8 +201,30 @@ test("epochMillisToDate codec", () => {
   expect(roundTrip).toBe(1640995200123);
 });
 
+// ============================================================================
+// json
+// ============================================================================
+
+const jsonCodec = <T extends z.core.$ZodType>(schema: T) =>
+  z.codec(z.string(), schema, {
+    decode: (jsonString, ctx) => {
+      try {
+        return JSON.parse(jsonString);
+      } catch (err: any) {
+        ctx.issues.push({
+          code: "invalid_format",
+          format: "json",
+          input: jsonString,
+          message: err.message,
+        });
+        return z.NEVER;
+      }
+    },
+    encode: (value) => JSON.stringify(value),
+  });
+
 test("json codec", () => {
-  const codec = json(z.object({ name: z.string(), age: z.number() }));
+  const codec = jsonCodec(z.object({ name: z.string(), age: z.number() }));
 
   // Test decode
   const decoded = z.decode(codec, '{"name":"Alice","age":30}');
@@ -281,6 +241,16 @@ test("json codec", () => {
   expect(JSON.parse(roundTrip)).toEqual(JSON.parse(original));
 });
 
+// ============================================================================
+// utf8ToBytes
+// ============================================================================
+
+const utf8ToBytes = () =>
+  z.codec(z.string(), z.instanceof(Uint8Array), {
+    decode: (str) => new TextEncoder().encode(str),
+    encode: (bytes) => new TextDecoder().decode(bytes),
+  });
+
 test("utf8ToBytes codec", () => {
   const codec = utf8ToBytes();
 
@@ -299,6 +269,16 @@ test("utf8ToBytes codec", () => {
   expect(roundTrip).toBe(original);
 });
 
+// ============================================================================
+// bytesToUtf8
+// ============================================================================
+
+const bytesToUtf8 = () =>
+  z.codec(z.instanceof(Uint8Array), z.string(), {
+    decode: (bytes) => new TextDecoder().decode(bytes),
+    encode: (str) => new TextEncoder().encode(str),
+  });
+
 test("bytesToUtf8 codec", () => {
   const codec = bytesToUtf8();
 
@@ -318,6 +298,16 @@ test("bytesToUtf8 codec", () => {
   expect(roundTrip).toEqual(original);
 });
 
+// ============================================================================
+// base64
+// ============================================================================
+
+const base64 = () =>
+  z.codec(z.base64(), z.instanceof(Uint8Array), {
+    decode: (base64String) => z.util.base64ToUint8Array(base64String),
+    encode: (bytes) => z.util.uint8ArrayToBase64(bytes),
+  });
+
 test("base64 codec", () => {
   const codec = base64();
 
@@ -336,6 +326,16 @@ test("base64 codec", () => {
   expect(roundTrip).toBe(original);
 });
 
+// ============================================================================
+// base64urlToBytes
+// ============================================================================
+
+const base64urlToBytes = () =>
+  z.codec(z.base64url(), z.instanceof(Uint8Array), {
+    decode: (base64urlString) => z.util.base64urlToUint8Array(base64urlString),
+    encode: (bytes) => z.util.uint8ArrayToBase64url(bytes),
+  });
+
 test("base64urlToBytes codec", () => {
   const codec = base64urlToBytes();
 
@@ -354,6 +354,16 @@ test("base64urlToBytes codec", () => {
   expect(roundTrip).toBe(original);
 });
 
+// ============================================================================
+// hexToBytes
+// ============================================================================
+
+const hexToBytes = () =>
+  z.codec(z.hex(), z.instanceof(Uint8Array), {
+    decode: (hexString) => z.util.hexToUint8Array(hexString),
+    encode: (bytes) => z.util.uint8ArrayToHex(bytes),
+  });
+
 test("hexToBytes codec", () => {
   const codec = hexToBytes();
 
@@ -376,6 +386,16 @@ test("hexToBytes codec", () => {
   expect(roundTrip).toBe("deadbeef");
 });
 
+// ============================================================================
+// stringToURL
+// ============================================================================
+
+const stringToURL = () =>
+  z.codec(z.url(), z.instanceof(URL), {
+    decode: (urlString) => new URL(urlString),
+    encode: (url) => url.href,
+  });
+
 test("stringToURL codec", () => {
   const codec = stringToURL();
 
@@ -396,6 +416,16 @@ test("stringToURL codec", () => {
   expect(roundTrip).toBe(original);
 });
 
+// ============================================================================
+// stringToHttpURL
+// ============================================================================
+
+const stringToHttpURL = () =>
+  z.codec(z.httpUrl(), z.instanceof(URL), {
+    decode: (urlString) => new URL(urlString),
+    encode: (url) => url.href,
+  });
+
 test("stringToHttpURL codec", () => {
   const codec = stringToHttpURL();
 
@@ -419,6 +449,16 @@ test("stringToHttpURL codec", () => {
   expect(roundTrip).toBe(original);
 });
 
+// ============================================================================
+// uriComponent
+// ============================================================================
+
+const uriComponent = () =>
+  z.codec(z.string(), z.string(), {
+    decode: (encodedString) => decodeURIComponent(encodedString),
+    encode: (decodedString) => encodeURIComponent(decodedString),
+  });
+
 test("uriComponent codec", () => {
   const codec = uriComponent();
 
@@ -442,6 +482,12 @@ test("uriComponent codec", () => {
   expect(decodedComplex).toBe(complex);
 });
 
+// ============================================================================
+// stringToBoolean
+// ============================================================================
+
+const stringToBoolean = (options?: { truthy?: string[]; falsy?: string[] }) => z.stringbool(options);
+
 test("stringToBoolean codec", () => {
   const codec = stringToBoolean();
 
@@ -469,6 +515,10 @@ test("stringToBoolean codec", () => {
   expect(z.encode(customCodec, false)).toBe("no");
 });
 
+// ============================================================================
+// Error Handling Tests
+// ============================================================================
+
 // Test error cases - these test input validation, not transform errors
 test("codec input validation", () => {
   // Test invalid base64 format
@@ -495,25 +545,10 @@ test("codec input validation", () => {
 // Test transform errors - these test errors added by transform functions
 test("codec transform error handling", () => {
   // JSON codec that can fail during transform
-  const jsonCodec = z.codec(z.string(), z.json(), {
-    decode: (jsonString, ctx) => {
-      try {
-        return JSON.parse(jsonString);
-      } catch (err: any) {
-        ctx.issues.push({
-          code: "invalid_format",
-          format: "json",
-          input: jsonString,
-          message: err.message,
-        });
-        return z.NEVER;
-      }
-    },
-    encode: (value) => JSON.stringify(value),
-  });
+  const anyJSON = jsonCodec(z.json());
 
   // Test successful JSON parsing
-  const validResult = z.safeDecode(jsonCodec, '{"valid": "json"}');
+  const validResult = z.safeDecode(anyJSON, '{"valid": "json"}');
   expect(validResult.success).toBe(true);
   if (validResult.success) {
     expect(validResult.data).toEqual({ valid: "json" });
@@ -521,7 +556,7 @@ test("codec transform error handling", () => {
 
   // Test invalid JSON that should create a single "invalid_format" issue
   // Verifies that the transform error aborts before reaching the output schema
-  const invalidResult = z.safeDecode(jsonCodec, '{"invalid":,}');
+  const invalidResult = z.safeDecode(anyJSON, '{"invalid":,}');
   expect(invalidResult.success).toBe(false);
   if (!invalidResult.success) {
     expect(invalidResult.error.issues).toMatchInlineSnapshot(`

package/src/v4/mini/external.ts

@@ -19,6 +19,7 @@ export {
   flattenError,
   toJSONSchema,
   TimePrecision,
+  util,
   NEVER,
 } from "../core/index.js";
 

package/v4/classic/external.cjs

@@ -29,7 +29,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.coerce = exports.iso = exports.ZodISODuration = exports.ZodISOTime = exports.ZodISODate = exports.ZodISODateTime = exports.locales = exports.NEVER = exports.TimePrecision = exports.toJSONSchema = exports.flattenError = exports.formatError = exports.prettifyError = exports.treeifyError = exports.regexes = exports.clone = exports.$brand = exports.$input = exports.$output = exports.config = exports.registry = exports.globalRegistry = exports.core = void 0;
+exports.coerce = exports.iso = exports.ZodISODuration = exports.ZodISOTime = exports.ZodISODate = exports.ZodISODateTime = exports.locales = exports.NEVER = exports.util = exports.TimePrecision = exports.toJSONSchema = exports.flattenError = exports.formatError = exports.prettifyError = exports.treeifyError = exports.regexes = exports.clone = exports.$brand = exports.$input = exports.$output = exports.config = exports.registry = exports.globalRegistry = exports.core = void 0;
 exports.core = __importStar(require("../core/index.cjs"));
 __exportStar(require("./schemas.cjs"), exports);
 __exportStar(require("./checks.cjs"), exports);
@@ -55,6 +55,7 @@ Object.defineProperty(exports, "formatError", { enumerable: true, get: function
 Object.defineProperty(exports, "flattenError", { enumerable: true, get: function () { return index_js_2.flattenError; } });
 Object.defineProperty(exports, "toJSONSchema", { enumerable: true, get: function () { return index_js_2.toJSONSchema; } });
 Object.defineProperty(exports, "TimePrecision", { enumerable: true, get: function () { return index_js_2.TimePrecision; } });
+Object.defineProperty(exports, "util", { enumerable: true, get: function () { return index_js_2.util; } });
 Object.defineProperty(exports, "NEVER", { enumerable: true, get: function () { return index_js_2.NEVER; } });
 exports.locales = __importStar(require("../locales/index.cjs"));
 // iso

package/v4/classic/external.d.cts

@@ -5,7 +5,7 @@ export * from "./errors.cjs";
 export * from "./parse.cjs";
 export * from "./compat.cjs";
 export type { infer, output, input } from "../core/index.cjs";
-export { globalRegistry, type GlobalMeta, registry, config, $output, $input, $brand, clone, regexes, treeifyError, prettifyError, formatError, flattenError, toJSONSchema, TimePrecision, NEVER, } from "../core/index.cjs";
+export { globalRegistry, type GlobalMeta, registry, config, $output, $input, $brand, clone, regexes, treeifyError, prettifyError, formatError, flattenError, toJSONSchema, TimePrecision, util, NEVER, } from "../core/index.cjs";
 export * as locales from "../locales/index.cjs";
 export { ZodISODateTime, ZodISODate, ZodISOTime, ZodISODuration } from "./iso.cjs";
 export * as iso from "./iso.cjs";

package/v4/classic/external.d.ts

@@ -5,7 +5,7 @@ export * from "./errors.js";
 export * from "./parse.js";
 export * from "./compat.js";
 export type { infer, output, input } from "../core/index.js";
-export { globalRegistry, type GlobalMeta, registry, config, $output, $input, $brand, clone, regexes, treeifyError, prettifyError, formatError, flattenError, toJSONSchema, TimePrecision, NEVER, } from "../core/index.js";
+export { globalRegistry, type GlobalMeta, registry, config, $output, $input, $brand, clone, regexes, treeifyError, prettifyError, formatError, flattenError, toJSONSchema, TimePrecision, util, NEVER, } from "../core/index.js";
 export * as locales from "../locales/index.js";
 export { ZodISODateTime, ZodISODate, ZodISOTime, ZodISODuration } from "./iso.js";
 export * as iso from "./iso.js";

package/v4/classic/external.js

@@ -8,7 +8,7 @@ export * from "./compat.js";
 import { config } from "../core/index.js";
 import en from "../locales/en.js";
 config(en());
-export { globalRegistry, registry, config, $output, $input, $brand, clone, regexes, treeifyError, prettifyError, formatError, flattenError, toJSONSchema, TimePrecision, NEVER, } from "../core/index.js";
+export { globalRegistry, registry, config, $output, $input, $brand, clone, regexes, treeifyError, prettifyError, formatError, flattenError, toJSONSchema, TimePrecision, util, NEVER, } from "../core/index.js";
 export * as locales from "../locales/index.js";
 // iso
 // must be exported from top-level

package/v4/mini/external.cjs

@@ -26,7 +26,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.coerce = exports.ZodMiniISODuration = exports.ZodMiniISOTime = exports.ZodMiniISODate = exports.ZodMiniISODateTime = exports.iso = exports.locales = exports.NEVER = exports.TimePrecision = exports.toJSONSchema = exports.flattenError = exports.formatError = exports.prettifyError = exports.treeifyError = exports.regexes = exports.clone = exports.$brand = exports.$input = exports.$output = exports.config = exports.registry = exports.globalRegistry = exports.core = void 0;
+exports.coerce = exports.ZodMiniISODuration = exports.ZodMiniISOTime = exports.ZodMiniISODate = exports.ZodMiniISODateTime = exports.iso = exports.locales = exports.NEVER = exports.util = exports.TimePrecision = exports.toJSONSchema = exports.flattenError = exports.formatError = exports.prettifyError = exports.treeifyError = exports.regexes = exports.clone = exports.$brand = exports.$input = exports.$output = exports.config = exports.registry = exports.globalRegistry = exports.core = void 0;
 exports.core = __importStar(require("../core/index.cjs"));
 __exportStar(require("./parse.cjs"), exports);
 __exportStar(require("./schemas.cjs"), exports);
@@ -46,6 +46,7 @@ Object.defineProperty(exports, "formatError", { enumerable: true, get: function
 Object.defineProperty(exports, "flattenError", { enumerable: true, get: function () { return index_js_1.flattenError; } });
 Object.defineProperty(exports, "toJSONSchema", { enumerable: true, get: function () { return index_js_1.toJSONSchema; } });
 Object.defineProperty(exports, "TimePrecision", { enumerable: true, get: function () { return index_js_1.TimePrecision; } });
+Object.defineProperty(exports, "util", { enumerable: true, get: function () { return index_js_1.util; } });
 Object.defineProperty(exports, "NEVER", { enumerable: true, get: function () { return index_js_1.NEVER; } });
 exports.locales = __importStar(require("../locales/index.cjs"));
 /** A special constant with type `never` */

package/v4/mini/external.d.cts

@@ -3,7 +3,7 @@ export * from "./parse.cjs";
 export * from "./schemas.cjs";
 export * from "./checks.cjs";
 export type { infer, output, input } from "../core/index.cjs";
-export { globalRegistry, registry, config, $output, $input, $brand, clone, regexes, treeifyError, prettifyError, formatError, flattenError, toJSONSchema, TimePrecision, NEVER, } from "../core/index.cjs";
+export { globalRegistry, registry, config, $output, $input, $brand, clone, regexes, treeifyError, prettifyError, formatError, flattenError, toJSONSchema, TimePrecision, util, NEVER, } from "../core/index.cjs";
 export * as locales from "../locales/index.cjs";
 /** A special constant with type `never` */
 export * as iso from "./iso.cjs";

package/v4/mini/external.d.ts

@@ -3,7 +3,7 @@ export * from "./parse.js";
 export * from "./schemas.js";
 export * from "./checks.js";
 export type { infer, output, input } from "../core/index.js";
-export { globalRegistry, registry, config, $output, $input, $brand, clone, regexes, treeifyError, prettifyError, formatError, flattenError, toJSONSchema, TimePrecision, NEVER, } from "../core/index.js";
+export { globalRegistry, registry, config, $output, $input, $brand, clone, regexes, treeifyError, prettifyError, formatError, flattenError, toJSONSchema, TimePrecision, util, NEVER, } from "../core/index.js";
 export * as locales from "../locales/index.js";
 /** A special constant with type `never` */
 export * as iso from "./iso.js";

package/v4/mini/external.js

@@ -2,7 +2,7 @@ export * as core from "../core/index.js";
 export * from "./parse.js";
 export * from "./schemas.js";
 export * from "./checks.js";
-export { globalRegistry, registry, config, $output, $input, $brand, clone, regexes, treeifyError, prettifyError, formatError, flattenError, toJSONSchema, TimePrecision, NEVER, } from "../core/index.js";
+export { globalRegistry, registry, config, $output, $input, $brand, clone, regexes, treeifyError, prettifyError, formatError, flattenError, toJSONSchema, TimePrecision, util, NEVER, } from "../core/index.js";
 export * as locales from "../locales/index.js";
 /** A special constant with type `never` */
 // export const NEVER = {} as never;