@wenathlan/saddle 1.8.17 → 2.0.2

package/docs/plans/19.research.errors.events.md

@@ -1,1523 +0,0 @@
-# Pesquisa: Error Handling e Event Emitter Patterns (2026)
-
-## Sumário
-
-1. [Custom Error Classes](#1-custom-error-classes)
-2. [Error Hierarchies with Error Codes](#2-error-hierarchies-with-error-codes)
-3. [Crawlee Error Pattern](#3-crawlee-error-pattern)
-4. [Error Classification](#4-error-classification)
-5. [Recovery Suggestions in Error Objects](#5-recovery-suggestions-in-error-objects)
-6. [Typed EventEmitter in TypeScript](#6-typed-eventemitter-in-typescript)
-7. [Best Packages](#7-best-packages)
-8. [Lifecycle Hooks](#8-lifecycle-hooks)
-9. [Middleware Pipelines](#9-middleware-pipelines)
-10. [Plugin/Hook Systems](#10-pluginhook-systems)
-11. [Tree-shaking](#11-tree-shaking)
-
----
-
-## 1. Custom Error Classes
-
-### The Problem with TypeScript Errors
-
-In TypeScript, when you extend `Error`, the prototype chain breaks. `instanceof` checks fail because TypeScript's transpilation of `extends Error` doesn't correctly set up the prototype. The fix is `Object.setPrototypeOf(this, ClassName.prototype)` in the constructor.
-
-### Basic Pattern
-
-```typescript
-class ScraperError extends Error {
-  public readonly code: string;
-  public readonly timestamp: Date;
-
-  constructor(message: string, code: string = 'SCRAPER_ERROR') {
-    super(message);
-    this.name = this.constructor.name;
-    this.code = code;
-    this.timestamp = new Date();
-
-    // Fix prototype chain for instanceof checks
-    Object.setPrototypeOf(this, new.target.prototype);
-
-    // Capture stack trace (V8 only, not available in all environments)
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, this.constructor);
-    }
-  }
-}
-
-// Now instanceof works correctly
-const err = new ScraperError('Connection failed');
-console.log(err instanceof ScraperError); // true
-console.log(err instanceof Error);        // true
-```
-
-### With `new.target` vs Explicit Class
-
-`new.target` is dynamic and works with subclasses. If you need broader compatibility:
-
-```typescript
-class ScraperError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = this.constructor.name;
-    // Explicit class version (safer for older transpilers)
-    Object.setPrototypeOf(this, ScraperError.prototype);
-  }
-}
-
-class NetworkError extends ScraperError {
-  constructor(message: string, public readonly url: string) {
-    super(message);
-    // Must re-set for each subclass in the chain
-    Object.setPrototypeOf(this, NetworkError.prototype);
-  }
-}
-```
-
-### Error Options Pattern
-
-```typescript
-interface ScraperErrorOptions {
-  code: string;
-  cause?: unknown;
-  retryable?: boolean;
-  metadata?: Record<string, unknown>;
-}
-
-class ScraperError extends Error {
-  public readonly code: string;
-  public readonly retryable: boolean;
-  public readonly metadata: Record<string, unknown>;
-
-  constructor(
-    message: string,
-    options: ScraperErrorOptions = { code: 'SCRAPER_ERROR' }
-  ) {
-    super(message, { cause: options.cause });
-    this.name = this.constructor.name;
-    this.code = options.code;
-    this.retryable = options.retryable ?? false;
-    this.metadata = options.metadata ?? {};
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
-}
-```
-
-### 2026 Best Practice: Error Cause Chain
-
-Use the `cause` property (native since ES2022) to chain errors without losing context:
-
-```typescript
-async function fetchPage(url: string): Promise<string> {
-  try {
-    const res = await fetch(url);
-    return await res.text();
-  } catch (error) {
-    throw new ScraperError(`Failed to fetch ${url}`, {
-      code: 'FETCH_FAILED',
-      retryable: true,
-      cause: error,
-      metadata: { url, timestamp: Date.now() }
-    });
-  }
-}
-```
-
----
-
-## 2. Error Hierarchies with Error Codes
-
-### Enum-Based Error Codes
-
-```typescript
-// Error codes as const enum for tree-shaking
-const ErrorCodes = {
-  // Network errors (1xxx)
-  NETWORK_TIMEOUT:        'E1001',
-  NETWORK_CONNECTION_REFUSED: 'E1002',
-  NETWORK_DNS_FAILURE:    'E1003',
-  NETWORK_TLS_ERROR:      'E1004',
-
-  // HTTP errors (2xxx)
-  HTTP_RATE_LIMITED:      'E2001',
-  HTTP_403:               'E2002',
-  HTTP_404:               'E2003',
-  HTTP_500:               'E2004',
-  HTTP_503:               'E2005',
-
-  // Browser errors (3xxx)
-  BROWSER_LAUNCH_FAILED:  'E3001',
-  BROWSER_CRASHED:        'E3002',
-  BROWSER_TIMEOUT:        'E3003',
-  BROWSER_NAVIGATION:     'E3004',
-
-  // Scraping errors (4xxx)
-  SELECTOR_NOT_FOUND:     'E4001',
-  PARSING_FAILED:         'E4002',
-  CAPTCHA_DETECTED:       'E4003',
-  BOT_DETECTED:           'E4004',
-
-  // Session errors (5xxx)
-  SESSION_EXPIRED:        'E5001',
-  SESSION_BLOCKED:        'E5002',
-  COOKIES_INVALID:        'E5003',
-
-  // Configuration errors (6xxx)
-  CONFIG_INVALID:         'E6001',
-  CONFIG_MISSING:         'E6002',
-} as const;
-
-type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];
-
-// Metadata about each error code
-const ErrorMetadata: Record<ErrorCode, {
-  description: string;
-  retryable: boolean;
-  severity: 'low' | 'medium' | 'high' | 'critical';
-  defaultRetryDelay?: number;
-}> = {
-  [ErrorCodes.NETWORK_TIMEOUT]: {
-    description: 'Request timed out',
-    retryable: true,
-    severity: 'medium',
-    defaultRetryDelay: 1000,
-  },
-  [ErrorCodes.HTTP_RATE_LIMITED]: {
-    description: 'Server returned 429 Too Many Requests',
-    retryable: true,
-    severity: 'medium',
-    defaultRetryDelay: 5000,
-  },
-  [ErrorCodes.BOT_DETECTED]: {
-    description: 'Anti-bot protection triggered',
-    retryable: false,
-    severity: 'high',
-  },
-  [ErrorCodes.SELECTOR_NOT_FOUND]: {
-    description: 'CSS selector matched no elements',
-    retryable: false,
-    severity: 'low',
-  },
-} as const;
-```
-
-### Full Hierarchy Implementation
-
-```typescript
-// Base error
-class ScraperError extends Error {
-  public readonly code: ErrorCode;
-  public readonly retryable: boolean;
-  public readonly severity: 'low' | 'medium' | 'high' | 'critical';
-  public readonly timestamp: number;
-  public readonly metadata: Record<string, unknown>;
-
-  constructor(
-    message: string,
-    options: {
-      code: ErrorCode;
-      cause?: unknown;
-      metadata?: Record<string, unknown>;
-    }
-  ) {
-    super(message, { cause: options.cause });
-    this.name = this.constructor.name;
-    this.code = options.code;
-    this.timestamp = Date.now();
-    this.metadata = options.metadata ?? {};
-
-    const info = ErrorMetadata[options.code];
-    this.retryable = info?.retryable ?? false;
-    this.severity = info?.severity ?? 'medium';
-
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
-
-  toJSON() {
-    return {
-      name: this.name,
-      message: this.message,
-      code: this.code,
-      retryable: this.retryable,
-      severity: this.severity,
-      timestamp: this.timestamp,
-      metadata: this.metadata,
-      stack: this.stack,
-    };
-  }
-}
-
-// Network errors
-class NetworkError extends ScraperError {
-  public readonly url: string;
-
-  constructor(message: string, url: string, options: { code: ErrorCode; cause?: unknown }) {
-    super(message, { ...options, metadata: { ...options.metadata, url } });
-    this.name = 'NetworkError';
-    this.url = url;
-    Object.setPrototypeOf(this, NetworkError.prototype);
-  }
-}
-
-// HTTP errors
-class HttpError extends ScraperError {
-  public readonly statusCode: number;
-  public readonly headers: Record<string, string>;
-
-  constructor(
-    message: string,
-    statusCode: number,
-    headers: Record<string, string> = {},
-    cause?: unknown
-  ) {
-    const code = mapHttpStatus(statusCode);
-    super(message, { code, cause, metadata: { statusCode, headers } });
-    this.name = 'HttpError';
-    this.statusCode = statusCode;
-    this.headers = headers;
-    Object.setPrototypeOf(this, HttpError.prototype);
-  }
-}
-
-function mapHttpStatus(status: number): ErrorCode {
-  if (status === 429) return ErrorCodes.HTTP_RATE_LIMITED;
-  if (status === 403) return ErrorCodes.HTTP_403;
-  if (status === 404) return ErrorCodes.HTTP_404;
-  if (status === 500) return ErrorCodes.HTTP_500;
-  if (status === 503) return ErrorCodes.HTTP_503;
-  return ErrorCodes.HTTP_500;
-}
-
-// Browser errors
-class BrowserError extends ScraperError {
-  constructor(message: string, code: ErrorCode, cause?: unknown) {
-    super(message, { code, cause });
-    this.name = 'BrowserError';
-    Object.setPrototypeOf(this, BrowserError.prototype);
-  }
-}
-
-// Scraping errors
-class ScrapingError extends ScraperError {
-  public readonly selector?: string;
-  public readonly url: string;
-
-  constructor(
-    message: string,
-    url: string,
-    options: { code: ErrorCode; selector?: string; cause?: unknown }
-  ) {
-    super(message, {
-      ...options,
-      metadata: { ...options.metadata, url, selector: options.selector },
-    });
-    this.name = 'ScrapingError';
-    this.url = url;
-    this.selector = options.selector;
-    Object.setPrototypeOf(this, ScrapingError.prototype);
-  }
-}
-```
-
----
-
-## 3. Crawlee Error Pattern
-
-Crawlee (by Apify) defines a set of specialized error classes that communicate error intent to the framework. This pattern is highly reusable.
-
-### Core Crawlee Errors
-
-```typescript
-// From Crawlee's design philosophy:
-
-/**
- * NonRetryableError - Signals the crawler to stop immediately.
- * Use for: fatal configuration errors, invalid state, permanent failures.
- */
-class NonRetryableError extends Error {
-  constructor(message: string, options?: { cause?: unknown }) {
-    super(message, options);
-    this.name = 'NonRetryableError';
-    Object.setPrototypeOf(this, NonRetryableError.prototype);
-  }
-}
-
-/**
- * CriticalError - Crash-level error. The crawler cannot recover.
- * Use for: browser crashed, out of memory, system-level failures.
- */
-class CriticalError extends Error {
-  constructor(message: string, options?: { cause?: unknown }) {
-    super(message, options);
-    this.name = 'CriticalError';
-    Object.setPrototypeOf(this, CriticalError.prototype);
-  }
-}
-
-/**
- * RetryRequestError - Explicitly signals that the request should be retried.
- * Use for: transient failures you want to handle manually.
- */
-class RetryRequestError extends Error {
-  public readonly retryDelay?: number;
-  public readonly errorCode?: string;
-
-  constructor(
-    message: string,
-    options?: {
-      retryDelay?: number;
-      errorCode?: string;
-      cause?: unknown;
-    }
-  ) {
-    super(message, options);
-    this.name = 'RetryRequestError';
-    this.retryDelay = options?.retryDelay;
-    this.errorCode = options?.errorCode;
-    Object.setPrototypeOf(this, RetryRequestError.prototype);
-  }
-}
-
-/**
- * SessionError - Session-specific failure (blocked, expired).
- * Use for: cookie invalidation, IP bans, session rotation needed.
- */
-class SessionError extends Error {
-  public readonly shouldRotateSession: boolean;
-
-  constructor(
-    message: string,
-    options?: { shouldRotateSession?: boolean; cause?: unknown }
-  ) {
-    super(message, options);
-    this.name = 'SessionError';
-    this.shouldRotateSession = options?.shouldRotateSession ?? true;
-    Object.setPrototypeOf(this, SessionError.prototype);
-  }
-}
-```
-
-### Using Crawlee Errors in Practice
-
-```typescript
-import { PlaywrightCrawler } from 'crawlee';
-
-const crawler = new PlaywrightCrawler({
-  async requestHandler({ request, page, session }) {
-    // Check for CAPTCHA → SessionError triggers rotation
-    if (await page.$('#captcha')) {
-      throw new SessionError('CAPTCHA detected', {
-        shouldRotateSession: true,
-      });
-    }
-
-    // Check for bot detection → NonRetryable stops the crawler
-    if (await page.$('.access-denied')) {
-      throw new NonRetryableError('Bot detected, IP is banned');
-    }
-
-    // Rate limiting → RetryRequestError with custom delay
-    if (await page.$('.rate-limit')) {
-      throw new RetryRequestError('Rate limited', {
-        retryDelay: 30_000,
-        errorCode: 'RATE_LIMITED',
-      });
-    }
-
-    // Browser crash → CriticalError stops everything
-    if (page.isClosed()) {
-      throw new CriticalError('Page was closed unexpectedly');
-    }
-
-    // Normal scraping...
-    const data = await page.evaluate(() => {
-      return { title: document.title };
-    });
-
-    awaitcrawler.pushData(data);
-  },
-
-  async failedRequestHandler({ request, error }) {
-    if (error instanceof NonRetryableError) {
-      console.error(`FATAL: ${error.message} — skipping ${request.url}`);
-    } else if (error instanceof SessionError) {
-      console.warn(`Session issue on ${request.url}, rotating...`);
-    } else {
-      console.error(`Request failed: ${request.url}`, error);
-    }
-  },
-});
-```
-
----
-
-## 4. Error Classification
-
-### Strategy Pattern for Retry Decisions
-
-```typescript
-interface RetryPolicy {
-  maxRetries: number;
-  baseDelay: number;
-  maxDelay: number;
-  backoffMultiplier: number;
-  retryableErrors: Set<ErrorCode>;
-  nonRetryableErrors: Set<ErrorCode>;
-}
-
-const DEFAULT_RETRY_POLICY: RetryPolicy = {
-  maxRetries: 3,
-  baseDelay: 1000,
-  maxDelay: 30_000,
-  backoffMultiplier: 2,
-  retryableErrors: new Set([
-    ErrorCodes.NETWORK_TIMEOUT,
-    ErrorCodes.NETWORK_CONNECTION_REFUSED,
-    ErrorCodes.HTTP_RATE_LIMITED,
-    ErrorCodes.HTTP_500,
-    ErrorCodes.HTTP_503,
-    ErrorCodes.BROWSER_CRASHED,
-  ]),
-  nonRetryableErrors: new Set([
-    ErrorCodes.HTTP_404,
-    ErrorCodes.BOT_DETECTED,
-    ErrorCodes.CAPTCHA_DETECTED,
-    ErrorCodes.CONFIG_INVALID,
-  ]),
-};
-
-class ErrorClassifier {
-  private policy: RetryPolicy;
-
-  constructor(policy: RetryPolicy = DEFAULT_RETRY_POLICY) {
-    this.policy = policy;
-  }
-
-  shouldRetry(error: ScraperError, attempt: number): boolean {
-    if (attempt >= this.policy.maxRetries) return false;
-    if (this.policy.nonRetryableErrors.has(error.code)) return false;
-    if (this.policy.retryableErrors.has(error.code)) return true;
-    return error.retryable;
-  }
-
-  getRetryDelay(error: ScraperError, attempt: number): number {
-    const delay = this.policy.baseDelay * Math.pow(this.policy.backoffMultiplier, attempt);
-    return Math.min(delay, this.policy.maxDelay);
-  }
-
-  classify(error: unknown): {
-    retryable: boolean;
-    severity: 'low' | 'medium' | 'high' | 'critical';
-    suggestedAction: string;
-  } {
-    if (error instanceof ScraperError) {
-      const retryable = this.shouldRetry(error, 0);
-      return {
-        retryable,
-        severity: error.severity,
-        suggestedAction: this.getSuggestedAction(error),
-      };
-    }
-
-    // Unknown errors are generally retryable once
-    return {
-      retryable: true,
-      severity: 'medium',
-      suggestedAction: 'Unknown error, retry cautiously',
-    };
-  }
-
-  private getSuggestedAction(error: ScraperError): string {
-    const actions: Partial<Record<ErrorCode, string>> = {
-      [ErrorCodes.NETWORK_TIMEOUT]: 'Increase timeout or reduce request rate',
-      [ErrorCodes.HTTP_RATE_LIMITED]: 'Wait and retry with exponential backoff',
-      [ErrorCodes.BOT_DETECTED]: 'Rotate proxy/user-agent, review request patterns',
-      [ErrorCodes.CAPTCHA_DETECTED]: 'Use CAPTCHA solving service or skip URL',
-      [ErrorCodes.SELECTOR_NOT_FOUND]: 'Verify selector, page structure may have changed',
-      [ErrorCodes.BROWSER_CRASHED]: 'Restart browser pool, check memory limits',
-      [ErrorCodes.SESSION_EXPIRED]: 'Refresh session cookies',
-    };
-    return actions[error.code] ?? 'Review error details';
-  }
-}
-```
-
----
-
-## 5. Recovery Suggestions in Error Objects
-
-### Structured Recovery Metadata
-
-```typescript
-interface RecoverySuggestion {
-  action: string;
-  description: string;
-  automated: boolean; // Can the framework do this automatically?
-  fallback?: () => unknown;
-}
-
-class ScraperError extends Error {
-  // ... (previous properties)
-  public readonly recovery: RecoverySuggestion[];
-
-  constructor(
-    message: string,
-    options: {
-      code: ErrorCode;
-      cause?: unknown;
-      recovery?: RecoverySuggestion[];
-      metadata?: Record<string, unknown>;
-    }
-  ) {
-    super(message, { cause: options.cause });
-    this.name = this.constructor.name;
-    this.code = options.code;
-    this.recovery = options.recovery ?? [];
-    this.timestamp = Date.now();
-    this.metadata = options.metadata ?? {};
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
-
-  /**
-   * Get the first automated recovery action, if any.
-   */
-  getAutoRecovery(): RecoverySuggestion | undefined {
-    return this.recovery.find(r => r.automated);
-  }
-
-  /**
-   * Get all human-readable recovery instructions.
-   */
-  getRecoveryInstructions(): string[] {
-    return this.recovery.map(r => `[${r.action}] ${r.description}`);
-  }
-}
-
-// Factory function for common errors with recovery suggestions
-function createRateLimitError(
-  url: string,
-  retryAfter?: number
-): ScraperError {
-  const delay = retryAfter ?? 5000;
-  return new ScraperError(`Rate limited by ${new URL(url).hostname}`, {
-    code: ErrorCodes.HTTP_RATE_LIMITED,
-    metadata: { url, retryAfter: delay },
-    recovery: [
-      {
-        action: 'WAIT_AND_RETRY',
-        description: `Wait ${delay}ms then retry the request`,
-        automated: true,
-      },
-      {
-        action: 'REDUCE_CONCURRENCY',
-        description: 'Lower concurrent request count for this domain',
-        automated: true,
-      },
-      {
-        action: 'ROTATE_PROXY',
-        description: 'Switch to a different proxy IP address',
-        automated: true,
-        fallback: () => ({ proxyChanged: true }),
-      },
-      {
-        action: 'REVIEW_ROBOTS_TXT',
-        description: 'Check if the site\'s robots.txt allows your crawl pattern',
-        automated: false,
-      },
-    ],
-  });
-}
-
-function createBotDetectedError(url: string): ScraperError {
-  return new ScraperError(`Bot detection triggered on ${new URL(url).hostname}`, {
-    code: ErrorCodes.BOT_DETECTED,
-    metadata: { url },
-    recovery: [
-      {
-        action: 'ROTATE_USER_AGENT',
-        description: 'Switch to a different browser fingerprint',
-        automated: true,
-      },
-      {
-        action: 'ADD_HUMAN_DELAY',
-        description: 'Insert random delays between actions',
-        automated: true,
-      },
-      {
-        action: 'STOP_CRAWLING',
-        description: 'This site has strong bot protection, consider stopping',
-        automated: false,
-      },
-    ],
-  });
-}
-```
-
-### Error Handler Using Recovery
-
-```typescript
-async function handleError(error: unknown): Promise<void> {
-  if (error instanceof ScraperError) {
-    console.error(`[${error.code}] ${error.message}`);
-
-    // Log recovery suggestions
-    const instructions = error.getRecoveryInstructions();
-    if (instructions.length > 0) {
-      console.log('Recovery suggestions:');
-      instructions.forEach(i => console.log(`  - ${i}`));
-    }
-
-    // Try automated recovery
-    const autoRecovery = error.getAutoRecovery();
-    if (autoRecovery?.fallback) {
-      const result = autoRecovery.fallback();
-      console.log(`Auto-recovery executed: ${autoRecovery.action}`, result);
-    }
-  } else {
-    console.error('Unexpected error:', error);
-  }
-}
-```
-
----
-
-## 6. Typed EventEmitter in TypeScript
-
-### The Event Map Pattern
-
-The core idea: define an interface mapping event names to their payload types. This gives you full type safety — TypeScript knows what `on`, `emit`, and `once` accept and return.
-
-```typescript
-// Define your event map
-interface ScraperEvents {
-  // Event name → payload type
-  'request:start': { url: string; timestamp: number };
-  'request:success': { url: string; data: unknown; duration: number };
-  'request:error': { url: string; error: ScraperError };
-  'request:retry': { url: string; attempt: number; delay: number };
-  'batch:complete': { total: number; succeeded: number; failed: number };
-  'browser:launch': { browser: string; pid: number };
-  'browser:crash': { browser: string; error: string };
-  'session:rotate': { oldSession: string; newSession: string };
-}
-```
-
-### Hand-Rolled Typed Emitter
-
-```typescript
-type EventMap = Record<string, unknown>;
-
-type EventKey<T extends EventMap> = string & keyof T;
-type EventCallback<T extends EventMap, K extends EventKey<T>> =
-  (payload: T[K]) => void | Promise<void>;
-
-class TypedEmitter<T extends EventMap> {
-  private listeners = new Map<string, Set<Function>>();
-
-  on<K extends EventKey<T>>(
-    event: K,
-    callback: EventCallback<T, K>
-  ): () => void {
-    if (!this.listeners.has(event)) {
-      this.listeners.set(event, new Set());
-    }
-    this.listeners.get(event)!.add(callback);
-
-    // Return unsubscribe function
-    return () => {
-      this.listeners.get(event)?.delete(callback);
-    };
-  }
-
-  once<K extends EventKey<T>>(event: K, callback: EventCallback<T, K>): () => void {
-    const wrapped = ((payload: T[K]) => {
-      this.off(event, wrapped as EventCallback<T, K>);
-      return callback(payload);
-    }) as EventCallback<T, K>;
-    return this.on(event, wrapped);
-  }
-
-  off<K extends EventKey<T>>(event: K, callback: EventCallback<T, K>): void {
-    this.listeners.get(event)?.delete(callback);
-  }
-
-  async emit<K extends EventKey<T>>(event: K, payload: T[K]): Promise<void> {
-    const callbacks = this.listeners.get(event);
-    if (!callbacks) return;
-
-    for (const callback of callbacks) {
-      try {
-        await (callback as EventCallback<T, K>)(payload);
-      } catch (error) {
-        console.error(`Error in listener for "${event}":`, error);
-      }
-    }
-  }
-
-  removeAllListeners(event?: EventKey<T>): void {
-    if (event) {
-      this.listeners.delete(event);
-    } else {
-      this.listeners.clear();
-    }
-  }
-
-  listenerCount(event: EventKey<T>): number {
-    return this.listeners.get(event)?.size ?? 0;
-  }
-}
-
-// Usage
-const emitter = new TypedEmitter<ScraperEvents>();
-
-// ✅ TypeScript knows payload is { url: string; timestamp: number }
-emitter.on('request:start', (payload) => {
-  console.log(`Starting ${payload.url} at ${payload.timestamp}`);
-});
-
-// ✅ TypeScript error if you try wrong event name or wrong payload
-// emitter.on('request:start', (payload) => {
-//   console.log(payload.data); // ❌ Error: 'data' does not exist
-// });
-```
-
----
-
-## 7. Best Packages
-
-### emittery 2.0.0 (Recommended for Modern Projects)
-
-- **Async-first**: All handlers are awaited
-- **AbortSignal support**: Native integration with `AbortController`
-- **Symbol.dispose**: Supports the new `using` keyword (TC39 Explicit Resource Management)
-- **Type-safe**: Excellent TypeScript support
-
-```typescript
-import Emittery from 'emittery';
-
-interface Events {
-  data: { chunk: Buffer; source: string };
-  error: { error: Error; recoverable: boolean };
-  done: undefined;
-}
-
-const emitter = new Emittery<Events>();
-
-// Async iteration
-async function processEvents() {
-  for await (const data of emitter.events('data')) {
-    console.log(`Received ${data.chunk.length} bytes from ${data.source}`);
-  }
-}
-
-// AbortSignal support
-const controller = new AbortController();
-emitter.on('data', async (data) => {
-  await processChunk(data);
-}, { signal: controller.signal });
-
-// Symbol.dispose for `using` keyword
-{
-  using _sub = emitter.on('error', (err) => console.error(err));
-  // Automatically unsubscribed when scope exits
-}
-```
-
-### eventemitter3 5.0.4 (Fastest)
-
-- **Fastest**: Benchmarks 2-5x faster than Node's EventEmitter
-- **Tiny**: ~1KB minified
-- **No extra features**: Just fast events
-
-```typescript
-import EventEmitter from 'eventemitter3';
-
-interface Events {
-  'data:chunk': Buffer;
-  'scrape:complete': { url: string; items: number };
-}
-
-const ee = new EventEmitter<Events>();
-
-// Same API as Node EventEmitter, but faster
-ee.on('data:chunk', (chunk) => {
-  console.log(chunk.length);
-});
-
-ee.emit('scrape:complete', { url: 'https://example.com', items: 42 });
-```
-
-### mitt 3.0.1 (Smallest)
-
-- **200 bytes** gzipped
-- **No dependencies**
-- **Works everywhere**: Browser, Node, Deno, Bun
-
-```typescript
-import mitt from 'mitt';
-
-interface Events {
-  'scrape:start': string;
-  'scrape:end': { url: string; duration: number };
-}
-
-const emitter = mitt<Events>();
-
-emitter.on('scrape:start', (url) => console.log(`Starting ${url}`));
-emitter.on('scrape:end', ({ url, duration }) => console.log(`${url}: ${duration}ms`));
-
-emitter.emit('scrape:start', 'https://example.com');
-```
-
-### Comparison Table
-
-| Feature | emittery 2.0 | eventemitter3 5.0 | mitt 3.0 |
-|---------|-------------|-------------------|----------|
-| Size (gzip) | ~3KB | ~1KB | ~200B |
-| Async handlers | ✅ Native | ❌ Manual | ❌ Manual |
-| AbortSignal | ✅ Built-in | ❌ No | ❌ No |
-| Symbol.dispose | ✅ Yes | ❌ No | ❌ No |
-| Type safety | ✅ Excellent | ✅ Good | ✅ Good |
-| Performance | Good | Best | Good |
-| Node.js | ✅ | ✅ | ✅ |
-| Browser | ✅ | ✅ | ✅ |
-
-**Recommendation**: Use `emittery` for new projects (best DX), `eventemitter3` for performance-critical paths, `mitt` for minimal bundles.
-
----
-
-## 8. Lifecycle Hooks
-
-### The Pattern
-
-Lifecycle hooks are named extension points where plugins or middleware can inject behavior. This pattern is used by `ky`, `ofetch`, and various scraping frameworks.
-
-```typescript
-interface RequestLifecycle {
-  beforeRequest: ((request: Request) => Request | Promise<Request>)[];
-  afterResponse: ((response: Response, request: Request) => Response | Promise<Response>)[];
-  beforeRetry: ((error: ScraperError, attempt: number) => void | Promise<void>)[];
-  beforeError: ((error: ScraperError) => ScraperError | Promise<ScraperError>)[];
-}
-
-class RequestPipeline {
-  private hooks: RequestLifecycle = {
-    beforeRequest: [],
-    afterResponse: [],
-    beforeRetry: [],
-    beforeError: [],
-  };
-
-  on<K extends keyof RequestLifecycle>(
-    hook: K,
-    callback: RequestLifecycle[K][number]
-  ): () => void {
-    this.hooks[hook].push(callback as never);
-    return () => {
-      const idx = this.hooks[hook].indexOf(callback as never);
-      if (idx !== -1) this.hooks[hook].splice(idx, 1);
-    };
-  }
-
-  async executeRequest(
-    url: string,
-    options: RequestInit = {}
-  ): Promise<Response> {
-    let request = new Request(url, options);
-    let attempt = 0;
-    const maxAttempts = 3;
-
-    while (attempt < maxAttempts) {
-      try {
-        // beforeRequest hooks
-        for (const hook of this.hooks.beforeRequest) {
-          request = await hook(request);
-        }
-
-        const response = await fetch(request);
-
-        // afterResponse hooks
-        let processedResponse = response;
-        for (const hook of this.hooks.afterResponse) {
-          processedResponse = await hook(processedResponse, request);
-        }
-
-        if (!processedResponse.ok) {
-          throw new HttpError(
-            `HTTP ${processedResponse.status}`,
-            processedResponse.status
-          );
-        }
-
-        return processedResponse;
-      } catch (error) {
-        const scraperError = error instanceof ScraperError
-          ? error
-          : new ScraperError(String(error), {
-              code: ErrorCodes.NETWORK_TIMEOUT,
-              cause: error,
-            });
-
-        // beforeError hooks
-        let finalError = scraperError;
-        for (const hook of this.hooks.beforeError) {
-          finalError = await hook(finalError);
-        }
-
-        if (finalError.retryable && attempt < maxAttempts - 1) {
-          // beforeRetry hooks
-          for (const hook of this.hooks.beforeRetry) {
-            await hook(finalError, attempt);
-          }
-          attempt++;
-          await new Promise(r => setTimeout(r, 1000 * attempt));
-          continue;
-        }
-
-        throw finalError;
-      }
-    }
-
-    throw new ScraperError('Max retries exceeded', {
-      code: ErrorCodes.NETWORK_TIMEOUT,
-    });
-  }
-}
-```
-
-### ky-Style Plugin API
-
-```typescript
-// ky-style hooks (simplified)
-interface KyOptions {
-  hooks?: {
-    beforeRequest?: ((request: Request) => Request | Promise<Request>)[];
-    afterResponse?: ((response: Response) => Response | Promise<Response>)[];
-    beforeRetry?: ((error: Error, retryCount: number) => void | Promise<void>)[];
-    beforeError?: ((error: HTTPError) => HTTPError | Promise<HTTPError>)[];
-  };
-}
-
-// Usage with ky
-import ky from 'ky';
-
-const api = ky.create({
-  hooks: {
-    beforeRequest: [
-      (request) => {
-        request.headers.set('Authorization', `Bearer ${getToken()}`);
-        return request;
-      },
-    ],
-    afterResponse: [
-      (response) => {
-        if (response.status === 401) {
-          refreshToken();
-        }
-        return response;
-      },
-    ],
-    beforeRetry: [
-      (error, retryCount) => {
-        console.log(`Retry #${retryCount} after ${error.message}`);
-      },
-    ],
-  },
-});
-```
-
-### ofetch Pattern
-
-```typescript
-import { ofetch } from 'ofetch';
-
-const fetcher = ofetch.create({
-  baseURL: 'https://api.example.com',
-  headers: { 'User-Agent': 'MyScraper/1.0' },
-
-  // Retry configuration
-  retry: 3,
-  retryDelay: 1000,
-  backoff: (attempt) => Math.pow(2, attempt) * 1000,
-
-  // Hook
-  onResponse({ response }) {
-    console.log(`Response: ${response.status}`);
-  },
-  onRequestError({ error }) {
-    console.error(`Request failed: ${error.message}`);
-  },
-});
-```
-
----
-
-## 9. Middleware Pipelines
-
-### Koa-Style Onion Model
-
-The onion model wraps the core handler in layers. Each middleware can run code before and after the core, forming a concentric structure like onion layers.
-
-```typescript
-type Middleware<TContext> = (
-  context: TContext,
-  next: () => Promise<void>
-) => Promise<void>;
-
-class MiddlewarePipeline<TContext> {
-  private middlewares: Middleware<TContext>[] = [];
-
-  use(middleware: Middleware<TContext>): this {
-    this.middlewares.push(middleware);
-    return this;
-  }
-
-  async execute(context: TContext): Promise<TContext> {
-    // Build the onion: each middleware wraps the next
-    let index = this.middlewares.length;
-
-    const dispatch = async (i: number): Promise<void> => {
-      if (i < this.middlewares.length) {
-        const middleware = this.middlewares[i];
-        await middleware(context, () => dispatch(i + 1));
-      }
-    };
-
-    await dispatch(0);
-    return context;
-  }
-}
-
-// Usage
-interface ScrapeContext {
-  url: string;
-  html?: string;
-  data?: unknown;
-  error?: ScraperError;
-  metadata: Record<string, unknown>;
-}
-
-const pipeline = new MiddlewarePipeline<ScrapeContext>();
-
-// Logging middleware
-pipeline.use(async (ctx, next) => {
-  const start = Date.now();
-  console.log(`→ ${ctx.url}`);
-  await next();
-  const duration = Date.now() - start;
-  console.log(`← ${ctx.url} (${duration}ms)`);
-});
-
-// User-Agent middleware
-pipeline.use(async (ctx, next) => {
-  // Modify request before
-  ctx.metadata.userAgent = 'Mozilla/5.0 ...';
-  await next();
-  // Process response after
-  if (ctx.html) {
-    console.log(`Fetched ${ctx.html.length} bytes`);
-  }
-});
-
-// Error handling middleware
-pipeline.use(async (ctx, next) => {
-  try {
-    await next();
-  } catch (error) {
-    ctx.error = error instanceof ScraperError
-      ? error
-      : new ScraperError(String(error), { code: ErrorCodes.NETWORK_TIMEOUT });
-    console.error(`Error on ${ctx.url}: ${ctx.error.message}`);
-  }
-});
-
-// Core handler (the innermost layer)
-pipeline.use(async (ctx, next) => {
-  const res = await fetch(ctx.url, {
-    headers: { 'User-Agent': ctx.metadata.userAgent as string },
-  });
-  ctx.html = await res.text();
-  await next();
-});
-
-// Execute
-const context: ScrapeContext = {
-  url: 'https://example.com',
-  metadata: {},
-};
-await pipeline.execute(context);
-```
-
-### Express-Style Flat Middleware
-
-```typescript
-type FlatMiddleware<T> = (item: T, next: () => Promise<void>) => Promise<void>;
-
-class FlatPipeline<T> {
-  private middlewares: FlatMiddleware<T>[] = [];
-
-  use(middleware: FlatMiddleware<T>): this {
-    this.middlewares.push(middleware);
-    return this;
-  }
-
-  async execute(item: T): Promise<T> {
-    let index = 0;
-
-    const next = async (): Promise<void> => {
-      if (index < this.middlewares.length) {
-        const middleware = this.middlewares[index++];
-        await middleware(item, next);
-      }
-    };
-
-    await next();
-    return item;
-  }
-}
-```
-
-### Interceptor Pattern (Axios-Style)
-
-```typescript
-interface Interceptor<T> {
-  onFulfilled: (value: T) => T | Promise<T>;
-  onRejected?: (error: unknown) => T | Promise<T>;
-}
-
-class InterceptorManager<T> {
-  private interceptors: Interceptor<T>[] = [];
-
-  use(
-    onFulfilled: (value: T) => T | Promise<T>,
-    onRejected?: (error: unknown) => T | Promise<T>
-  ): number {
-    this.interceptors.push({ onFulfilled, onRejected });
-    return this.interceptors.length - 1;
-  }
-
-  eject(id: number): void {
-    this.interceptors.splice(id, 1);
-  }
-
-  async run(value: T): Promise<T> {
-    let result = value;
-    for (const interceptor of this.interceptors) {
-      try {
-        result = await interceptor.onFulfilled(result);
-      } catch (error) {
-        if (interceptor.onRejected) {
-          result = await interceptor.onRejected(error);
-        } else {
-          throw error;
-        }
-      }
-    }
-    return result;
-  }
-}
-
-// Usage
-const requestInterceptors = new InterceptorManager<Request>();
-const responseInterceptors = new InterceptorManager<Response>();
-
-requestInterceptors.use(
-  (request) => {
-    request.headers.set('X-Request-ID', crypto.randomUUID());
-    return request;
-  }
-);
-
-responseInterceptors.use(
-  (response) => {
-    console.log(`Status: ${response.status}`);
-    return response;
-  },
-  (error) => {
-    console.error('Response error:', error);
-    throw error;
-  }
-);
-```
-
----
-
-## 10. Plugin/Hook Systems
-
-### HookRegistry with Typed Events
-
-```typescript
-type HookHandler<T = void> = (context: T) => T | Promise<T>;
-
-class HookRegistry<TEventMap extends Record<string, unknown>> {
-  private hooks = new Map<string, Set<HookHandler<any>>>();
-  private priorities = new Map<string, Map<HookHandler<any>, number>>();
-
-  /**
-   * Register a hook handler with optional priority (lower = runs first).
-   */
-  on<K extends keyof TEventMap & string>(
-    event: K,
-    handler: HookHandler<TEventMap[K]>,
-    priority: number = 10
-  ): () => void {
-    if (!this.hooks.has(event)) {
-      this.hooks.set(event, new Set());
-      this.priorities.set(event, new Map());
-    }
-
-    this.hooks.get(event)!.add(handler);
-    this.priorities.get(event)!.set(handler, priority);
-
-    return () => {
-      this.hooks.get(event)?.delete(handler);
-      this.priorities.get(event)?.delete(handler);
-    };
-  }
-
-  /**
-   * Execute all handlers for an event, in priority order.
-   * Each handler receives the result of the previous one.
-   */
-  async trigger<K extends keyof TEventMap & string>(
-    event: K,
-    initial: TEventMap[K]
-  ): Promise<TEventMap[K]> {
-    const handlers = this.hooks.get(event);
-    if (!handlers || handlers.size === 0) return initial;
-
-    // Sort by priority
-    const sorted = [...handlers].sort((a, b) => {
-      const pa = this.priorities.get(event)!.get(a) ?? 10;
-      const pb = this.priorities.get(event)!.get(b) ?? 10;
-      return pa - pb;
-    });
-
-    let result = initial;
-    for (const handler of sorted) {
-      try {
-        result = await handler(result);
-      } catch (error) {
-        console.error(`Hook "${event}" handler failed:`, error);
-      }
-    }
-
-    return result;
-  }
-
-  /**
-   * Execute all handlers for an event (fire-and-forget style).
-   */
-  async notify<K extends keyof TEventMap & string>(
-    event: K,
-    payload: TEventMap[K]
-  ): Promise<void> {
-    const handlers = this.hooks.get(event);
-    if (!handlers) return;
-
-    for (const handler of handlers) {
-      try {
-        await handler(payload);
-      } catch (error) {
-        console.error(`Notification handler for "${event}" failed:`, error);
-      }
-    }
-  }
-
-  /**
-   * Remove all hooks, optionally for a specific event.
-   */
-  clear(event?: keyof TEventMap & string): void {
-    if (event) {
-      this.hooks.delete(event);
-      this.priorities.delete(event);
-    } else {
-      this.hooks.clear();
-      this.priorities.clear();
-    }
-  }
-}
-
-// Define event types
-interface CrawlerHooks {
-  'request:before': { url: string; options: RequestInit };
-  'request:after': { url: string; response: Response };
-  'parse:before': { url: string; html: string };
-  'parse:after': { url: string; data: unknown };
-  'error': { url: string; error: ScraperError };
-}
-
-// Usage
-const hooks = new HookRegistry<CrawlerHooks>();
-
-// Register hooks with priorities
-hooks.on('request:before', async (ctx) => {
-  ctx.options.headers = { ...ctx.options.headers, 'User-Agent': 'Bot/1.0' };
-  return ctx;
-}, 1); // Priority 1 (runs first)
-
-hooks.on('request:before', async (ctx) => {
-  console.log(`Fetching ${ctx.url}`);
-  return ctx;
-}, 10); // Priority 10 (runs second)
-
-// Plugin system using HookRegistry
-class RateLimitPlugin {
-  private requestCounts = new Map<string, number>();
-
-  register(hooks: HookRegistry<CrawlerHooks>): void {
-    hooks.on('request:before', async (ctx) => {
-      const domain = new URL(ctx.url).hostname;
-      const count = this.requestCounts.get(domain) ?? 0;
-
-      if (count >= 10) {
-        await new Promise(r => setTimeout(r, 1000));
-        this.requestCounts.set(domain, 0);
-      }
-
-      this.requestCounts.set(domain, count + 1);
-      return ctx;
-    }, 5);
-  }
-}
-
-// Plugin usage
-const rateLimitPlugin = new RateLimitPlugin();
-rateLimitPlugin.register(hooks);
-```
-
----
-
-## 11. Tree-shaking
-
-### Principles
-
-Tree-shaking removes unused code at build time. For your error classes and utilities to be tree-shakeable:
-
-1. **ESM-only**: Use `export`/`import`, never `module.exports`
-2. **Named exports**: Avoid default exports (bundlers can't rename them)
-3. **No side effects**: Mark package as side-effect-free
-4. **Avoid namespace re-exports**: Don't do `export * as utils from './utils'`
-
-### package.json Configuration
-
-```json
-{
-  "type": "module",
-  "sideEffects": false,
-  "exports": {
-    ".": {
-      "import": "./dist/index.mjs",
-      "types": "./dist/index.d.ts"
-    },
-    "./errors": {
-      "import": "./dist/errors.mjs",
-      "types": "./dist/errors.d.ts"
-    },
-    "./events": {
-      "import": "./dist/events.mjs",
-      "types": "./dist/events.d.ts"
-    }
-  }
-}
-```
-
-### ESM-Only Module Structure
-
-```typescript
-// src/errors/index.ts — Named exports only!
-export { ScraperError } from './scraper-error.js';
-export { NetworkError } from './network-error.js';
-export { HttpError } from './http-error.js';
-export { BrowserError } from './browser-error.js';
-export { ScrapingError } from './scraping-error.js';
-export { ErrorCodes } from './error-codes.js';
-export { ErrorClassifier } from './error-classifier.js';
-
-// ❌ DON'T: Default export
-// export default { ScraperError, NetworkError };
-
-// ❌ DON'T: Namespace re-export
-// import * as errors from './errors';
-// export { errors };
-
-// ✅ DO: Named exports (tree-shakeable)
-// import { ScraperError, NetworkError } from '@myscrape/errors';
-```
-
-### Avoiding Side Effects
-
-```typescript
-// ❌ BAD: Side effects in module scope
-export class ScraperError extends Error { /* ... */ }
-const globalRegistry = new ErrorRegistry(); // Side effect!
-globalRegistry.register(ScraperError);
-
-// ✅ GOOD: Pure exports, side effects only on explicit call
-export class ScraperError extends Error { /* ... */ }
-export function createRegistry(): ErrorRegistry {
-  return new ErrorRegistry();
-}
-
-// ✅ GOOD: Lazy initialization
-let _registry: ErrorRegistry | null = null;
-export function getRegistry(): ErrorRegistry {
-  if (!_registry) {
-    _registry = new ErrorRegistry();
-  }
-  return _registry;
-}
-```
-
-### tsconfig.json for ESM
-
-```json
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "declaration": true,
-    "declarationMap": true,
-    "sourceMap": true,
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "**/*.test.ts"]
-}
-```
-
-### Bundle Analysis
-
-```bash
-# Analyze bundle size
-npx @next/bundle-analyzer
-
-# Or use source-map-explorer
-npx source-map-explorer dist/index.mjs
-
-# Check what's included
-npx esbuild src/index.ts --bundle --analyze
-```
-
----
-
-## Summary: Quick Reference
-
-| Pattern | When to Use | Key Package |
-|---------|-------------|-------------|
-| Custom errors with `Object.setPrototypeOf` | Any TypeScript project | Built-in |
-| Error codes (enum) | Large projects needing error taxonomy | Built-in |
-| Crawlee error classes | Crawling frameworks | crawlee |
-| Error classifier | Retry logic | Custom |
-| Recovery suggestions | Self-healing systems | Custom |
-| TypedEmitter | Event-driven scrapers | emittery / eventemitter3 |
-| Lifecycle hooks | HTTP clients, scrapers | Custom / ky / ofetch |
-| Middleware pipelines | Request processing chains | Custom |
-| HookRegistry | Plugin systems | Custom |
-| Tree-shaking | Production bundles | tsconfig + package.json |