Chapter 55: The Zod Package — Method Overview

Core Idea

The zod package (the "flagship" library) extends zod/v4/core's $ZodType with ZodType, adding the full family of chainable instance methods that make Zod's method-based API discoverable via autocomplete — this is the default choice unless bundle size is a hard constraint (in which case see Zod Mini).

Key Concepts

• z.ZodType: base class for every schema in the zod package, extending z.$ZodType from core.
• Method categories on every schema instance: parsing (.parse, .safeParse, .parseAsync, .safeParseAsync), refinements (.refine, .superRefine — deprecated, use .check() — .overwrite), wrappers (.optional, .nonoptional, .nullable, .nullish, .default, .array, .or, .transform, .catch, .pipe, .readonly), metadata/registries (.register, .describe, .meta), and utilities (.check, .clone, .brand, .isOptional(), .isNullable()).

Code Examples

import * as z from "zod";

const schema = z.object({
  name: z.string(),
  age: z.number().int().positive(),
  email: z.email(),
});

const mySchema = z.string();
mySchema.parse(data);
mySchema.safeParse(data);
mySchema.refine(refinementFunc);
mySchema.optional().nullable().default("x");
mySchema.isOptional(); // boolean

• What it demonstrates: the breadth of chainable methods available on any schema, spanning parsing, refinement, wrapping, and introspection.

Key Takeaways

1. zod is the right default for most applications — it trades a small bundle-size cost for a far more ergonomic, autocomplete-friendly API than Zod Mini.
2. .isOptional()/.isNullable() are quick boolean introspection methods, useful when writing generic code that needs to check a schema's wrapper state without full type-level analysis.
3. .superRefine() is deprecated in favor of .check() — prefer the latter in new code.

Connects To

• Zod Mini — Overview & When to Use It: the tree-shakable alternative to this method-based API.
• Optional, Exact Optional, Nullable & Nullish: the wrapper methods listed here in more depth.