Zod

https://v3.zod.dev/
Admin
Zod is a TypeScript-first schema declaration and validation library for parsing and validating data.
Tokens:40,624
Snippets:363
Trust Score:9.9
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install Zod via npm, deno, yarn, bun, or pnpm

Source: https://v3.zod.dev/

Commands to install Zod using various package managers. The rest of the documentation assumes npm and direct import from the 'zod' package.

```bash
npm install zod       # npm
deno add npm:zod      # deno
yarn add zod          # yarn
bun add zod           # bun
pnpm add zod          # pnpm
```

--------------------------------

### Create a partial object with .partial()

Source: https://v3.zod.dev/

Starting object for the .required() example. Uses .partial() to make all properties optional.

```typescript
const user = z
  .object({
    email: z.string(),
    username: z.string(),
  })
  .partial();
// { email?: string | undefined; username?: string | undefined }
```

--------------------------------

### Base object for partial example

Source: https://v3.zod.dev/

Object schema with required email and username fields.

```typescript
const user = z.object({
  email: z.string(),
  username: z.string(),
});
// { email: string; username: string }
```

--------------------------------

### Async transform example

Source: https://v3.zod.dev/

Shows how to use an async transform. Requires using .parseAsync() or .safeParseAsync() to parse data, otherwise Zod will throw an error.

```typescript
const IdToUser = z
  .string()
  .uuid()
  .transform(async (id) => {
    return await getUserById(id);
  });
```

--------------------------------

### Recipe schema for pick/omit

Source: https://v3.zod.dev/

Base object schema used in the following pick and omit examples.

```typescript
const Recipe = z.object({
  id: z.string(),
  name: z.string(),
  ingredients: z.array(z.string()),
});
```

--------------------------------

### Basic transform example

Source: https://v3.zod.dev/

Shows how to use the transform method to change the parsed value. The result is a ZodEffects instance, not a ZodString.

```typescript
const stringToNumber = z.string().transform((val) => val.length);

stringToNumber.parse("string"); // => 6
```

--------------------------------

### Structural typing example

Source: https://v3.zod.dev/

Shows that TypeScript's structural typing allows a Dog to be passed where a Cat is expected because they have the same shape.

```typescript
type Cat = { name: string };
type Dog = { name: string };

const petCat = (cat: Cat) => {};
const fido: Dog = { name: "fido" };
petCat(fido); // works fine
```

--------------------------------

### Union APIs

Source: https://v3.zod.dev/

Documentation for Zod union APIs, including z.union, .or, and z.discriminatedUnion, with examples of usage and their properties.

```APIDOC
## z.union

### Description
Creates a union type that validates input against multiple schemas in order, returning the first that matches.

### Method
z.union

### Syntax
z.union([schema1, schema2, ...])

### Parameters
- **options** (ZodType[]) - Required - An array of Zod schemas to test input against.

### Examples
```js
const stringOrNumber = z.union([z.string(), z.number()]);
stringOrNumber.parse("foo"); // passes
stringOrNumber.parse(14); // passes
```

### Notes
- Options are tested in order; first success is used.
- Can be used with `.or` method: `z.string().or(z.number())`.

## .or

### Description
An alternative to `z.union` that composes two schemas with an OR relationship.

### Method
.or

### Syntax
schema.or(otherSchema)

### Example
```js
const stringOrNumber = z.string().or(z.number());
```

## z.discriminatedUnion

### Description
Creates a discriminated union of object schemas that share a common discriminator key. This enables efficient parsing and friendlier errors.

### Method
z.discriminatedUnion

### Syntax
z.discriminatedUnion(discriminatorKey, options)

### Parameters
- **discriminatorKey** (string) - Required - The key used to determine which schema to use.
- **options** (ZodObject[] with literal discriminator) - Required - Array of object schemas, each having a literal value at the discriminator key.

### Example
```js
const myUnion = z.discriminatedUnion("status", [
  z.object({ status: z.literal("success"), data: z.string() }),
  z.object({ status: z.literal("failed"), error: z.instanceof(Error) }),
]);
myUnion.parse({ status: "success", data: "yippie ki yay" });
```

### Properties
- **options** (ZodObject[]) - The array of schemas composing the union. Can be used to merge unions: `[...A.options, ...B.options]`.

```

