zod 3.14.0 → 3.14.3

package/README.md

@@ -3,11 +3,11 @@
   <h1 align="center">Zod</h1>
 </p>
 <p align="center">
+<a href="https://github.com/edgedb/edgedb-js/actions"><img src="https://github.com/colinhacks/zod/actions/workflows/test.yml/badge.svg?event=push&branch=master" alt="Zod CI status" /></a>
 <a href="https://twitter.com/colinhacks" rel="nofollow"><img src="https://img.shields.io/badge/created%20by-@colinhacks-4BBAAB.svg" alt="Created by Colin McDonnell"></a>
 <a href="https://opensource.org/licenses/MIT" rel="nofollow"><img src="https://img.shields.io/github/license/colinhacks/zod" alt="License"></a>
 <a href="https://www.npmjs.com/package/zod" rel="nofollow"><img src="https://img.shields.io/npm/dw/zod.svg" alt="npm"></a>
 <a href="https://www.npmjs.com/package/zod" rel="nofollow"><img src="https://img.shields.io/github/stars/colinhacks/zod" alt="stars"></a>
-<a href="./src/__tests__" rel="nofollow"><img src="./coverage.svg" alt="coverage"></a>
 <a href="https://discord.gg/KaSRdyX2vc" rel="nofollow"><img src="https://img.shields.io/discord/893487829802418277?label=Discord&logo=discord&logoColor=white" alt="discord server"></a>
 </p>
 
