latency-lab 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 latency-lab contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,434 @@
+# latency-lab
+
+> Inject realistic network chaos into backend applications during local development and testing.
+
+[![npm version](https://img.shields.io/npm/v/latency-lab.svg)](https://www.npmjs.com/package/latency-lab)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)](#)
+
+Unlike a simple `setTimeout` wrapper, `latency-lab` models real-world degraded network conditions: sine-wave quality fluctuations, bursty jitter, probabilistic packet loss, TCP-level connection drops, and HTTP error injection — all composable, all typed.
+
+---
+
+## Why latency-lab?
+
+| Feature | Simple delay | latency-lab |
+|---|---|---|
+| Base delay | ✅ | ✅ |
+| Random jitter | ❌ | ✅ |
+| Wave fluctuations | ❌ | ✅ |
+| Packet loss / TCP drop | ❌ | ✅ |
+| HTTP error injection | ❌ | ✅ |
+| Route exclusions | ❌ | ✅ |
+| Typed presets | ❌ | ✅ |
+| Zero runtime deps | ✅ | ✅ |
+
+---
+
+## Installation
+
+```bash
+npm install --save-dev latency-lab
+# or
+pnpm add -D latency-lab
+# or
+yarn add -D latency-lab
+```
+
+Peer dependencies (install only what you need):
+
+```bash
+# For Express
+npm install express
+
+# For Next.js
+npm install next
+```
+
+---
+
+## Quick Start
+
+### Express
+
+```ts
+import express from 'express';
+import { chaosMiddleware, presets } from 'latency-lab';
+
+const app = express();
+
+// Use a preset
+app.use(chaosMiddleware(presets.flakyCafeWifi));
+
+// Or configure manually
+app.use(chaosMiddleware({
+  baseDelay: 200,
+  jitter: 80,
+  wavePeriod: 30,
+  failureRate: 0.05,
+  failureType: 'random',
+  errorCodes: [500, 502, 503],
+  excludeRoutes: ['/health', '/metrics'],
+}));
+
+app.listen(3000);
+```
+
+### Next.js App Router
+
+```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);
+```
+
+---
+
+## Presets
+
+Ready-to-use network profiles:
+
+### `presets.subwayTunnel`
+
+Sudden quality drops with intermittent total blackouts. High jitter, moderate loss.
+
+```ts
+{
+  baseDelay: 800,
+  jitter: 600,
+  wavePeriod: 8,
+  failureRate: 0.20,
+  failureType: 'tcp-drop',
+  errorCodes: [503, 504],
+}
+```
+
+### `presets.flakyCafeWifi`
+
+Unpredictable café Wi-Fi — mostly works, occasionally terrible.
+
+```ts
+{
+  baseDelay: 150,
+  jitter: 300,
+  wavePeriod: 20,
+  failureRate: 0.08,
+  failureType: 'random',
+  errorCodes: [502, 503, 504],
+}
+```
+
+### `presets.slow3g`
+
+Classic slow 3G — high latency, low jitter, low failure rate.
+
+```ts
+{
+  baseDelay: 400,
+  jitter: 100,
+  wavePeriod: 60,
+  failureRate: 0.03,
+  failureType: 'http-error',
+  errorCodes: [408, 503],
+}
+```
+
+### `presets.congestedStadium`
+
+Stadium network — extremely variable, high congestion loss.
+
+```ts
+{
+  baseDelay: 600,
+  jitter: 800,
+  wavePeriod: 5,
+  failureRate: 0.30,
+  failureType: 'random',
+  errorCodes: [429, 503, 504, 520],
+}
+```
+
+---
+
+## Express Examples
+
+### Basic setup
+
+```ts
+import express from 'express';
+import { chaosMiddleware } from 'latency-lab';
+
+const app = express();
+
+app.use(chaosMiddleware({
+  baseDelay: 300,
+  jitter: 150,
+  failureRate: 0.1,
+  failureType: 'http-error',
+  errorCodes: [500, 503],
+}));
+```
+
+### Excluding routes
+
+```ts
+app.use(chaosMiddleware({
+  baseDelay: 200,
+  jitter: 50,
+  failureRate: 0.05,
+  failureType: 'random',
+  errorCodes: [503],
+  excludeRoutes: ['/health', '/ready', '/_internal'],
+}));
+```
+
+### Conditional activation
+
+```ts
+if (process.env.CHAOS_ENABLED === 'true') {
+  app.use(chaosMiddleware(presets.flakyCafeWifi));
+}
+```
+
+---
+
+## Next.js Examples
+
+### App Router — single route
+
+```ts
+// app/api/posts/route.ts
+import { withChaos } from 'latency-lab/next';
+import { NextRequest, NextResponse } from 'next/server';
+
+async function GET(_req: NextRequest): Promise<NextResponse> {
+  const posts = await db.posts.findAll();
+  return NextResponse.json(posts);
+}
+
+export const GET = withChaos(GET, {
+  baseDelay: 300,
+  jitter: 100,
+  failureRate: 0.05,
+  failureType: 'http-error',
+  errorCodes: [503],
+});
+```
+
+### App Router — route exclusions
+
+```ts
+export const GET = withChaos(GET, {
+  ...presets.slow3g,
+  excludeRoutes: ['/api/health'],
+});
+```
+
+---
+
+## API Reference
+
+### `calculateDelay(options: ChaosOptions): number`
+
+Returns the computed delay in milliseconds for a single request.
+
+The formula is:
+
+```
+delay = baseDelay + randomJitter + waveFluctuation
+```
+
+- **randomJitter**: uniform random in `[-jitter, +jitter]`
+- **waveFluctuation**: `sin(now/1000 * 2π/wavePeriod) * jitter * 0.5` (zero when `wavePeriod` is omitted)
+- Final value clamped to `≥ 0`
+
+---
+
+### `shouldFail(options: ChaosOptions): boolean`
+
+Returns `true` with probability equal to `options.failureRate`.
+
+```ts
+shouldFail({ failureRate: 0.1, ... }) // ~10% chance
+```
+
+---
+
+### `pickErrorCode(options: ChaosOptions): number`
+
+Returns a randomly chosen HTTP status code from `options.errorCodes`.
+
+Throws `ChaosConfigError` if the array is empty.
+
+---
+
+### `resolveFailureType(options: ChaosOptions): ResolvedFailureType`
+
+When `failureType` is `'random'`, randomly picks between `'http-error'` and `'tcp-drop'`. Otherwise returns the configured type.
+
+---
+
+### `sleep(ms: number): Promise<void>`
+
+Non-blocking async sleep using `setTimeout`.
+
+---
+
+### `validateChaosOptions(options: unknown): ChaosOptions`
+
+Validates a chaos configuration object. Throws `ChaosConfigError` on invalid input.
+
+---
+
+### `chaosMiddleware(options: MiddlewareOptions): ConnectMiddleware`
+
+Returns an Express/Connect-compatible middleware function.
+
+```ts
+import { chaosMiddleware } from 'latency-lab';
+
+app.use(chaosMiddleware({
+  baseDelay: 200,
+  jitter: 80,
+  failureRate: 0.05,
+  failureType: 'http-error',
+  errorCodes: [503],
+  excludeRoutes: ['/health'],
+}));
+```
+
+---
+
+### `withChaos(handler, options): typeof handler`
+
+Wraps a Next.js App Router handler with chaos injection.
+
+```ts
+import { withChaos } from 'latency-lab/next';
+
+export const GET = withChaos(myGetHandler, presets.slow3g);
+```
+
+---
+
+### `ChaosOptions`
+
+```ts
+interface ChaosOptions {
+  /** Base latency in milliseconds. Must be ≥ 0. */
+  baseDelay: number;
+  /** Maximum jitter added/subtracted from baseDelay. Must be ≥ 0. */
+  jitter: number;
+  /** Period of the sine-wave fluctuation in seconds. Optional. */
+  wavePeriod?: number;
+  /** Probability of a failure per request. Range: [0, 1]. */
+  failureRate: number;
+  /** How failures are expressed. */
+  failureType: 'http-error' | 'tcp-drop' | 'random';
+  /** Pool of HTTP status codes to pick from on failure. Must be non-empty. */
+  errorCodes: number[];
+}
+```
+
+---
+
+### `MiddlewareOptions`
+
+```ts
+interface MiddlewareOptions extends ChaosOptions {
+  /** Route path prefixes to exclude from chaos injection. */
+  excludeRoutes?: string[];
+}
+```
+
+---
+
+### `presets`
+
+```ts
+import { presets } from 'latency-lab';
+
+presets.subwayTunnel
+presets.flakyCafeWifi
+presets.slow3g
+presets.congestedStadium
+```
+
+All preset values are `readonly` and fully typed as `ChaosOptions`.
+
+---
+
+## FAQ
+
+**Q: Does this work in production?**
+
+No. `latency-lab` is designed for local development and CI testing. Never use it in production — it intentionally degrades request handling.
+
+**Q: Can I compose multiple presets?**
+
+Yes, using object spread:
+
+```ts
+const combined = {
+  ...presets.slow3g,
+  failureRate: 0.2,
+  excludeRoutes: ['/health'],
+};
+```
+
+**Q: Does it buffer response bodies?**
+
+No. Delay is injected before the request reaches your handler. Response streaming is unaffected.
+
+**Q: What does `tcp-drop` do in HTTP middleware?**
+
+True TCP drops require operating at the socket level and cannot be done cleanly inside HTTP middleware. In `latency-lab`, `tcp-drop` approximates a dropped connection by destroying the socket (`res.socket?.destroy()` in Express, returning a 503 in Next.js). The behavior is documented in each adapter.
+
+**Q: Does it affect WebSocket connections?**
+
+No. It only affects standard HTTP request/response cycles.
+
+---
+
+## Performance Notes
+
+- Zero runtime overhead when `failureRate: 0` and `baseDelay: 0` and `jitter: 0`
+- Delay is implemented with `setTimeout` — no busy-waiting, no event loop blocking
+- All calculations are synchronous and O(1)
+- No memory retained per request
+- Safe under high concurrency
+
+---
+
+## Limitations
+
+- TCP drop simulation in Express destroys the underlying socket. Some HTTP clients may retry automatically.
+- TCP drop in Next.js returns a 503 response (true socket destruction is not possible in App Router handlers).
+- Wave fluctuation uses wall-clock time (`Date.now()`), which means multiple concurrent requests at the same instant receive similar wave offsets (by design).
+- Route exclusion uses prefix matching. Regex patterns are not supported.
+
+---
+
+## Contributing
+
+Contributions are welcome! Please follow these steps to contribute:
+
+1. Fork the repository.
+2. Create a new branch for your feature or bugfix.
+3. Make your changes and ensure tests pass.
+4. Submit a pull request with a clear description of your changes.
+
+For major changes, please open an issue first to discuss what you would like to change.
+
+---
+
+## License
+
+MIT © Mahesh Trapasiya

package/dist/core.cjs

@@ -0,0 +1,146 @@
+'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);
+  });
+}
+
+exports.calculateDelay = calculateDelay;
+exports.isExcluded = isExcluded;
+exports.pickErrorCode = pickErrorCode;
+exports.resolveFailureType = resolveFailureType;
+exports.shouldFail = shouldFail;
+exports.sleep = sleep;
+exports.validateChaosOptions = validateChaosOptions;
+//# sourceMappingURL=core.cjs.map
+//# sourceMappingURL=core.cjs.map

package/dist/core.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/core.ts"],"names":[],"mappings":"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","file":"core.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"]}