Runtime Validation Best Practices

import { z } from 'zod';

// Define schema
const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  age: z.number().int().positive().optional(),
  role: z.enum(['admin', 'user', 'guest']),
});

// Infer type from schema
type User = z.infer<typeof UserSchema>;

// Validate at trust boundaries
export const createUser = (data: unknown): User => {
  return UserSchema.parse(data); // Throws on validation failure
};

// Safe parsing for user input
export const validateUser = (data: unknown): Result<User, z.ZodError> => {
  const result = UserSchema.safeParse(data);
  if (result.success) {
    return { ok: true, value: result.data };
  }
  return { ok: false, error: result.error };
};

// Base schemas
const AddressSchema = z.object({
  street: z.string(),
  city: z.string(),
  zipCode: z.string().regex(/^\d{5}$/),
});

const ContactSchema = z.object({
  email: z.string().email(),
  phone: z.string().optional(),
});

// Compose schemas
const CustomerSchema = z.object({
  name: z.string(),
  address: AddressSchema,
  contact: ContactSchema,
  metadata: z.record(z.string(), z.unknown()),
});

// Extend schemas
const PremiumCustomerSchema = CustomerSchema.extend({
  tier: z.literal('premium'),
  discount: z.number().min(0).max(100),
});

// Pick/omit fields
const PublicCustomerSchema = CustomerSchema.pick({
  name: true,
  contact: true,
});

// Transform data during validation
const DateSchema = z.string().transform((str) => new Date(str));

const NormalizedEmailSchema = z
  .string()
  .email()
  .transform((email) => email.toLowerCase().trim());

// Custom validation with refine
const PasswordSchema = z
  .string()
  .min(8)
  .refine((pwd) => /[A-Z]/.test(pwd), {
    message: 'Must contain uppercase letter',
  })
  .refine((pwd) => /[0-9]/.test(pwd), {
    message: 'Must contain number',
  });

// Complex validation
const RangeSchema = z
  .object({
    min: z.number(),
    max: z.number(),
  })
  .refine((data) => data.max > data.min, {
    message: 'Max must be greater than min',
    path: ['max'],
  });

// Express middleware
import { Request, Response, NextFunction } from 'express';

const validateRequest = <T>(schema: z.Schema<T>) => {
  return (req: Request, res: Response, next: NextFunction) => {
    const result = schema.safeParse(req.body);
    if (!result.success) {
      return res.status(400).json({
        error: 'Validation failed',
        details: result.error.format(),
      });
    }
    req.body = result.data;
    next();
  };
};

// Usage
app.post('/users', validateRequest(UserSchema), (req, res) => {
  const user = req.body; // Type-safe and validated
  // ... create user
});

// Environment configuration
const ConfigSchema = z.object({
  NODE_ENV: z.enum(['development', 'production', 'test']),
  PORT: z.string().transform((s) => parseInt(s, 10)),
  DATABASE_URL: z.string().url(),
  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
  FEATURE_FLAGS: z
    .string()
    .transform((s) => s.split(','))
    .default(''),
});

// Load and validate at startup
export const config = ConfigSchema.parse(process.env);

// Optional with default
const SettingsSchema = z.object({
  theme: z.enum(['light', 'dark']).default('light'),
  language: z.string().default('en'),
});

// Nullable vs optional
const ProfileSchema = z.object({
  bio: z.string().optional(), // Field may be missing
  avatar: z.string().nullable(), // Field present but may be null
  website: z.string().nullish(), // May be missing or null
});

// Discriminated union validation
const EventSchema = z.discriminatedUnion('type', [
  z.object({ type: z.literal('click'), x: z.number(), y: z.number() }),
  z.object({ type: z.literal('keypress'), key: z.string() }),
]);

// Recursive schemas
type Category = {
  name: string;
  subcategories: Category[];
};

const CategorySchema: z.ZodType<Category> = z.lazy(() =>
  z.object({
    name: z.string(),
    subcategories: z.array(CategorySchema),
  })
);