--------------------------------

### Extract parameters and return type from function schema

Source: https://v3.zod.dev/

Shows how to use .parameters() and .returnType() to extract the input and output schemas from a function schema. The examples show the resulting Zod types.

```typescript
myFunction.parameters();
// => ZodTuple<[ZodString, ZodNumber]>

myFunction.returnType();
// => ZodBoolean
```

--------------------------------

### Implement a function schema with .implement()

Source: https://v3.zod.dev/

Shows how to use .implement() to create a validated function. The implementation receives typed arguments and the returned function validates inputs and outputs. Example trims a string and returns its length.

```typescript
const trimmedLength = z
  .function()
  .args(z.string()) // accepts an arbitrary number of arguments
  .returns(z.number())
  .implement((x) => {
    // TypeScript knows x is a string!
    return x.trim().length;
  });

trimmedLength("sandwich"); // => 8
trimmedLength(" asdf "); // => 4
```

--------------------------------

### Asynchronous refinements with .refine

Source: https://v3.zod.dev/

Refinements can be async, but you must use .parseAsync to parse data when using them. The example shows a placeholder for verifying a user ID in a database.

```typescript
const userId = z.string().refine(async (id) => {
  // verify that ID exists in database
  return true;
});
```

--------------------------------

### String coercion examples with various inputs

Source: https://v3.zod.dev/

Shows how z.coerce.string() coerces different input types: numbers, booleans, undefined, and null, all converted to their string representation.

```typescript
schema.parse(12); // => "12"
schema.parse(true); // => "true"
schema.parse(undefined); // => "undefined"
schema.parse(null); // => "null"
```

--------------------------------

### superRefine example with multiple issues

Source: https://v3.zod.dev/

Shows how to use superRefine to add multiple custom issues. Validation passes if ctx.addIssue is not called. Issues can use any ZodIssueCode.

```typescript
const Strings = z.array(z.string()).superRefine((val, ctx) => {
  if (val.length > 3) {
    ctx.addIssue({
      code: z.ZodIssueCode.too_big,
      maximum: 3,
      type: "array",
      inclusive: true,
      message: "Too many items 😡",
    });
  }

  if (val.length !== new Set(val).size) {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      message: `No duplicates allowed.`,
    });
  }
});
```

--------------------------------

### Interleaving transforms and refinements

Source: https://v3.zod.dev/

Transforms and refinements can be chained together. This example transforms a string to its length and then refines that the length is greater than 25.

```typescript
z.string()
  .transform((val) => val.length)
  .refine((val) => val > 25);
```

--------------------------------

### Customizing error path with .refine

Source: https://v3.zod.dev/

Use the path option in .refine to specify where in the data structure the error should be reported. The example shows a password confirmation check.

```typescript
const passwordForm = z
  .object({
    password: z.string(),
    confirm: z.string(),
  })
  .refine((data) => data.password === data.confirm, {
    message: "Passwords don't match",
    path: ["confirm"], // path of error
  });

passwordForm.parse({ password: "asdf", confirm: "qwer" });
```

--------------------------------

### Two-schema z.record overload

Source: https://v3.zod.dev/CHANGELOG

Uses the overloaded z.record with two schemas: the first validates keys, the second validates values. Examples show numeric keys and enum keys.

```ts
const schema = z.record(z.number(), z.boolean());
type schema = z.infer<typeof schema>; // Record<number, boolean>

const schema = z.record(z.enum(["Tuna", "Trout"]), z.boolean());
type schema = z.infer<typeof schema>; // Record<"Tuna" | "Trout", boolean>
```

