latency-lab 1.0.0 → 1.1.1

package/dist/next.d.cts

@@ -2,74 +2,23 @@ import { MiddlewareOptions } from './types.cjs';
 
 /**
  * Next.js App Router adapter for latency-lab.
- *
- * Wraps App Router route handlers (`GET`, `POST`, etc.) with chaos injection.
- *
- * **TCP drop limitation:**
- * App Router handlers run in a higher-level abstraction — the raw socket is
- * not accessible inside a route handler. `tcp-drop` is therefore approximated
- * by returning a 503 response with an `X-Chaos-Tcp-Drop: 1` header so callers
- * can distinguish it from a real 503 during testing.
- *
- * Usage:
- * ```ts
- * // app/api/users/route.ts
- * import { withChaos, presets } from 'latency-lab/next';
- * import { NextRequest, NextResponse } from 'next/server';
- *
- * async function GET(_req: NextRequest): Promise<NextResponse> {
- *   return NextResponse.json({ users: [] });
- * }
- *
- * export const GET = withChaos(GET, presets.slow3g);
- * ```
  */
 
-/**
- * Structural subset of `NextRequest` used internally.
- * Fully compatible with the real `NextRequest` from `next/server`.
- */
+/** Structural subset of NextRequest used by the adapter. */
 interface NextRequestLike {
     readonly url: string;
     readonly method: string;
     readonly headers: Headers;
 }
-/**
- * Structural subset of `NextResponse` used internally.
- * Fully compatible with the real `NextResponse` from `next/server`.
- */
+/** Structural subset of NextResponse used by the adapter. */
 interface NextResponseLike extends Response {
     readonly status: number;
     readonly headers: Headers;
 }
-/**
- * A Next.js App Router route handler.
- *
- * The generic `Req` and `Res` parameters let callers use the real
- * `NextRequest` / `NextResponse` types without this library depending on them.
- */
+/** Next.js App Router route handler signature. */
 type NextRouteHandler<Req extends NextRequestLike = NextRequestLike, Res extends NextResponseLike = NextResponseLike> = (req: Req, ctx?: unknown) => Promise<Res>;
 /**
  * Wraps a Next.js App Router route handler with chaos injection.
- *
- * The returned handler has the same signature as the original, so it can be
- * re-exported directly:
- *
- * ```ts
- * export const GET = withChaos(myHandler, presets.flakyCafeWifi);
- * ```
- *
- * Behaviour:
- * 1. Routes matching `excludeRoutes` are passed through immediately.
- * 2. A realistic delay is injected via `sleep()`.
- * 3. When a failure is triggered:
- *    - `'http-error'` → returns a Response with a status from `errorCodes`
- *    - `'tcp-drop'`   → returns a 503 with `X-Chaos-Tcp-Drop: 1` (limitation noted above)
- * 4. Otherwise, the original handler is called and its response is returned.
- *
- * @param handler - The original App Router route handler.
- * @param options - Chaos configuration. Validated eagerly.
- * @returns A wrapped handler with the same signature.
  */
 declare function withChaos<Req extends NextRequestLike, Res extends NextResponseLike>(handler: NextRouteHandler<Req, Res>, options: MiddlewareOptions): NextRouteHandler<Req, Res>;
 

package/dist/next.d.ts

@@ -2,74 +2,23 @@ import { MiddlewareOptions } from './types.js';
 
 /**
  * Next.js App Router adapter for latency-lab.
- *
- * Wraps App Router route handlers (`GET`, `POST`, etc.) with chaos injection.
- *
- * **TCP drop limitation:**
- * App Router handlers run in a higher-level abstraction — the raw socket is
- * not accessible inside a route handler. `tcp-drop` is therefore approximated
- * by returning a 503 response with an `X-Chaos-Tcp-Drop: 1` header so callers
- * can distinguish it from a real 503 during testing.
- *
- * Usage:
- * ```ts
- * // app/api/users/route.ts
- * import { withChaos, presets } from 'latency-lab/next';
- * import { NextRequest, NextResponse } from 'next/server';
- *
- * async function GET(_req: NextRequest): Promise<NextResponse> {
- *   return NextResponse.json({ users: [] });
- * }
- *
- * export const GET = withChaos(GET, presets.slow3g);
- * ```
  */
 
-/**
- * Structural subset of `NextRequest` used internally.
- * Fully compatible with the real `NextRequest` from `next/server`.
- */
+/** Structural subset of NextRequest used by the adapter. */
 interface NextRequestLike {
     readonly url: string;
     readonly method: string;
     readonly headers: Headers;
 }
