@wenathlan/saddle 1.8.17 → 2.0.2

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

@@ -1,1350 +0,0 @@
-# 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 |