--------------------------------

### Coerce to string with z.coerce.string()

Source: https://v3.zod.dev/

Creates a ZodString schema that coerces input to a string using the String() function. The example shows parsing a number 12 to the string "12".

```typescript
const schema = z.coerce.string();
schema.parse("tuna"); // => "tuna"
schema.parse(12); // => "12"
```

--------------------------------

### Define a signup form schema with Zod

Source: https://v3.zod.dev/ERROR_HANDLING

Defines a Zod object schema for a signup form with name, email, and optional phone fields. This schema is used in subsequent examples to validate form data.

```ts
const FormData = z.object({
  name: z.string(),
  contactInfo: z.object({
    email: z.string().email(),
    phone: z.string().optional(),
  }),
});
```

--------------------------------

### Format Zod error with .format()

Source: https://v3.zod.dev/

Use the .format() method on a ZodError to get a nested object with error messages. The example parses an object with a name field expecting a string but receives a number, then accesses the formatted error for the name field.

```typescript
const result = z
  .object({
    name: z.string(),
  })
  .safeParse({ name: 12 });

if (!result.success) {
  const formatted = result.error.format();
  /* {
    name: { _errors: [ 'Expected string, received number' ] }
  } */

  formatted.name?._errors;
  // => ["Expected string, received number"]
}
```

--------------------------------

### Using .promise() to create a promise schema

Source: https://v3.zod.dev/

Shows the convenience method .promise() and its equivalent using z.promise().

```typescript
const stringPromise = z.string().promise(); // Promise<string>

// equivalent to
z.promise(z.string());
```

--------------------------------

### Using .describe() to add a description property

Source: https://v3.zod.dev/

Shows how to add a description property to a schema, useful for documentation or JSON Schema generation.

```typescript
const documentedString = z
  .string()
  .describe("A useful bit of text, if you know what to do with it.");
documentedString.description; // A useful bit of text…
```

--------------------------------

### Access array element schema with .element

Source: https://v3.zod.dev/

Use .element to get the schema for an element of the array.

```typescript
stringArray.element; // => string schema
```

--------------------------------

### Retrieve options with .options property

Source: https://v3.zod.dev/

Returns the list of options as a tuple.

```typescript
FishEnum.options; // ["Salmon", "Tuna", "Trout"];
```

--------------------------------

### Basic usage: creating a string schema

Source: https://v3.zod.dev/

Shows how to create a string schema, parse values, and use safeParse. parse throws ZodError on invalid input, while safeParse returns a result object.

```typescript
import { z } from "zod";

// creating a schema for strings
const mySchema = z.string();

// parsing
mySchema.parse("tuna"); // => "tuna"
mySchema.parse(12); // => throws ZodError

// "safe" parsing (doesn't throw error if validation fails)
mySchema.safeParse("tuna"); // => { success: true; data: "tuna" }
mySchema.safeParse(12); // => { success: false; error: ZodError }
```

--------------------------------

### Using .array() to create an array schema

Source: https://v3.zod.dev/

Shows the convenience method .array() and its equivalent using z.array().

```typescript
const stringArray = z.string().array(); // string[]

// equivalent to
z.array(z.string());
```

--------------------------------

### Access enum values with .enum property

Source: https://v3.zod.dev/

Use the .enum property to get autocompletion and access the underlying object mapping.

```typescript
FishEnum.enum.Salmon; // => autocompletes

FishEnum.enum;
/*
=> {
  Salmon: "Salmon",
  Tuna: "Tuna",
  Trout: "Trout",
}
*/
```

--------------------------------

### Set schema utility methods

Source: https://v3.zod.dev/

Shows nonempty, min, max, and size constraints for set schemas.

```typescript
z.set(z.string()).nonempty(); // must contain at least one item
z.set(z.string()).min(5); // must contain 5 or more items
z.set(z.string()).max(5); // must contain 5 or fewer items
z.set(z.string()).size(5); // must contain 5 items exactly
```

