latency-lab 1.0.0

package/dist/types.d.cts

@@ -0,0 +1,89 @@
+/**
+ * How a simulated failure is expressed to the client.
+ *
+ * - `'http-error'`  — Respond with an HTTP error status code drawn from `errorCodes`.
+ * - `'tcp-drop'`    — Approximate a TCP connection drop by destroying the socket
+ *                     (Express) or returning a 503 (Next.js, where true socket
+ *                     destruction is unavailable in App Router handlers).
+ * - `'random'`      — Randomly choose between `'http-error'` and `'tcp-drop'`
+ *                     each time a failure occurs.
+ */
+type FailureType = 'http-error' | 'tcp-drop' | 'random';
+/**
+ * Resolved failure type after `'random'` has been evaluated.
+ * Never `'random'` — always a concrete action.
+ */
+type ResolvedFailureType = Exclude<FailureType, 'random'>;
+/**
+ * Core chaos configuration.
+ *
+ * All time values are in **milliseconds** unless otherwise noted.
+ */
+interface ChaosOptions {
+    /**
+     * Base latency added to every request in milliseconds.
+     * Must be ≥ 0.
+     */
+    baseDelay: number;
+    /**
+     * Maximum magnitude of random jitter added to or subtracted from
+     * `baseDelay` in milliseconds. Must be ≥ 0.
+     *
+     * Actual jitter per request is sampled uniformly from `[-jitter, +jitter]`.
+     */
+    jitter: number;
+    /**
+     * Period of a sine-wave fluctuation applied on top of jitter, in **seconds**.
+     *
+     * This simulates slowly oscillating network quality (e.g., a roaming device
+     * moving in and out of signal). When omitted, no wave fluctuation is applied.
+     *
+     * Must be > 0 when provided.
+     */
+    wavePeriod?: number;
+    /**
+     * Probability that a given request results in a simulated failure.
+     * Must be in the range [0, 1].
+     *
+     * - `0`   → failures never occur
+     * - `1`   → every request fails
+     * - `0.1` → ~10% of requests fail
+     */
+    failureRate: number;
+    /**
+     * Determines how simulated failures are expressed to callers.
+     */
+    failureType: FailureType;
+    /**
+     * Pool of HTTP status codes to choose from when responding with an HTTP error.
+     * Must contain at least one entry.
+     *
+     * Only used when `failureType` resolves to `'http-error'`.
+     */
+    errorCodes: number[];
+}
+/**
+ * Options passed to framework-level middleware / handler wrappers.
+ * Extends `ChaosOptions` with request-filtering capabilities.
+ */
+interface MiddlewareOptions extends ChaosOptions {
+    /**
+     * List of URL path prefixes that should bypass chaos injection entirely.
+     *
+     * Matching is prefix-based and case-sensitive.
+     *
+     * @example
+     * excludeRoutes: ['/health', '/metrics', '/_next']
+     */
+    excludeRoutes?: string[];
+}
+/**
+ * Structured error thrown when a `ChaosOptions` or `MiddlewareOptions`
+ * object fails validation.
+ */
+declare class ChaosConfigError extends Error {
+    readonly name = "ChaosConfigError";
+    constructor(message: string);
+}
+
+export { ChaosConfigError, type ChaosOptions, type FailureType, type MiddlewareOptions, type ResolvedFailureType };

package/dist/types.d.ts

