@wenathlan/saddle 1.8.2 → 1.8.5

package/docs/plans/20.research.zod.validation.md

@@ -0,0 +1,1350 @@
+# Pesquisa: Zod Schema Validation para TypeScript (2026)
+
+## Sumário
+
+1. [Zod v4: O que mudou](#1-zod-v4-o-que-mudou)
+2. [Runtime Validation of Scraping Options](#2-runtime-validation-of-scraping-options)
+3. [Creating Zod Schemas for Core Types](#3-creating-zod-schemas-for-core-types)
+4. [API Input Validation Middleware](#4-api-input-validation-middleware)
+5. [CLI Validation with z.coerce](#5-cli-validation-with-zcoerce)
+6. [Deriving TypeScript Types](#6-deriving-typescript-types)
+7. [Best Practices](#7-best-practices)
+8. [Response Validation Pattern](#8-response-validation-pattern)
+9. [JSON Schema Generation](#9-json-schema-generation)
+10. [Complete Code Examples](#10-complete-code-examples)
+
+---
+
+## 1. Zod v4: O que mudou
+
+### Performance Improvements
+
+Zod v4 (released 2025-2026) brings major improvements:
+
+| Metric | Zod v3 | Zod v4 | Improvement |
+|--------|--------|--------|-------------|
+| Parse speed | ~1x | ~14x | 14x faster |
+| Bundle size | ~60KB | ~26KB | 2.3x smaller |
+| Type inference | Good | Excellent | Better DX |
+| Error messages | Basic | Rich | More helpful |
+
+### Key New Features
+
+```typescript
+import { z } from 'zod/v4';
+
+// 1. z.strictObject — rejects unknown keys at runtime
+const strictConfig = z.strictObject({
+  url: z.string().url(),
+  maxRetries: z.number().int().positive(),
+  // Unknown keys throw ZodError
+});
+
+// 2. .prefault() — default values computed lazily
+const options = z.object({
+  concurrency: z.number().default(5),
+  timeout: z.number().default(30_000),
+  userAgent: z.string().prefault(() => `Bot/${Math.random().toString(36)}`),
+});
+
+// 3. z.interface() — proper interface-like semantics
+const IScrapeResult = z.interface({
+  url: z.string(),
+  title: z.string(),
+  links: z.array(z.string()),
+});
+
+// 4. Improved error messages
+const schema = z.string().email();
+schema.parse('not-an-email');
+// v3: "Invalid email"
+// v4: "Invalid email: expected string matching email format, received 'not-an-email'"
+
+// 5. Pattern matching
+const result = z.union([z.string(), z.number()]).safeParse(true);
+// v4 gives better error: "Invalid input: expected string | number, received boolean"
+```
+
+### Migration from v3 to v4
+
+```typescript
+// v3
+import { z } from 'zod';
+const schema = z.object({ name: z.string() });
+
+// v4 (drop-in with import path change)
+import { z } from 'zod/v4';
+const schema = z.object({ name: z.string() });
+
+// For backwards compatibility
+import { z } from 'zod';
+// Zod v4 is backwards compatible with v3 API
+// But v4 has new features only available with 'zod/v4'
+```
+
+---
+
+## 2. Runtime Validation of Scraping Options
+
+### Why Runtime Validation?
+
+TypeScript types are erased at compile time. If your scraper receives options from:
+- CLI arguments (strings)
+- API requests (JSON)
+- Config files (YAML/JSON)
+- Environment variables (strings)
+
+...you need runtime validation to ensure they match your expected types.
+
+### Core Scraping Options Schema
+
+```typescript
+import { z } from 'zod';
+
+// Enum-like unions
+const HttpMethod = z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
+const ProxyType = z.enum(['http', 'https', 'socks5']);
+const BrowserType = z.enum(['chromium', 'firefox', 'webkit']);
+
+// URL with custom validation
+const SafeUrl = z.string()
+  .url()
+  .refine(
+    (url) => {
+      try {
+        const parsed = new URL(url);
+        return ['http:', 'https:'].includes(parsed.protocol);
+      } catch {
+        return false;
+      }
+    },
+    { message: 'URL must use http or https protocol' }
+  );
+
+// Proxy configuration
+const ProxyConfig = z.object({
+  url: z.string().url(),
+  username: z.string().optional(),
+  password: z.string().optional(),
+  type: ProxyType.default('http'),
+}).strict();
+
+// Header map
+const Headers = z.record(z.string(), z.string()).default({
+  'Accept': 'text/html,application/xhtml+xml',
+  'Accept-Language': 'en-US,en;q=0.9',
+});
+
+// Selector with timeout
+const SelectorConfig = z.object({
+  selector: z.string().min(1),
+  timeout: z.number().int().positive().default(5000),
+  optional: z.boolean().default(false),
+});
+
+// Main scrape options — the most important schema
+const ScrapeOptions = z.object({
+  // Target
+  url: SafeUrl,
+  method: HttpMethod.default('GET'),
+  headers: Headers,
+
+  // Browser settings
+  browser: BrowserType.default('chromium'),
+  headless: z.boolean().default(true),
+  viewport: z.object({
+    width: z.number().int().min(320).max(7680).default(1920),
+    height: z.number().int().min(240).max(4320).default(1080),
+  }).default({}),
+
+  // Timing
+  timeout: z.number().int().positive().default(30_000),
+  waitForSelector: SelectorConfig.optional(),
+  waitAfterLoad: z.number().int().min(0).default(0),
+
+  // Retry
+  maxRetries: z.number().int().min(0).max(10).default(3),
+  retryDelay: z.number().int().min(0).default(1000),
+  retryBackoff: z.enum(['linear', 'exponential']).default('exponential'),
+
+  // Proxy
+  proxy: ProxyConfig.optional(),
+
+  // Extraction
+  selectors: z.record(z.string(), SelectorConfig).optional(),
+  evaluatePage: z.string().optional(), // Serialized function
+
+  // Session
+  sessionId: z.string().uuid().optional(),
+  cookies: z.array(z.object({
+    name: z.string(),
+    value: z.string(),
+    domain: z.string().optional(),
+    path: z.string().default('/'),
+  })).optional(),
+
+  // Rate limiting
+  maxConcurrency: z.number().int().min(1).max(100).default(5),
+  requestsPerSecond: z.number().positive().optional(),
+  delayBetweenRequests: z.number().int().min(0).optional(),
+
+  // Output
+  format: z.enum(['html', 'text', 'json', 'screenshot']).default('html'),
+  screenshotFullPage: z.boolean().default(false),
+}).strict();
+
+// Cross-field refinements
+const ScrapeOptionsWithRefinements = ScrapeOptions.refine(
+  (opts) => {
+    // If using screenshot, must be in headless mode or have specific format
+    if (opts.screenshotFullPage && opts.format !== 'screenshot') {
+      return false;
+    }
+    return true;
+  },
+  {
+    message: 'screenshotFullPage requires format="screenshot"',
+    path: ['screenshotFullPage'],
+  }
+).refine(
+  (opts) => {
+    // requestsPerSecond and delayBetweenRequests are mutually exclusive
+    if (opts.requestsPerSecond && opts.delayBetweenRequests) {
+      return false;
+    }
+    return true;
+  },
+  {
+    message: 'Cannot set both requestsPerSecond and delayBetweenRequests',
+    path: ['requestsPerSecond'],
+  }
+);
+```
+
+### Browser Agent Config Schema
+
+```typescript
+const BrowserAgentConfig = z.object({
+  // Browser management
+  browserPool: z.object({
+    minBrowsers: z.number().int().min(1).default(1),
+    maxBrowsers: z.number().int().min(1).max(20).default(5),
+    maxPagesPerBrowser: z.number().int().min(1).max(50).default(10),
+    idleTimeout: z.number().int().min(1000).default(60_000),
+    launchTimeout: z.number().int().min(1000).default(30_000),
+  }).default({}),
+
+  // Session management
+  sessions: z.object({
+    maxSessions: z.number().int().min(1).default(100),
+    sessionTimeout: z.number().int().min(60_000).default(3_600_000),
+    rotateOnBlock: z.boolean().default(true),
+    cookiePersistence: z.boolean().default(true),
+  }).default({}),
+
+  // Anti-detection
+  stealth: z.object({
+    enabled: z.boolean().default(true),
+    randomizeViewport: z.boolean().default(true),
+    randomizeTiming: z.boolean().default(true),
+    minDelay: z.number().int().min(0).default(500),
+    maxDelay: z.number().int().min(0).default(2000),
+    humanizeMouse: z.boolean().default(true),
+  }).default({}),
+
+  // Plugin system
+  plugins: z.array(z.object({
+    name: z.string(),
+    enabled: z.boolean().default(true),
+    config: z.record(z.unknown()).default({}),
+  })).default([]),
+
+  // Error handling
+  errorHandling: z.object({
+    maxConsecutiveErrors: z.number().int().min(1).default(5),
+    circuitBreakerThreshold: z.number().min(0).max(1).default(0.5),
+    circuitBreakerResetTimeout: z.number().int().min(1000).default(60_000),
+    onCriticalError: z.enum(['stop', 'skip', 'restart']).default('stop'),
+  }).default({}),
+
+  // Logging
+  logging: z.object({
+    level: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+    requestLogging: z.boolean().default(true),
+    errorLogging: z.boolean().default(true),
+  }).default({}),
+}).strict();
+```
+
+---
+
+## 3. Creating Zod Schemas for Core Types
+
+### Data Extraction Schema
+
+```typescript
+// Schema for scraped data
+const ScrapedItem = z.object({
+  url: z.string().url(),
+  title: z.string(),
+  description: z.string().optional(),
+  content: z.string().optional(),
+  links: z.array(z.string().url()).default([]),
+  images: z.array(z.object({
+    src: z.string().url(),
+    alt: z.string().default(''),
+  })).default([]),
+  metadata: z.record(z.string(), z.unknown()).default({}),
+  scrapedAt: z.string().datetime().default(() => new Date().toISOString()),
+});
+
+// Schema for structured data extraction
+const ExtractionRule = z.object({
+  name: z.string().min(1),
+  selector: z.string().min(1),
+  type: z.enum(['text', 'html', 'attribute', 'list', 'count']),
+  attribute: z.string().optional(), // For type='attribute'
+  multiple: z.boolean().default(false),
+  required: z.boolean().default(true),
+  transform: z.enum(['string', 'number', 'boolean', 'date', 'json']).optional(),
+  default: z.unknown().optional(),
+}).refine(
+  (rule) => rule.type === 'attribute' ? !!rule.attribute : true,
+  { message: 'attribute name required when type="attribute"', path: ['attribute'] }
+);
+
+const ExtractionConfig = z.object({
+  items: z.string().min(1), // Container selector
+  rules: z.array(ExtractionRule).min(1),
+  pagination: z.object({
+    nextSelector: z.string().min(1),
+    maxPages: z.number().int().min(1).default(10),
+    waitForLoad: z.number().int().min(0).default(2000),
+  }).optional(),
+}).strict();
+```
+
+### Queue and Job Schema
+
+```typescript
+const JobPriority = z.enum(['critical', 'high', 'normal', 'low']);
+
+const ScrapeJob = z.object({
+  id: z.string().uuid().default(() => crypto.randomUUID()),
+  url: z.string().url(),
+  priority: JobPriority.default('normal'),
+  options: ScrapeOptions.partial().default({}),
+  metadata: z.record(z.unknown()).default({}),
+  createdAt: z.string().datetime().default(() => new Date().toISOString()),
+  attempts: z.number().int().min(0).default(0),
+  maxAttempts: z.number().int().min(1).default(3),
+  status: z.enum(['pending', 'running', 'completed', 'failed', 'cancelled']).default('pending'),
+}).strict();
+
+const BatchConfig = z.object({
+  jobs: z.array(ScrapeJob).min(1).max(10_000),
+  concurrency: z.number().int().min(1).max(100).default(10),
+  rateLimit: z.object({
+    requestsPerSecond: z.number().positive(),
+    burstSize: z.number().int().positive().default(5),
+  }).optional(),
+  deadline: z.string().datetime().optional(),
+  onProgress: z.function().optional(), // Can't validate functions with Zod
+}).strict();
+```
+
+---
+
+## 4. API Input Validation Middleware
+
+### Express/Hono/Fastify Pattern
+
+```typescript
+import { z } from 'zod';
+import type { ZodSchema, ZodError } from 'zod';
+import type { Request, Response, NextFunction } from 'express';
+
+// Generic validation middleware
+function validate<T extends ZodSchema>(
+  schema: T,
+  source: 'body' | 'query' | 'params' = 'body'
+) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    const result = schema.safeParse(req[source]);
+
+    if (!result.success) {
+      const errors = formatZodError(result.error);
+      return res.status(400).json({
+        error: 'Validation failed',
+        details: errors,
+      });
+    }
+
+    // Replace with validated/transformed data
+    (req as any)[source] = result.data;
+    next();
+  };
+}
+
+// Format ZodError into a readable structure
+function formatZodError(error: ZodError): Array<{
+  path: string;
+  message: string;
+  code: string;
+}> {
+  return error.issues.map((issue) => ({
+    path: issue.path.join('.'),
+    message: issue.message,
+    code: issue.code,
+  }));
+}
+
+// Usage with Express
+import express from 'express';
+
+const app = express();
+app.use(express.json());
+
+// POST /api/scrape — validates body
+app.post(
+  '/api/scrape',
+  validate(ScrapeOptions),
+  async (req, res) => {
+    // req.body is now typed as ScrapeOptions (validated)
+    const result = await scrape(req.body);
+    res.json(result);
+  }
+);
+
+// GET /api/jobs/:id — validates params
+app.get(
+  '/api/jobs/:id',
+  validate(z.object({ id: z.string().uuid() }), 'params'),
+  async (req, res) => {
+    // req.params.id is validated as UUID
+    const job = await getJob(req.params.id);
+    res.json(job);
+  }
+);
+
+// GET /api/jobs — validates query
+app.get(
+  '/api/jobs',
+  validate(
+    z.object({
+      page: z.coerce.number().int().min(1).default(1),
+      limit: z.coerce.number().int().min(1).max(100).default(20),
+      status: z.enum(['pending', 'running', 'completed', 'failed']).optional(),
+    }),
+    'query'
+  ),
+  async (req, res) => {
+    // req.query is validated and coerced
+    const jobs = await listJobs(req.query);
+    res.json(jobs);
+  }
+);
+```
+
+### Hono-Specific Pattern
+
+```typescript
+import { Hono } from 'hono';
+import { zValidator } from '@hono/zod-validator';
+
+const app = new Hono();
+
+// Hono has built-in Zod validator
+app.post(
+  '/api/scrape',
+  zValidator('json', ScrapeOptions, (result, c) => {
+    if (!result.success) {
+      return c.json({ error: result.error.issues }, 400);
+    }
+  }),
+  async (c) => {
+    const body = c.req.valid('json');
+    // body is fully typed and validated
+    const result = await scrape(body);
+    return c.json(result);
+  }
+);
+```
+
+### Fastify Pattern
+
+```typescript
+import Fastify from 'fastify';
+import { Type } from '@sinclair/typebox';
+import { Value } from '@sinclair/typebox';
+
+// Or use Zod with fastify-type-provider-zod
+import { ZodTypeProvider } from 'fastify-type-provider-zod';
+import { z } from 'zod';
+
+const fastify = Fastify().withTypeProvider<ZodTypeProvider>();
+
+fastify.post('/api/scrape', {
+  schema: {
+    body: ScrapeOptions,
+    response: {
+      200: z.object({
+        success: z.boolean(),
+        data: ScrapedItem,
+      }),
+    },
+  },
+}, async (request, reply) => {
+  // request.body is typed
+  const result = await scrape(request.body);
+  return { success: true, data: result };
+});
+```
+
+---
+
+## 5. CLI Validation with z.coerce
+
+### The Problem
+
+CLI arguments are always strings. `z.coerce` converts them to the correct type during validation.
+
+```typescript
+import { z } from 'zod';
+
+// CLI argument schema
+const CliOptions = z.object({
+  // String arguments (no coercion needed)
+  url: z.string().url('Invalid URL'),
+  output: z.string().default('./output'),
+
+  // Coerced number arguments
+  concurrency: z.coerce.number()
+    .int()
+    .min(1, 'Concurrency must be at least 1')
+    .max(100, 'Concurrency cannot exceed 100')
+    .default(5),
+
+  timeout: z.coerce.number()
+    .int()
+    .min(1000, 'Timeout must be at least 1000ms')
+    .default(30_000),
+
+  maxRetries: z.coerce.number()
+    .int()
+    .min(0)
+    .max(10)
+    .default(3),
+
+  // Coerced boolean arguments
+  headless: z.coerce.boolean().default(true),
+  verbose: z.coerce.boolean().default(false),
+  followRedirects: z.coerce.boolean().default(true),
+
+  // Enum arguments
+  browser: z.enum(['chromium', 'firefox', 'webkit']).default('chromium'),
+  format: z.enum(['json', 'csv', 'html']).default('json'),
+
+  // Date coercion
+  since: z.coerce.date().optional(),
+
+  // Array arguments (comma-separated)
+  urls: z.string().transform((val) => val.split(',').map(u => u.trim())),
+}).strict();
+
+// Parse CLI args
+function parseCliArgs(argv: string[]): z.infer<typeof CliOptions> {
+  // Simple arg parser (use commander/yargs in production)
+  const args: Record<string, string> = {};
+
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith('--')) {
+      const [key, value] = arg.slice(2).split('=');
+      args[key] = value ?? argv[++i] ?? 'true';
+    }
+  }
+
+  const result = CliOptions.safeParse(args);
+
+  if (!result.success) {
+    console.error('Invalid arguments:');
+    for (const issue of result.error.issues) {
+      console.error(`  --${issue.path.join('.')}: ${issue.message}`);
+    }
+    process.exit(1);
+  }
+
+  return result.data;
+}
+
+// Usage
+const options = parseCliArgs(process.argv);
+console.log(`Scraping ${options.url} with ${options.concurrency} concurrent requests`);
+```
+
+### Commander.js Integration
+
+```typescript
+import { Command } from 'commander';
+import { z } from 'zod';
+
+const program = new Command();
+
+const scrapeSchema = z.object({
+  url: z.string().url(),
+  concurrency: z.coerce.number().int().min(1).max(100).default(5),
+  timeout: z.coerce.number().int().min(1000).default(30_000),
+  headless: z.coerce.boolean().default(true),
+  browser: z.enum(['chromium', 'firefox', 'webkit']).default('chromium'),
+  output: z.string().default('./output'),
+  verbose: z.coerce.boolean().default(false),
+});
+
+program
+  .name('scraper')
+  .description('Web scraper CLI')
+  .version('1.0.0')
+  .argument('<url>', 'URL to scrape')
+  .option('-c, --concurrency <number>', 'Concurrent requests', '5')
+  .option('-t, --timeout <number>', 'Request timeout in ms', '30000')
+  .option('--no-headless', 'Run browser in headed mode')
+  .option('-b, --browser <type>', 'Browser type', 'chromium')
+  .option('-o, --output <dir>', 'Output directory', './output')
+  .option('-v, --verbose', 'Verbose output')
+  .action(async (url, opts) => {
+    const result = scrapeSchema.safeParse({ url, ...opts });
+
+    if (!result.success) {
+      console.error('Validation error:');
+      result.error.issues.forEach(i => {
+        console.error(`  ${i.path.join('.')}: ${i.message}`);
+      });
+      process.exit(1);
+    }
+
+    await runScraper(result.data);
+  });
+
+program.parse();
+```
+
+---
+
+## 6. Deriving TypeScript Types
+
+### The z.infer Pattern
+
+Zod schemas are the source of truth. TypeScript types are derived from them — never the other way around.
+
+```typescript
+import { z } from 'zod';
+
+// Define the schema
+const ScrapeOptions = z.object({
+  url: z.string().url(),
+  concurrency: z.number().int().default(5),
+  headless: z.boolean().default(true),
+  proxy: z.object({
+    url: z.string().url(),
+    username: z.string().optional(),
+  }).optional(),
+});
+
+// Derive the TypeScript type
+type ScrapeOptions = z.infer<typeof ScrapeOptions>;
+// {
+//   url: string;
+//   concurrency: number;
+//   headless: boolean;
+//   proxy?: { url: string; username?: string } | undefined;
+// }
+
+// For input (before defaults are applied)
+type ScrapeOptionsInput = z.input<typeof ScrapeOptions>;
+// { url: string; concurrency?: number; headless?: boolean; proxy?: ... }
+
+// For output (after defaults, transforms, refinements)
+type ScrapeOptionsOutput = z.output<typeof ScrapeOptions>;
+// { url: string; concurrency: number; headless: boolean; proxy?: ... }
+```
+
+### Extracting Types from Complex Schemas
+
+```typescript
+const ScrapedItem = z.object({
+  url: z.string().url(),
+  title: z.string(),
+  data: z.record(z.string(), z.unknown()),
+  tags: z.array(z.string()),
+  metadata: z.object({
+    scrapedAt: z.string().datetime(),
+    duration: z.number(),
+    status: z.enum(['success', 'partial', 'failed']),
+  }),
+});
+
+// Full type
+type ScrapedItem = z.infer<typeof ScrapedItem>;
+
+// Partial type (all optional)
+const PartialScrapedItem = ScrapedItem.partial();
+type PartialScrapedItem = z.infer<typeof PartialScrapedItem>;
+
+// Pick specific fields
+const ScrapedItemSummary = ScrapedItem.pick({
+  url: true,
+  title: true,
+  metadata: true,
+});
+type ScrapedItemSummary = z.infer<typeof ScrapedItemSummary>;
+
+// Omit specific fields
+const ScrapedItemData = ScrapedItem.omit({ metadata: true });
+type ScrapedItemData = z.infer<typeof ScrapedItemData>;
+
+// Extend with additional fields
+const ExtendedItem = ScrapedItem.extend({
+  screenshot: z.string().optional(),
+  pdf: z.string().optional(),
+});
+type ExtendedItem = z.infer<typeof ExtendedItem>;
+```
+
+### Utility Types from Zod
+
+```typescript
+// Make specific fields required
+const RequiredConfig = BrowserAgentConfig.required({
+  browserPool: true,
+  sessions: true,
+});
+
+// Deep partial (recursive)
+const DeepPartialScrapeOptions = ScrapeOptions.deepPartial();
+type DeepPartialScrapeOptions = z.infer<typeof DeepPartialScrapeOptions>;
+
+// Brand types for nominal typing
+const UserId = z.string().uuid().brand<'UserId'>();
+type UserId = z.infer<typeof UserId>;
+
+function getUser(id: UserId) { /* ... */ }
+
+// ✅ Works
+const id = UserId.parse('550e8400-e29b-41d4-a716-446655440000');
+getUser(id);
+
+// ❌ Compile error — can't pass random string
+getUser('550e8400-e29b-41d4-a716-446655440000');
+```
+
+---
+
+## 7. Best Practices
+
+### Validate at Boundaries, Trust Internally
+
+```typescript
+// ❌ BAD: Validating everywhere
+function processItem(item: ScrapedItem) {
+  const validated = ScrapedItem.parse(item); // Unnecessary!
+  return validated.title;
+}
+
+// ✅ GOOD: Validate once at the boundary
+async function scrapeAndProcess(url: string): Promise<ProcessedItem> {
+  // Boundary: incoming data from external source
+  const html = await fetch(url).then(r => r.text());
+  const raw = extractData(html); // Returns unknown
+
+  // Validate once
+  const item = ScrapedItem.parse(raw);
+
+  // Trust internally — no more validation needed
+  return processItem(item);
+}
+
+function processItem(item: ScrapedItem): ProcessedItem {
+  // item is guaranteed to be ScrapedItem
+  return { title: item.title.toUpperCase() };
+}
+```
+
+### Use safeParse at Boundaries
+
+```typescript
+// For operations that shouldn't throw
+function tryParseScrapeOptions(input: unknown): ScrapeOptions | null {
+  const result = ScrapeOptions.safeParse(input);
+  if (result.success) {
+    return result.data;
+  }
+  console.error('Invalid options:', result.error.format());
+  return null;
+}
+
+// For API responses
+async function fetchAndValidate<T extends z.ZodSchema>(
+  url: string,
+  schema: T
+): Promise<z.infer<T>> {
+  const res = await fetch(url);
+  const json = await res.json();
+
+  const result = schema.safeParse(json);
+  if (!result.success) {
+    throw new ScraperError('Invalid API response', {
+      code: 'RESPONSE_VALIDATION_FAILED',
+      metadata: { url, errors: result.error.issues },
+    });
+  }
+
+  return result.data;
+}
+```
+
+### Compose Schemas
+
+```typescript
+// Build complex schemas from simple ones
+const BaseEntity = z.object({
+  id: z.string().uuid(),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+});
+
+const ScrapedPage = BaseEntity.extend({
+  url: z.string().url(),
+  title: z.string(),
+  content: z.string(),
+  links: z.array(z.string().url()),
+});
+
+const ScrapedProduct = BaseEntity.extend({
+  url: z.string().url(),
+  name: z.string(),
+  price: z.number().positive(),
+  inStock: z.boolean(),
+  images: z.array(z.string().url()),
+});
+
+// Discriminated union for different scraped types
+const ScrapedEntity = z.discriminatedUnion('type', [
+  ScrapedPage.extend({ type: z.literal('page') }),
+  ScrapedProduct.extend({ type: z.literal('product') }),
+]);
+```
+
+---
+
+## 8. Response Validation Pattern
+
+### Validating External API Responses
+
+```typescript
+import { z } from 'zod';
+
+// Schema for a specific API
+const ExternalApiResponse = z.object({
+  status: z.enum(['ok', 'error']),
+  data: z.object({
+    results: z.array(z.object({
+      id: z.number(),
+      title: z.string(),
+      body: z.string(),
+    })),
+    total: z.number(),
+    page: z.number(),
+  }).optional(),
+  error: z.string().optional(),
+}).refine(
+  (res) => res.status === 'ok' ? !!res.data : !!res.error,
+  { message: 'Response must have data when status is ok, or error when status is error' }
+);
+
+async function fetchExternalData(query: string) {
+  const res = await fetch(`https://api.example.com/search?q=${query}`);
+  const json = await res.json();
+
+  const result = ExternalApiResponse.safeParse(json);
+
+  if (!result.success) {
+    // Log the raw response for debugging
+    console.error('Unexpected API response format:', json);
+    throw new ScraperError('External API returned unexpected format', {
+      code: 'RESPONSE_VALIDATION_FAILED',
+      metadata: {
+        issues: result.error.issues,
+        rawResponse: json,
+      },
+    });
+  }
+
+  if (result.data.status === 'error') {
+    throw new ScraperError(`External API error: ${result.data.error}`, {
+      code: 'EXTERNAL_API_ERROR',
+    });
+  }
+
+  return result.data.data!;
+}
+```
+
+### Validating Scraped HTML Structure
+
+```typescript
+// After extracting data from HTML, validate the structure
+const HtmlExtractedData = z.object({
+  title: z.string().min(1),
+  price: z.string().transform((val) => {
+    const num = parseFloat(val.replace(/[^0-9.]/g, ''));
+    if (isNaN(num)) throw new Error(`Invalid price: ${val}`);
+    return num;
+  }),
+  rating: z.string().transform((val) => {
+    const num = parseFloat(val);
+    if (num < 0 || num > 5) throw new Error(`Rating out of range: ${val}`);
+    return num;
+  }),
+  reviewCount: z.string().transform((val) => {
+    const num = parseInt(val.replace(/[^0-9]/g, ''), 10);
+    if (isNaN(num)) throw new Error(`Invalid review count: ${val}`);
+    return num;
+  }),
+  images: z.array(z.string().url()),
+  inStock: z.string().transform((val) => {
+    const lower = val.toLowerCase();
+    return lower.includes('in stock') || lower.includes('available');
+  }),
+});
+
+// Transform and validate in one step
+function parseProductPage(html: string): z.infer<typeof HtmlExtractedData> {
+  const raw = extractFromHtml(html); // Returns unknown
+  return HtmlExtractedData.parse(raw); // Throws on invalid data
+}
+```
+
+---
+
+## 9. JSON Schema Generation
+
+### Zod v4: z.toJSONSchema
+
+```typescript
+import { z } from 'zod/v4';
+
+const ScrapeOptions = z.object({
+  url: z.string().url(),
+  concurrency: z.number().int().min(1).max(100).default(5),
+  headless: z.boolean().default(true),
+  browser: z.enum(['chromium', 'firefox', 'webkit']).default('chromium'),
+  proxy: z.object({
+    url: z.string().url(),
+    type: z.enum(['http', 'https', 'socks5']).default('http'),
+  }).optional(),
+  selectors: z.record(z.string(), z.object({
+    selector: z.string(),
+    type: z.enum(['text', 'html', 'attribute']),
+  })).optional(),
+});
+
+// Generate JSON Schema
+const jsonSchema = z.toJSONSchema(ScrapeOptions);
+
+console.log(JSON.stringify(jsonSchema, null, 2));
+// Output:
+// {
+//   "type": "object",
+//   "properties": {
+//     "url": { "type": "string", "format": "uri" },
+//     "concurrency": { "type": "integer", "minimum": 1, "maximum": 100, "default": 5 },
+//     "headless": { "type": "boolean", "default": true },
+//     "browser": { "type": "string", "enum": ["chromium", "firefox", "webkit"], "default": "chromium" },
+//     "proxy": {
+//       "type": "object",
+//       "properties": {
+//         "url": { "type": "string", "format": "uri" },
+//         "type": { "type": "string", "enum": ["http", "https", "socks5"], "default": "http" }
+//       },
+//       "required": ["url"]
+//     },
+//     "selectors": {
+//       "type": "object",
+//       "additionalProperties": {
+//         "type": "object",
+//         "properties": {
+//           "selector": { "type": "string" },
+//           "type": { "type": "string", "enum": ["text", "html", "attribute"] }
+//         },
+//         "required": ["selector", "type"]
+//       }
+//     }
+//   },
+//   "required": ["url"],
+//   "additionalProperties": false
+// }
+```
+
+### Use Cases for JSON Schema
+
+```typescript
+// 1. Generate OpenAPI docs
+import { z } from 'zod/v4';
+
+const apiSchema = z.object({
+  body: ScrapeOptions,
+  response: z.object({
+    success: z.boolean(),
+    data: ScrapedItem,
+  }),
+});
+
+const jsonSchema = z.toJSONSchema(apiSchema);
+// Use with swagger-ui or redoc
+
+// 2. Generate VS Code settings schema
+const VsCodeSettings = z.object({
+  'scraper.defaultBrowser': z.enum(['chromium', 'firefox', 'webkit']),
+  'scraper.concurrency': z.number().int().min(1).max(100),
+  'scraper.outputDir': z.string(),
+});
+
+const vscodeSchema = z.toJSONSchema(VsCodeSettings);
+// Write to .vscode/settings.schema.json
+
+// 3. Validate config files at runtime
+const configSchema = z.object({
+  targets: z.array(z.object({
+    url: z.string().url(),
+    schedule: z.string(), // cron expression
+  })),
+  global: BrowserAgentConfig,
+});
+
+// Load and validate config
+const configPath = path.resolve('scraper.config.json');
+const configJson = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+const config = configSchema.parse(configJson);
+
+// 4. Client-side form validation
+// Use JSON Schema to generate form fields in React/Vue
+const formSchema = z.toJSONSchema(ScrapeOptions);
+// Pass to react-jsonschema-form or similar
+```
+
+### OpenAPI Integration
+
+```typescript
+import { z } from 'zod/v4';
+import { createDocument } from 'zod-openapi';
+
+const app = z.object({
+  openapi: z.literal('3.1.0'),
+  info: z.object({
+    title: 'Scraper API',
+    version: z.string(),
+  }),
+  paths: z.record(z.string(), z.object({
+    post: z.object({
+      requestBody: z.object({
+        content: z.record(z.string(), z.object({
+          schema: z.toJSONSchema(ScrapeOptions),
+        })),
+      }),
+      responses: z.record(z.string(), z.object({
+        description: z.string(),
+        content: z.record(z.string(), z.object({
+          schema: z.toJSONSchema(ScrapedItem),
+        })),
+      })),
+    }),
+  })),
+});
+
+// Generate OpenAPI spec
+const spec = app.parse({
+  openapi: '3.1.0',
+  info: { title: 'Scraper API', version: '1.0.0' },
+  paths: {
+    '/api/scrape': {
+      post: {
+        requestBody: {
+          content: {
+            'application/json': {
+              schema: z.toJSONSchema(ScrapeOptions),
+            },
+          },
+        },
+        responses: {
+          '200': {
+            description: 'Success',
+            content: {
+              'application/json': {
+                schema: z.toJSONSchema(ScrapedItem),
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+});
+```
+
+---
+
+## 10. Complete Code Examples
+
+### Full Scraper Config Validation System
+
+```typescript
+import { z } from 'zod';
+
+// ============================================
+// Schema Definitions
+// ============================================
+
+const UrlSchema = z.string().url().refine(
+  (url) => {
+    try {
+      const parsed = new URL(url);
+      return ['http:', 'https:'].includes(parsed.protocol);
+    } catch {
+      return false;
+    }
+  },
+  { message: 'URL must use http or https protocol' }
+);
+
+const ProxySchema = z.object({
+  url: UrlSchema,
+  username: z.string().optional(),
+  password: z.string().optional(),
+  type: z.enum(['http', 'https', 'socks5']).default('http'),
+}).strict();
+
+const SelectorSchema = z.object({
+  selector: z.string().min(1, 'Selector cannot be empty'),
+  timeout: z.number().int().min(100).max(60_000).default(5000),
+  optional: z.boolean().default(false),
+  waitForVisible: z.boolean().default(false),
+}).strict();
+
+const ScrapeOptionsSchema = z.object({
+  url: UrlSchema,
+  method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']).default('GET'),
+  headers: z.record(z.string(), z.string()).default({
+    'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9',
+    'Accept-Language': 'en-US,en;q=0.9',
+  }),
+  body: z.union([z.string(), z.record(z.unknown())]).optional(),
+  browser: z.enum(['chromium', 'firefox', 'webkit']).default('chromium'),
+  headless: z.boolean().default(true),
+  viewport: z.object({
+    width: z.number().int().min(320).max(7680).default(1920),
+    height: z.number().int().min(240).max(4320).default(1080),
+  }).default({}),
+  timeout: z.number().int().min(1000).max(300_000).default(30_000),
+  waitForSelector: SelectorSchema.optional(),
+  waitAfterLoad: z.number().int().min(0).max(60_000).default(0),
+  maxRetries: z.number().int().min(0).max(10).default(3),
+  retryDelay: z.number().int().min(0).max(60_000).default(1000),
+  retryBackoff: z.enum(['linear', 'exponential']).default('exponential'),
+  proxy: ProxySchema.optional(),
+  selectors: z.record(z.string(), SelectorSchema).optional(),
+  sessionId: z.string().uuid().optional(),
+  cookies: z.array(z.object({
+    name: z.string(),
+    value: z.string(),
+    domain: z.string().optional(),
+    path: z.string().default('/'),
+  })).optional(),
+  maxConcurrency: z.number().int().min(1).max(100).default(5),
+  requestsPerSecond: z.number().positive().optional(),
+  delayBetweenRequests: z.number().int().min(0).max(60_000).optional(),
+  format: z.enum(['html', 'text', 'json', 'screenshot']).default('html'),
+  screenshotFullPage: z.boolean().default(false),
+}).strict()
+  .refine(
+    (opts) => !(opts.requestsPerSecond && opts.delayBetweenRequests),
+    { message: 'Cannot set both requestsPerSecond and delayBetweenRequests' }
+  )
+  .refine(
+    (opts) => opts.screenshotFullPage ? opts.format === 'screenshot' : true,
+    { message: 'screenshotFullPage requires format="screenshot"' }
+  );
+
+const BatchConfigSchema = z.object({
+  urls: z.array(UrlSchema).min(1).max(10_000),
+  defaultOptions: ScrapeOptionsSchema.partial().default({}),
+  concurrency: z.number().int().min(1).max(100).default(10),
+  rateLimit: z.object({
+    requestsPerSecond: z.number().positive(),
+    burstSize: z.number().int().positive().default(5),
+  }).optional(),
+  deadline: z.string().datetime().optional(),
+  onProgress: z.function().optional(),
+}).strict();
+
+const BrowserAgentConfigSchema = z.object({
+  browserPool: z.object({
+    minBrowsers: z.number().int().min(1).default(1),
+    maxBrowsers: z.number().int().min(1).max(20).default(5),
+    maxPagesPerBrowser: z.number().int().min(1).max(50).default(10),
+    idleTimeout: z.number().int().min(1000).default(60_000),
+    launchTimeout: z.number().int().min(1000).default(30_000),
+  }).default({}),
+  sessions: z.object({
+    maxSessions: z.number().int().min(1).default(100),
+    sessionTimeout: z.number().int().min(60_000).default(3_600_000),
+    rotateOnBlock: z.boolean().default(true),
+  }).default({}),
+  stealth: z.object({
+    enabled: z.boolean().default(true),
+    randomizeViewport: z.boolean().default(true),
+    randomizeTiming: z.boolean().default(true),
+    minDelay: z.number().int().min(0).default(500),
+    maxDelay: z.number().int().min(0).default(2000),
+  }).default({}),
+  errorHandling: z.object({
+    maxConsecutiveErrors: z.number().int().min(1).default(5),
+    circuitBreakerThreshold: z.number().min(0).max(1).default(0.5),
+    circuitBreakerResetTimeout: z.number().int().min(1000).default(60_000),
+  }).default({}),
+}).strict();
+
+// ============================================
+// Validation Utility
+// ============================================
+
+class ValidationError extends Error {
+  public readonly issues: z.ZodIssue[];
+
+  constructor(error: z.ZodError) {
+    const message = error.issues
+      .map(i => `${i.path.join('.')}: ${i.message}`)
+      .join('\n');
+    super(`Validation failed:\n${message}`);
+    this.name = 'ValidationError';
+    this.issues = error.issues;
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      issues: this.issues.map(i => ({
+        path: i.path.join('.'),
+        message: i.message,
+        code: i.code,
+      })),
+    };
+  }
+}
+
+function validate<T extends z.ZodSchema>(schema: T, data: unknown): z.infer<T> {
+  const result = schema.safeParse(data);
+  if (!result.success) {
+    throw new ValidationError(result.error);
+  }
+  return result.data;
+}
+
+// ============================================
+// Usage
+// ============================================
+
+// Single URL scrape
+const options = validate(ScrapeOptionsSchema, {
+  url: 'https://example.com',
+  concurrency: 3,
+  proxy: {
+    url: 'http://proxy.example.com:8080',
+    type: 'http',
+  },
+});
+
+// Batch scrape
+const batch = validate(BatchConfigSchema, {
+  urls: [
+    'https://example.com/page1',
+    'https://example.com/page2',
+    'https://example.com/page3',
+  ],
+  concurrency: 5,
+  defaultOptions: {
+    headless: true,
+    maxRetries: 3,
+  },
+});
+
+// Browser agent config
+const agentConfig = validate(BrowserAgentConfigSchema, {
+  browserPool: {
+    maxBrowsers: 3,
+    maxPagesPerBrowser: 15,
+  },
+  stealth: {
+    enabled: true,
+    randomizeTiming: true,
+  },
+});
+
+// CLI args validation
+const cliOptions = validate(
+  z.object({
+    url: z.string().url(),
+    concurrency: z.coerce.number().int().min(1).max(100).default(5),
+    headless: z.coerce.boolean().default(true),
+    verbose: z.coerce.boolean().default(false),
+  }),
+  {
+    url: process.argv[2],
+    concurrency: process.argv[3],
+    headless: process.argv[4],
+    verbose: process.argv[5],
+  }
+);
+
+// API request validation (Express middleware)
+function validateBody<T extends z.ZodSchema>(schema: T) {
+  return (req: any, res: any, next: any) => {
+    const result = schema.safeParse(req.body);
+    if (!result.success) {
+      return res.status(400).json({
+        error: 'Validation failed',
+        details: result.error.issues.map(i => ({
+          path: i.path.join('.'),
+          message: i.message,
+        })),
+      });
+    }
+    req.body = result.data;
+    next();
+  };
+}
+
+// app.post('/api/scrape', validateBody(ScrapeOptionsSchema), handler);
+```
+
+---
+
+## Summary: Quick Reference
+
+| Task | Zod API | Example |
+|------|---------|---------|
+| Basic object | `z.object({...})` | `z.object({ url: z.string() })` |
+| String URL | `z.string().url()` | Validates URL format |
+| Number with bounds | `z.number().min().max()` | `z.number().int().min(1).max(100)` |
+| Enum | `z.enum([...])` | `z.enum(['a', 'b', 'c'])` |
+| Default values | `.default(value)` | `z.number().default(5)` |
+| Optional | `.optional()` | `z.string().optional()` |
+| Coerce from string | `z.coerce.number()` | CLI arguments |
+| Transform | `.transform(fn)` | Parse string to Date |
+| Refine | `.refine(fn, msg)` | Cross-field validation |
+| Discriminated union | `z.discriminatedUnion()` | Different response types |
+| Strict object | `z.strictObject()` | Reject unknown keys |
+| Derive TS type | `z.infer<typeof schema>` | Type from schema |
+| Safe parse | `.safeParse(data)` | Returns result, no throw |
+| Generate JSON Schema | `z.toJSONSchema()` | v4 only |