--------------------------------

### Flatten errors with .flatten() method

Source: https://v3.zod.dev/ERROR_HANDLING

Uses `.flatten()` to get a flat structure with `formErrors` and `fieldErrors`. This is more convenient for one-level-deep schemas.

```ts
if (!result.success) {
  console.log(result.error.flatten());
}
/*
  {
    formErrors: [],
    fieldErrors: {
      name: ['Expected string, received null'],
      contactInfo: ['Invalid email']
    },
  }
*/
```

--------------------------------

### Resulting ZodError from .refine with custom path

Source: https://v3.zod.dev/

This is the error object that results from the previous example when validation fails. It shows the custom path and message.

```typescript
ZodError {
  issues: [{
    "code": "custom",
    "path": [ "confirm" ],
    "message": "Passwords don't match"
  }]
}
```

--------------------------------

### Using .default() with a function for dynamic defaults

Source: https://v3.zod.dev/

Shows how to pass a function to .default() that is re-executed each time a default is needed, producing different random values.

```typescript
const numberWithRandomDefault = z.number().default(Math.random);

numberWithRandomDefault.parse(undefined); // => 0.4413456736055323
numberWithRandomDefault.parse(undefined); // => 0.1871840107401901
numberWithRandomDefault.parse(undefined); // => 0.7223408162401552
```

--------------------------------

### TypeScript type for discriminated union

Source: https://v3.zod.dev/

TypeScript type definition for a discriminated union with a 'status' discriminator key. Used as a reference for the z.discriminatedUnion example.

```typescript
type MyUnion =
  | { status: "success"; data: string }
  | { status: "failed"; error: Error };
```

--------------------------------

### Using .optional() to make a schema optional

Source: https://v3.zod.dev/

Shows the convenience method .optional() and its equivalent using z.optional().

```typescript
const optionalString = z.string().optional(); // string | undefined

// equivalent to
z.optional(z.string());
```

--------------------------------

### Using .nullish() to accept null and undefined

Source: https://v3.zod.dev/

Shows the convenience method .nullish() and its equivalent using .nullable().optional().

```typescript
const nullishString = z.string().nullish(); // string | null | undefined

// equivalent to
z.string().nullable().optional();
```

--------------------------------

### Basic usage: creating an object schema

Source: https://v3.zod.dev/

Shows how to create an object schema and extract the inferred TypeScript type using z.infer.

```typescript
import { z } from "zod";

const User = z.object({
  username: z.string(),
});

User.parse({ username: "Ludwig" });

// extract the inferred type
type User = z.infer<typeof User>;
// { username: string }
```

--------------------------------

### Inferring the inferred type with z.infer cast

Source: https://v3.zod.dev/

When using z.ZodTypeAny, the parsed data is typed as any. Cast the result with z.infer<T> to get the correct inferred type.

```typescript
function parseData<T extends z.ZodTypeAny>(data: unknown, schema: T) {
  return schema.parse(data);
}

parseData("sup", z.string());
// => any
```

```typescript
function parseData<T extends z.ZodTypeAny>(data: unknown, schema: T) {
  return schema.parse(data) as z.infer<T>;
  //                        ^^^^^^^^^^^^^^ <- add this
}

parseData("sup", z.string());
// => string
```

--------------------------------

### Handling validation errors with ZodError

Source: https://v3.zod.dev/

ZodError contains an issues array with detailed validation information. The example shows a safeParse failure and the resulting issues array.

```typescript
const result = z
  .object({
    name: z.string(),
  })
  .safeParse({ name: 12 });

if (!result.success) {
  result.error.issues;
  /* [
      {
        "code": "invalid_type",
        "expected": "string",
        "received": "number",
        "path": [ "name" ],
        "message": "Expected string, received number"
      }
  ] */
}
```

--------------------------------