@@ -0,0 +1,89 @@
+/**
+ * How a simulated failure is expressed to the client.
+ *
+ * - `'http-error'`  — Respond with an HTTP error status code drawn from `errorCodes`.
+ * - `'tcp-drop'`    — Approximate a TCP connection drop by destroying the socket
+ *                     (Express) or returning a 503 (Next.js, where true socket
+ *                     destruction is unavailable in App Router handlers).
+ * - `'random'`      — Randomly choose between `'http-error'` and `'tcp-drop'`
+ *                     each time a failure occurs.
+ */
+type FailureType = 'http-error' | 'tcp-drop' | 'random';
+/**
+ * Resolved failure type after `'random'` has been evaluated.
+ * Never `'random'` — always a concrete action.
+ */
+type ResolvedFailureType = Exclude<FailureType, 'random'>;
+/**
+ * Core chaos configuration.
+ *
+ * All time values are in **milliseconds** unless otherwise noted.
+ */
+interface ChaosOptions {
+    /**
+     * Base latency added to every request in milliseconds.
+     * Must be ≥ 0.
+     */
+    baseDelay: number;
+    /**
+     * Maximum magnitude of random jitter added to or subtracted from
+     * `baseDelay` in milliseconds. Must be ≥ 0.
+     *
+     * Actual jitter per request is sampled uniformly from `[-jitter, +jitter]`.
+     */
+    jitter: number;
+    /**
+     * Period of a sine-wave fluctuation applied on top of jitter, in **seconds**.
+     *
+     * This simulates slowly oscillating network quality (e.g., a roaming device
+     * moving in and out of signal). When omitted, no wave fluctuation is applied.
+     *
+     * Must be > 0 when provided.
+     */
+    wavePeriod?: number;
+    /**
+     * Probability that a given request results in a simulated failure.
+     * Must be in the range [0, 1].
+     *
+     * - `0`   → failures never occur
+     * - `1`   → every request fails
+     * - `0.1` → ~10% of requests fail
+     */
+    failureRate: number;
+    /**
+     * Determines how simulated failures are expressed to callers.
+     */
+    failureType: FailureType;
+    /**
+     * Pool of HTTP status codes to choose from when responding with an HTTP error.
+     * Must contain at least one entry.
+     *
+     * Only used when `failureType` resolves to `'http-error'`.
+     */
+    errorCodes: number[];
+}
+/**
+ * Options passed to framework-level middleware / handler wrappers.
+ * Extends `ChaosOptions` with request-filtering capabilities.
+ */
+interface MiddlewareOptions extends ChaosOptions {
+    /**
+     * List of URL path prefixes that should bypass chaos injection entirely.
+     *
+     * Matching is prefix-based and case-sensitive.
+     *
+     * @example
+     * excludeRoutes: ['/health', '/metrics', '/_next']
+     */
+    excludeRoutes?: string[];
+}
+/**
+ * Structured error thrown when a `ChaosOptions` or `MiddlewareOptions`
+ * object fails validation.
+ */
+declare class ChaosConfigError extends Error {
+    readonly name = "ChaosConfigError";
+    constructor(message: string);
+}
+
+export { ChaosConfigError, type ChaosOptions, type FailureType, type MiddlewareOptions, type ResolvedFailureType };

package/dist/types.js

@@ -0,0 +1,12 @@
+// src/types.ts
+var ChaosConfigError = class extends Error {
+  name = "ChaosConfigError";
+  constructor(message) {
+    super(message);
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+export { ChaosConfigError };
+//# sourceMappingURL=types.js.map
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +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"]}

package/package.json

@@ -0,0 +1,127 @@
+{
+  "name": "latency-lab",
+  "version": "1.0.0",
+  "description": "Inject realistic network chaos into backend applications during local development and testing",
+  "keywords": [
+    "network",
+    "chaos",
+    "latency",
+    "testing",
+    "middleware",
+    "express",
+    "nextjs",
+    "development",
+    "simulation",
+    "fault-injection"
+  ],
+  "author": "Mahesh Trapasiya",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MaheshTrapasiya/latency-lab.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MaheshTrapasiya/latency-lab/issues"
+  },
+  "homepage": "https://github.com/MaheshTrapasiya/latency-lab#readme",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./core": {
+      "import": {
+        "types": "./dist/core.d.ts",
+        "default": "./dist/core.js"
+      },
+      "require": {
+        "types": "./dist/core.d.cts",
+        "default": "./dist/core.cjs"
+      }
+    },
+    "./express": {
+      "import": {
+        "types": "./dist/express.d.ts",
+        "default": "./dist/express.js"
+      },
+      "require": {
+        "types": "./dist/express.d.cts",
+        "default": "./dist/express.cjs"
+      }
+    },
+    "./next": {
+      "import": {
+        "types": "./dist/next.d.ts",
+        "default": "./dist/next.js"
+      },
+      "require": {
+        "types": "./dist/next.d.cts",
+        "default": "./dist/next.cjs"
+      }
+    },
+    "./presets": {
+      "import": {
+        "types": "./dist/presets.d.ts",
+        "default": "./dist/presets.js"
+      },
+      "require": {
+        "types": "./dist/presets.d.cts",
+        "default": "./dist/presets.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "build:check": "tsc -p tsconfig.build.json --noEmit",
+    "dev": "tsup --watch",
+    "lint": "eslint src test",
+    "lint:fix": "eslint src test --fix",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build:check && npm run lint && npm run test && npm run build",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "@vitest/coverage-v8": "^2.1.9",
+    "eslint": "^9.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.9"
+  },
+  "peerDependencies": {
+    "express": "^4.0.0 || ^5.0.0",
+    "next": "^14.0.0 || ^15.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}