@@ -94,8 +94,10 @@ These docs have been translated into [Chinese](./README_ZH.md).
   - [.promise](#promise)
   - [.or](#or)
   - [.and](#and)
-- [Type inference](#type-inference)
-- [Errors](#errors)
+- [Guides and concepts](#guides-and-concepts)
+  - [Type inference](#type-inference)
+  - [Writing generic functions](#writing-generic-functions)
+  - [Error handling](#error-handling)
 - [Comparison](#comparison)
   - [Joi](#joi)
   - [Yup](#yup)
@@ -241,6 +243,8 @@ There are a growing number of tools that are built atop or support Zod natively!
 - [`soly`](https://github.com/mdbetancourt/soly): Create CLI applications with zod.
 - [`graphql-codegen-typescript-validation-schema`](https://github.com/Code-Hex/graphql-codegen-typescript-validation-schema): GraphQL Code Generator plugin to generate form validation schema from your GraphQL schema
 - [`zod-prisma`](https://github.com/CarterGrimmeisen/zod-prisma): Generate Zod schemas from your Prisma schema.
+- [`fastify-type-provider-zod`](https://github.com/turkerdev/fastify-type-provider-zod): Create Fastify type providers from Zod schemas
+- [`Supervillain`](https://github.com/Southclaws/supervillain): Generate Zod schemas from your Go structs
 
 ### Form integrations
 
@@ -1687,7 +1691,9 @@ z.object({ name: z.string() }).and(z.object({ age: z.number() })); // { name: st
 z.intersection(z.object({ name: z.string() }), z.object({ age: z.number() }));
 ```
 
-# Type inference
+# Guides and concepts
+
+## Type inference
 
 You can extract the TypeScript type of any schema with `z.infer<typeof mySchema>` .
 
@@ -1716,16 +1722,72 @@ type output = z.output<typeof stringToNumber>; // number
 type inferred = z.infer<typeof stringToNumber>; // number
 ```
 
-# Errors
+## Writing generic functions
+
+When attempting to write a functions that accepts a Zod schemas as an input, it's common to try something like this:
+
+```ts
+function makeSchemaOptional<T>(schema: z.ZodType<T>) {
+  return schema.optional();
+}
+```
+
+This approach has some issues. The `schema` variable in this function is typed as an instance of `ZodType`, which is an abstract class that all Zod schemas inherit from. This approach loses type information, namely _which subclass_ the input actually is.
+
+```ts
+const arg = makeSchemaOptional(z.string());
+arg.unwrap();
+```
+
+A better approach is for the generate parameter to refer to _the schema as a whole_.
+
+```ts
+function makeSchemaOptional<T extends z.ZodTypeAny>(schema: T) {
+  return schema.optional();
+}
+```
+
+> `ZodTypeAny` is just a shorthand for `ZodType<any, any, any>`, a type that is broad enough to match any Zod schema.
+
+As you can see, `schema` is now fully and properly typed.
+
+```ts
+const arg = makeSchemaOptional(z.string());
+arg.unwrap(); // ZodString
+```
+
+### Restricting valid schemas
+
+The `ZodType` class has three generic parameters.
+
+```ts
+class ZodType<
+  Output,
+  Def extends ZodTypeDef = ZodTypeDef,
+  Input = Output
+> { ... }
+```
+
+By contraining these in your generic input, you can limit what schemas are allowable as inputs to your function:
+
+```ts
+function makeSchemaOptional<T extends z.ZodType<string>>(schema: T) {
+  return schema.optional();
+}
+
+makeSchemaOptional(z.string());
+// works fine
+
+makeSchemaOptional(z.number());
+// Error: 'ZodNumber' is not assignable to parameter of type 'ZodType<string, ZodTypeDef, string>'
+```
+
+## Error handling
 
 Zod provides a subclass of Error called `ZodError`. ZodErrors contain an `issues` array containing detailed information about the validation problems.
 
 ```ts
-const data = z
-  .object({
-    name: z.string(),
-  })
-  .safeParse({ name: 12 });
+const data = z.object({ name: z.string() }).safeParse({ name: 12 });
 
 if (!data.success) {
   data.error.issues;

package/lib/benchmarks/index.js

@@ -5,11 +5,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const discriminatedUnion_1 = __importDefault(require("./discriminatedUnion"));
 const object_1 = __importDefault(require("./object"));
+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,

package/lib/benchmarks/primitives.d.ts

@@ -0,0 +1,5 @@
+import Benchmark from "benchmark";
+declare const _default: {
+    suites: Benchmark.Suite[];
+};
+export default _default;

package/lib/benchmarks/primitives.js

@@ -0,0 +1,78 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const benchmark_1 = __importDefault(require("benchmark"));
+const index_1 = require("../index");
+const enumSuite = new benchmark_1.default.Suite("z.enum");
+const enumSchema = index_1.z.enum(["a", "b", "c"]);
+enumSuite
+    .add("valid", () => {
+    enumSchema.parse("a");
+})
+    .add("invalid", () => {
+    try {
+        enumSchema.parse("x");
+    }
+    catch (e) { }
+})
+    .on("cycle", (e) => {
+    console.log(`z.enum: ${e.target}`);
+});
+const undefinedSuite = new benchmark_1.default.Suite("z.undefined");
+const undefinedSchema = index_1.z.undefined();
+undefinedSuite
+    .add("valid", () => {
+    undefinedSchema.parse(undefined);
+})
+    .add("invalid", () => {
+    try {
+        undefinedSchema.parse(1);
+    }
+    catch (e) { }
+})
+    .on("cycle", (e) => {
+    console.log(`z.undefined: ${e.target}`);
+});
+const literalSuite = new benchmark_1.default.Suite("z.literal");
+const short = "short";
+const bad = "bad";
+const literalSchema = index_1.z.literal("short");
+literalSuite
+    .add("valid", () => {
+    literalSchema.parse(short);
+})
+    .add("invalid", () => {
+    try {
+        literalSchema.parse(bad);
+    }
+    catch (e) { }
+})
+    .on("cycle", (e) => {
+    console.log(`z.literal: ${e.target}`);
+});
+const numberSuite = new benchmark_1.default.Suite("z.number");
+const numberSchema = index_1.z.number().int();
+numberSuite
+    .add("valid", () => {
+    numberSchema.parse(1);
+})
+    .add("invalid type", () => {
+    try {
+        numberSchema.parse("bad");
+    }
+    catch (e) { }
+})
+    .add("invalid number", () => {
+    try {
+        numberSchema.parse(0.5);
+    }
+    catch (e) { }
+})
+    .on("cycle", (e) => {
+    console.log(`z.number: ${e.target}`);
+});
+exports.default = {
+    suites: [enumSuite, undefinedSuite, literalSuite, numberSuite],
+};

package/lib/benchmarks/string.js

@@ -17,6 +17,8 @@ const manual = (str) => {
     return str;
 };
 const stringSchema = index_1.z.string();
+const optionalStringSchema = index_1.z.string().optional();
+const optionalNullableStringSchema = index_1.z.string().optional().nullable();
 suite
     .add("empty string", () => {
     stringSchema.parse(empty);
@@ -26,6 +28,15 @@ suite
 })
     .add("long string", () => {
     stringSchema.parse(long);
+})
+    .add("optional string", () => {
+    optionalStringSchema.parse(long);
+})
+    .add("nullable string", () => {
+    optionalNullableStringSchema.parse(long);
+})
+    .add("nullable (null) string", () => {
+    optionalNullableStringSchema.parse(null);
 })
     .add("invalid: null", () => {
     try {

package/lib/helpers/parseUtil.d.ts

@@ -38,11 +38,14 @@ export declare type ParsePathComponent = string | number;
 export declare type ParsePath = ParsePathComponent[];
 export declare const EMPTY_PATH: ParsePath;
 export interface ParseContext {
+    readonly common: {
+        readonly issues: ZodIssue[];
+        readonly contextualErrorMap?: ZodErrorMap;
+        readonly async: boolean;
+        readonly typeCache: Map<any, ZodParsedType> | undefined;
+    };
     readonly path: ParsePath;
-    readonly issues: ZodIssue[];
     readonly schemaErrorMap?: ZodErrorMap;
-    readonly contextualErrorMap?: ZodErrorMap;
-    readonly async: boolean;
     readonly parent: ParseContext | null;
     readonly data: any;
     readonly parsedType: ZodParsedType;

package/lib/helpers/parseUtil.js

@@ -97,13 +97,13 @@ function addIssueToContext(ctx, issueData) {
         data: ctx.data,
         path: ctx.path,
         errorMaps: [
-            ctx.contextualErrorMap,
+            ctx.common.contextualErrorMap,
             ctx.schemaErrorMap,
             ZodError_1.overrideErrorMap,
             ZodError_1.defaultErrorMap, // then global default map
         ].filter((x) => !!x),
     });
-    ctx.issues.push(issue);
+    ctx.common.issues.push(issue);
 }
 exports.addIssueToContext = addIssueToContext;
 class ParseStatus {