@mdus/use-http-request-hook

A production-ready React hook for making HTTP requests with built-in caching, debounce, waterfall protection, and AbortController.

This lightweight hook abstracts away the complexity of fetch, providing a robust solution for data fetching that handles race conditions, duplicates, and component unmounting automatically.

---

✨ Features

• ✅ Universal HTTP Support: Handles GET, POST, PUT, DELETE and others. Automatically serializes JSON bodies and sets Content-Type.
• ⚡ Smart Caching: Built-in LRU (Least Recently Used) caching strategy (max 100 entries) for GET requests to minimize network load.
• 🛡️ Waterfall Protection: Implements request deduplication. If two components request the same URL simultaneously, only one network request is fired.
• 🛑 Auto-Cancellation: Uses AbortController to automatically cancel in-flight requests when the component unmounts, preventing "state update on unmounted component" errors.
• ⏱️ Debounce Support: Built-in debounce capability, making it perfect for search inputs and dynamic filters.

---

📦 Installation

# npm
npm install @mdus/use-http-request-hook

# yarn
yarn add @mdus/use-http-request-hook

# pnpm
pnpm add @mdus/use-http-request-hook

---

💻 Quick Start

1. Basic GET Request

Fetch data effortlessly with automatic loading and error states.

import React from 'react';
import useHttpRequest from '@mdus/use-http-request-hook';

const UserProfile = ({ userId }) => {
  const { data, isLoading, error } = useHttpRequest(
    `https://jsonplaceholder.typicode.com/users/${userId}`,
  );

  if (isLoading) return <div className="spinner">Loading user...</div>;
  if (error) return <div className="error">Error: {error}</div>;
  if (!data) return null;

  return (
    <div className="card">
      <h2>{data.name}</h2>
      <p>Email: {data.email}</p>
    </div>
  );
};

2. POST/DELETE Requests & Options

The hook supports complex configurations. Changing options (like body) triggers the request, or you can use refetch to trigger it manually.

import React, { useState } from 'react';
import useHttpRequest from '@mdus/use-http-request-hook';

const CreatePost = () => {
  const [shouldCreate, setShouldCreate] = useState(false);

  // The hook runs when 'url' is provided.
  // We pass null initially to prevent execution until ready.
  const { data, isLoading, error } = useHttpRequest(
    shouldCreate ? 'https://jsonplaceholder.typicode.com/posts' : null,
    {
      method: 'POST',
      body: {
        title: 'foo',
        body: 'bar',
        userId: 1,
      },
      headers: {
        Authorization: 'Bearer my-token',
      },
    },
  );

  return (
    <div>
      <button onClick={() => setShouldCreate(true)} disabled={isLoading}>
        {isLoading ? 'Creating...' : 'Create Post'}
      </button>

      {error && <p style={{ color: 'red' }}>Failed: {error}</p>}

      {data && <div style={{ color: 'green' }}>Created Post ID: {data.id}</div>}
    </div>
  );
};

---

📖 API Reference

useHttpRequest(url, options)

Arguments

Argument	Type	Description
url	string | null	The API endpoint URL. Pass null to pause/skip the request.
options	object	(Optional) Configuration object for the request.

Options Object

Property	Default	Description
method	'GET'	HTTP method (GET, POST, PUT, DELETE, etc.).
headers	{}	Custom request headers. Content-Type: application/json is added automatically if a body is present.
body	null	Request body. If provided, it is automatically stringified.
debounce	0	Delay in milliseconds before executing the request. Useful for search inputs.

Return Values

Property	Type	Description
data	any	The parsed JSON response from the API. null until loaded.
error	string | null	Error message if the request fails (network error or non-200 status).
isLoading	boolean	true while the request is in flight or debouncing.
refetch	function	Function to manually trigger the request again using the current options.

Global Utilities

The package exports utility functions to manage the internal cache.

import { clearCache, invalidateURL } from '@mdus/use-http-request-hook';

// Clear the entire internal cache
clearCache();

// Remove a specific URL from the cache and in-flight tracking
invalidateURL('https://api.example.com/users/1');

---

🛠 Under the Hood

🚀 In-Flight Deduplication

To prevent "waterfalls" or double-fetching, this library maintains a global inFlightMap. If Component A requests /api/user/1 and Component B requests /api/user/1 while the first is still pending, only one network call is made. Both components subscribe to the same promise.

🧹 Auto-Cleanup

Every request generates an AbortController. If the component unmounts or the url changes before the request completes, the abort() signal is fired. This ensures your application stays performant and avoids memory leaks from stale asynchronous operations.

---

Developed with ❤️ by Md Umar Siddique