### Extract input and output types with z.input and z.output

Source: https://v3.zod.dev/

For schemas with transforms, input and output types can differ. Use z.input and z.output to extract them separately. z.infer returns the output type.

```typescript
const stringToNumber = z.string().transform((val) => val.length);

// ⚠️ Important: z.infer returns the OUTPUT type!
type input = z.input<typeof stringToNumber>; // string
type output = z.output<typeof stringToNumber>; // number

// equivalent to z.output!
type inferred = z.infer<typeof stringToNumber>; // number
```

--------------------------------

### Define function schema inputs and outputs

Source: https://v3.zod.dev/

Shows how to define argument types and return type for a function schema using .args() and .returns(). The inferred type includes the argument names and types.

```typescript
const myFunction = z
  .function()
  .args(z.string(), z.number()) // accepts an arbitrary number of arguments
  .returns(z.boolean());

type myFunction = z.infer<typeof myFunction>;
// => (arg0: string, arg1: number)=>boolean
```

--------------------------------

### Using .nullable() to make a schema nullable

Source: https://v3.zod.dev/

Shows the convenience method .nullable() and its equivalent using z.nullable().

```typescript
const nullableString = z.string().nullable(); // string | null

// equivalent to
z.nullable(z.string());
```

--------------------------------

### Merging discriminated unions with .options

Source: https://v3.zod.dev/

Combines two discriminated unions by destructuring their .options arrays into a new discriminated union. The example shows the pattern with placeholder options.

```typescript
const A = z.discriminatedUnion("status", [
  /* options */
]);
const B = z.discriminatedUnion("status", [
  /* options */
]);

const AB = z.discriminatedUnion("status", [...A.options, ...B.options]);
```

--------------------------------

### Create a function schema with z.function()

Source: https://v3.zod.dev/

Creates a basic function schema with no arguments or return type specified. The inferred type is ()=>unknown.

```typescript
const myFunction = z.function();

type myFunction = z.infer<typeof myFunction>;
// => ()=>unknown
```

--------------------------------

### Validate unknown keys with .catchall()

Source: https://v3.zod.dev/

Uses .catchall() to validate all unknown keys against a schema. Valid keys pass, invalid keys throw ZodError.

```typescript
const person = z
  .object({
    name: z.string(),
  })
  .catchall(z.number());

person.parse({
  name: "bob dylan",
  validExtraKey: 61, // works fine
});

person.parse({
  name: "bob dylan",
  validExtraKey: false, // fails
});
// => throws ZodError
```

--------------------------------

### Function schema without .returns()

Source: https://v3.zod.dev/

If you only care about validating inputs, omit .returns(). The output type is inferred from the implementation. The example shows a function that takes a string and returns an array of numbers.

```typescript
const myFunction = z
  .function()
  .args(z.string())
  .implement((arg) => {
    return [arg.length];
  });

myFunction; // (arg: string)=>number[]
```

--------------------------------

### z.string().or(z.number()) convenience method

Source: https://v3.zod.dev/

Alternative syntax for creating a union using the .or method. Equivalent to z.union([z.string(), z.number()]).

```typescript
const stringOrNumber = z.string().or(z.number());
```

--------------------------------

### Extract TypeScript type with z.infer

Source: https://v3.zod.dev/

Use z.infer<typeof mySchema> to extract the output type of a schema. The example shows that the inferred type is string, and assigning a number causes a TypeScript error.

```typescript
const A = z.string();
type A = z.infer<typeof A>; // string

const u: A = 12; // TypeError
const u: A = "asdf"; // compiles
```

--------------------------------

### Using .default() to set a default value

Source: https://v3.zod.dev/

Shows how to use .default() to substitute a default value when parsing undefined. The default value is parsed by the schema.

```typescript
const stringWithDefault = z.string().default("tuna");

stringWithDefault.parse(undefined); // => "tuna"
```

--------------------------------

### Using .safeParse to avoid throwing errors

