\n\n \n \n \n\n### [Read the docs →](https://zod.dev/api)\n\n \n \n\n## What is Zod?\n\nZod is a TypeScript-first validation library. Define a schema and parse some data with it. You'll get back a strongly typed, validated result.\n\n```ts\nimport * as z from \"zod\";\n\nconst User = z.object({\n name: z.string(),\n});\n\n// some untrusted data...\nconst input = {\n /* stuff */\n};\n\n// the parsed result is validated and type safe!\nconst data = User.parse(input);\n\n// so you can use it with confidence :)\nconsole.log(data.name);\n```\n\n \n\n## Features\n\n- Zero external dependencies\n- Works in Node.js and all modern browsers\n- Tiny: `2kb` core bundle (gzipped)\n- Immutable API: methods return a new instance\n- Concise interface\n- Works with TypeScript and plain JS\n- Built-in JSON Schema conversion\n- Extensive ecosystem\n\n \n\n## Installation\n\n```sh\nnpm install zod\n```\n\n \n\n## Basic usage\n\nBefore you can do anything else, you need to define a schema. For the purposes of this guide, we'll use a simple object schema.\n\n```ts\nimport * as z from \"zod\";\n\nconst Player = z.object({\n username: z.string(),\n xp: z.number(),\n});\n```\n\n### Parsing data\n\nGiven any Zod schema, use `.parse` to validate an input. If it's valid, Zod returns a strongly-typed _deep clone_ of the input.\n\n```ts\nPlayer.parse({ username: \"billie\", xp: 100 });\n// => returns { username: \"billie\", xp: 100 }\n```\n\n**Note** — If your schema uses certain asynchronous APIs like `async` [refinements](https://zod.dev/api#refinements) or [transforms](https://zod.dev/api#transforms), you'll need to use the `.parseAsync()` method instead.\n\n```ts\nconst schema = z.string().refine(async (val) => val.length <= 8);\n\nawait schema.parseAsync(\"hello\");\n// => \"hello\"\n```\n\n### Handling errors\n\nWhen validation fails, the `.parse()` method will throw a `ZodError` instance with granular information about the validation issues.\n\n```ts\ntry {\n Player.parse({ username: 42, xp: \"100\" });\n} catch (err) {\n if (err instanceof z.ZodError) {\n err.issues;\n /* [\n {\n expected: 'string',\n code: 'invalid_type',\n path: [ 'username' ],\n message: 'Invalid input: expected string'\n },\n {\n expected: 'number',\n code: 'invalid_type',\n path: [ 'xp' ],\n message: 'Invalid input: expected number'\n }\n ] */\n }\n}\n```\n\nTo avoid a `try/catch` block, you can use the `.safeParse()` method to get back a plain result object containing either the successfully parsed data or a `ZodError`. The result type is a [discriminated union](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions), so you can handle both cases conveniently.\n\n```ts\nconst result = Player.safeParse({ username: 42, xp: \"100\" });\nif (!result.success) {\n result.error; // ZodError instance\n} else {\n result.data; // { username: string; xp: number }\n}\n```\n\n**Note** — If your schema uses certain asynchronous APIs like `async` [refinements](https://zod.dev/api#refinements) or [transforms](https://zod.dev/api#transforms), you'll need to use the `.safeParseAsync()` method instead.\n\n```ts\nconst schema = z.string().refine(async (val) => val.length <= 8);\n\nawait schema.safeParseAsync(\"hello\");\n// => { success: true; data: \"hello\" }\n```\n\n### Inferring types\n\nZod infers a static type from your schema definitions. You can extract this type with the `z.infer<>` utility and use it however you like.\n\n```ts\nconst Player = z.object({\n username: z.string(),\n xp: z.number(),\n});\n\n// extract the inferred type\ntype Player = z.infer;\n\n// use it in your code\nconst player: Player = { username: \"billie\", xp: 100 };\n```\n\nIn some cases, the input & output types of a schema can diverge. For instance, the `.transform()` API can convert the input from one type to another. In these cases, you can extract the input and output types independently:\n\n```ts\nconst mySchema = z.string().transform((val) => val.length);\n\ntype MySchemaIn = z.input;\n// => string\n\ntype MySchemaOut = z.output; // equivalent to z.infer\n// number\n```\n","readmeFilename":"README.md"}
![\"Zod](\"logo.svg\")
\n ![\"Zod](\"https://github.com/colinhacks/zod/actions/workflows/test.yml/badge.svg?event=push&branch=main\"){kind=icon}
\n![\"License\"](\"https://img.shields.io/github/license/colinhacks/zod\")
![\"npm\"](\"https://img.shields.io/npm/dw/zod.svg\")
\n![\"discord](\"https://img.shields.io/discord/893487829802418277?label=Discord&logo=discord&logoColor=white\")
![\"stars\"](\"https://img.shields.io/github/stars/colinhacks/zod\")
![\"jazz](\"https://raw.githubusercontent.com/garden-co/jazz/938f6767e46cdfded60e50d99bf3b533f4809c68/homepage/homepage/public/Zod%20sponsor%20message.png\")
\n