latency-lab 1.0.0

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/core.ts","../src/presets.ts","../src/express.ts","../src/next.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * How a simulated failure is expressed to the client.\n *\n * - `'http-error'`  — Respond with an HTTP error status code drawn from `errorCodes`.\n * - `'tcp-drop'`    — Approximate a TCP connection drop by destroying the socket\n *                     (Express) or returning a 503 (Next.js, where true socket\n *                     destruction is unavailable in App Router handlers).\n * - `'random'`      — Randomly choose between `'http-error'` and `'tcp-drop'`\n *                     each time a failure occurs.\n */\nexport type FailureType = 'http-error' | 'tcp-drop' | 'random';\n\n/**\n * Resolved failure type after `'random'` has been evaluated.\n * Never `'random'` — always a concrete action.\n */\nexport type ResolvedFailureType = Exclude<FailureType, 'random'>;\n\n/**\n * Core chaos configuration.\n *\n * All time values are in **milliseconds** unless otherwise noted.\n */\nexport interface ChaosOptions {\n  /**\n   * Base latency added to every request in milliseconds.\n   * Must be ≥ 0.\n   */\n  baseDelay: number;\n\n  /**\n   * Maximum magnitude of random jitter added to or subtracted from\n   * `baseDelay` in milliseconds. Must be ≥ 0.\n   *\n   * Actual jitter per request is sampled uniformly from `[-jitter, +jitter]`.\n   */\n  jitter: number;\n\n  /**\n   * Period of a sine-wave fluctuation applied on top of jitter, in **seconds**.\n   *\n   * This simulates slowly oscillating network quality (e.g., a roaming device\n   * moving in and out of signal). When omitted, no wave fluctuation is applied.\n   *\n   * Must be > 0 when provided.\n   */\n  wavePeriod?: number;\n\n  /**\n   * Probability that a given request results in a simulated failure.\n   * Must be in the range [0, 1].\n   *\n   * - `0`   → failures never occur\n   * - `1`   → every request fails\n   * - `0.1` → ~10% of requests fail\n   */\n  failureRate: number;\n\n  /**\n   * Determines how simulated failures are expressed to callers.\n   */\n  failureType: FailureType;\n\n  /**\n   * Pool of HTTP status codes to choose from when responding with an HTTP error.\n   * Must contain at least one entry.\n   *\n   * Only used when `failureType` resolves to `'http-error'`.\n   */\n  errorCodes: number[];\n}\n\n/**\n * Options passed to framework-level middleware / handler wrappers.\n * Extends `ChaosOptions` with request-filtering capabilities.\n */\nexport interface MiddlewareOptions extends ChaosOptions {\n  /**\n   * List of URL path prefixes that should bypass chaos injection entirely.\n   *\n   * Matching is prefix-based and case-sensitive.\n   *\n   * @example\n   * excludeRoutes: ['/health', '/metrics', '/_next']\n   */\n  excludeRoutes?: string[];\n}\n\n/**\n * Structured error thrown when a `ChaosOptions` or `MiddlewareOptions`\n * object fails validation.\n */\nexport class ChaosConfigError extends Error {\n  override readonly name = 'ChaosConfigError';\n\n  constructor(message: string) {\n    super(message);\n    // Maintain proper prototype chain in transpiled output\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n}\n","import { ChaosConfigError } from './types.js';\nimport type { ChaosOptions, ResolvedFailureType } from './types.js';\n\n// ---------------------------------------------------------------------------\n// Validation\n// ---------------------------------------------------------------------------\n\n/**\n * Validates a raw object as a `ChaosOptions`. Throws `ChaosConfigError`\n * with a descriptive message if any field is invalid or missing.\n *\n * This is the single source of truth for option validation — all public\n * entry-points (middleware factories, `withChaos`, etc.) should call this\n * before storing or using options.\n */\nexport function validateChaosOptions(options: unknown): ChaosOptions {\n  if (options === null || typeof options !== 'object') {\n    throw new ChaosConfigError('ChaosOptions must be a plain object.');\n  }\n\n  const o = options as Record<string, unknown>;\n\n  // --- baseDelay -----------------------------------------------------------\n  if (typeof o['baseDelay'] !== 'number' || !Number.isFinite(o['baseDelay'])) {\n    throw new ChaosConfigError(\n      `ChaosOptions.baseDelay must be a finite number, got: ${String(o['baseDelay'])}`,\n    );\n  }\n  if (o['baseDelay'] < 0) {\n    throw new ChaosConfigError(\n      `ChaosOptions.baseDelay must be ≥ 0, got: ${String(o['baseDelay'])}`,\n    );\n  }\n\n  // --- jitter --------------------------------------------------------------\n  if (typeof o['jitter'] !== 'number' || !Number.isFinite(o['jitter'])) {\n    throw new ChaosConfigError(\n      `ChaosOptions.jitter must be a finite number, got: ${String(o['jitter'])}`,\n    );\n  }\n  if (o['jitter'] < 0) {\n    throw new ChaosConfigError(\n      `ChaosOptions.jitter must be ≥ 0, got: ${String(o['jitter'])}`,\n    );\n  }\n\n  // --- wavePeriod (optional) -----------------------------------------------\n  if (o['wavePeriod'] !== undefined) {\n    if (typeof o['wavePeriod'] !== 'number' || !Number.isFinite(o['wavePeriod'])) {\n      throw new ChaosConfigError(\n        `ChaosOptions.wavePeriod must be a finite number when provided, got: ${String(o['wavePeriod'])}`,\n      );\n    }\n    if (o['wavePeriod'] <= 0) {\n      throw new ChaosConfigError(\n        `ChaosOptions.wavePeriod must be > 0 when provided, got: ${String(o['wavePeriod'])}`,\n      );\n    }\n  }\n\n  // --- failureRate ---------------------------------------------------------\n  if (typeof o['failureRate'] !== 'number' || !Number.isFinite(o['failureRate'])) {\n    throw new ChaosConfigError(\n      `ChaosOptions.failureRate must be a finite number, got: ${String(o['failureRate'])}`,\n    );\n  }\n  if (o['failureRate'] < 0 || o['failureRate'] > 1) {\n    throw new ChaosConfigError(\n      `ChaosOptions.failureRate must be in [0, 1], got: ${String(o['failureRate'])}`,\n    );\n  }\n\n  // --- failureType ---------------------------------------------------------\n  const validFailureTypes = new Set<string>(['http-error', 'tcp-drop', 'random']);\n  if (typeof o['failureType'] !== 'string' || !validFailureTypes.has(o['failureType'])) {\n    throw new ChaosConfigError(\n      `ChaosOptions.failureType must be one of \"http-error\" | \"tcp-drop\" | \"random\", ` +\n        `got: ${String(o['failureType'])}`,\n    );\n  }\n\n  // --- errorCodes ----------------------------------------------------------\n  if (!Array.isArray(o['errorCodes'])) {\n    throw new ChaosConfigError(\n      `ChaosOptions.errorCodes must be an array, got: ${typeof o['errorCodes']}`,\n    );\n  }\n  if (o['errorCodes'].length === 0) {\n    throw new ChaosConfigError(\n      'ChaosOptions.errorCodes must contain at least one HTTP status code.',\n    );\n  }\n  for (const code of o['errorCodes'] as unknown[]) {\n    if (typeof code !== 'number' || !Number.isInteger(code) || code < 100 || code > 599) {\n      throw new ChaosConfigError(\n        `ChaosOptions.errorCodes contains invalid HTTP status code: ${String(code)}. ` +\n          'Each code must be an integer in [100, 599].',\n      );\n    }\n  }\n\n  return {\n    baseDelay: o['baseDelay'] as number,\n    jitter: o['jitter'] as number,\n    ...(o['wavePeriod'] !== undefined ? { wavePeriod: o['wavePeriod'] as number } : {}),\n    failureRate: o['failureRate'] as number,\n    failureType: o['failureType'] as ChaosOptions['failureType'],\n    errorCodes: o['errorCodes'] as number[],\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Delay calculation\n// ---------------------------------------------------------------------------\n\n/**\n * Compute a realistic delay for a single request, in milliseconds.\n *\n * Formula:\n * ```\n * delay = baseDelay + randomJitter + waveFluctuation\n * ```\n *\n * - **randomJitter**: sampled uniformly from `[-jitter, +jitter]`\n * - **waveFluctuation**: `sin(t * 2π / wavePeriod) * jitter * 0.5` where\n *   `t = Date.now() / 1000` in seconds (zero when `wavePeriod` is omitted)\n * - Result is clamped to `≥ 0` (negative delays are meaningless)\n *\n * @param options - Validated `ChaosOptions`.\n * @returns Delay in milliseconds (always ≥ 0).\n */\nexport function calculateDelay(options: ChaosOptions): number {\n  const { baseDelay, jitter, wavePeriod } = options;\n\n  // Uniform random jitter: value in [-jitter, +jitter]\n  const randomJitter = (Math.random() * 2 - 1) * jitter;\n\n  // Sine-wave fluctuation — models slow oscillation in network quality\n  let waveFluctuation = 0;\n  if (wavePeriod !== undefined) {\n    const tSeconds = Date.now() / 1000;\n    const phase = (tSeconds * (2 * Math.PI)) / wavePeriod;\n    // Scale by half the jitter magnitude so the wave amplitude stays within\n    // the same order of magnitude as the random jitter component.\n    waveFluctuation = Math.sin(phase) * jitter * 0.5;\n  }\n\n  const raw = baseDelay + randomJitter + waveFluctuation;\n  return Math.max(0, raw);\n}\n\n// ---------------------------------------------------------------------------\n// Failure logic\n// ---------------------------------------------------------------------------\n\n/**\n * Returns `true` with probability `options.failureRate`.\n *\n * Uses `Math.random()` — suitable for non-cryptographic simulation purposes.\n *\n * @param options - Validated `ChaosOptions`.\n */\nexport function shouldFail(options: ChaosOptions): boolean {\n  if (options.failureRate === 0) return false;\n  if (options.failureRate === 1) return true;\n  return Math.random() < options.failureRate;\n}\n\n/**\n * Picks a random HTTP status code from `options.errorCodes`.\n *\n * Assumes `options.errorCodes` is non-empty (enforced by `validateChaosOptions`).\n *\n * @param options - Validated `ChaosOptions`.\n * @returns A status code from the configured pool.\n */\nexport function pickErrorCode(options: ChaosOptions): number {\n  const { errorCodes } = options;\n  if (errorCodes.length === 0) {\n    // Guard: this should never happen after validation, but we protect anyway.\n    throw new ChaosConfigError(\n      'Cannot pick an error code from an empty errorCodes array.',\n    );\n  }\n  const index = Math.floor(Math.random() * errorCodes.length);\n  // Non-null assertion is safe: index is always in [0, errorCodes.length - 1]\n  return errorCodes[index]!;\n}\n\n/**\n * Resolves the configured `failureType` to a concrete action.\n *\n * When `failureType` is `'random'`, randomly selects between `'http-error'`\n * and `'tcp-drop'` with equal probability.\n *\n * @param options - Validated `ChaosOptions`.\n * @returns A `ResolvedFailureType` — never `'random'`.\n */\nexport function resolveFailureType(options: ChaosOptions): ResolvedFailureType {\n  if (options.failureType === 'random') {\n    return Math.random() < 0.5 ? 'http-error' : 'tcp-drop';\n  }\n  return options.failureType;\n}\n\n// ---------------------------------------------------------------------------\n// Async utilities\n// ---------------------------------------------------------------------------\n\n/**\n * Non-blocking async sleep.\n *\n * Uses `setTimeout` under the hood — never busy-waits, never blocks the\n * event loop. Safe to `await` from any async context.\n *\n * @param ms - Duration to sleep in milliseconds. Values ≤ 0 resolve immediately.\n */\nexport function sleep(ms: number): Promise<void> {\n  if (ms <= 0) return Promise.resolve();\n  return new Promise<void>((resolve) => {\n    setTimeout(resolve, ms);\n  });\n}\n\n// ---------------------------------------------------------------------------\n// Route exclusion helper\n// ---------------------------------------------------------------------------\n\n/**\n * Returns `true` if the given URL path matches any of the excluded route\n * prefixes.\n *\n * Matching is prefix-based and case-sensitive. A trailing slash on the\n * prefix is not required — `/health` excludes `/health`, `/health/`, and\n * `/health/check`.\n *\n * @param pathname    - The incoming request path (e.g. `/api/users`).\n * @param excludeRoutes - Array of path prefixes to exclude.\n */\nexport function isExcluded(pathname: string, excludeRoutes: readonly string[]): boolean {\n  return excludeRoutes.some((prefix) => {\n    if (pathname === prefix) return true;\n    // Ensure we match the prefix at a path boundary\n    return pathname.startsWith(prefix.endsWith('/') ? prefix : `${prefix}/`) ||\n      pathname.startsWith(prefix);\n  });\n}\n","import type { ChaosOptions } from './types.js';\n\n// ---------------------------------------------------------------------------\n// Named network condition presets\n// ---------------------------------------------------------------------------\n\n/**\n * Simulates a subway tunnel or underground environment.\n *\n * Characteristics:\n * - Very high base latency\n * - Significant jitter (signal drops and recovers)\n * - Fast sine-wave cycle (8 s) — connection oscillates rapidly\n * - High failure rate with TCP drops (abrupt disconnection)\n */\nconst subwayTunnel: Readonly<ChaosOptions> = Object.freeze({\n  baseDelay: 800,\n  jitter: 600,\n  wavePeriod: 8,\n  failureRate: 0.2,\n  failureType: 'tcp-drop',\n  errorCodes: [503, 504],\n} satisfies ChaosOptions);\n\n/**\n * Simulates a flaky café Wi-Fi connection.\n *\n * Characteristics:\n * - Moderate base latency (mostly usable)\n * - High burst jitter (sudden quality drops)\n * - Medium wave period (20 s) — quality drifts slowly\n * - Low-to-moderate failure rate, mixed failure types\n */\nconst flakyCafeWifi: Readonly<ChaosOptions> = Object.freeze({\n  baseDelay: 150,\n  jitter: 300,\n  wavePeriod: 20,\n  failureRate: 0.08,\n  failureType: 'random',\n  errorCodes: [502, 503, 504],\n} satisfies ChaosOptions);\n\n/**\n * Simulates a classic slow 3G mobile connection.\n *\n * Characteristics:\n * - High base latency (~400 ms RTT)\n * - Low jitter (3G is slow but predictable)\n * - Long wave period (60 s) — signal quality shifts gradually\n * - Low failure rate, HTTP errors only (timeouts / service unavailable)\n */\nconst slow3g: Readonly<ChaosOptions> = Object.freeze({\n  baseDelay: 400,\n  jitter: 100,\n  wavePeriod: 60,\n  failureRate: 0.03,\n  failureType: 'http-error',\n  errorCodes: [408, 503],\n} satisfies ChaosOptions);\n\n/**\n * Simulates a heavily congested stadium or event venue network.\n *\n * Characteristics:\n * - High base latency (hundreds of users sharing bandwidth)\n * - Extremely high jitter (burst congestion causes wild swings)\n * - Very short wave period (5 s) — network quality ping-pongs rapidly\n * - Very high failure rate, all failure types possible\n */\nconst congestedStadium: Readonly<ChaosOptions> = Object.freeze({\n  baseDelay: 600,\n  jitter: 800,\n  wavePeriod: 5,\n  failureRate: 0.3,\n  failureType: 'random',\n  errorCodes: [429, 503, 504, 520],\n} satisfies ChaosOptions);\n\n/**\n * Collection of all built-in network chaos presets.\n *\n * All values are `readonly` — spread them to extend:\n *\n * @example\n * ```ts\n * import { presets } from 'latency-lab';\n *\n * const myOptions = {\n *   ...presets.slow3g,\n *   failureRate: 0.15,\n *   excludeRoutes: ['/health'],\n * };\n * ```\n */\nexport const presets = Object.freeze({\n  subwayTunnel,\n  flakyCafeWifi,\n  slow3g,\n  congestedStadium,\n} as const);\n\nexport type PresetName = keyof typeof presets;\n","/**\n * Express / Connect adapter for latency-lab.\n *\n * This module introduces zero runtime dependencies on Express. Types are\n * inlined so that `express` remains a peer / optional dependency — the\n * middleware works with any framework that honours the Connect signature:\n *\n *   (req: IncomingMessage, res: ServerResponse, next: (err?: unknown) => void) => void\n *\n * Usage:\n * ```ts\n * import express from 'express';\n * import { chaosMiddleware, presets } from 'latency-lab';\n *\n * const app = express();\n * app.use(chaosMiddleware(presets.flakyCafeWifi));\n * ```\n */\n\nimport type { IncomingMessage, ServerResponse } from 'node:http';\nimport type { Socket } from 'node:net';\nimport type { MiddlewareOptions } from './types.js';\nimport {\n  calculateDelay,\n  isExcluded,\n  pickErrorCode,\n  resolveFailureType,\n  shouldFail,\n  sleep,\n  validateChaosOptions,\n} from './core.js';\n\n// ---------------------------------------------------------------------------\n// Internal types\n// ---------------------------------------------------------------------------\n\n/**\n * Minimal Connect-compatible middleware signature.\n * Compatible with Express 4/5 and raw `node:http` middleware stacks.\n */\nexport type ConnectMiddleware = (\n  req: IncomingMessage,\n  res: ServerResponse,\n  next: (err?: unknown) => void,\n) => void;\n\n/**\n * Shape of a socket that optionally exposes `.destroy()`.\n * We avoid importing from `node:net` at the call-site to stay tree-shakeable.\n */\ntype DestroyableSocket = Socket & { destroyed: boolean };\n\n// ---------------------------------------------------------------------------\n// Helper — TCP drop approximation\n// ---------------------------------------------------------------------------\n\n/**\n * Approximates a TCP connection drop by destroying the underlying socket.\n *\n * **Limitations:**\n * - Calling `socket.destroy()` sends a TCP RST to the peer.\n * - Some HTTP clients (including Node's own `http.request`) will surface this\n *   as an `ECONNRESET` error and may retry automatically.\n * - HTTP/2 connections share a multiplexed socket — destroying it affects all\n *   streams, not just the current request.\n */\nfunction dropTcpConnection(res: ServerResponse): void {\n  const socket = res.socket as DestroyableSocket | null;\n  if (socket !== null && !socket.destroyed) {\n    socket.destroy();\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Helper — send HTTP error\n// ---------------------------------------------------------------------------\n\nfunction sendHttpError(res: ServerResponse, statusCode: number): void {\n  if (res.headersSent) return;\n  res.writeHead(statusCode, {\n    'Content-Type': 'application/json',\n    'X-Chaos-Injected': '1',\n  });\n  res.end(\n    JSON.stringify({\n      error: 'Chaos injected error',\n      status: statusCode,\n    }),\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Public factory\n// ---------------------------------------------------------------------------\n\n/**\n * Creates a Connect/Express-compatible chaos middleware.\n *\n * The middleware:\n * 1. Skips excluded routes immediately (calls `next()`).\n * 2. Calculates a realistic delay and `await`s it.\n * 3. Optionally injects a failure (HTTP error or TCP drop).\n * 4. Calls `next()` to hand off to the application for normal requests.\n *\n * @param options - Chaos configuration. Validated eagerly at factory time.\n * @returns A Connect-compatible middleware function.\n *\n * @example\n * ```ts\n * app.use(chaosMiddleware({\n *   baseDelay: 200,\n *   jitter: 80,\n *   failureRate: 0.05,\n *   failureType: 'http-error',\n *   errorCodes: [503],\n *   excludeRoutes: ['/health'],\n * }));\n * ```\n */\nexport function chaosMiddleware(options: MiddlewareOptions): ConnectMiddleware {\n  // Validate at factory time so misconfiguration surfaces immediately on\n  // startup rather than on the first request.\n  const validated = validateChaosOptions(options);\n  const excludeRoutes: readonly string[] = options.excludeRoutes ?? [];\n\n  const middleware: ConnectMiddleware = (req, res, next) => {\n    // Async work is wrapped in an IIFE so the middleware signature stays\n    // synchronous (required by Connect) while still using async/await internally.\n    (async (): Promise<void> => {\n      const pathname = req.url ?? '/';\n\n      // --- Route exclusion -------------------------------------------------\n      if (excludeRoutes.length > 0 && isExcluded(pathname, excludeRoutes)) {\n        next();\n        return;\n      }\n\n      // --- Delay injection -------------------------------------------------\n      const delay = calculateDelay(validated);\n      await sleep(delay);\n\n      // --- Failure injection -----------------------------------------------\n      if (shouldFail(validated)) {\n        const failureType = resolveFailureType(validated);\n\n        if (failureType === 'tcp-drop') {\n          dropTcpConnection(res);\n          return; // do NOT call next() — connection is gone\n        }\n\n        // failureType === 'http-error'\n        const statusCode = pickErrorCode(validated);\n        sendHttpError(res, statusCode);\n        return; // do NOT call next() — response already sent\n      }\n\n      // --- Pass through to application -------------------------------------\n      next();\n    })().catch((err: unknown) => {\n      // Surface unexpected errors to Express's error handler\n      next(err);\n    });\n  };\n\n  return middleware;\n}\n","/**\n * Next.js App Router adapter for latency-lab.\n *\n * Wraps App Router route handlers (`GET`, `POST`, etc.) with chaos injection.\n *\n * **TCP drop limitation:**\n * App Router handlers run in a higher-level abstraction — the raw socket is\n * not accessible inside a route handler. `tcp-drop` is therefore approximated\n * by returning a 503 response with an `X-Chaos-Tcp-Drop: 1` header so callers\n * can distinguish it from a real 503 during testing.\n *\n * Usage:\n * ```ts\n * // app/api/users/route.ts\n * import { withChaos, presets } from 'latency-lab/next';\n * import { NextRequest, NextResponse } from 'next/server';\n *\n * async function GET(_req: NextRequest): Promise<NextResponse> {\n *   return NextResponse.json({ users: [] });\n * }\n *\n * export const GET = withChaos(GET, presets.slow3g);\n * ```\n */\n\nimport type { MiddlewareOptions } from './types.js';\nimport {\n  calculateDelay,\n  isExcluded,\n  pickErrorCode,\n  resolveFailureType,\n  shouldFail,\n  sleep,\n  validateChaosOptions,\n} from './core.js';\n\n// ---------------------------------------------------------------------------\n// Minimal Next.js type stubs\n//\n// We deliberately avoid importing from 'next/server' so that `next` remains\n// a peer dependency. The shapes below are structurally compatible with the\n// real `NextRequest` / `NextResponse` from Next.js 14 and 15.\n// ---------------------------------------------------------------------------\n\n/**\n * Structural subset of `NextRequest` used internally.\n * Fully compatible with the real `NextRequest` from `next/server`.\n */\nexport interface NextRequestLike {\n  readonly url: string;\n  readonly method: string;\n  readonly headers: Headers;\n}\n\n/**\n * Structural subset of `NextResponse` used internally.\n * Fully compatible with the real `NextResponse` from `next/server`.\n */\nexport interface NextResponseLike extends Response {\n  readonly status: number;\n  readonly headers: Headers;\n}\n\n/**\n * A Next.js App Router route handler.\n *\n * The generic `Req` and `Res` parameters let callers use the real\n * `NextRequest` / `NextResponse` types without this library depending on them.\n */\nexport type NextRouteHandler<\n  Req extends NextRequestLike = NextRequestLike,\n  Res extends NextResponseLike = NextResponseLike,\n> = (req: Req, ctx?: unknown) => Promise<Res>;\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Builds a minimal JSON error Response compatible with `NextResponse.json()`.\n *\n * We construct a plain `Response` instead of calling `NextResponse.json()` to\n * avoid importing from `next/server` at runtime.\n */\nfunction buildErrorResponse(statusCode: number, headers?: HeadersInit): Response {\n  const body = JSON.stringify({\n    error: 'Chaos injected error',\n    status: statusCode,\n  });\n  const merged = new Headers(headers);\n  merged.set('Content-Type', 'application/json');\n  merged.set('X-Chaos-Injected', '1');\n  return new Response(body, { status: statusCode, headers: merged });\n}\n\n/**\n * Extracts the pathname from a URL string.\n * Falls back to the full string if parsing fails (non-standard environments).\n */\nfunction pathnameFrom(url: string): string {\n  try {\n    return new URL(url).pathname;\n  } catch {\n    // If the URL is relative or malformed, treat the whole value as the path\n    const questionMark = url.indexOf('?');\n    return questionMark === -1 ? url : url.slice(0, questionMark);\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Public factory\n// ---------------------------------------------------------------------------\n\n/**\n * Wraps a Next.js App Router route handler with chaos injection.\n *\n * The returned handler has the same signature as the original, so it can be\n * re-exported directly:\n *\n * ```ts\n * export const GET = withChaos(myHandler, presets.flakyCafeWifi);\n * ```\n *\n * Behaviour:\n * 1. Routes matching `excludeRoutes` are passed through immediately.\n * 2. A realistic delay is injected via `sleep()`.\n * 3. When a failure is triggered:\n *    - `'http-error'` → returns a Response with a status from `errorCodes`\n *    - `'tcp-drop'`   → returns a 503 with `X-Chaos-Tcp-Drop: 1` (limitation noted above)\n * 4. Otherwise, the original handler is called and its response is returned.\n *\n * @param handler - The original App Router route handler.\n * @param options - Chaos configuration. Validated eagerly.\n * @returns A wrapped handler with the same signature.\n */\nexport function withChaos<\n  Req extends NextRequestLike,\n  Res extends NextResponseLike,\n>(\n  handler: NextRouteHandler<Req, Res>,\n  options: MiddlewareOptions,\n): NextRouteHandler<Req, Res> {\n  // Validate at wrap time so misconfiguration fails fast at module load,\n  // not on the first incoming request.\n  const validated = validateChaosOptions(options);\n  const excludeRoutes: readonly string[] = options.excludeRoutes ?? [];\n\n  return async (req: Req, ctx?: unknown): Promise<Res> => {\n    const pathname = pathnameFrom(req.url);\n\n    // --- Route exclusion ---------------------------------------------------\n    if (excludeRoutes.length > 0 && isExcluded(pathname, excludeRoutes)) {\n      return handler(req, ctx);\n    }\n\n    // --- Delay injection ---------------------------------------------------\n    const delay = calculateDelay(validated);\n    await sleep(delay);\n\n    // --- Failure injection -------------------------------------------------\n    if (shouldFail(validated)) {\n      const failureType = resolveFailureType(validated);\n\n      if (failureType === 'tcp-drop') {\n        // True TCP drop is not possible inside an App Router handler.\n        // We approximate it with a 503 and a marker header so test suites\n        // can detect the simulated drop.\n        return buildErrorResponse(503, {\n          'X-Chaos-Tcp-Drop': '1',\n        }) as unknown as Res;\n      }\n\n      // failureType === 'http-error'\n      const statusCode = pickErrorCode(validated);\n      return buildErrorResponse(statusCode) as unknown as Res;\n    }\n\n    // --- Delegate to original handler -------------------------------------\n    return handler(req, ctx);\n  };\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,6 @@
+export { ChaosConfigError, ChaosOptions, FailureType, MiddlewareOptions, ResolvedFailureType } from './types.cjs';
+export { calculateDelay, isExcluded, pickErrorCode, resolveFailureType, shouldFail, sleep, validateChaosOptions } from './core.cjs';
+export { PresetName, presets } from './presets.cjs';
+export { ConnectMiddleware, chaosMiddleware } from './express.cjs';
+export { NextRequestLike, NextResponseLike, NextRouteHandler, withChaos } from './next.cjs';
+import 'node:http';

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { ChaosConfigError, ChaosOptions, FailureType, MiddlewareOptions, ResolvedFailureType } from './types.js';
+export { calculateDelay, isExcluded, pickErrorCode, resolveFailureType, shouldFail, sleep, validateChaosOptions } from './core.js';
+export { PresetName, presets } from './presets.js';
+export { ConnectMiddleware, chaosMiddleware } from './express.js';
+export { NextRequestLike, NextResponseLike, NextRouteHandler, withChaos } from './next.js';
+import 'node:http';

package/dist/index.js

@@ -0,0 +1,271 @@
+// src/types.ts
+var ChaosConfigError = class extends Error {
+  name = "ChaosConfigError";
+  constructor(message) {
+    super(message);
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/core.ts
+function validateChaosOptions(options) {
+  if (options === null || typeof options !== "object") {
+    throw new ChaosConfigError("ChaosOptions must be a plain object.");
+  }
+  const o = options;
+  if (typeof o["baseDelay"] !== "number" || !Number.isFinite(o["baseDelay"])) {
+    throw new ChaosConfigError(
+      `ChaosOptions.baseDelay must be a finite number, got: ${String(o["baseDelay"])}`
+    );
+  }
+  if (o["baseDelay"] < 0) {
+    throw new ChaosConfigError(
+      `ChaosOptions.baseDelay must be \u2265 0, got: ${String(o["baseDelay"])}`
+    );
+  }
+  if (typeof o["jitter"] !== "number" || !Number.isFinite(o["jitter"])) {
+    throw new ChaosConfigError(
+      `ChaosOptions.jitter must be a finite number, got: ${String(o["jitter"])}`
+    );
+  }
+  if (o["jitter"] < 0) {
+    throw new ChaosConfigError(
+      `ChaosOptions.jitter must be \u2265 0, got: ${String(o["jitter"])}`
+    );
+  }
+  if (o["wavePeriod"] !== void 0) {
+    if (typeof o["wavePeriod"] !== "number" || !Number.isFinite(o["wavePeriod"])) {
+      throw new ChaosConfigError(
+        `ChaosOptions.wavePeriod must be a finite number when provided, got: ${String(o["wavePeriod"])}`
+      );
+    }
+    if (o["wavePeriod"] <= 0) {
+      throw new ChaosConfigError(
+        `ChaosOptions.wavePeriod must be > 0 when provided, got: ${String(o["wavePeriod"])}`
+      );
+    }
+  }
+  if (typeof o["failureRate"] !== "number" || !Number.isFinite(o["failureRate"])) {
+    throw new ChaosConfigError(
+      `ChaosOptions.failureRate must be a finite number, got: ${String(o["failureRate"])}`
+    );
+  }
+  if (o["failureRate"] < 0 || o["failureRate"] > 1) {
+    throw new ChaosConfigError(
+      `ChaosOptions.failureRate must be in [0, 1], got: ${String(o["failureRate"])}`
+    );
+  }
+  const validFailureTypes = /* @__PURE__ */ new Set(["http-error", "tcp-drop", "random"]);
+  if (typeof o["failureType"] !== "string" || !validFailureTypes.has(o["failureType"])) {
+    throw new ChaosConfigError(
+      `ChaosOptions.failureType must be one of "http-error" | "tcp-drop" | "random", got: ${String(o["failureType"])}`
+    );
+  }
+  if (!Array.isArray(o["errorCodes"])) {
+    throw new ChaosConfigError(
+      `ChaosOptions.errorCodes must be an array, got: ${typeof o["errorCodes"]}`
+    );
+  }
+  if (o["errorCodes"].length === 0) {
+    throw new ChaosConfigError(
+      "ChaosOptions.errorCodes must contain at least one HTTP status code."
+    );
+  }
+  for (const code of o["errorCodes"]) {
+    if (typeof code !== "number" || !Number.isInteger(code) || code < 100 || code > 599) {
+      throw new ChaosConfigError(
+        `ChaosOptions.errorCodes contains invalid HTTP status code: ${String(code)}. Each code must be an integer in [100, 599].`
+      );
+    }
+  }
+  return {
+    baseDelay: o["baseDelay"],
+    jitter: o["jitter"],
+    ...o["wavePeriod"] !== void 0 ? { wavePeriod: o["wavePeriod"] } : {},
+    failureRate: o["failureRate"],
+    failureType: o["failureType"],
+    errorCodes: o["errorCodes"]
+  };
+}
+function calculateDelay(options) {
+  const { baseDelay, jitter, wavePeriod } = options;
+  const randomJitter = (Math.random() * 2 - 1) * jitter;
+  let waveFluctuation = 0;
+  if (wavePeriod !== void 0) {
+    const tSeconds = Date.now() / 1e3;
+    const phase = tSeconds * (2 * Math.PI) / wavePeriod;
+    waveFluctuation = Math.sin(phase) * jitter * 0.5;
+  }
+  const raw = baseDelay + randomJitter + waveFluctuation;
+  return Math.max(0, raw);
+}
+function shouldFail(options) {
+  if (options.failureRate === 0) return false;
+  if (options.failureRate === 1) return true;
+  return Math.random() < options.failureRate;
+}
+function pickErrorCode(options) {
+  const { errorCodes } = options;
+  if (errorCodes.length === 0) {
+    throw new ChaosConfigError(
+      "Cannot pick an error code from an empty errorCodes array."
+    );
+  }
+  const index = Math.floor(Math.random() * errorCodes.length);
+  return errorCodes[index];
+}
+function resolveFailureType(options) {
+  if (options.failureType === "random") {
+    return Math.random() < 0.5 ? "http-error" : "tcp-drop";
+  }
+  return options.failureType;
+}
+function sleep(ms) {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+function isExcluded(pathname, excludeRoutes) {
+  return excludeRoutes.some((prefix) => {
+    if (pathname === prefix) return true;
+    return pathname.startsWith(prefix.endsWith("/") ? prefix : `${prefix}/`) || pathname.startsWith(prefix);
+  });
+}
+
+// src/presets.ts
+var subwayTunnel = Object.freeze({
+  baseDelay: 800,
+  jitter: 600,
+  wavePeriod: 8,
+  failureRate: 0.2,
+  failureType: "tcp-drop",
+  errorCodes: [503, 504]
+});
+var flakyCafeWifi = Object.freeze({
+  baseDelay: 150,
+  jitter: 300,
+  wavePeriod: 20,
+  failureRate: 0.08,
+  failureType: "random",
+  errorCodes: [502, 503, 504]
+});
+var slow3g = Object.freeze({
+  baseDelay: 400,
+  jitter: 100,
+  wavePeriod: 60,
+  failureRate: 0.03,
+  failureType: "http-error",
+  errorCodes: [408, 503]
+});
+var congestedStadium = Object.freeze({
+  baseDelay: 600,
+  jitter: 800,
+  wavePeriod: 5,
+  failureRate: 0.3,
+  failureType: "random",
+  errorCodes: [429, 503, 504, 520]
+});
+var presets = Object.freeze({
+  subwayTunnel,
+  flakyCafeWifi,
+  slow3g,
+  congestedStadium
+});
+
+// src/express.ts
+function dropTcpConnection(res) {
+  const socket = res.socket;
+  if (socket !== null && !socket.destroyed) {
+    socket.destroy();
+  }
+}
+function sendHttpError(res, statusCode) {
+  if (res.headersSent) return;
+  res.writeHead(statusCode, {
+    "Content-Type": "application/json",
+    "X-Chaos-Injected": "1"
+  });
+  res.end(
+    JSON.stringify({
+      error: "Chaos injected error",
+      status: statusCode
+    })
+  );
+}
+function chaosMiddleware(options) {
+  const validated = validateChaosOptions(options);
+  const excludeRoutes = options.excludeRoutes ?? [];
+  const middleware = (req, res, next) => {
+    (async () => {
+      const pathname = req.url ?? "/";
+      if (excludeRoutes.length > 0 && isExcluded(pathname, excludeRoutes)) {
+        next();
+        return;
+      }
+      const delay = calculateDelay(validated);
+      await sleep(delay);
+      if (shouldFail(validated)) {
+        const failureType = resolveFailureType(validated);
+        if (failureType === "tcp-drop") {
+          dropTcpConnection(res);
+          return;
+        }
+        const statusCode = pickErrorCode(validated);
+        sendHttpError(res, statusCode);
+        return;
+      }
+      next();
+    })().catch((err) => {
+      next(err);
+    });
+  };
+  return middleware;
+}
+
+// src/next.ts
+function buildErrorResponse(statusCode, headers) {
+  const body = JSON.stringify({
+    error: "Chaos injected error",
+    status: statusCode
+  });
+  const merged = new Headers(headers);
+  merged.set("Content-Type", "application/json");
+  merged.set("X-Chaos-Injected", "1");
+  return new Response(body, { status: statusCode, headers: merged });
+}
+function pathnameFrom(url) {
+  try {
+    return new URL(url).pathname;
+  } catch {
+    const questionMark = url.indexOf("?");
+    return questionMark === -1 ? url : url.slice(0, questionMark);
+  }
+}
+function withChaos(handler, options) {
+  const validated = validateChaosOptions(options);
+  const excludeRoutes = options.excludeRoutes ?? [];
+  return async (req, ctx) => {
+    const pathname = pathnameFrom(req.url);
+    if (excludeRoutes.length > 0 && isExcluded(pathname, excludeRoutes)) {
+      return handler(req, ctx);
+    }
+    const delay = calculateDelay(validated);
+    await sleep(delay);
+    if (shouldFail(validated)) {
+      const failureType = resolveFailureType(validated);
+      if (failureType === "tcp-drop") {
+        return buildErrorResponse(503, {
+          "X-Chaos-Tcp-Drop": "1"
+        });
+      }
+      const statusCode = pickErrorCode(validated);
+      return buildErrorResponse(statusCode);
+    }
+    return handler(req, ctx);
+  };
+}
+
+export { ChaosConfigError, calculateDelay, chaosMiddleware, isExcluded, pickErrorCode, presets, resolveFailureType, shouldFail, sleep, validateChaosOptions, withChaos };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/core.ts","../src/presets.ts","../src/express.ts","../src/next.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * How a simulated failure is expressed to the client.\n *\n * - `'http-error'`  — Respond with an HTTP error status code drawn from `errorCodes`.\n * - `'tcp-drop'`    — Approximate a TCP connection drop by destroying the socket\n *                     (Express) or returning a 503 (Next.js, where true socket\n *                     destruction is unavailable in App Router handlers).\n * - `'random'`      — Randomly choose between `'http-error'` and `'tcp-drop'`\n *                     each time a failure occurs.\n */\nexport type FailureType = 'http-error' | 'tcp-drop' | 'random';\n\n/**\n * Resolved failure type after `'random'` has been evaluated.\n * Never `'random'` — always a concrete action.\n */\nexport type ResolvedFailureType = Exclude<FailureType, 'random'>;\n\n/**\n * Core chaos configuration.\n *\n * All time values are in **milliseconds** unless otherwise noted.\n */\nexport interface ChaosOptions {\n  /**\n   * Base latency added to every request in milliseconds.\n   * Must be ≥ 0.\n   */\n  baseDelay: number;\n\n  /**\n   * Maximum magnitude of random jitter added to or subtracted from\n   * `baseDelay` in milliseconds. Must be ≥ 0.\n   *\n   * Actual jitter per request is sampled uniformly from `[-jitter, +jitter]`.\n   */\n  jitter: number;\n\n  /**\n   * Period of a sine-wave fluctuation applied on top of jitter, in **seconds**.\n   *\n   * This simulates slowly oscillating network quality (e.g., a roaming device\n   * moving in and out of signal). When omitted, no wave fluctuation is applied.\n   *\n   * Must be > 0 when provided.\n   */\n  wavePeriod?: number;\n\n  /**\n   * Probability that a given request results in a simulated failure.\n   * Must be in the range [0, 1].\n   *\n   * - `0`   → failures never occur\n   * - `1`   → every request fails\n   * - `0.1` → ~10% of requests fail\n   */\n  failureRate: number;\n\n  /**\n   * Determines how simulated failures are expressed to callers.\n   */\n  failureType: FailureType;\n\n  /**\n   * Pool of HTTP status codes to choose from when responding with an HTTP error.\n   * Must contain at least one entry.\n   *\n   * Only used when `failureType` resolves to `'http-error'`.\n   */\n  errorCodes: number[];\n}\n\n/**\n * Options passed to framework-level middleware / handler wrappers.\n * Extends `ChaosOptions` with request-filtering capabilities.\n */\nexport interface MiddlewareOptions extends ChaosOptions {\n  /**\n   * List of URL path prefixes that should bypass chaos injection entirely.\n   *\n   * Matching is prefix-based and case-sensitive.\n   *\n   * @example\n   * excludeRoutes: ['/health', '/metrics', '/_next']\n   */\n  excludeRoutes?: string[];\n}\n\n/**\n * Structured error thrown when a `ChaosOptions` or `MiddlewareOptions`\n * object fails validation.\n */\nexport class ChaosConfigError extends Error {\n  override readonly name = 'ChaosConfigError';\n\n  constructor(message: string) {\n    super(message);\n    // Maintain proper prototype chain in transpiled output\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n}\n","import { ChaosConfigError } from './types.js';\nimport type { ChaosOptions, ResolvedFailureType } from './types.js';\n\n// ---------------------------------------------------------------------------\n// Validation\n// ---------------------------------------------------------------------------\n\n/**\n * Validates a raw object as a `ChaosOptions`. Throws `ChaosConfigError`\n * with a descriptive message if any field is invalid or missing.\n *\n * This is the single source of truth for option validation — all public\n * entry-points (middleware factories, `withChaos`, etc.) should call this\n * before storing or using options.\n */\nexport function validateChaosOptions(options: unknown): ChaosOptions {\n  if (options === null || typeof options !== 'object') {\n    throw new ChaosConfigError('ChaosOptions must be a plain object.');\n  }\n\n  const o = options as Record<string, unknown>;\n\n  // --- baseDelay -----------------------------------------------------------\n  if (typeof o['baseDelay'] !== 'number' || !Number.isFinite(o['baseDelay'])) {\n    throw new ChaosConfigError(\n      `ChaosOptions.baseDelay must be a finite number, got: ${String(o['baseDelay'])}`,\n    );\n  }\n  if (o['baseDelay'] < 0) {\n    throw new ChaosConfigError(\n      `ChaosOptions.baseDelay must be ≥ 0, got: ${String(o['baseDelay'])}`,\n    );\n  }\n\n  // --- jitter --------------------------------------------------------------\n  if (typeof o['jitter'] !== 'number' || !Number.isFinite(o['jitter'])) {\n    throw new ChaosConfigError(\n      `ChaosOptions.jitter must be a finite number, got: ${String(o['jitter'])}`,\n    );\n  }\n  if (o['jitter'] < 0) {\n    throw new ChaosConfigError(\n      `ChaosOptions.jitter must be ≥ 0, got: ${String(o['jitter'])}`,\n    );\n  }\n\n  // --- wavePeriod (optional) -----------------------------------------------\n  if (o['wavePeriod'] !== undefined) {\n    if (typeof o['wavePeriod'] !== 'number' || !Number.isFinite(o['wavePeriod'])) {\n      throw new ChaosConfigError(\n        `ChaosOptions.wavePeriod must be a finite number when provided, got: ${String(o['wavePeriod'])}`,\n      );\n    }\n    if (o['wavePeriod'] <= 0) {\n      throw new ChaosConfigError(\n        `ChaosOptions.wavePeriod must be > 0 when provided, got: ${String(o['wavePeriod'])}`,\n      );\n    }\n  }\n\n  // --- failureRate ---------------------------------------------------------\n  if (typeof o['failureRate'] !== 'number' || !Number.isFinite(o['failureRate'])) {\n    throw new ChaosConfigError(\n      `ChaosOptions.failureRate must be a finite number, got: ${String(o['failureRate'])}`,\n    );\n  }\n  if (o['failureRate'] < 0 || o['failureRate'] > 1) {\n    throw new ChaosConfigError(\n      `ChaosOptions.failureRate must be in [0, 1], got: ${String(o['failureRate'])}`,\n    );\n  }\n\n  // --- failureType ---------------------------------------------------------\n  const validFailureTypes = new Set<string>(['http-error', 'tcp-drop', 'random']);\n  if (typeof o['failureType'] !== 'string' || !validFailureTypes.has(o['failureType'])) {\n    throw new ChaosConfigError(\n      `ChaosOptions.failureType must be one of \"http-error\" | \"tcp-drop\" | \"random\", ` +\n        `got: ${String(o['failureType'])}`,\n    );\n  }\n\n  // --- errorCodes ----------------------------------------------------------\n  if (!Array.isArray(o['errorCodes'])) {\n    throw new ChaosConfigError(\n      `ChaosOptions.errorCodes must be an array, got: ${typeof o['errorCodes']}`,\n    );\n  }\n  if (o['errorCodes'].length === 0) {\n    throw new ChaosConfigError(\n      'ChaosOptions.errorCodes must contain at least one HTTP status code.',\n    );\n  }\n  for (const code of o['errorCodes'] as unknown[]) {\n    if (typeof code !== 'number' || !Number.isInteger(code) || code < 100 || code > 599) {\n      throw new ChaosConfigError(\n        `ChaosOptions.errorCodes contains invalid HTTP status code: ${String(code)}. ` +\n          'Each code must be an integer in [100, 599].',\n      );\n    }\n  }\n\n  return {\n    baseDelay: o['baseDelay'] as number,\n    jitter: o['jitter'] as number,\n    ...(o['wavePeriod'] !== undefined ? { wavePeriod: o['wavePeriod'] as number } : {}),\n    failureRate: o['failureRate'] as number,\n    failureType: o['failureType'] as ChaosOptions['failureType'],\n    errorCodes: o['errorCodes'] as number[],\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Delay calculation\n// ---------------------------------------------------------------------------\n\n/**\n * Compute a realistic delay for a single request, in milliseconds.\n *\n * Formula:\n * ```\n * delay = baseDelay + randomJitter + waveFluctuation\n * ```\n *\n * - **randomJitter**: sampled uniformly from `[-jitter, +jitter]`\n * - **waveFluctuation**: `sin(t * 2π / wavePeriod) * jitter * 0.5` where\n *   `t = Date.now() / 1000` in seconds (zero when `wavePeriod` is omitted)\n * - Result is clamped to `≥ 0` (negative delays are meaningless)\n *\n * @param options - Validated `ChaosOptions`.\n * @returns Delay in milliseconds (always ≥ 0).\n */\nexport function calculateDelay(options: ChaosOptions): number {\n  const { baseDelay, jitter, wavePeriod } = options;\n\n  // Uniform random jitter: value in [-jitter, +jitter]\n  const randomJitter = (Math.random() * 2 - 1) * jitter;\n\n  // Sine-wave fluctuation — models slow oscillation in network quality\n  let waveFluctuation = 0;\n  if (wavePeriod !== undefined) {\n    const tSeconds = Date.now() / 1000;\n    const phase = (tSeconds * (2 * Math.PI)) / wavePeriod;\n    // Scale by half the jitter magnitude so the wave amplitude stays within\n    // the same order of magnitude as the random jitter component.\n    waveFluctuation = Math.sin(phase) * jitter * 0.5;\n  }\n\n  const raw = baseDelay + randomJitter + waveFluctuation;\n  return Math.max(0, raw);\n}\n\n// ---------------------------------------------------------------------------\n// Failure logic\n// ---------------------------------------------------------------------------\n\n/**\n * Returns `true` with probability `options.failureRate`.\n *\n * Uses `Math.random()` — suitable for non-cryptographic simulation purposes.\n *\n * @param options - Validated `ChaosOptions`.\n */\nexport function shouldFail(options: ChaosOptions): boolean {\n  if (options.failureRate === 0) return false;\n  if (options.failureRate === 1) return true;\n  return Math.random() < options.failureRate;\n}\n\n/**\n * Picks a random HTTP status code from `options.errorCodes`.\n *\n * Assumes `options.errorCodes` is non-empty (enforced by `validateChaosOptions`).\n *\n * @param options - Validated `ChaosOptions`.\n * @returns A status code from the configured pool.\n */\nexport function pickErrorCode(options: ChaosOptions): number {\n  const { errorCodes } = options;\n  if (errorCodes.length === 0) {\n    // Guard: this should never happen after validation, but we protect anyway.\n    throw new ChaosConfigError(\n      'Cannot pick an error code from an empty errorCodes array.',\n    );\n  }\n  const index = Math.floor(Math.random() * errorCodes.length);\n  // Non-null assertion is safe: index is always in [0, errorCodes.length - 1]\n  return errorCodes[index]!;\n}\n\n/**\n * Resolves the configured `failureType` to a concrete action.\n *\n * When `failureType` is `'random'`, randomly selects between `'http-error'`\n * and `'tcp-drop'` with equal probability.\n *\n * @param options - Validated `ChaosOptions`.\n * @returns A `ResolvedFailureType` — never `'random'`.\n */\nexport function resolveFailureType(options: ChaosOptions): ResolvedFailureType {\n  if (options.failureType === 'random') {\n    return Math.random() < 0.5 ? 'http-error' : 'tcp-drop';\n  }\n  return options.failureType;\n}\n\n// ---------------------------------------------------------------------------\n// Async utilities\n// ---------------------------------------------------------------------------\n\n/**\n * Non-blocking async sleep.\n *\n * Uses `setTimeout` under the hood — never busy-waits, never blocks the\n * event loop. Safe to `await` from any async context.\n *\n * @param ms - Duration to sleep in milliseconds. Values ≤ 0 resolve immediately.\n */\nexport function sleep(ms: number): Promise<void> {\n  if (ms <= 0) return Promise.resolve();\n  return new Promise<void>((resolve) => {\n    setTimeout(resolve, ms);\n  });\n}\n\n// ---------------------------------------------------------------------------\n// Route exclusion helper\n// ---------------------------------------------------------------------------\n\n/**\n * Returns `true` if the given URL path matches any of the excluded route\n * prefixes.\n *\n * Matching is prefix-based and case-sensitive. A trailing slash on the\n * prefix is not required — `/health` excludes `/health`, `/health/`, and\n * `/health/check`.\n *\n * @param pathname    - The incoming request path (e.g. `/api/users`).\n * @param excludeRoutes - Array of path prefixes to exclude.\n */\nexport function isExcluded(pathname: string, excludeRoutes: readonly string[]): boolean {\n  return excludeRoutes.some((prefix) => {\n    if (pathname === prefix) return true;\n    // Ensure we match the prefix at a path boundary\n    return pathname.startsWith(prefix.endsWith('/') ? prefix : `${prefix}/`) ||\n      pathname.startsWith(prefix);\n  });\n}\n","import type { ChaosOptions } from './types.js';\n\n// ---------------------------------------------------------------------------\n// Named network condition presets\n// ---------------------------------------------------------------------------\n\n/**\n * Simulates a subway tunnel or underground environment.\n *\n * Characteristics:\n * - Very high base latency\n * - Significant jitter (signal drops and recovers)\n * - Fast sine-wave cycle (8 s) — connection oscillates rapidly\n * - High failure rate with TCP drops (abrupt disconnection)\n */\nconst subwayTunnel: Readonly<ChaosOptions> = Object.freeze({\n  baseDelay: 800,\n  jitter: 600,\n  wavePeriod: 8,\n  failureRate: 0.2,\n  failureType: 'tcp-drop',\n  errorCodes: [503, 504],\n} satisfies ChaosOptions);\n\n/**\n * Simulates a flaky café Wi-Fi connection.\n *\n * Characteristics:\n * - Moderate base latency (mostly usable)\n * - High burst jitter (sudden quality drops)\n * - Medium wave period (20 s) — quality drifts slowly\n * - Low-to-moderate failure rate, mixed failure types\n */\nconst flakyCafeWifi: Readonly<ChaosOptions> = Object.freeze({\n  baseDelay: 150,\n  jitter: 300,\n  wavePeriod: 20,\n  failureRate: 0.08,\n  failureType: 'random',\n  errorCodes: [502, 503, 504],\n} satisfies ChaosOptions);\n\n/**\n * Simulates a classic slow 3G mobile connection.\n *\n * Characteristics:\n * - High base latency (~400 ms RTT)\n * - Low jitter (3G is slow but predictable)\n * - Long wave period (60 s) — signal quality shifts gradually\n * - Low failure rate, HTTP errors only (timeouts / service unavailable)\n */\nconst slow3g: Readonly<ChaosOptions> = Object.freeze({\n  baseDelay: 400,\n  jitter: 100,\n  wavePeriod: 60,\n  failureRate: 0.03,\n  failureType: 'http-error',\n  errorCodes: [408, 503],\n} satisfies ChaosOptions);\n\n/**\n * Simulates a heavily congested stadium or event venue network.\n *\n * Characteristics:\n * - High base latency (hundreds of users sharing bandwidth)\n * - Extremely high jitter (burst congestion causes wild swings)\n * - Very short wave period (5 s) — network quality ping-pongs rapidly\n * - Very high failure rate, all failure types possible\n */\nconst congestedStadium: Readonly<ChaosOptions> = Object.freeze({\n  baseDelay: 600,\n  jitter: 800,\n  wavePeriod: 5,\n  failureRate: 0.3,\n  failureType: 'random',\n  errorCodes: [429, 503, 504, 520],\n} satisfies ChaosOptions);\n\n/**\n * Collection of all built-in network chaos presets.\n *\n * All values are `readonly` — spread them to extend:\n *\n * @example\n * ```ts\n * import { presets } from 'latency-lab';\n *\n * const myOptions = {\n *   ...presets.slow3g,\n *   failureRate: 0.15,\n *   excludeRoutes: ['/health'],\n * };\n * ```\n */\nexport const presets = Object.freeze({\n  subwayTunnel,\n  flakyCafeWifi,\n  slow3g,\n  congestedStadium,\n} as const);\n\nexport type PresetName = keyof typeof presets;\n","/**\n * Express / Connect adapter for latency-lab.\n *\n * This module introduces zero runtime dependencies on Express. Types are\n * inlined so that `express` remains a peer / optional dependency — the\n * middleware works with any framework that honours the Connect signature:\n *\n *   (req: IncomingMessage, res: ServerResponse, next: (err?: unknown) => void) => void\n *\n * Usage:\n * ```ts\n * import express from 'express';\n * import { chaosMiddleware, presets } from 'latency-lab';\n *\n * const app = express();\n * app.use(chaosMiddleware(presets.flakyCafeWifi));\n * ```\n */\n\nimport type { IncomingMessage, ServerResponse } from 'node:http';\nimport type { Socket } from 'node:net';\nimport type { MiddlewareOptions } from './types.js';\nimport {\n  calculateDelay,\n  isExcluded,\n  pickErrorCode,\n  resolveFailureType,\n  shouldFail,\n  sleep,\n  validateChaosOptions,\n} from './core.js';\n\n// ---------------------------------------------------------------------------\n// Internal types\n// ---------------------------------------------------------------------------\n\n/**\n * Minimal Connect-compatible middleware signature.\n * Compatible with Express 4/5 and raw `node:http` middleware stacks.\n */\nexport type ConnectMiddleware = (\n  req: IncomingMessage,\n  res: ServerResponse,\n  next: (err?: unknown) => void,\n) => void;\n\n/**\n * Shape of a socket that optionally exposes `.destroy()`.\n * We avoid importing from `node:net` at the call-site to stay tree-shakeable.\n */\ntype DestroyableSocket = Socket & { destroyed: boolean };\n\n// ---------------------------------------------------------------------------\n// Helper — TCP drop approximation\n// ---------------------------------------------------------------------------\n\n/**\n * Approximates a TCP connection drop by destroying the underlying socket.\n *\n * **Limitations:**\n * - Calling `socket.destroy()` sends a TCP RST to the peer.\n * - Some HTTP clients (including Node's own `http.request`) will surface this\n *   as an `ECONNRESET` error and may retry automatically.\n * - HTTP/2 connections share a multiplexed socket — destroying it affects all\n *   streams, not just the current request.\n */\nfunction dropTcpConnection(res: ServerResponse): void {\n  const socket = res.socket as DestroyableSocket | null;\n  if (socket !== null && !socket.destroyed) {\n    socket.destroy();\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Helper — send HTTP error\n// ---------------------------------------------------------------------------\n\nfunction sendHttpError(res: ServerResponse, statusCode: number): void {\n  if (res.headersSent) return;\n  res.writeHead(statusCode, {\n    'Content-Type': 'application/json',\n    'X-Chaos-Injected': '1',\n  });\n  res.end(\n    JSON.stringify({\n      error: 'Chaos injected error',\n      status: statusCode,\n    }),\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Public factory\n// ---------------------------------------------------------------------------\n\n/**\n * Creates a Connect/Express-compatible chaos middleware.\n *\n * The middleware:\n * 1. Skips excluded routes immediately (calls `next()`).\n * 2. Calculates a realistic delay and `await`s it.\n * 3. Optionally injects a failure (HTTP error or TCP drop).\n * 4. Calls `next()` to hand off to the application for normal requests.\n *\n * @param options - Chaos configuration. Validated eagerly at factory time.\n * @returns A Connect-compatible middleware function.\n *\n * @example\n * ```ts\n * app.use(chaosMiddleware({\n *   baseDelay: 200,\n *   jitter: 80,\n *   failureRate: 0.05,\n *   failureType: 'http-error',\n *   errorCodes: [503],\n *   excludeRoutes: ['/health'],\n * }));\n * ```\n */\nexport function chaosMiddleware(options: MiddlewareOptions): ConnectMiddleware {\n  // Validate at factory time so misconfiguration surfaces immediately on\n  // startup rather than on the first request.\n  const validated = validateChaosOptions(options);\n  const excludeRoutes: readonly string[] = options.excludeRoutes ?? [];\n\n  const middleware: ConnectMiddleware = (req, res, next) => {\n    // Async work is wrapped in an IIFE so the middleware signature stays\n    // synchronous (required by Connect) while still using async/await internally.\n    (async (): Promise<void> => {\n      const pathname = req.url ?? '/';\n\n      // --- Route exclusion -------------------------------------------------\n      if (excludeRoutes.length > 0 && isExcluded(pathname, excludeRoutes)) {\n        next();\n        return;\n      }\n\n      // --- Delay injection -------------------------------------------------\n      const delay = calculateDelay(validated);\n      await sleep(delay);\n\n      // --- Failure injection -----------------------------------------------\n      if (shouldFail(validated)) {\n        const failureType = resolveFailureType(validated);\n\n        if (failureType === 'tcp-drop') {\n          dropTcpConnection(res);\n          return; // do NOT call next() — connection is gone\n        }\n\n        // failureType === 'http-error'\n        const statusCode = pickErrorCode(validated);\n        sendHttpError(res, statusCode);\n        return; // do NOT call next() — response already sent\n      }\n\n      // --- Pass through to application -------------------------------------\n      next();\n    })().catch((err: unknown) => {\n      // Surface unexpected errors to Express's error handler\n      next(err);\n    });\n  };\n\n  return middleware;\n}\n","/**\n * Next.js App Router adapter for latency-lab.\n *\n * Wraps App Router route handlers (`GET`, `POST`, etc.) with chaos injection.\n *\n * **TCP drop limitation:**\n * App Router handlers run in a higher-level abstraction — the raw socket is\n * not accessible inside a route handler. `tcp-drop` is therefore approximated\n * by returning a 503 response with an `X-Chaos-Tcp-Drop: 1` header so callers\n * can distinguish it from a real 503 during testing.\n *\n * Usage:\n * ```ts\n * // app/api/users/route.ts\n * import { withChaos, presets } from 'latency-lab/next';\n * import { NextRequest, NextResponse } from 'next/server';\n *\n * async function GET(_req: NextRequest): Promise<NextResponse> {\n *   return NextResponse.json({ users: [] });\n * }\n *\n * export const GET = withChaos(GET, presets.slow3g);\n * ```\n */\n\nimport type { MiddlewareOptions } from './types.js';\nimport {\n  calculateDelay,\n  isExcluded,\n  pickErrorCode,\n  resolveFailureType,\n  shouldFail,\n  sleep,\n  validateChaosOptions,\n} from './core.js';\n\n// ---------------------------------------------------------------------------\n// Minimal Next.js type stubs\n//\n// We deliberately avoid importing from 'next/server' so that `next` remains\n// a peer dependency. The shapes below are structurally compatible with the\n// real `NextRequest` / `NextResponse` from Next.js 14 and 15.\n// ---------------------------------------------------------------------------\n\n/**\n * Structural subset of `NextRequest` used internally.\n * Fully compatible with the real `NextRequest` from `next/server`.\n */\nexport interface NextRequestLike {\n  readonly url: string;\n  readonly method: string;\n  readonly headers: Headers;\n}\n\n/**\n * Structural subset of `NextResponse` used internally.\n * Fully compatible with the real `NextResponse` from `next/server`.\n */\nexport interface NextResponseLike extends Response {\n  readonly status: number;\n  readonly headers: Headers;\n}\n\n/**\n * A Next.js App Router route handler.\n *\n * The generic `Req` and `Res` parameters let callers use the real\n * `NextRequest` / `NextResponse` types without this library depending on them.\n */\nexport type NextRouteHandler<\n  Req extends NextRequestLike = NextRequestLike,\n  Res extends NextResponseLike = NextResponseLike,\n> = (req: Req, ctx?: unknown) => Promise<Res>;\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Builds a minimal JSON error Response compatible with `NextResponse.json()`.\n *\n * We construct a plain `Response` instead of calling `NextResponse.json()` to\n * avoid importing from `next/server` at runtime.\n */\nfunction buildErrorResponse(statusCode: number, headers?: HeadersInit): Response {\n  const body = JSON.stringify({\n    error: 'Chaos injected error',\n    status: statusCode,\n  });\n  const merged = new Headers(headers);\n  merged.set('Content-Type', 'application/json');\n  merged.set('X-Chaos-Injected', '1');\n  return new Response(body, { status: statusCode, headers: merged });\n}\n\n/**\n * Extracts the pathname from a URL string.\n * Falls back to the full string if parsing fails (non-standard environments).\n */\nfunction pathnameFrom(url: string): string {\n  try {\n    return new URL(url).pathname;\n  } catch {\n    // If the URL is relative or malformed, treat the whole value as the path\n    const questionMark = url.indexOf('?');\n    return questionMark === -1 ? url : url.slice(0, questionMark);\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Public factory\n// ---------------------------------------------------------------------------\n\n/**\n * Wraps a Next.js App Router route handler with chaos injection.\n *\n * The returned handler has the same signature as the original, so it can be\n * re-exported directly:\n *\n * ```ts\n * export const GET = withChaos(myHandler, presets.flakyCafeWifi);\n * ```\n *\n * Behaviour:\n * 1. Routes matching `excludeRoutes` are passed through immediately.\n * 2. A realistic delay is injected via `sleep()`.\n * 3. When a failure is triggered:\n *    - `'http-error'` → returns a Response with a status from `errorCodes`\n *    - `'tcp-drop'`   → returns a 503 with `X-Chaos-Tcp-Drop: 1` (limitation noted above)\n * 4. Otherwise, the original handler is called and its response is returned.\n *\n * @param handler - The original App Router route handler.\n * @param options - Chaos configuration. Validated eagerly.\n * @returns A wrapped handler with the same signature.\n */\nexport function withChaos<\n  Req extends NextRequestLike,\n  Res extends NextResponseLike,\n>(\n  handler: NextRouteHandler<Req, Res>,\n  options: MiddlewareOptions,\n): NextRouteHandler<Req, Res> {\n  // Validate at wrap time so misconfiguration fails fast at module load,\n  // not on the first incoming request.\n  const validated = validateChaosOptions(options);\n  const excludeRoutes: readonly string[] = options.excludeRoutes ?? [];\n\n  return async (req: Req, ctx?: unknown): Promise<Res> => {\n    const pathname = pathnameFrom(req.url);\n\n    // --- Route exclusion ---------------------------------------------------\n    if (excludeRoutes.length > 0 && isExcluded(pathname, excludeRoutes)) {\n      return handler(req, ctx);\n    }\n\n    // --- Delay injection ---------------------------------------------------\n    const delay = calculateDelay(validated);\n    await sleep(delay);\n\n    // --- Failure injection -------------------------------------------------\n    if (shouldFail(validated)) {\n      const failureType = resolveFailureType(validated);\n\n      if (failureType === 'tcp-drop') {\n        // True TCP drop is not possible inside an App Router handler.\n        // We approximate it with a 503 and a marker header so test suites\n        // can detect the simulated drop.\n        return buildErrorResponse(503, {\n          'X-Chaos-Tcp-Drop': '1',\n        }) as unknown as Res;\n      }\n\n      // failureType === 'http-error'\n      const statusCode = pickErrorCode(validated);\n      return buildErrorResponse(statusCode) as unknown as Res;\n    }\n\n    // --- Delegate to original handler -------------------------------------\n    return handler(req, ctx);\n  };\n}\n"]}

package/dist/next.cjs

@@ -0,0 +1,183 @@
+'use strict';
+
+// src/types.ts
+var ChaosConfigError = class extends Error {
+  name = "ChaosConfigError";
+  constructor(message) {
+    super(message);
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/core.ts
+function validateChaosOptions(options) {
+  if (options === null || typeof options !== "object") {
+    throw new ChaosConfigError("ChaosOptions must be a plain object.");
+  }
+  const o = options;
+  if (typeof o["baseDelay"] !== "number" || !Number.isFinite(o["baseDelay"])) {
+    throw new ChaosConfigError(
+      `ChaosOptions.baseDelay must be a finite number, got: ${String(o["baseDelay"])}`
+    );
+  }
+  if (o["baseDelay"] < 0) {
+    throw new ChaosConfigError(
+      `ChaosOptions.baseDelay must be \u2265 0, got: ${String(o["baseDelay"])}`
+    );
+  }
+  if (typeof o["jitter"] !== "number" || !Number.isFinite(o["jitter"])) {
+    throw new ChaosConfigError(
+      `ChaosOptions.jitter must be a finite number, got: ${String(o["jitter"])}`
+    );
+  }
+  if (o["jitter"] < 0) {
+    throw new ChaosConfigError(
+      `ChaosOptions.jitter must be \u2265 0, got: ${String(o["jitter"])}`
+    );
+  }
+  if (o["wavePeriod"] !== void 0) {
+    if (typeof o["wavePeriod"] !== "number" || !Number.isFinite(o["wavePeriod"])) {
+      throw new ChaosConfigError(
+        `ChaosOptions.wavePeriod must be a finite number when provided, got: ${String(o["wavePeriod"])}`
+      );
+    }
+    if (o["wavePeriod"] <= 0) {
+      throw new ChaosConfigError(
+        `ChaosOptions.wavePeriod must be > 0 when provided, got: ${String(o["wavePeriod"])}`
+      );
+    }
+  }
+  if (typeof o["failureRate"] !== "number" || !Number.isFinite(o["failureRate"])) {
+    throw new ChaosConfigError(
+      `ChaosOptions.failureRate must be a finite number, got: ${String(o["failureRate"])}`
+    );
+  }
+  if (o["failureRate"] < 0 || o["failureRate"] > 1) {
+    throw new ChaosConfigError(
+      `ChaosOptions.failureRate must be in [0, 1], got: ${String(o["failureRate"])}`
+    );
+  }
+  const validFailureTypes = /* @__PURE__ */ new Set(["http-error", "tcp-drop", "random"]);
+  if (typeof o["failureType"] !== "string" || !validFailureTypes.has(o["failureType"])) {
+    throw new ChaosConfigError(
+      `ChaosOptions.failureType must be one of "http-error" | "tcp-drop" | "random", got: ${String(o["failureType"])}`
+    );
+  }
+  if (!Array.isArray(o["errorCodes"])) {
+    throw new ChaosConfigError(
+      `ChaosOptions.errorCodes must be an array, got: ${typeof o["errorCodes"]}`
+    );
+  }
+  if (o["errorCodes"].length === 0) {
+    throw new ChaosConfigError(
+      "ChaosOptions.errorCodes must contain at least one HTTP status code."
+    );
+  }
+  for (const code of o["errorCodes"]) {
+    if (typeof code !== "number" || !Number.isInteger(code) || code < 100 || code > 599) {
+      throw new ChaosConfigError(
+        `ChaosOptions.errorCodes contains invalid HTTP status code: ${String(code)}. Each code must be an integer in [100, 599].`
+      );
+    }
+  }
+  return {
+    baseDelay: o["baseDelay"],
+    jitter: o["jitter"],
+    ...o["wavePeriod"] !== void 0 ? { wavePeriod: o["wavePeriod"] } : {},
+    failureRate: o["failureRate"],
+    failureType: o["failureType"],
+    errorCodes: o["errorCodes"]
+  };
+}
+function calculateDelay(options) {
+  const { baseDelay, jitter, wavePeriod } = options;
+  const randomJitter = (Math.random() * 2 - 1) * jitter;
+  let waveFluctuation = 0;
+  if (wavePeriod !== void 0) {
+    const tSeconds = Date.now() / 1e3;
+    const phase = tSeconds * (2 * Math.PI) / wavePeriod;
+    waveFluctuation = Math.sin(phase) * jitter * 0.5;
+  }
+  const raw = baseDelay + randomJitter + waveFluctuation;
+  return Math.max(0, raw);
+}
+function shouldFail(options) {
+  if (options.failureRate === 0) return false;
+  if (options.failureRate === 1) return true;
+  return Math.random() < options.failureRate;
+}
+function pickErrorCode(options) {
+  const { errorCodes } = options;
+  if (errorCodes.length === 0) {
+    throw new ChaosConfigError(
+      "Cannot pick an error code from an empty errorCodes array."
+    );
+  }
+  const index = Math.floor(Math.random() * errorCodes.length);
+  return errorCodes[index];
+}
+function resolveFailureType(options) {
+  if (options.failureType === "random") {
+    return Math.random() < 0.5 ? "http-error" : "tcp-drop";
+  }
+  return options.failureType;
+}
+function sleep(ms) {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+function isExcluded(pathname, excludeRoutes) {
+  return excludeRoutes.some((prefix) => {
+    if (pathname === prefix) return true;
+    return pathname.startsWith(prefix.endsWith("/") ? prefix : `${prefix}/`) || pathname.startsWith(prefix);
+  });
+}
+
+// src/next.ts
+function buildErrorResponse(statusCode, headers) {
+  const body = JSON.stringify({
+    error: "Chaos injected error",
+    status: statusCode
+  });
+  const merged = new Headers(headers);
+  merged.set("Content-Type", "application/json");
+  merged.set("X-Chaos-Injected", "1");
+  return new Response(body, { status: statusCode, headers: merged });
+}
+function pathnameFrom(url) {
+  try {
+    return new URL(url).pathname;
+  } catch {
+    const questionMark = url.indexOf("?");
+    return questionMark === -1 ? url : url.slice(0, questionMark);
+  }
+}
+function withChaos(handler, options) {
+  const validated = validateChaosOptions(options);
+  const excludeRoutes = options.excludeRoutes ?? [];
+  return async (req, ctx) => {
+    const pathname = pathnameFrom(req.url);
+    if (excludeRoutes.length > 0 && isExcluded(pathname, excludeRoutes)) {
+      return handler(req, ctx);
+    }
+    const delay = calculateDelay(validated);
+    await sleep(delay);
+    if (shouldFail(validated)) {
+      const failureType = resolveFailureType(validated);
+      if (failureType === "tcp-drop") {
+        return buildErrorResponse(503, {
+          "X-Chaos-Tcp-Drop": "1"
+        });
+      }
+      const statusCode = pickErrorCode(validated);
+      return buildErrorResponse(statusCode);
+    }
+    return handler(req, ctx);
+  };
+}
+
+exports.withChaos = withChaos;
+//# sourceMappingURL=next.cjs.map
+//# sourceMappingURL=next.cjs.map