Source: https://v3.zod.dev/

Use .safeParse to get a discriminated union result instead of throwing. The result is either { success: true, data } or { success: false, error: ZodError }.

```typescript
stringSchema.safeParse(12);
// => { success: false; error: ZodError }

stringSchema.safeParse("billie");
// => { success: true; data: 'billie' }
```

--------------------------------

### ZodType with ZodEffects

Source: https://v3.zod.dev/

Shows how to define input and output types when using z.ZodType with z.ZodEffects like .refine.

```typescript
const isValidId = (id: string): id is `${string}/${string}` =>
  id.split("/").length === 2;

const baseSchema = z.object({
  id: z.string().refine(isValidId),
});

type Input = z.input<typeof baseSchema> & {
  children: Input[];
};

type Output = z.output<typeof baseSchema> & {
  children: Output[];
};

const schema: z.ZodType<Output, z.ZodTypeDef, Input> = baseSchema.extend({
  children: z.lazy(() => schema.array()),
});
```

--------------------------------

### All primitive coercion constructors

Source: https://v3.zod.dev/

Lists the coercion constructors for each primitive type: String(input), Number(input), Boolean(input), BigInt(input), and new Date(input).

```typescript
z.coerce.string(); // String(input)
z.coerce.number(); // Number(input)
z.coerce.boolean(); // Boolean(input)
z.coerce.bigint(); // BigInt(input)
z.coerce.date(); // new Date(input)
```

--------------------------------

### Custom Error Map with ZodErrorMap

Source: https://v3.zod.dev/ERROR_HANDLING

Define a custom error map that overrides messages for invalid_type and custom errors, using error.params for custom validators. Falls back to the default error message. The example then parses a string with a number input, producing a ZodError with the custom message.

```ts
import * as z from "zod";

const customErrorMap: z.ZodErrorMap = (error, ctx) => {
  /*
  This is where you override the various error codes
  */
  switch (error.code) {
    case z.ZodIssueCode.invalid_type:
      if (error.expected === "string") {
        return { message: `This ain't a string!` };
      }
      break;
    case z.ZodIssueCode.custom:
      // produce a custom message using error.params
      // error.params won't be set unless you passed
      // a `params` arguments into a custom validator
      const params = error.params || {};
      if (params.myField) {
        return { message: `Bad input: ${params.myField}` };
      }
      break;
  }

  // fall back to default message!
  return { message: ctx.defaultError };
};

z.string().parse(12, { errorMap: customErrorMap });

/* throws: 
  ZodError {
    errors: [{
      code: "invalid_type",
      path: [],
      message: "This ain't a string!",
      expected: "string",
      received: "number",
    }]
  }
*/
```

--------------------------------

### Chaining order: apply built-in methods before transform

Source: https://v3.zod.dev/

Demonstrates that built-in methods like .email() must be applied before any transforms, because the transform returns a ZodEffects instance.

```typescript
const emailToDomain = z
  .string()
  .email()
  .transform((val) => val.split("@")[1]);

emailToDomain.parse("colinhacks@example.com"); // => example.com
```

--------------------------------

### Numerical keys in TypeScript records

Source: https://v3.zod.dev/

Demonstrates that TypeScript's { [k: number]: string } type still uses string keys at runtime, as shown by the typeof key output.

```typescript
const testMap: { [k: number]: string } = {
  1: "one",
};

for (const key in testMap) {
  console.log(`${key}: ${typeof key}`);
}
// prints: `1: string`
```

--------------------------------

### Using .catch() with a function for dynamic catch values

Source: https://v3.zod.dev/

Shows how to pass a function to .catch() that receives a ctx object with the caught error and returns a new catch value each time.

```typescript
const numberWithRandomCatch = z.number().catch((ctx) => {
  ctx.error; // the caught ZodError
  return Math.random();
});

