Merge branch 'master' into patch-1

colinhacks · May 21, 2023 · a88eac2 · a88eac2
2 parents 7004199 + 11e507c
commit a88eac2
Show file tree

Hide file tree

Showing 14 changed files with 727 additions and 249 deletions.
diff --git a/README.md b/README.md
@@ -45,20 +45,32 @@
 
 #### Go to [zod.js.org](https://zod.js.org) >> -->
 
+- [Table of contents](#table-of-contents)
 - [Introduction](#introduction)
   - [Sponsors](#sponsors)
+    - [Gold](#gold)
+    - [Silver](#silver)
+    - [Bronze](#bronze)
   - [Ecosystem](#ecosystem)
+    - [Resources](#resources)
+    - [API libraries](#api-libraries)
+    - [Form integrations](#form-integrations)
+    - [Zod to X](#zod-to-x)
+    - [X to Zod](#x-to-zod)
+    - [Mocking](#mocking)
+    - [Powered by Zod](#powered-by-zod)
+    - [Utilities for Zod](#utilities-for-zod)
 - [Installation](#installation)
   - [Requirements](#requirements)
-  - [Node/npm](#from-npm-nodebun)
-  - [Deno](#from-denolandx-deno)
+  - [From `npm` (Node/Bun)](#from-npm-nodebun)
+  - [From `deno.land/x` (Deno)](#from-denolandx-deno)
 - [Basic usage](#basic-usage)
 - [Primitives](#primitives)
 - [Coercion for primitives](#coercion-for-primitives)
 - [Literals](#literals)
 - [Strings](#strings)
-  - [Datetime](#iso-datetimes)
-  - [IP](#ip-addresses)
+  - [ISO datetimes](#iso-datetimes)
+  - [IP addresses](#ip-addresses)
 - [Numbers](#numbers)
 - [BigInts](#bigints)
 - [NaNs](#nans)
@@ -69,70 +81,84 @@
 - [Optionals](#optionals)
 - [Nullables](#nullables)
 - [Objects](#objects)
-  - [.shape](#shape)
-  - [.keyof](#keyof)
-  - [.extend](#extend)
-  - [.merge](#merge)
-  - [.pick/.omit](#pickomit)
-  - [.partial](#partial)
-  - [.deepPartial](#deepPartial)
-  - [.passthrough](#passthrough)
-  - [.strict](#strict)
-  - [.strip](#strip)
-  - [.catchall](#catchall)
+  - [`.shape`](#shape)
+  - [`.keyof`](#keyof)
+  - [`.extend`](#extend)
+  - [`.merge`](#merge)
+  - [`.pick/.omit`](#pickomit)
+  - [`.partial`](#partial)
+  - [`.deepPartial`](#deeppartial)
+  - [`.required`](#required)
+  - [`.passthrough`](#passthrough)
+  - [`.strict`](#strict)
+  - [`.strip`](#strip)
+  - [`.catchall`](#catchall)
 - [Arrays](#arrays)
-  - [.element](#element)
-  - [.nonempty](#nonempty)
-  - [.min/.max/.length](#minmaxlength)
+  - [`.element`](#element)
+  - [`.nonempty`](#nonempty)
+  - [`.min/.max/.length`](#minmaxlength)
 - [Tuples](#tuples)
 - [Unions](#unions)
-- [Discriminated Unions](#discriminated-unions)
+- [Discriminated unions](#discriminated-unions)
 - [Records](#records)
+  - [Record key type](#record-key-type)
 - [Maps](#maps)
 - [Sets](#sets)
 - [Intersections](#intersections)
 - [Recursive types](#recursive-types)
+  - [ZodType with ZodEffects](#zodtype-with-zodeffects)
   - [JSON type](#json-type)
-  - [Cyclical data](#cyclical-objects)
+  - [Cyclical objects](#cyclical-objects)
 - [Promises](#promises)
 - [Instanceof](#instanceof)
 - [Functions](#functions)
 - [Preprocess](#preprocess)
-- [Custom](#custom-schemas)
+- [Custom schemas](#custom-schemas)
 - [Schema methods](#schema-methods)
-  - [.parse](#parse)
-  - [.parseAsync](#parseasync)
-  - [.safeParse](#safeparse)
-  - [.safeParseAsync](#safeparseasync)
-  - [.refine](#refine)
-  - [.superRefine](#superRefine)
-  - [.transform](#transform)
-  - [.default](#default)
-  - [.describe](#describe)
-  - [.catch](#catch)
-  - [.optional](#optional)
-  - [.nullable](#nullable)
-  - [.nullish](#nullish)
-  - [.array](#array)
-  - [.promise](#promise)
-  - [.or](#or)
-  - [.and](#and)
-  - [.brand](#brand)
-  - [.pipe](#pipe)
+  - [`.parse`](#parse)
+  - [`.parseAsync`](#parseasync)
+  - [`.safeParse`](#safeparse)
+  - [`.safeParseAsync`](#safeparseasync)
+  - [`.refine`](#refine)
+    - [Arguments](#arguments)
+    - [Customize error path](#customize-error-path)
+    - [Asynchronous refinements](#asynchronous-refinements)
+    - [Relationship to transforms](#relationship-to-transforms)
+  - [`.superRefine`](#superrefine)
+    - [Abort early](#abort-early)
+    - [Type refinements](#type-refinements)
+  - [`.transform`](#transform)
+    - [Chaining order](#chaining-order)
+    - [Validating during transform](#validating-during-transform)
+    - [Relationship to refinements](#relationship-to-refinements)
+    - [Async transforms](#async-transforms)
+  - [`.default`](#default)
+  - [`.describe`](#describe)
+  - [`.catch`](#catch)
+  - [`.optional`](#optional)
+  - [`.nullable`](#nullable)
+  - [`.nullish`](#nullish)
+  - [`.array`](#array)
+  - [`.promise`](#promise)
+  - [`.or`](#or)
+  - [`.and`](#and)
+  - [`.brand`](#brand)
+  - [`.pipe()`](#pipe)
+    - [You can use `.pipe()` to fix common issues with `z.coerce`.](#you-can-use-pipe-to-fix-common-issues-with-zcoerce)
 - [Guides and concepts](#guides-and-concepts)
   - [Type inference](#type-inference)
   - [Writing generic functions](#writing-generic-functions)
+    - [Constraining allowable inputs](#constraining-allowable-inputs)
   - [Error handling](#error-handling)
   - [Error formatting](#error-formatting)
 - [Comparison](#comparison)
   - [Joi](#joi)
   - [Yup](#yup)
   - [io-ts](#io-ts)
   - [Runtypes](#runtypes)
+  - [Ow](#ow)
 - [Changelog](#changelog)
 
-<!-- **Zod 2 is coming! Follow [@colinhacks](https://twitter.com/colinhacks) to stay updated and discuss the future of Zod.** -->
-
 ## Introduction
 
 Zod is a TypeScript-first schema declaration and validation library. I'm using the term "schema" to broadly refer to any data type, from a simple `string` to a complex nested object.
@@ -386,17 +412,16 @@ Sponsorship at any level is appreciated and encouraged. For individual developer
       <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"/>
+     <td align="center">
+      <a href="https://www.masterborn.com/career?utm_source=github&utm_medium=referral&utm_campaign=zodsponsoring">
+        <img src="https://avatars.githubusercontent.com/u/48984031?s=200&v=4" width="100px;" alt="MasterBorn logo"/>
       </a>
       <br />
-      <b>Avana Wallet</b>
+      <b>MasterBorn</b>
       <br/>
-      <a href="https://www.avanawallet.com/">avanawallet.com</a><br/>
-      <span>Solana non-custodial wallet</span>
+      <a href="https://www.masterborn.com/career?utm_source=github&utm_medium=referral&utm_campaign=zodsponsoring">masterborn.com</a>
       <br />
-    </td> -->
+    </td>
   </tr>
 </table>
 
@@ -417,6 +442,7 @@ There are a growing number of tools that are built atop or support Zod natively!
 - [`domain-functions`](https://github.com/SeasonedSoftware/domain-functions/): Decouple your business logic from your framework using composable functions. With first-class type inference from end to end powered by Zod schemas.
 - [`@zodios/core`](https://github.com/ecyrbe/zodios): A typescript API client with runtime and compile time validation backed by axios and zod.
 - [`express-zod-api`](https://github.com/RobinTail/express-zod-api): Build Express-based APIs with I/O schema validation and custom middlewares.
+- [`tapiduck`](https://github.com/sumukhbarve/monoduck/blob/main/src/tapiduck/README.md): End-to-end typesafe JSON APIs with Zod and Express; a bit like tRPC, but simpler.
 
 #### Form integrations
 
@@ -443,6 +469,7 @@ There are a growing number of tools that are built atop or support Zod natively!
 - [`fastify-type-provider-zod`](https://github.com/turkerdev/fastify-type-provider-zod): Create Fastify type providers from Zod schemas.
 - [`zod-to-openapi`](https://github.com/asteasolutions/zod-to-openapi): Generate full OpenAPI (Swagger) docs from Zod, including schemas, endpoints & parameters.
 - [`nestjs-graphql-zod`](https://github.com/incetarik/nestjs-graphql-zod): Generates NestJS GraphQL model classes from Zod schemas. Provides GraphQL method decorators working with Zod schemas.
+- [`zod-openapi`](https://github.com/samchungy/zod-openapi): Create full OpenAPI v3.x documentation from Zod Schemas.
 
 #### X to Zod
 
@@ -462,6 +489,7 @@ There are a growing number of tools that are built atop or support Zod natively!
 - [`@anatine/zod-mock`](https://github.com/anatine/zod-plugins/tree/main/packages/zod-mock): Generate mock data from a Zod schema. Powered by [faker.js](https://github.com/faker-js/faker).
 - [`zod-mocking`](https://github.com/dipasqualew/zod-mocking): Generate mock data from your Zod schemas.
 - [`zod-fixture`](https://github.com/timdeschryver/zod-fixture): Use your zod schemas to automate the generation of non-relevant test fixtures in a deterministic way.
+- [`zocker`](https://zocker.sigrist.dev): Generate plausible mock-data from your schemas.
 
 #### Powered by Zod
 
@@ -501,6 +529,15 @@ bun add zod           # bun
 pnpm add zod          # pnpm
 ```
 
+Zod also publishes a canary version on every commit. To install the canary:
+
+```sh
+npm install zod@canary       # npm
+yarn add zod@canary          # yarn
+bun add zod@canary           # bun
+pnpm add zod@canary          # pnpm
+```
+
 ### From `deno.land/x` (Deno)
 
 Unlike Node, Deno relies on direct URL imports instead of a package manager like NPM. Zod is available on [deno.land/x](https://deno.land/x). The latest version can be imported like so:
@@ -973,7 +1010,7 @@ FruitEnum.parse("Cantaloupe"); // fails
 
 **Const enums**
 
-The `.nativeEnum()` function works for `as const` objects as well. ⚠️ `as const` required TypeScript 3.4+!
+The `.nativeEnum()` function works for `as const` objects as well. ⚠️ `as const` requires TypeScript 3.4+!
 
 ```ts
 const Fruits = {

diff --git a/README_ZH.md b/README_ZH.md
@@ -280,7 +280,6 @@ Zod 被设计成对开发者尽可能友好。其目的是消除重复的类型
 
 _要在这里看到你的名字 + Twitter + 網站 , 请在[Freelancer](https://github.com/sponsors/colinhacks) 或 [Consultancy](https://github.com/sponsors/colinhacks)赞助 Zod ._
 
-
 # 生态系统
 
 有越来越多的工具是建立在 Zod 之上或原生支持 Zod 的! 如果你在 Zod 的基础上建立了一个工具或库，请在[Twitter](https://twitter.com/colinhacks) 或者 [Discussion](https://github.com/colinhacks/zod/discussions)上告诉我。我会在下面添加，并在推特上发布。
@@ -292,7 +291,7 @@ _要在这里看到你的名字 + Twitter + 網站 , 请在[Freelancer](https://
 - [`zod-fast-check`](https://github.com/DavidTimms/zod-fast-check): 从 Zod 模式中生成 `fast-check` 的任意数据。
 - [`zod-endpoints`](https://github.com/flock-community/zod-endpoints): 约定优先的严格类型的端点与 Zod。兼容 OpenAPI。
 - [`express-zod-api`](https://github.com/RobinTail/express-zod-api): 用 I/O 模式验证和自定义中间件构建基于 Express 的 API 服务
-- [`zod-i18n-map`](https://github.com/aiji42/zod-i18n): 有助于翻译zod错误信息。
+- [`zod-i18n-map`](https://github.com/aiji42/zod-i18n): 有助于翻译 zod 错误信息。
 - [`mobx-zod-form`](https://github.com/MonoidDev/mobx-zod-form): 以数据为中心的表格构建工具，基于 MobX 和 Zod。
 
 # 安装
@@ -314,6 +313,7 @@ _要在这里看到你的名字 + Twitter + 網站 , 请在[Freelancer](https://
 ```
 
 ### 从`npm`(Node/Bun)安装
+
 ```sh
 npm install zod
 yarn add zod          # yarn
@@ -323,7 +323,8 @@ pnpm add zod          # pnpm
 
 ### 从`deno.land/x` (Deno)安装
 
-和Node不同，Demo依靠一个直接的URL导入而非像npm这样的包管理器。可以这样导入最新版本的Zod:
+和 Node 不同，Demo 依靠一个直接的 URL 导入而非像 npm 这样的包管理器。可以这样导入最新版本的 Zod:
+
 ```ts
 import { z } from "https://deno.land/x/zod/mod.ts";
 ```
@@ -334,8 +335,7 @@ import { z } from "https://deno.land/x/zod/mod.ts";
 import { z } from "https://deno.land/x/zod@v3.16.1/mod.ts";
 ```
 
-> README的剩余部分假定你是直接通过npm安装的`zod`包。
-
+> README 的剩余部分假定你是直接通过 npm 安装的`zod`包。
 
 # 基本用法
 
@@ -929,6 +929,13 @@ const FishEnum = z.enum(fish);
 
 在这种情况下，Zod 无法推断出各个枚举元素；相反，推断出的类型将是 `string` 而不是`'Salmon'|'Tuna'|'Trout'`。
 
+另一种可行的方式是使用`as const`，这样 Zod 就可以推断出正确的类型。
+
+```ts
+const VALUES = ["Salmon", "Tuna", "Trout"] as const;
+const FishEnum = z.enum(VALUES);
+```
+
 **自动补全**
 
 为了获得 Zod 枚举的自动完成，请使用你的模式的`.enum`属性: