fetch-network-simulator

A development-time API request/response network behavior simulator for frontend applications.

This library intercepts the global fetch function and modifies how real HTTP requests behave before responses reach your application.

It does not mock APIs. It operates on real network calls at the JavaScript request/response layer.

What It Simulates

• Artificial latency (slow API responses)
• Packet loss (random request failures)
• Automatic retry behavior
• Stale or out-of-order responses
• Concurrency limits (burst control)
• Bandwidth throttling

This allows you to validate UI behavior under unstable network conditions during development.

Installation

Install as a development dependency:

npm install fetch-network-simulator --save-dev

Initialization (Important)

The simulator must be enabled at your application entry point.

Place it in:

• main.js
• main.jsx
• index.js
• Or the top-level bootstrap file

Do not initialize it inside components or request utilities.

Example:

import { enableNetworkSimulator } from "fetch-network-simulator";

if (process.env.NODE_ENV === "development") {
  enableNetworkSimulator({
    debug: true,

    latency: { enabled: true, delayMs: 1500 },
    packetLoss: { enabled: true, lossRate: 0.3 },
    retry: { enabled: true, maxAttempts: 3, retryDelayMs: 200 },
    staleResponse: { enabled: true, staleProbability: 0.5 },
    burstControl: { enabled: true, maxConcurrent: 1 },
    networkSpeed: { enabled: true, kbps: 500 }
  });
}

Why at the root?

Because the simulator wraps the global fetch. If initialized late, earlier requests may bypass interception.

Disable

import { disableNetworkSimulator } from "fetch-network-simulator";

disableNetworkSimulator();

Debug Mode

Enable structured request lifecycle logs:

debug: true

When enabled, the simulator groups logs in the console for each request.

Logged lifecycle events include:

• Request start
• Applied rules
• Artificial delay injection
• Retry attempts
• Failures
• Final resolution
• Response ordering behavior

This helps identify:

• Race conditions
• Incorrect retry handling
• State overwrites
• Missing loading or error states

If debug is not set or false, the simulator runs silently.

How It Works

The library replaces the global fetch with a wrapped version.

Normal flow:

Application → fetch → network → response

With simulator:

Application → fetch → simulator → rule engine → real fetch → modified response → application

Each network behavior is implemented as a rule in a deterministic execution pipeline.

Built-in Rules

• LatencyRule
• PacketLossRule
• RetryRule
• StaleResponseRule
• BurstControlRule
• NetworkSpeedRule

Each rule supports lifecycle hooks:

• beforeRequest(context)
• afterResponse(context, response)
• onError(context, error)

Rules execute in a predictable order and can be extended.

Scope & Limitations

• Browser-only
• Intercepts fetch only
• Operates at the API request/response layer
• Not a TCP-level or OS-level network simulator
• Not an API mocking framework

It modifies real HTTP requests at runtime inside JavaScript.

Roadmap

Planned improvements:

• Request cancellation simulation (AbortController)
• Response reordering / packet ordering simulation
• Enhanced deterministic debugging controls

Source

Repository and documentation:

https://github.com/thisiskps/fetch-network-simulator

License

MIT