numberWithRandomCatch.parse("sup"); // => 0.4413456736055323
numberWithRandomCatch.parse("sup"); // => 0.1871840107401901
numberWithRandomCatch.parse("sup"); // => 0.7223408162401552
```

--------------------------------

### Using .or() to create a union type

Source: https://v3.zod.dev/

Shows the convenience method .or() and its equivalent using z.union().

```typescript
const stringOrNumber = z.string().or(z.number()); // string | number

// equivalent to
z.union([z.string(), z.number()]);
```

--------------------------------

### Using .catch() to provide a catch value

Source: https://v3.zod.dev/

Shows how to use .catch() to return a fallback value when parsing fails. The catch value is returned instead of throwing an error.

```typescript
const numberWithCatch = z.number().catch(42);

numberWithCatch.parse(5); // => 5
numberWithCatch.parse("tuna"); // => 42
```

--------------------------------

### Using .brand for nominal typing

Source: https://v3.zod.dev/

Demonstrates how to use .brand to create a branded type that only accepts validated inputs, preventing plain objects from being passed.

```typescript
const Cat = z.object({ name: z.string() }).brand<"Cat">();
type Cat = z.infer<typeof Cat>;

const petCat = (cat: Cat) => {};

// this works
const simba = Cat.parse({ name: "simba" });
petCat(simba);

// this doesn't
petCat({ name: "fido" });
```

--------------------------------

### Use a record schema for validation

Source: https://v3.zod.dev/

Shows how to assign values to a record schema. Valid values pass, while invalid ones cause a TypeError.

```typescript
const userStore: UserStore = {};

userStore["77d2586b-9e8e-4ecf-8b21-ea7e0530eadd"] = {
  name: "Carlotta",
}; // passes

userStore["77d2586b-9e8e-4ecf-8b21-ea7e0530eadd"] = {
  whatever: "Ice cream sundae",
}; // TypeError
```

--------------------------------

### Using .and() to create an intersection type

Source: https://v3.zod.dev/

Shows the convenience method .and() and its equivalent using z.intersection().

```typescript
const nameAndAge = z
  .object({ name: z.string() })
  .and(z.object({ age: z.number() })); // { name: string } & { age: number }

// equivalent to
z.intersection(z.object({ name: z.string() }), z.object({ age: z.number() }));
```

--------------------------------

### Type refinement with superRefine and refine

Source: https://v3.zod.dev/

Shows how to use a type predicate with superRefine to narrow the type, allowing subsequent refinements to use the narrowed type. Must use ctx.addIssue instead of returning a boolean.

```typescript
const schema = z
  .object({
    first: z.string(),
    second: z.number(),
  })
  .nullable()
  .superRefine((arg, ctx): arg is { first: string; second: number } => {
    if (!arg) {
      ctx.addIssue({
        code: z.ZodIssueCode.custom, // customize your issue
        message: "object should exist",
      });
    }

    return z.NEVER; // The return value is not used, but we need to return something to satisfy the typing
  })
  // here, TS knows that arg is not null
  .refine((arg) => arg.first === "bob", "`first` is not `bob`!");
```

--------------------------------

### .partial() with specific keys

Source: https://v3.zod.dev/

Makes only the specified properties optional.

```typescript
const optionalEmail = user.partial({
  email: true,
});
/*
{
  email?: string | undefined;
  username: string
}
*/
```

--------------------------------

### Chaining .transform and .pipe

Source: https://v3.zod.dev/

Shows how to use .pipe to validate the result of a .transform() operation.

```typescript
z.string()
  .transform((val) => val.length)
  .pipe(z.number().min(5));
```

--------------------------------

### Set a global error map with z.setErrorMap

Source: https://v3.zod.dev/ERROR_HANDLING

Shows how to set a global error map using z.setErrorMap. This map receives the default error message as ctx.defaultError and can override it.

```ts
const myErrorMap: z.ZodErrorMap = /* ... */;
z.setErrorMap(myErrorMap);
```

--------------------------------

### Parse promise schema with invalid and valid inputs

Source: https://v3.zod.dev/

Demonstrates parsing behavior for promise schemas. Synchronous parse checks for Promise instance, while async parse validates the resolved value. Shows errors for non-Promise and non-number values.

```typescript
numberPromise.parse("tuna");
// ZodError: Non-Promise type: string