-/**
- * Structural subset of `NextResponse` used internally.
- * Fully compatible with the real `NextResponse` from `next/server`.
- */
+/** Structural subset of NextResponse used by the adapter. */
 interface NextResponseLike extends Response {
     readonly status: number;
     readonly headers: Headers;
 }
-/**
- * A Next.js App Router route handler.
- *
- * The generic `Req` and `Res` parameters let callers use the real
- * `NextRequest` / `NextResponse` types without this library depending on them.
- */
+/** Next.js App Router route handler signature. */
 type NextRouteHandler<Req extends NextRequestLike = NextRequestLike, Res extends NextResponseLike = NextResponseLike> = (req: Req, ctx?: unknown) => Promise<Res>;
 /**
  * Wraps a Next.js App Router route handler with chaos injection.
- *
- * The returned handler has the same signature as the original, so it can be
- * re-exported directly:
- *
- * ```ts
- * export const GET = withChaos(myHandler, presets.flakyCafeWifi);
- * ```
- *
- * Behaviour:
- * 1. Routes matching `excludeRoutes` are passed through immediately.
- * 2. A realistic delay is injected via `sleep()`.
- * 3. When a failure is triggered:
- *    - `'http-error'` → returns a Response with a status from `errorCodes`
- *    - `'tcp-drop'`   → returns a 503 with `X-Chaos-Tcp-Drop: 1` (limitation noted above)
- * 4. Otherwise, the original handler is called and its response is returned.
- *
- * @param handler - The original App Router route handler.
- * @param options - Chaos configuration. Validated eagerly.
- * @returns A wrapped handler with the same signature.
  */
 declare function withChaos<Req extends NextRequestLike, Res extends NextResponseLike>(handler: NextRouteHandler<Req, Res>, options: MiddlewareOptions): NextRouteHandler<Req, Res>;
 

package/dist/next.js

@@ -120,6 +120,20 @@ function resolveFailureType(options) {
   }
   return options.failureType;
 }
