🛡️ Zod Playground – Mastering Type-safe Validation in TypeScript

Zod is a TypeScript-first schema declaration and validation library. This article demonstrates the usage of Zod for validating and parsing data structures, building form validators, discriminated unions, custom errors, and much more.

📦 Features Covered

• ✅ Schema creation and type inference

• ✅ Safe and unsafe parsing

• ✅ Enums and literals

• ✅ Object extensions and transformations

• ✅ Discriminated unions

• ✅ Record vs Map

• ✅ Default values

• ✅ Optional, nullable, and nullish handling

• ✅ Custom error messages using errorMap

• ✅ Promise schema

• ✅ Nested schemas and advanced schema composition

• ✅ Clean error reporting using zod-validation-error

🔧 Basic Schema and Type Inference

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

type userType = z.infer<typeof UserSchema>;

• strict() ensures no extra fields are allowed.

• z.infer auto-generates a TypeScript type from the schema.

🔍 Parsing Data

1. parse() – throws error if invalid

UserSchema.parse({ username: "Kajal" });

2. safeParse() – returns success boolean and error

UserSchema.safeParse({ username: "Kajal" });

🧠 Enum & Union

Using native enum:

enum JobPref {
  Remote,
  Onsite,
  Hybrid,
}
z.nativeEnum(JobPref);

Using string literals:

z.enum(["Remote", "Onsite", "Hybrid"]);

🧩 Advanced Object Schema

const userSchema2 = z.object({
  username: z.string().min(5).max(100),
  age: z.number().positive().default(Math.random()),
  birthday: z.date().optional(),
  isProgrammer: z.boolean().default(true),
  website: z.string().url().nullable(),
  hobbies: z.array(z.string()).nonempty().min(1).max(4),
  workPreference: z.enum(["Remote", "Onsite", "Hybrid"]).optional(),
}).passthrough();

Notes:

• .optional() – field can be undefined.

• .nullable() – field can be null.

• .nonempty() – array cannot be empty.

• .default() – sets default value if not provided.

• .passthrough() – allows extra fields.

• .strict() – blocks any extra fields.

🧪 Schema Utilities

• pick() – include only some fields

• omit() – remove specific fields

• deepPartial() – optional deep fields

• extend() – add new fields

• partial() – all fields optional

🔗 Tuple and Set

z.tuple([z.date(), z.number().gt(25)]).rest(z.string()); // fixed and variable parts
z.set(z.number()); // unique array values

🔄 Discriminated Union

Perfect for handling polymorphic data:

const textSchema = z.object({ type: z.literal("text"), content: z.string() });
const imageSchema = z.object({ type: z.literal("image"), url: z.string().url(), alt: z.string() });

const messageSchema = z.discriminatedUnion("type", [textSchema, imageSchema]);

This validates objects based on a type field and automatically picks the right schema.

🗃️ Record vs Map

Record (like object with dynamic keys)

z.record(z.number()); // key: string, val: number
z.record(z.string(), z.number()); // key: string, val: number

Map (JS Map object)

z.map(z.string(), z.number()); // key: string, val: number

Use record for plain JS objects and map when working with Map instances.

🔐 Refinement & Custom Errors

const brandEmail = z
  .string()
  .email()
  .refine(val => val.endsWith("kajalpiyaaa.in"), {
    message: "Email must end with @kajalpiyaaa.in",
  });

Use refine() to add custom validation logic.

🧼 Clean Error Output

import { fromZodError } from "zod-validation-error";

const result = brandEmail.safeParse(email);
if (!result.success) {
  console.log(fromZodError(result.error));
}


This gives **pretty error messages** instead of long error stacks.



## ❌ Custom Error Message Globally

```ts
const Schema = z.array(z.string(), {
  errorMap: () => ({ message: "yo it's a string!" }),
});

Use errorMap to define schema-specific error messages.

🧵 Promise Handling

const userAsync = z.promise(z.string());
// Ensures the resolved value is a string

🧠 Best Practices

• Use .infer<typeof Schema> to keep DRY in types.

• .safeParse() is great for graceful error handling.

• Prefer zod-validation-error for clean dev experience.

• Chain validations (like .min(), .default()) as needed.

• Use discriminated unions for clear type-safe API schemas.

🏁 Conclusion

This article showcases most of the core and advanced Zod features, making it an ideal reference for:

• Form validation

• API validation

• Config object schema enforcement

• Type-safe client-server communication

Thanks to web dev simplified!