numberPromise.parse(Promise.resolve("tuna"));
// => Promise<number>

const test = async () => {
  await numberPromise.parse(Promise.resolve("tuna"));
  // ZodError: Non-number type: string

  await numberPromise.parse(Promise.resolve(3.14));
  // => 3.14
};
```

--------------------------------

### Create a ZodError instance

Source: https://v3.zod.dev/ERROR_HANDLING

Imports Zod and creates a new ZodError instance with an empty issues array.

```typescript
import * as z from "zod";

const myError = new z.ZodError([]);
```

--------------------------------

### Pass a contextual error map to parse

Source: https://v3.zod.dev/ERROR_HANDLING

Shows how to pass an error map directly to a parse method, giving it highest priority.

```ts
z.string().parse("adsf", { errorMap: myErrorMap });
```

--------------------------------

### Create a promise schema with z.promise()

Source: https://v3.zod.dev/

Creates a Zod promise schema that validates a Promise containing a number. Parsing a non-Promise throws a ZodError, while parsing a Promise validates the resolved value asynchronously.

```typescript
const numberPromise = z.promise(z.number());
```

--------------------------------

### z.object() with required properties

Source: https://v3.zod.dev/

Defines an object schema with all properties required by default. Shows how to extract the inferred type.

```typescript
// all properties are required by default
const Dog = z.object({
  name: z.string(),
  age: z.number(),
});

// extract the inferred type like this
type Dog = z.infer<typeof Dog>;

// equivalent to:
type Dog = {
  name: string;
  age: number;
};
```

--------------------------------

### Validating during transform with ctx.addIssue

Source: https://v3.zod.dev/

Shows how to validate and transform in one step using the ctx object. Use z.NEVER to return early from the transform function.

```typescript
const numberInString = z.string().transform((val, ctx) => {
  const parsed = parseInt(val);
  if (isNaN(parsed)) {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      message: "Not a number",
    });

    // This is a special symbol you can use to
    // return early from the transform function.
    // It has type `never` so it does not affect the
    // inferred return type.
    return z.NEVER;
  }
  return parsed;
});
```

--------------------------------

### Create subsets with .extract and .exclude

Source: https://v3.zod.dev/

Use .extract to keep only specified values and .exclude to remove specified values.

```typescript
const FishEnum = z.enum(["Salmon", "Tuna", "Trout"]);
const SalmonAndTrout = FishEnum.extract(["Salmon", "Trout"]);
const TunaOnly = FishEnum.exclude(["Salmon", "Trout"]);
```

--------------------------------

### Schema-bound error maps: z.string({ errorMap }) and shorthand options

Source: https://v3.zod.dev/ERROR_HANDLING

Shows two ways to associate an error map with a schema: passing an errorMap option or using invalid_type_error/required_error shorthand. The shorthand creates an error map under the hood.

```ts
z.string({ errorMap: myErrorMap });

// this creates an error map under the hood
z.string({
  invalid_type_error: "Invalid name",
  required_error: "Name is required",
});
```

--------------------------------

### Literal schemas

Source: https://v3.zod.dev/

Create literal schemas for exact values like strings, numbers, bigints, booleans, and symbols. Retrieve the literal value via `.value`.

```typescript
const tuna = z.literal("tuna");
const twelve = z.literal(12);
const twobig = z.literal(2n); // bigint literal
const tru = z.literal(true);

const terrificSymbol = Symbol("terrific");
const terrific = z.literal(terrificSymbol);

// retrieve literal value
tuna.value; // "tuna"
```
Tokens:
Raw