+function decideChaos(options) {
+  const delay = calculateDelay(options);
+  if (!shouldFail(options)) {
+    return { outcome: "pass", delay };
+  }
+  if (resolveFailureType(options) === "tcp-drop") {
+    return { outcome: "tcp-drop", delay };
+  }
+  return {
+    outcome: "http-error",
+    delay,
+    statusCode: pickErrorCode(options)
+  };
+}
 function sleep(ms) {
   if (ms <= 0) return Promise.resolve();
   return new Promise((resolve) => {
@@ -135,14 +149,16 @@ function isExcluded(pathname, excludeRoutes) {
 
 // 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 });
+  return new Response(
+    JSON.stringify({
+      error: "Chaos injected error",
+      status: statusCode
+    }),
+    { status: statusCode, headers: merged }
+  );
 }
 function pathnameFrom(url) {
   try {
@@ -160,17 +176,15 @@ function withChaos(handler, options) {
     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);
+    const decision = decideChaos(validated);
+    await sleep(decision.delay);
+    if (decision.outcome === "tcp-drop") {
+      return buildErrorResponse(503, {
+        "X-Chaos-Tcp-Drop": "1"
+      });
+    }
+    if (decision.outcome === "http-error") {
+      return buildErrorResponse(decision.statusCode);
     }
     return handler(req, ctx);
   };

package/dist/next.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/types.ts","../src/core.ts","../src/next.ts"],"names":[],"mappings":"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","file":"next.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","/**\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"]}
+{"version":3,"sources":["../src/types.ts","../src/core.ts","../src/next.ts"],"names":[],"mappings":"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","file":"next.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/** Resolved action for one request after all randomness has been evaluated. */\nexport type ChaosDecision =\n  | { outcome: 'pass'; delay: number }\n  | { outcome: 'http-error'; delay: number; statusCode: number }\n  | { outcome: 'tcp-drop'; delay: number };\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 {\n  ChaosDecision,\n  ChaosOptions,\n  ResolvedFailureType,\n} 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/** Resolves the complete chaos outcome for one request. */\nexport function decideChaos(options: ChaosOptions): ChaosDecision {\n  const delay = calculateDelay(options);\n\n  if (!shouldFail(options)) {\n    return { outcome: 'pass', delay };\n  }\n\n  if (resolveFailureType(options) === 'tcp-drop') {\n    return { outcome: 'tcp-drop', delay };\n  }\n\n  return {\n    outcome: 'http-error',\n    delay,\n    statusCode: pickErrorCode(options),\n  };\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","/**\n * Next.js App Router adapter for latency-lab.\n */\n\nimport { decideChaos, isExcluded, sleep, validateChaosOptions } from './core.js';\nimport type { MiddlewareOptions } from './types.js';\n\n/** Structural subset of NextRequest used by the adapter. */\nexport interface NextRequestLike {\n  readonly url: string;\n  readonly method: string;\n  readonly headers: Headers;\n}\n\n/** Structural subset of NextResponse used by the adapter. */\nexport interface NextResponseLike extends Response {\n  readonly status: number;\n  readonly headers: Headers;\n}\n\n/** Next.js App Router route handler signature. */\nexport type NextRouteHandler<\n  Req extends NextRequestLike = NextRequestLike,\n  Res extends NextResponseLike = NextResponseLike,\n> = (req: Req, ctx?: unknown) => Promise<Res>;\n\nfunction buildErrorResponse(statusCode: number, headers?: HeadersInit): Response {\n  const merged = new Headers(headers);\n  merged.set('Content-Type', 'application/json');\n  merged.set('X-Chaos-Injected', '1');\n\n  return new Response(\n    JSON.stringify({\n      error: 'Chaos injected error',\n      status: statusCode,\n    }),\n    { status: statusCode, headers: merged },\n  );\n}\n\nfunction pathnameFrom(url: string): string {\n  try {\n    return new URL(url).pathname;\n  } catch {\n    const questionMark = url.indexOf('?');\n    return questionMark === -1 ? url : url.slice(0, questionMark);\n  }\n}\n\n/**\n * Wraps a Next.js App Router route handler with chaos injection.\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  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    if (excludeRoutes.length > 0 && isExcluded(pathname, excludeRoutes)) {\n      return handler(req, ctx);\n    }\n\n    const decision = decideChaos(validated);\n    await sleep(decision.delay);\n\n    if (decision.outcome === 'tcp-drop') {\n      return buildErrorResponse(503, {\n        'X-Chaos-Tcp-Drop': '1',\n      }) as unknown as Res;\n    }\n\n    if (decision.outcome === 'http-error') {\n      return buildErrorResponse(decision.statusCode) as unknown as Res;\n    }\n\n    return handler(req, ctx);\n  };\n}\n"]}

package/dist/presets.cjs

@@ -33,11 +33,38 @@ var congestedStadium = Object.freeze({
   failureType: "random",
   errorCodes: [429, 503, 504, 520]
 });
+var satelliteLink = Object.freeze({
+  baseDelay: 600,
+  jitter: 50,
+  wavePeriod: 120,
+  failureRate: 0.01,
+  failureType: "http-error",
+  errorCodes: [408, 504]
+});
+var mobileDataRoaming = Object.freeze({
+  baseDelay: 250,
+  jitter: 350,
+  wavePeriod: 15,
+  failureRate: 0.08,
+  failureType: "random",
+  errorCodes: [408, 429, 502, 503, 504]
+});
+var corpVPN = Object.freeze({
+  baseDelay: 120,
+  jitter: 80,
+  wavePeriod: 45,
+  failureRate: 0.03,
+  failureType: "tcp-drop",
+  errorCodes: [502, 503, 504]
+});
 var presets = Object.freeze({
   subwayTunnel,
   flakyCafeWifi,
   slow3g,
-  congestedStadium
+  congestedStadium,
+  satelliteLink,
+  mobileDataRoaming,
+  corpVPN
 });
 
 exports.presets = presets;

package/dist/presets.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/presets.ts"],"names":[],"mappings":";;;AAeA,IAAM,YAAA,GAAuC,OAAO,MAAA,CAAO;AAAA,EACzD,SAAA,EAAW,GAAA;AAAA,EACX,MAAA,EAAQ,GAAA;AAAA,EACR,UAAA,EAAY,CAAA;AAAA,EACZ,WAAA,EAAa,GAAA;AAAA,EACb,WAAA,EAAa,UAAA;AAAA,EACb,UAAA,EAAY,CAAC,GAAA,EAAK,GAAG;AACvB,CAAwB,CAAA;AAWxB,IAAM,aAAA,GAAwC,OAAO,MAAA,CAAO;AAAA,EAC1D,SAAA,EAAW,GAAA;AAAA,EACX,MAAA,EAAQ,GAAA;AAAA,EACR,UAAA,EAAY,EAAA;AAAA,EACZ,WAAA,EAAa,IAAA;AAAA,EACb,WAAA,EAAa,QAAA;AAAA,EACb,UAAA,EAAY,CAAC,GAAA,EAAK,GAAA,EAAK,GAAG;AAC5B,CAAwB,CAAA;AAWxB,IAAM,MAAA,GAAiC,OAAO,MAAA,CAAO;AAAA,EACnD,SAAA,EAAW,GAAA;AAAA,EACX,MAAA,EAAQ,GAAA;AAAA,EACR,UAAA,EAAY,EAAA;AAAA,EACZ,WAAA,EAAa,IAAA;AAAA,EACb,WAAA,EAAa,YAAA;AAAA,EACb,UAAA,EAAY,CAAC,GAAA,EAAK,GAAG;AACvB,CAAwB,CAAA;AAWxB,IAAM,gBAAA,GAA2C,OAAO,MAAA,CAAO;AAAA,EAC7D,SAAA,EAAW,GAAA;AAAA,EACX,MAAA,EAAQ,GAAA;AAAA,EACR,UAAA,EAAY,CAAA;AAAA,EACZ,WAAA,EAAa,GAAA;AAAA,EACb,WAAA,EAAa,QAAA;AAAA,EACb,UAAA,EAAY,CAAC,GAAA,EAAK,GAAA,EAAK,KAAK,GAAG;AACjC,CAAwB,CAAA;AAkBjB,IAAM,OAAA,GAAU,OAAO,MAAA,CAAO;AAAA,EACnC,YAAA;AAAA,EACA,aAAA;AAAA,EACA,MAAA;AAAA,EACA;AACF,CAAU","file":"presets.cjs","sourcesContent":["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"]}
+{"version":3,"sources":["../src/presets.ts"],"names":[],"mappings":";;;AAeA,IAAM,YAAA,GAAuC,OAAO,MAAA,CAAO;AAAA,EACzD,SAAA,EAAW,GAAA;AAAA,EACX,MAAA,EAAQ,GAAA;AAAA,EACR,UAAA,EAAY,CAAA;AAAA,EACZ,WAAA,EAAa,GAAA;AAAA,EACb,WAAA,EAAa,UAAA;AAAA,EACb,UAAA,EAAY,CAAC,GAAA,EAAK,GAAG;AACvB,CAAwB,CAAA;AAWxB,IAAM,aAAA,GAAwC,OAAO,MAAA,CAAO;AAAA,EAC1D,SAAA,EAAW,GAAA;AAAA,EACX,MAAA,EAAQ,GAAA;AAAA,EACR,UAAA,EAAY,EAAA;AAAA,EACZ,WAAA,EAAa,IAAA;AAAA,EACb,WAAA,EAAa,QAAA;AAAA,EACb,UAAA,EAAY,CAAC,GAAA,EAAK,GAAA,EAAK,GAAG;AAC5B,CAAwB,CAAA;AAWxB,IAAM,MAAA,GAAiC,OAAO,MAAA,CAAO;AAAA,EACnD,SAAA,EAAW,GAAA;AAAA,EACX,MAAA,EAAQ,GAAA;AAAA,EACR,UAAA,EAAY,EAAA;AAAA,EACZ,WAAA,EAAa,IAAA;AAAA,EACb,WAAA,EAAa,YAAA;AAAA,EACb,UAAA,EAAY,CAAC,GAAA,EAAK,GAAG;AACvB,CAAwB,CAAA;AAWxB,IAAM,gBAAA,GAA2C,OAAO,MAAA,CAAO;AAAA,EAC7D,SAAA,EAAW,GAAA;AAAA,EACX,MAAA,EAAQ,GAAA;AAAA,EACR,UAAA,EAAY,CAAA;AAAA,EACZ,WAAA,EAAa,GAAA;AAAA,EACb,WAAA,EAAa,QAAA;AAAA,EACb,UAAA,EAAY,CAAC,GAAA,EAAK,GAAA,EAAK,KAAK,GAAG;AACjC,CAAwB,CAAA;AAGxB,IAAM,aAAA,GAAwC,OAAO,MAAA,CAAO;AAAA,EAC1D,SAAA,EAAW,GAAA;AAAA,EACX,MAAA,EAAQ,EAAA;AAAA,EACR,UAAA,EAAY,GAAA;AAAA,EACZ,WAAA,EAAa,IAAA;AAAA,EACb,WAAA,EAAa,YAAA;AAAA,EACb,UAAA,EAAY,CAAC,GAAA,EAAK,GAAG;AACvB,CAAwB,CAAA;AAGxB,IAAM,iBAAA,GAA4C,OAAO,MAAA,CAAO;AAAA,EAC9D,SAAA,EAAW,GAAA;AAAA,EACX,MAAA,EAAQ,GAAA;AAAA,EACR,UAAA,EAAY,EAAA;AAAA,EACZ,WAAA,EAAa,IAAA;AAAA,EACb,WAAA,EAAa,QAAA;AAAA,EACb,YAAY,CAAC,GAAA,EAAK,GAAA,EAAK,GAAA,EAAK,KAAK,GAAG;AACtC,CAAwB,CAAA;AAGxB,IAAM,OAAA,GAAkC,OAAO,MAAA,CAAO;AAAA,EACpD,SAAA,EAAW,GAAA;AAAA,EACX,MAAA,EAAQ,EAAA;AAAA,EACR,UAAA,EAAY,EAAA;AAAA,EACZ,WAAA,EAAa,IAAA;AAAA,EACb,WAAA,EAAa,UAAA;AAAA,EACb,UAAA,EAAY,CAAC,GAAA,EAAK,GAAA,EAAK,GAAG;AAC5B,CAAwB,CAAA;AAkBjB,IAAM,OAAA,GAAU,OAAO,MAAA,CAAO;AAAA,EACnC,YAAA;AAAA,EACA,aAAA;AAAA,EACA,MAAA;AAAA,EACA,gBAAA;AAAA,EACA,aAAA;AAAA,EACA,iBAAA;AAAA,EACA;AACF,CAAU","file":"presets.cjs","sourcesContent":["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/** Stable but inherently high-latency satellite internet. */\nconst satelliteLink: Readonly<ChaosOptions> = Object.freeze({\n  baseDelay: 600,\n  jitter: 50,\n  wavePeriod: 120,\n  failureRate: 0.01,\n  failureType: 'http-error',\n  errorCodes: [408, 504],\n} satisfies ChaosOptions);\n\n/** International mobile roaming with bursts and mixed failures. */\nconst mobileDataRoaming: Readonly<ChaosOptions> = Object.freeze({\n  baseDelay: 250,\n  jitter: 350,\n  wavePeriod: 15,\n  failureRate: 0.08,\n  failureType: 'random',\n  errorCodes: [408, 429, 502, 503, 504],\n} satisfies ChaosOptions);\n\n/** Corporate VPN latency with occasional abrupt connection loss. */\nconst corpVPN: Readonly<ChaosOptions> = Object.freeze({\n  baseDelay: 120,\n  jitter: 80,\n  wavePeriod: 45,\n  failureRate: 0.03,\n  failureType: 'tcp-drop',\n  errorCodes: [502, 503, 504],\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  satelliteLink,\n  mobileDataRoaming,\n  corpVPN,\n} as const);\n\nexport type PresetName = keyof typeof presets;\n"]}

package/dist/presets.d.cts

@@ -21,6 +21,9 @@ declare const presets: Readonly<{
     readonly flakyCafeWifi: Readonly<ChaosOptions>;
     readonly slow3g: Readonly<ChaosOptions>;
     readonly congestedStadium: Readonly<ChaosOptions>;
+    readonly satelliteLink: Readonly<ChaosOptions>;
+    readonly mobileDataRoaming: Readonly<ChaosOptions>;
+    readonly corpVPN: Readonly<ChaosOptions>;
 }>;
 type PresetName = keyof typeof presets;
 

package/dist/presets.d.ts

@@ -21,6 +21,9 @@ declare const presets: Readonly<{
     readonly flakyCafeWifi: Readonly<ChaosOptions>;
     readonly slow3g: Readonly<ChaosOptions>;
     readonly congestedStadium: Readonly<ChaosOptions>;
+    readonly satelliteLink: Readonly<ChaosOptions>;
+    readonly mobileDataRoaming: Readonly<ChaosOptions>;
+    readonly corpVPN: Readonly<ChaosOptions>;
 }>;
 type PresetName = keyof typeof presets;
 

package/dist/presets.js

@@ -31,11 +31,38 @@ var congestedStadium = Object.freeze({
   failureType: "random",
   errorCodes: [429, 503, 504, 520]
 });
+var satelliteLink = Object.freeze({
+  baseDelay: 600,
+  jitter: 50,
+  wavePeriod: 120,
+  failureRate: 0.01,
+  failureType: "http-error",
+  errorCodes: [408, 504]
+});
+var mobileDataRoaming = Object.freeze({
+  baseDelay: 250,
+  jitter: 350,
+  wavePeriod: 15,
+  failureRate: 0.08,
+  failureType: "random",
+  errorCodes: [408, 429, 502, 503, 504]
+});
+var corpVPN = Object.freeze({
+  baseDelay: 120,
+  jitter: 80,
+  wavePeriod: 45,
+  failureRate: 0.03,
+  failureType: "tcp-drop",
+  errorCodes: [502, 503, 504]
+});
 var presets = Object.freeze({
   subwayTunnel,
   flakyCafeWifi,
   slow3g,
-  congestedStadium
+  congestedStadium,
+  satelliteLink,
+  mobileDataRoaming,
+  corpVPN
 });
 
 export { presets };

package/dist/presets.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/presets.ts"],"names":[],"mappings":";AAeA,IAAM,YAAA,GAAuC,OAAO,MAAA,CAAO;AAAA,EACzD,SAAA,EAAW,GAAA;AAAA,EACX,MAAA,EAAQ,GAAA;AAAA,EACR,UAAA,EAAY,CAAA;AAAA,EACZ,WAAA,EAAa,GAAA;AAAA,EACb,WAAA,EAAa,UAAA;AAAA,EACb,UAAA,EAAY,CAAC,GAAA,EAAK,GAAG;AACvB,CAAwB,CAAA;AAWxB,IAAM,aAAA,GAAwC,OAAO,MAAA,CAAO;AAAA,EAC1D,SAAA,EAAW,GAAA;AAAA,EACX,MAAA,EAAQ,GAAA;AAAA,EACR,UAAA,EAAY,EAAA;AAAA,EACZ,WAAA,EAAa,IAAA;AAAA,EACb,WAAA,EAAa,QAAA;AAAA,EACb,UAAA,EAAY,CAAC,GAAA,EAAK,GAAA,EAAK,GAAG;AAC5B,CAAwB,CAAA;AAWxB,IAAM,MAAA,GAAiC,OAAO,MAAA,CAAO;AAAA,EACnD,SAAA,EAAW,GAAA;AAAA,EACX,MAAA,EAAQ,GAAA;AAAA,EACR,UAAA,EAAY,EAAA;AAAA,EACZ,WAAA,EAAa,IAAA;AAAA,EACb,WAAA,EAAa,YAAA;AAAA,EACb,UAAA,EAAY,CAAC,GAAA,EAAK,GAAG;AACvB,CAAwB,CAAA;AAWxB,IAAM,gBAAA,GAA2C,OAAO,MAAA,CAAO;AAAA,EAC7D,SAAA,EAAW,GAAA;AAAA,EACX,MAAA,EAAQ,GAAA;AAAA,EACR,UAAA,EAAY,CAAA;AAAA,EACZ,WAAA,EAAa,GAAA;AAAA,EACb,WAAA,EAAa,QAAA;AAAA,EACb,UAAA,EAAY,CAAC,GAAA,EAAK,GAAA,EAAK,KAAK,GAAG;AACjC,CAAwB,CAAA;AAkBjB,IAAM,OAAA,GAAU,OAAO,MAAA,CAAO;AAAA,EACnC,YAAA;AAAA,EACA,aAAA;AAAA,EACA,MAAA;AAAA,EACA;AACF,CAAU","file":"presets.js","sourcesContent":["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"]}
+{"version":3,"sources":["../src/presets.ts"],"names":[],"mappings":";AAeA,IAAM,YAAA,GAAuC,OAAO,MAAA,CAAO;AAAA,EACzD,SAAA,EAAW,GAAA;AAAA,EACX,MAAA,EAAQ,GAAA;AAAA,EACR,UAAA,EAAY,CAAA;AAAA,EACZ,WAAA,EAAa,GAAA;AAAA,EACb,WAAA,EAAa,UAAA;AAAA,EACb,UAAA,EAAY,CAAC,GAAA,EAAK,GAAG;AACvB,CAAwB,CAAA;AAWxB,IAAM,aAAA,GAAwC,OAAO,MAAA,CAAO;AAAA,EAC1D,SAAA,EAAW,GAAA;AAAA,EACX,MAAA,EAAQ,GAAA;AAAA,EACR,UAAA,EAAY,EAAA;AAAA,EACZ,WAAA,EAAa,IAAA;AAAA,EACb,WAAA,EAAa,QAAA;AAAA,EACb,UAAA,EAAY,CAAC,GAAA,EAAK,GAAA,EAAK,GAAG;AAC5B,CAAwB,CAAA;AAWxB,IAAM,MAAA,GAAiC,OAAO,MAAA,CAAO;AAAA,EACnD,SAAA,EAAW,GAAA;AAAA,EACX,MAAA,EAAQ,GAAA;AAAA,EACR,UAAA,EAAY,EAAA;AAAA,EACZ,WAAA,EAAa,IAAA;AAAA,EACb,WAAA,EAAa,YAAA;AAAA,EACb,UAAA,EAAY,CAAC,GAAA,EAAK,GAAG;AACvB,CAAwB,CAAA;AAWxB,IAAM,gBAAA,GAA2C,OAAO,MAAA,CAAO;AAAA,EAC7D,SAAA,EAAW,GAAA;AAAA,EACX,MAAA,EAAQ,GAAA;AAAA,EACR,UAAA,EAAY,CAAA;AAAA,EACZ,WAAA,EAAa,GAAA;AAAA,EACb,WAAA,EAAa,QAAA;AAAA,EACb,UAAA,EAAY,CAAC,GAAA,EAAK,GAAA,EAAK,KAAK,GAAG;AACjC,CAAwB,CAAA;AAGxB,IAAM,aAAA,GAAwC,OAAO,MAAA,CAAO;AAAA,EAC1D,SAAA,EAAW,GAAA;AAAA,EACX,MAAA,EAAQ,EAAA;AAAA,EACR,UAAA,EAAY,GAAA;AAAA,EACZ,WAAA,EAAa,IAAA;AAAA,EACb,WAAA,EAAa,YAAA;AAAA,EACb,UAAA,EAAY,CAAC,GAAA,EAAK,GAAG;AACvB,CAAwB,CAAA;AAGxB,IAAM,iBAAA,GAA4C,OAAO,MAAA,CAAO;AAAA,EAC9D,SAAA,EAAW,GAAA;AAAA,EACX,MAAA,EAAQ,GAAA;AAAA,EACR,UAAA,EAAY,EAAA;AAAA,EACZ,WAAA,EAAa,IAAA;AAAA,EACb,WAAA,EAAa,QAAA;AAAA,EACb,YAAY,CAAC,GAAA,EAAK,GAAA,EAAK,GAAA,EAAK,KAAK,GAAG;AACtC,CAAwB,CAAA;AAGxB,IAAM,OAAA,GAAkC,OAAO,MAAA,CAAO;AAAA,EACpD,SAAA,EAAW,GAAA;AAAA,EACX,MAAA,EAAQ,EAAA;AAAA,EACR,UAAA,EAAY,EAAA;AAAA,EACZ,WAAA,EAAa,IAAA;AAAA,EACb,WAAA,EAAa,UAAA;AAAA,EACb,UAAA,EAAY,CAAC,GAAA,EAAK,GAAA,EAAK,GAAG;AAC5B,CAAwB,CAAA;AAkBjB,IAAM,OAAA,GAAU,OAAO,MAAA,CAAO;AAAA,EACnC,YAAA;AAAA,EACA,aAAA;AAAA,EACA,MAAA;AAAA,EACA,gBAAA;AAAA,EACA,aAAA;AAAA,EACA,iBAAA;AAAA,EACA;AACF,CAAU","file":"presets.js","sourcesContent":["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/** Stable but inherently high-latency satellite internet. */\nconst satelliteLink: Readonly<ChaosOptions> = Object.freeze({\n  baseDelay: 600,\n  jitter: 50,\n  wavePeriod: 120,\n  failureRate: 0.01,\n  failureType: 'http-error',\n  errorCodes: [408, 504],\n} satisfies ChaosOptions);\n\n/** International mobile roaming with bursts and mixed failures. */\nconst mobileDataRoaming: Readonly<ChaosOptions> = Object.freeze({\n  baseDelay: 250,\n  jitter: 350,\n  wavePeriod: 15,\n  failureRate: 0.08,\n  failureType: 'random',\n  errorCodes: [408, 429, 502, 503, 504],\n} satisfies ChaosOptions);\n\n/** Corporate VPN latency with occasional abrupt connection loss. */\nconst corpVPN: Readonly<ChaosOptions> = Object.freeze({\n  baseDelay: 120,\n  jitter: 80,\n  wavePeriod: 45,\n  failureRate: 0.03,\n  failureType: 'tcp-drop',\n  errorCodes: [502, 503, 504],\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  satelliteLink,\n  mobileDataRoaming,\n  corpVPN,\n} as const);\n\nexport type PresetName = keyof typeof presets;\n"]}

package/dist/types.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/types.ts"],"names":[],"mappings":";;;AA4FO,IAAM,gBAAA,GAAN,cAA+B,KAAA,CAAM;AAAA,EACxB,IAAA,GAAO,kBAAA;AAAA,EAEzB,YAAY,OAAA,EAAiB;AAC3B,IAAA,KAAA,CAAM,OAAO,CAAA;AAEb,IAAA,MAAA,CAAO,cAAA,CAAe,IAAA,EAAM,GAAA,CAAA,MAAA,CAAW,SAAS,CAAA;AAAA,EAClD;AACF","file":"types.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"]}
+{"version":3,"sources":["../src/types.ts"],"names":[],"mappings":";;;AAkGO,IAAM,gBAAA,GAAN,cAA+B,KAAA,CAAM;AAAA,EACxB,IAAA,GAAO,kBAAA;AAAA,EAEzB,YAAY,OAAA,EAAiB;AAC3B,IAAA,KAAA,CAAM,OAAO,CAAA;AAEb,IAAA,MAAA,CAAO,cAAA,CAAe,IAAA,EAAM,GAAA,CAAA,MAAA,CAAW,SAAS,CAAA;AAAA,EAClD;AACF","file":"types.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/** Resolved action for one request after all randomness has been evaluated. */\nexport type ChaosDecision =\n  | { outcome: 'pass'; delay: number }\n  | { outcome: 'http-error'; delay: number; statusCode: number }\n  | { outcome: 'tcp-drop'; delay: number };\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"]}

package/dist/types.d.cts

@@ -14,6 +14,18 @@ type FailureType = 'http-error' | 'tcp-drop' | 'random';
  * Never `'random'` — always a concrete action.
  */
 type ResolvedFailureType = Exclude<FailureType, 'random'>;
+/** Resolved action for one request after all randomness has been evaluated. */
+type ChaosDecision = {
+    outcome: 'pass';
+    delay: number;
+} | {
+    outcome: 'http-error';
+    delay: number;
+    statusCode: number;
+} | {
+    outcome: 'tcp-drop';
+    delay: number;
+};
 /**
  * Core chaos configuration.
  *
@@ -86,4 +98,4 @@ declare class ChaosConfigError extends Error {
     constructor(message: string);
 }
 
-export { ChaosConfigError, type ChaosOptions, type FailureType, type MiddlewareOptions, type ResolvedFailureType };
+export { ChaosConfigError, type ChaosDecision, type ChaosOptions, type FailureType, type MiddlewareOptions, type ResolvedFailureType };

package/dist/types.d.ts

@@ -14,6 +14,18 @@ type FailureType = 'http-error' | 'tcp-drop' | 'random';
  * Never `'random'` — always a concrete action.
  */
 type ResolvedFailureType = Exclude<FailureType, 'random'>;
+/** Resolved action for one request after all randomness has been evaluated. */
+type ChaosDecision = {
+    outcome: 'pass';
+    delay: number;
+} | {
+    outcome: 'http-error';
+    delay: number;
+    statusCode: number;
+} | {
+    outcome: 'tcp-drop';
+    delay: number;
+};
 /**
  * Core chaos configuration.
  *
@@ -86,4 +98,4 @@ declare class ChaosConfigError extends Error {
     constructor(message: string);
 }
 
-export { ChaosConfigError, type ChaosOptions, type FailureType, type MiddlewareOptions, type ResolvedFailureType };
+export { ChaosConfigError, type ChaosDecision, type ChaosOptions, type FailureType, type MiddlewareOptions, type ResolvedFailureType };

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/types.ts"],"names":[],"mappings":";AA4FO,IAAM,gBAAA,GAAN,cAA+B,KAAA,CAAM;AAAA,EACxB,IAAA,GAAO,kBAAA;AAAA,EAEzB,YAAY,OAAA,EAAiB;AAC3B,IAAA,KAAA,CAAM,OAAO,CAAA;AAEb,IAAA,MAAA,CAAO,cAAA,CAAe,IAAA,EAAM,GAAA,CAAA,MAAA,CAAW,SAAS,CAAA;AAAA,EAClD;AACF","file":"types.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"]}
+{"version":3,"sources":["../src/types.ts"],"names":[],"mappings":";AAkGO,IAAM,gBAAA,GAAN,cAA+B,KAAA,CAAM;AAAA,EACxB,IAAA,GAAO,kBAAA;AAAA,EAEzB,YAAY,OAAA,EAAiB;AAC3B,IAAA,KAAA,CAAM,OAAO,CAAA;AAEb,IAAA,MAAA,CAAO,cAAA,CAAe,IAAA,EAAM,GAAA,CAAA,MAAA,CAAW,SAAS,CAAA;AAAA,EAClD;AACF","file":"types.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/** Resolved action for one request after all randomness has been evaluated. */\nexport type ChaosDecision =\n  | { outcome: 'pass'; delay: number }\n  | { outcome: 'http-error'; delay: number; statusCode: number }\n  | { outcome: 'tcp-drop'; delay: number };\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"]}