axios-react-hook 1.0.0 → 2.0.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 MUHAMMED RASHID
-
-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.
+MIT License
+
+Copyright (c) 2026 Muhammed Rashid
+
+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

@@ -1,47 +1,152 @@
-# axios-react-hook
-
-A simple and customizable React hook for making HTTP requests using Axios.
-
-## Features
-
-- ✅ Supports GET, POST, PUT, DELETE, PATCH, etc.
-- ✅ Auto and manual fetching
-- ✅ Refetch support
-- ✅ Pass your own Axios instance
-
-## Installation
-
-```bash
-npm install axios-react-hook
-```
-
-## Usage
-
-```js
-import useAxios from 'axios-react-hook';
-import axiosInstance from './axiosInstance'; // Optional custom instance
-
-const { data, loading, error, refetch } = useAxios(
-  'https://jsonplaceholder.typicode.com/posts',
-  'get',
-  null,
-  true,
-  axiosInstance
-);
-```
-
-## API
-
-### Parameters
-
-| Param         | Type     | Default | Description                            |
-|---------------|----------|---------|----------------------------------------|
-| `url`         | `string` | —       | Request URL                            |
-| `method`      | `string` | `'get'` | HTTP method                            |
-| `data`        | `object` | `null`  | Request payload or query params        |
-| `auto`        | `boolean`| `true`  | Auto execute request on mount          |
-| `instance`    | `AxiosInstance` | `axios` | Custom Axios instance (optional) |
-
-## License
-
-MIT
+# axios-react-hook
+
+A lightweight React hook for Axios-based API calls with support for all HTTP methods.
+
+[![npm](https://img.shields.io/npm/v/axios-react-hook)](https://www.npmjs.com/package/axios-react-hook)
+[![license](https://img.shields.io/npm/l/axios-react-hook)](./LICENSE)
+
+> **v2.0.0** — V2 is now the default import.
+> Existing users on `^1.0.0` are **not affected** — npm never auto-upgrades across major versions.
+> If you upgrade manually, see the [migration guide](#migrating-v1--v2) below.
+
+---
+
+## Features
+
+**Default (V2)**
+- ✅ Object-based config — readable, no positional-arg juggling
+- ✅ Query `params` serialised into the URL automatically
+- ✅ Per-request `headers` and `timeout`
+- ✅ `onSuccess` / `onError` callbacks
+- ✅ `AbortController` cancellation — prevents race conditions and unmount warnings
+- ✅ HTTP `status` code in return value
+- ✅ `cancel()` to abort in-flight requests manually
+- ✅ Supports GET, POST, PUT, PATCH, DELETE and more
+- ✅ Auto-fetch on mount, manual trigger via `refetch()`
+- ✅ Pass your own Axios instance
+
+**V1** (still available at `axios-react-hook/v1`)
+- ✅ Positional-argument API — unchanged since 1.0.0
+
+---
+
+## Installation
+
+```bash
+npm install axios-react-hook
+```
+
+---
+
+## Quick Start
+
+### V2 (default)
+
+```js
+import useAxios from 'axios-react-hook';
+
+function Posts() {
+  const { data, loading, error, status } = useAxios({
+    url: 'https://jsonplaceholder.typicode.com/posts',
+    params: { _limit: 10 },
+  });
+
+  if (loading) return <p>Loading…</p>;
+  if (error)   return <p>{status} — {error.message}</p>;
+
+  return (
+    <ul>
+      {data.map(post => <li key={post.id}>{post.title}</li>)}
+    </ul>
+  );
+}
+```
+
+### V1 (legacy)
+
+```js
+import useAxios from 'axios-react-hook/v1';
+
+function Posts() {
+  const { data, loading, error } = useAxios(
+    'https://jsonplaceholder.typicode.com/posts'
+  );
+
+  if (loading) return <p>Loading…</p>;
+  if (error)   return <p>Error: {error.message}</p>;
+
+  return (
+    <ul>
+      {data.map(post => <li key={post.id}>{post.title}</li>)}
+    </ul>
+  );
+}
+```
+
+---
+
+## Import paths
+
+| Import path           | API    | Who should use it                       |
+|-----------------------|--------|-----------------------------------------|
+| `axios-react-hook`    | **V2** | Everyone on a fresh install / new code  |
+| `axios-react-hook/v2` | V2     | Explicit V2 import (same as default)    |
+| `axios-react-hook/v1` | V1     | Users who upgraded and need the old API |
+
+---
+
+## API Reference
+
+### V2 Options
+
+| Option      | Type            | Default  | Description                                             |
+|-------------|-----------------|----------|---------------------------------------------------------|
+| `url`       | `string`        | —        | Request URL *(required)*                                |
+| `method`    | `string`        | `'get'`  | HTTP method: `get` `post` `put` `patch` `delete`        |
+| `body`      | `any`           | `null`   | Request body (POST / PUT / PATCH / DELETE)              |
+| `params`    | `object`        | `null`   | URL query parameters e.g. `{ page: 1, limit: 10 }`     |
+| `headers`   | `object`        | `null`   | Per-request headers                                     |
+| `timeout`   | `number`        | `0`      | Request timeout in ms (`0` = no timeout)                |
+| `auto`      | `boolean`       | `true`   | Auto-fire on mount and whenever config changes          |
+| `instance`  | `AxiosInstance` | `axios`  | Custom axios instance                                   |
+| `onSuccess` | `Function`      | `null`   | Called with `(data, response)` on success               |
+| `onError`   | `Function`      | `null`   | Called with `(error)` on failure                        |
+
+### V2 Return value
+
+| Key       | Type       | Description                                  |
+|-----------|------------|----------------------------------------------|
+| `data`    | `any`      | Response payload                             |
+| `loading` | `boolean`  | `true` while a request is in flight          |
+| `error`   | `Error`    | Error from the last failed request           |
+| `status`  | `number`   | HTTP status code (`200`, `404`, …) or `null` |
+| `refetch` | `Function` | Manually trigger the request                 |
+| `cancel`  | `Function` | Cancel the currently in-flight request       |
+
+---
+
+## Migrating V1 → V2
+
+```js
+// Before (V1)
+import useAxios from 'axios-react-hook/v1';
+const { data, loading, error, refetch } = useAxios(url, method, body, auto, instance);
+
+// After (V2)
+import useAxios from 'axios-react-hook';
+const { data, loading, error, status, refetch, cancel } = useAxios({
+  url, method, body, auto, instance,
+});
+```
+
+---
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md).
+
+---
+
+## License
+
+MIT © [Muhammed Rashid](https://github.com/devmdrd)

package/package.json

@@ -1,16 +1,27 @@
-{
-  "name": "axios-react-hook",
-  "version": "1.0.0",
-  "description": "A lightweight React hook for Axios-based API calls with support for all HTTP methods.",
-  "main": "src/useAxios.js",
-  "keywords": ["axios", "react", "hook", "api", "http"],
-  "author": "Muhammed Rashid",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/devmdrd/axios-react-hook"
-  },
-  "dependencies": {
-    "axios": "^1.6.0"
-  }
-}
+{
+  "name": "axios-react-hook",
+  "version": "2.0.0",
+  "description": "A lightweight React hook for Axios-based API calls with support for all HTTP methods.",
+  "main": "src/useAxios.js",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./src/useAxios.js"
+  },
+  "keywords": ["axios", "react", "hook", "api", "http", "fetch"],
+  "author": "Muhammed Rashid",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/devmdrd/axios-react-hook"
+  },
+  "dependencies": {
+    "axios": "^1.6.0"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  }
+}

package/src/useAxios.js

@@ -1,33 +1,146 @@
-import { useState, useEffect } from 'react';
-import axios from 'axios';
-
-export default function useAxios(
-  url,
-  method = 'get',
-  body = null,
-  auto = true,
-  instance = axios
-) {
-  const [data, setData] = useState(null);
-  const [loading, setLoading] = useState(auto);
-  const [error, setError] = useState(null);
-
-  const fetch = async () => {
-    setLoading(true);
-    setError(null);
-    try {
-      const res = await instance[method](url, body);
-      setData(res.data);
-    } catch (err) {
-      setError(err);
-    } finally {
-      setLoading(false);
-    }
-  };
-
-  useEffect(() => {
-    if (auto) fetch();
-  }, [url]);
-
-  return { data, loading, error, refetch: fetch };
-}
+import { useState, useEffect, useCallback, useRef } from 'react';
+import axios from 'axios';
+
+/**
+ * useAxios v2
+ *
+ * An improved React hook for HTTP requests with object-based config,
+ * automatic request cancellation, per-request headers/params/timeout,
+ * and success/error callbacks.
+ *
+ * @param {object}        options
+ * @param {string}        options.url                - The request URL (required)
+ * @param {string}        [options.method='get']     - HTTP method: get | post | put | patch | delete
+ * @param {any}           [options.body=null]        - Request body / payload (POST, PUT, PATCH, DELETE)
+ * @param {object}        [options.params=null]      - URL query parameters e.g. { page: 1, limit: 10 }
+ * @param {object}        [options.headers=null]     - Per-request headers merged on top of instance defaults
+ * @param {number}        [options.timeout=0]        - Request timeout in milliseconds (0 = no timeout)
+ * @param {boolean}       [options.auto=true]        - When true, fires on mount and whenever config changes
+ * @param {AxiosInstance} [options.instance=axios]   - Custom axios instance (e.g. with interceptors or base URL)
+ * @param {Function}      [options.onSuccess]        - Called with (data, response) on a successful request
+ * @param {Function}      [options.onError]          - Called with (error) when the request fails
+ *
+ * @returns {{ data: any, loading: boolean, error: Error|null, status: number|null, refetch: Function, cancel: Function }}
+ *
+ * @example
+ * // Auto GET on mount
+ * const { data, loading, error, status } = useAxios({
+ *   url: 'https://api.example.com/posts',
+ * });
+ *
+ * @example
+ * // GET with query params
+ * const { data } = useAxios({
+ *   url: 'https://api.example.com/posts',
+ *   params: { userId: 1, _limit: 5 },
+ * });
+ *
+ * @example
+ * // Manual POST with callbacks
+ * const { refetch } = useAxios({
+ *   url: 'https://api.example.com/posts',
+ *   method: 'post',
+ *   body: { title: 'Hello', body: 'World' },
+ *   auto: false,
+ *   onSuccess: (data) => console.log('Created:', data),
+ *   onError:   (err)  => console.error('Failed:', err.message),
+ * });
+ */
+export default function useAxios(options = {}) {
+  const {
+    url,
+    method     = 'get',
+    body       = null,
+    params     = null,
+    headers    = null,
+    timeout    = 0,
+    auto       = true,
+    instance   = axios,
+    onSuccess  = null,
+    onError    = null,
+  } = options;
+
+  // ── State ──────────────────────────────────────────────────────────────────
+
+  const [data,    setData]    = useState(null);
+  // Only start in loading state when auto=true AND a URL is already provided
+  const [loading, setLoading] = useState(auto && !!url);
+  const [error,   setError]   = useState(null);
+  // HTTP status code of the last response (e.g. 200, 404) — null before first request
+  const [status,  setStatus]  = useState(null);
+
+  // Holds the AbortController for the currently in-flight request.
+  // Stored in a ref so changing it never triggers a re-render.
+  const abortRef = useRef(null);
+
+  // ── Cancel ─────────────────────────────────────────────────────────────────
+
+  // Stable reference (empty dep array) so it never causes fetch to re-create.
+  const cancel = useCallback(() => {
+    abortRef.current?.abort();
+  }, []);
+
+  // ── Fetch function ─────────────────────────────────────────────────────────
+
+  const fetch = useCallback(async () => {
+    if (!url) return; // guard — do nothing without a URL
+
+    // Cancel any previous in-flight request before starting a new one.
+    // This prevents stale responses from overwriting state (race condition fix).
+    cancel();
+    const controller = new AbortController();
+    abortRef.current = controller;
+
+    setLoading(true);
+    setError(null);
+
+    // Build the axios request config — only attach optional fields when provided
+    const config = {
+      url,
+      method: method.toLowerCase(),
+      signal: controller.signal, // ties this request to the AbortController
+    };
+    if (params)      config.params   = params;
+    if (body)        config.data     = body;
+    if (headers)     config.headers  = headers;
+    if (timeout > 0) config.timeout  = timeout;
+
+    try {
+      const res = await instance.request(config);
+      setData(res.data);
+      setStatus(res.status);
+      onSuccess?.(res.data, res); // optional success callback
+    } catch (err) {
+      // Cancellation throws a CanceledError / AbortError — ignore it silently.
+      // We do NOT update state for cancelled requests.
+      if (err.name === 'CanceledError' || err.name === 'AbortError') return;
+      setError(err);
+      setStatus(err.response?.status ?? null); // null for network errors (no response)
+      onError?.(err); // optional error callback
+    } finally {
+      // Always clear loading — success, failure, or anything else
+      setLoading(false);
+    }
+  }, [url, method, body, params, headers, timeout, instance, onSuccess, onError, cancel]);
+
+  // ── Auto-fetch ─────────────────────────────────────────────────────────────
+
+  useEffect(() => {
+    if (!url || !auto) return;
+    fetch();
+    // Cleanup: cancel the in-flight request if the component unmounts
+    // or if the config changes before the response arrives.
+    return () => cancel();
+  }, [fetch]); // fetch itself changes only when any config value changes
+
+  // ── Return ─────────────────────────────────────────────────────────────────
+
+  return {
+    data,
+    loading,
+    error,
+    status,
+    refetch: fetch, // alias — same function, more intuitive name at the call site
+    cancel,
+  };
+}