zod 3.20.6 → 3.21.1

package/README.md

@@ -24,6 +24,8 @@
   <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
   <a href="https://www.npmjs.com/package/zod">npm</a>
   <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://deno.land/x/zod">deno</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
   <a href="https://github.com/colinhacks/zod/issues/new">Issues</a>
   <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
   <a href="https://twitter.com/colinhacks">@colinhacks</a>
@@ -55,7 +57,10 @@
 - [Coercion for primitives](#coercion-for-primitives)
 - [Literals](#literals)
 - [Strings](#strings)
+  - [Datetime](#datetime-validation)
+  - [IP](#ip-address-validation)
 - [Numbers](#numbers)
+- [BigInts](#bigints)
 - [NaNs](#nans)
 - [Booleans](#booleans)
 - [Dates](#dates)
@@ -113,6 +118,7 @@
   - [.or](#or)
   - [.and](#and)
   - [.brand](#brand)
+  - [.pipe](#pipe)
 - [Guides and concepts](#guides-and-concepts)
   - [Type inference](#type-inference)
   - [Writing generic functions](#writing-generic-functions)
@@ -200,6 +206,26 @@ Sponsorship at any level is appreciated and encouraged. For individual developer
       <a href="https://proxy.com">proxy.com</a>
     </td>
   </tr>
+    <tr>
+    <td align="center">
+      <a href="https://trigger.dev/">
+        <img src="https://avatars.githubusercontent.com/u/95297378?s=200&v=4" width="200px;" alt="Trigger.dev logo" />
+      </a>
+      <br />
+      <b>Trigger.dev</b>
+      <br />
+      <a href="https://trigger.dev">trigger.dev</a>
+    </td>
+    <!-- <td align="center">
+      <a href="https://proxy.com/">
+        <img src="https://avatars.githubusercontent.com/u/14321439?s=200&v=4" width="200px;" alt="Proxy logo" />
+      </a>
+      <br />
+      <b>Proxy</b>
+      <br />
+      <a href="https://proxy.com">proxy.com</a>
+    </td> -->
+  </tr>
 </table>
 
 #### Silver
@@ -303,7 +329,7 @@ Sponsorship at any level is appreciated and encouraged. For individual developer
     </td>
   </tr>
   <tr>
-  <td align="center">
+    <td align="center">
       <a href="https://fungible.systems/">
         <img src="https://avatars.githubusercontent.com/u/80220121?s=200&v=4" width="100px;" alt="Fungible Systems logo"/>
       </a>
@@ -335,6 +361,39 @@ Sponsorship at any level is appreciated and encouraged. For individual developer
       <br />
     </td>
   </tr>
+  <tr>
+  <td align="center">
+      <a href="https://learnwithjason.dev">
+        <img src="https://avatars.githubusercontent.com/u/66575486?s=200&v=4" width="100px;" alt="Learn with Jason logo"/>
+      </a>
+      <br />
+      <b>Jason Lengstorf</b>
+      <br/>
+      <a href="https://learnwithjason.dev/">learnwithjason.dev</a>
+      <br />
+    </td>
+    <td align="center">
+      <a href="https://ill.inc/">
+        <img src="https://avatars.githubusercontent.com/u/89107581?s=200&v=4" width="100px;" alt="Global Illumination"/>
+      </a>
+      <br />
+      <b>Global Illumination, Inc.</b>
+      <br/>
+      <a href="https://ill.inc/">ill.inc</a>
+      <br />
+    </td>
+    <!-- <td align="center">
+      <a href="https://www.avanawallet.com/">
+        <img src="https://avatars.githubusercontent.com/u/105452197?s=200&v=4" width="100px;" alt="Avana Wallet logo"/>
+      </a>
+      <br />
+      <b>Avana Wallet</b>
+      <br/>
+      <a href="https://www.avanawallet.com/">avanawallet.com</a><br/>
+      <span>Solana non-custodial wallet</span>
+      <br />
+    </td> -->
+  </tr>
 </table>
 
 ### Ecosystem
@@ -581,19 +640,28 @@ tuna.value; // "tuna"
 Zod includes a handful of string-specific validations.
 
 ```ts
+// validations
 z.string().max(5);
 z.string().min(5);
 z.string().length(5);
 z.string().email();
 z.string().url();
+z.string().emoji();
 z.string().uuid();
 z.string().cuid();
 z.string().cuid2();
+z.string().ulid();
 z.string().regex(regex);
+z.string().includes(string);
 z.string().startsWith(string);
 z.string().endsWith(string);
-z.string().trim(); // trim whitespace
 z.string().datetime(); // defaults to UTC, see below for options
+z.string().ip(); // defaults to IPv4 and IPv6, see below for options
+
+// transformations
+z.string().trim(); // trim whitespace
+z.string().toLowerCase(); // toLowerCase
+z.string().toUpperCase(); // toUpperCase
 ```
 
 > Check out [validator.js](https://github.com/validatorjs/validator.js) for a bunch of other useful string validation functions that can be used in conjunction with [Refinements](#refine).
@@ -615,13 +683,16 @@ z.string().max(5, { message: "Must be 5 or fewer characters long" });
 z.string().length(5, { message: "Must be exactly 5 characters long" });
 z.string().email({ message: "Invalid email address" });
 z.string().url({ message: "Invalid url" });
+z.string().emoji({ message: "Contains non-emoji characters" });
 z.string().uuid({ message: "Invalid UUID" });
+z.string().includes("tuna", { message: "Must include tuna" });
 z.string().startsWith("https://", { message: "Must provide secure URL" });
 z.string().endsWith(".com", { message: "Only .com domains allowed" });
 z.string().datetime({ message: "Invalid datetime string! Must be UTC." });
+z.string().ip({ message: "Invalid IP address" });
 ```
 
-### Datetime validation
+### ISO datetimes
 
 The `z.string().datetime()` method defaults to UTC validation: no timezone offsets with arbitrary sub-second decimal precision.
 
@@ -656,6 +727,31 @@ datetime.parse("2020-01-01T00:00:00Z"); // fail
 datetime.parse("2020-01-01T00:00:00.123456Z"); // fail
 ```
 
+### IP addresses
+
+The `z.string().ip()` method by default validate IPv4 and IPv6.
+
+```ts
+const ip = z.string().ip();
+
+ip.parse("192.168.1.1"); // pass
+ip.parse("84d5:51a0:9114:1855:4cfa:f2d7:1f12:7003"); // pass
+ip.parse("84d5:51a0:9114:1855:4cfa:f2d7:1f12:192.168.1.1"); // pass
+
+ip.parse("256.1.1.1"); // fail
+ip.parse("84d5:51a0:9114:gggg:4cfa:f2d7:1f12:7003"); // fail
+```
+
+You can additionally set the IP `version`.
+
+```ts
+const ipv4 = z.string().ip({ version: "v4" });
+ipv4.parse("84d5:51a0:9114:1855:4cfa:f2d7:1f12:7003"); // fail
+
+const ipv6 = z.string().ip({ version: "v6" });
+ipv6.parse("192.168.1.1"); // fail
+```
+
 ## Numbers
 
 You can customize certain error messages when creating a number schema.
@@ -685,6 +781,7 @@ z.number().nonpositive(); //  <= 0
 z.number().multipleOf(5); // Evenly divisible by 5. Alias .step(5)
 
 z.number().finite(); // value must be finite, not Infinity or -Infinity
+z.number().safe(); // value must be between Number.MIN_SAFE_INTEGER and Number.MAX_SAFE_INTEGER
 ```
 
 Optionally, you can pass in a second argument to provide a custom error message.
@@ -693,6 +790,24 @@ Optionally, you can pass in a second argument to provide a custom error message.
 z.number().lte(5, { message: "this👏is👏too👏big" });
 ```
 
+## BigInts
+
+Zod includes a handful of bigint-specific validations.
+
+```ts
+z.bigint().gt(5n);
+z.bigint().gte(5n); // alias `.min(5n)`
+z.bigint().lt(5n);
+z.bigint().lte(5n); // alias `.max(5n)`
+
+z.bigint().positive(); // > 0n
+z.bigint().nonnegative(); // >= 0n
+z.bigint().negative(); // < 0n
+z.bigint().nonpositive(); // <= 0n
+
+z.bigint().multipleOf(5n); // Evenly divisible by 5n.
+```
+
 ## NaNs
 
 You can customize certain error messages when creating a nan schema.
@@ -1409,7 +1524,7 @@ type NumberSet = z.infer<typeof numberSet>;
 // type NumberSet = Set<number>
 ```
 
-Set schemas can be further contrainted with the following utility methods.
+Set schemas can be further constrained with the following utility methods.
 
 ```ts
 z.set(z.string()).nonempty(); // must contain at least one item
@@ -1703,9 +1818,14 @@ This returns a `ZodEffects` instance. `ZodEffects` is a wrapper class that conta
 You can create a Zod schema for any TypeScript type by using `z.custom()`. This is useful for creating schemas for types that are not supported by Zod out of the box, such as template string literals.
 
 ```ts
-const px = z.custom<`${number}px`>((val) => /^\d+px$/.test(val));
-px.parse("100px"); // pass
-px.parse("100vw"); // fail
+const px = z.custom<`${number}px`>((val) => {
+  return /^\d+px$/.test(val as string);
+});
+
+type px = z.infer<typeof px>; // `${number}px`
+
+px.parse("42px"); // "42px"
+px.parse("42vw"); // throws;
 ```
 
 If you don't provide a validation function, Zod will allow any value. This can be dangerous!
@@ -1714,6 +1834,12 @@ If you don't provide a validation function, Zod will allow any value. This can b
 z.custom<{ arg: string }>(); // performs no validation
 ```
 
+You can customize the error message and other options by passing a second argument. This parameter works the same way as the params parameter of [`.refine`](#refine).
+
+```ts
+z.custom<...>((val) => ..., "custom error message");
+```
+
 ## Schema methods
 
 All Zod schemas contain certain methods.
@@ -2118,14 +2244,17 @@ numberWithCatch.parse(5); // => 5
 numberWithCatch.parse("tuna"); // => 42
 ```
 
-Optionally, you can pass a function into `.catch` that will be re-executed whenever a default value needs to be generated:
+Optionally, you can pass a function into `.catch` that will be re-executed whenever a default value needs to be generated. A `ctx` object containing the caught error will be passed into this function.
 
 ```ts
-const numberWithRandomCatch = z.number().catch(Math.random);
+const numberWithRandomCatch = z.number().catch((ctx) => {
+  ctx.error; // the caught ZodError
+  return Math.random();
+});
 
-numberWithRandomDefault.parse("sup"); // => 0.4413456736055323
-numberWithRandomDefault.parse("sup"); // => 0.1871840107401901
-numberWithRandomDefault.parse("sup"); // => 0.7223408162401552
+numberWithRandomCatch.parse("sup"); // => 0.4413456736055323
+numberWithRandomCatch.parse("sup"); // => 0.1871840107401901
+numberWithRandomCatch.parse("sup"); // => 0.7223408162401552
 ```
 
 Conceptually, this is how Zod processes "catch values":
@@ -2253,6 +2382,18 @@ type Cat = z.infer<typeof Cat>;
 
 Note that branded types do not affect the runtime result of `.parse`. It is a static-only construct.
 
+### `.pipe()`
+
+Schemas can be chained into validation "pipelines". It's useful for easily validating the result after a `.transform()`:
+
+```ts
+z.string()
+  .transform((val) => val.length)
+  .pipe(z.number().min(5));
+```
+
+The `.pipe()` method returns a `ZodPipeline` instance.
+
 ## Guides and concepts
 
 ### Type inference
@@ -2349,14 +2490,14 @@ makeSchemaOptional(z.number());
 Zod provides a subclass of Error called `ZodError`. ZodErrors contain an `issues` array containing detailed information about the validation problems.
 
 ```ts
-const data = z
+const result = z
   .object({
     name: z.string(),
   })
   .safeParse({ name: 12 });
 
-if (!data.success) {
-  data.error.issues;
+if (!result.success) {
+  result.error.issues;
   /* [
       {
         "code": "invalid_type",
@@ -2378,14 +2519,14 @@ Zod's error reporting emphasizes _completeness_ and _correctness_. If you are lo
 You can use the `.format()` method to convert this error into a nested object.
 
 ```ts
-const data = z
+const result = z
   .object({
     name: z.string(),
   })
   .safeParse({ name: 12 });
 
-if (!data.success) {
-  const formatted = data.error.format();
+if (!result.success) {
+  const formatted = result.error.format();
   /* {
     name: { _errors: [ 'Expected string, received number' ] }
   } */

package/lib/ZodError.d.ts

@@ -70,7 +70,10 @@ export interface ZodInvalidReturnTypeIssue extends ZodIssueBase {
 export interface ZodInvalidDateIssue extends ZodIssueBase {
     code: typeof ZodIssueCode.invalid_date;
 }
-export declare type StringValidation = "email" | "url" | "uuid" | "regex" | "cuid" | "cuid2" | "datetime" | {
+export declare type StringValidation = "email" | "url" | "emoji" | "uuid" | "regex" | "cuid" | "cuid2" | "ulid" | "datetime" | "ip" | {
+    includes: string;
+    position?: number;
+} | {
     startsWith: string;
 } | {
     endsWith: string;
@@ -81,24 +84,24 @@ export interface ZodInvalidStringIssue extends ZodIssueBase {
 }
 export interface ZodTooSmallIssue extends ZodIssueBase {
     code: typeof ZodIssueCode.too_small;
-    minimum: number;
+    minimum: number | bigint;
     inclusive: boolean;
     exact?: boolean;
-    type: "array" | "string" | "number" | "set" | "date";
+    type: "array" | "string" | "number" | "set" | "date" | "bigint";
 }
 export interface ZodTooBigIssue extends ZodIssueBase {
     code: typeof ZodIssueCode.too_big;
-    maximum: number;
+    maximum: number | bigint;
     inclusive: boolean;
     exact?: boolean;
-    type: "array" | "string" | "number" | "set" | "date";
+    type: "array" | "string" | "number" | "set" | "date" | "bigint";
 }
 export interface ZodInvalidIntersectionTypesIssue extends ZodIssueBase {
     code: typeof ZodIssueCode.invalid_intersection_types;
 }
 export interface ZodNotMultipleOfIssue extends ZodIssueBase {
     code: typeof ZodIssueCode.not_multiple_of;
-    multipleOf: number;
+    multipleOf: number | bigint;
 }
 export interface ZodNotFiniteIssue extends ZodIssueBase {
     code: typeof ZodIssueCode.not_finite;
@@ -118,15 +121,16 @@ export declare type ZodIssue = ZodIssueOptionalMessage & {
     message: string;
 };
 export declare const quotelessJson: (obj: any) => string;
+declare type recursiveZodFormattedError<T> = T extends [any, ...any[]] ? {
+    [K in keyof T]?: ZodFormattedError<T[K]>;
+} : T extends any[] ? {
+    [k: number]: ZodFormattedError<T[number]>;
+} : T extends object ? {
+    [K in keyof T]?: ZodFormattedError<T[K]>;
+} : unknown;
 export declare type ZodFormattedError<T, U = string> = {
     _errors: U[];
-} & (NonNullable<T> extends [any, ...any[]] ? {
-    [K in keyof NonNullable<T>]?: ZodFormattedError<NonNullable<T>[K], U>;
-} : NonNullable<T> extends any[] ? {
-    [k: number]: ZodFormattedError<NonNullable<T>[number], U>;
-} : NonNullable<T> extends object ? {
-    [K in keyof NonNullable<T>]?: ZodFormattedError<NonNullable<T>[K], U>;
-} : unknown);
+} & recursiveZodFormattedError<NonNullable<T>>;
 export declare type inferFormattedError<T extends ZodType<any, any, any>, U = string> = ZodFormattedError<TypeOf<T>, U>;
 export declare class ZodError<T = any> extends Error {
     issues: ZodIssue[];

package/lib/ZodError.js

@@ -37,7 +37,6 @@ class ZodError extends Error {
         };
         const actualProto = new.target.prototype;
         if (Object.setPrototypeOf) {
-            // eslint-disable-next-line ban/ban
             Object.setPrototypeOf(this, actualProto);
         }
         else {
@@ -77,13 +76,6 @@ class ZodError extends Error {
                         const terminal = i === issue.path.length - 1;
                         if (!terminal) {
                             curr[el] = curr[el] || { _errors: [] };
-                            // if (typeof el === "string") {
-                            //   curr[el] = curr[el] || { _errors: [] };
-                            // } else if (typeof el === "number") {
-                            //   const errorArray: any = [];
-                            //   errorArray._errors = [];
-                            //   curr[el] = curr[el] || errorArray;
-                            // }
                         }
                         else {
                             curr[el] = curr[el] || { _errors: [] };

package/lib/benchmarks/index.js

@@ -9,13 +9,38 @@ const primitives_1 = __importDefault(require("./primitives"));
 const realworld_1 = __importDefault(require("./realworld"));
 const string_1 = __importDefault(require("./string"));
 const union_1 = __importDefault(require("./union"));
-for (const suite of [
-    ...realworld_1.default.suites,
-    ...primitives_1.default.suites,
-    ...string_1.default.suites,
-    ...object_1.default.suites,
-    ...union_1.default.suites,
-    ...discriminatedUnion_1.default.suites,
-]) {
+const argv = process.argv.slice(2);
+let suites = [];
+if (!argv.length) {
+    suites = [
+        ...realworld_1.default.suites,
+        ...primitives_1.default.suites,
+        ...string_1.default.suites,
+        ...object_1.default.suites,
+        ...union_1.default.suites,
+        ...discriminatedUnion_1.default.suites,
+    ];
+}
+else {
+    if (argv.includes("--realworld")) {
+        suites.push(...realworld_1.default.suites);
+    }
+    if (argv.includes("--primitives")) {
+        suites.push(...primitives_1.default.suites);
+    }
+    if (argv.includes("--string")) {
+        suites.push(...string_1.default.suites);
+    }
+    if (argv.includes("--object")) {
+        suites.push(...object_1.default.suites);
+    }
+    if (argv.includes("--union")) {
+        suites.push(...union_1.default.suites);
+    }
+    if (argv.includes("--discriminatedUnion")) {
+        suites.push(...discriminatedUnion_1.default.suites);
+    }
+}
+for (const suite of suites) {
     suite.run();
 }

package/lib/helpers/parseUtil.js

@@ -38,7 +38,7 @@ function addIssueToContext(ctx, issueData) {
             ctx.common.contextualErrorMap,
             ctx.schemaErrorMap,
             (0, errors_1.getErrorMap)(),
-            en_1.default, // then global default map
+            en_1.default,
         ].filter((x) => !!x),
     });
     ctx.common.issues.push(issue);

package/lib/helpers/util.d.ts

@@ -11,16 +11,39 @@ export declare namespace util {
     export const objectValues: (obj: any) => any[];
     export const objectKeys: ObjectConstructor["keys"];
     export const find: <T>(arr: T[], checker: (arg: T) => any) => T | undefined;
-    export type identity<T> = T;
-    export type flatten<T> = identity<{
-        [k in keyof T]: T[k];
-    }>;
+    export type identity<T> = objectUtil.identity<T>;
+    export type flatten<T> = objectUtil.flatten<T>;
     export type noUndefined<T> = T extends undefined ? never : T;
     export const isInteger: NumberConstructor["isInteger"];
     export function joinValues<T extends any[]>(array: T, separator?: string): string;
     export const jsonStringifyReplacer: (_: string, value: any) => any;
     export {};
 }
+export declare namespace objectUtil {
+    export type MergeShapes<U, V> = {
+        [k in Exclude<keyof U, keyof V>]: U[k];
+    } & V;
+    type optionalKeys<T extends object> = {
+        [k in keyof T]: undefined extends T[k] ? k : never;
+    }[keyof T];
+    type requiredKeys<T extends object> = {
+        [k in keyof T]: undefined extends T[k] ? never : k;
+    }[keyof T];
+    export type addQuestionMarks<T extends object> = Partial<Pick<T, optionalKeys<T>>> & Pick<T, requiredKeys<T>>;
+    export type identity<T> = T;
+    export type flatten<T> = identity<{
+        [k in keyof T]: T[k];
+    }>;
+    export type noNeverKeys<T> = {
+        [k in keyof T]: [T[k]] extends [never] ? never : k;
+    }[keyof T];
+    export type noNever<T> = identity<{
+        [k in noNeverKeys<T>]: k extends keyof T ? T[k] : never;
+    }>;
+    export const mergeShapes: <U, T>(first: U, second: T) => T & U;
+    export type extendShape<A, B> = flatten<Omit<A, keyof B> & B>;
+    export {};
+}
 export declare const ZodParsedType: {
     function: "function";
     number: "number";

package/lib/helpers/util.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getParsedType = exports.ZodParsedType = exports.util = void 0;
+exports.getParsedType = exports.ZodParsedType = exports.objectUtil = exports.util = void 0;
 var util;
 (function (util) {
     util.assertEqual = (val) => val;
@@ -30,8 +30,8 @@ var util;
             return obj[e];
         });
     };
-    util.objectKeys = typeof Object.keys === "function" // eslint-disable-line ban/ban
-        ? (obj) => Object.keys(obj) // eslint-disable-line ban/ban
+    util.objectKeys = typeof Object.keys === "function"
+        ? (obj) => Object.keys(obj)
         : (object) => {
             const keys = [];
             for (const key in object) {
@@ -49,7 +49,7 @@ var util;
         return undefined;
     };
     util.isInteger = typeof Number.isInteger === "function"
-        ? (val) => Number.isInteger(val) // eslint-disable-line ban/ban
+        ? (val) => Number.isInteger(val)
         : (val) => typeof val === "number" && isFinite(val) && Math.floor(val) === val;
     function joinValues(array, separator = " | ") {
         return array
@@ -64,6 +64,15 @@ var util;
         return value;
     };
 })(util = exports.util || (exports.util = {}));
+var objectUtil;
+(function (objectUtil) {
+    objectUtil.mergeShapes = (first, second) => {
+        return {
+            ...first,
+            ...second,
+        };
+    };
+})(objectUtil = exports.objectUtil || (exports.objectUtil = {}));
 exports.ZodParsedType = util.arrayToEnum([
     "string",
     "nan",

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-import * as mod from "./external";
+import * as z from "./external";
 export * from "./external";
-export { mod as z };
-export default mod;
+export { z };
+export default z;

package/lib/index.js

@@ -23,7 +23,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.z = void 0;
-const mod = __importStar(require("./external"));
-exports.z = mod;
+const z = __importStar(require("./external"));
+exports.z = z;
 __exportStar(require("./external"), exports);
-exports.default = mod;
+exports.default = z;