use-abort 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,248 @@
+# use-abort
+
+A lightweight, production-ready React hook for safely handling async API calls with automatic request cancellation using `AbortController`.
+
+## Features
+
+✅ **Automatic Cancellation** - Aborts previous requests when a new one starts  
+✅ **Cleanup on Unmount** - Automatically cancels pending requests when component unmounts  
+✅ **Stale Response Prevention** - Ensures only the latest request updates state  
+✅ **Error Handling** - Gracefully handles errors while ignoring abort errors  
+✅ **TypeScript First** - Full type safety with TypeScript generics  
+✅ **Zero Dependencies** - Only requires React (peer dependency)  
+✅ **Framework Agnostic** - Works with any async function (fetch, axios, etc.)
+
+## Installation
+
+```bash
+npm install use-abort
+```
+
+```bash
+yarn add use-abort
+```
+
+```bash
+pnpm add use-abort
+```
+
+## Usage
+
+### Basic Example
+
+```tsx
+import { useAbort } from "use-abort";
+
+// Define your async function (must accept AbortSignal as first parameter)
+const fetchUser = async (signal: AbortSignal, userId: string) => {
+  const response = await fetch(`/api/users/${userId}`, { signal });
+  if (!response.ok) throw new Error("Failed to fetch user");
+  return response.json();
+};
+
+function UserProfile({ userId }: { userId: string }) {
+  const { run, cancel, data, error, loading } = useAbort(fetchUser);
+
+  useEffect(() => {
+    run(userId);
+  }, [userId, run]);
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  if (data) return <div>User: {data.name}</div>;
+  return null;
+}
+```
+
+### Search with Auto-Cancel Example
+
+```tsx
+import { useAbort } from "use-abort";
+import { useState, useEffect } from "react";
+
+const searchAPI = async (signal: AbortSignal, query: string) => {
+  const response = await fetch(`/api/search?q=${query}`, { signal });
+  return response.json();
+};
+
+function SearchBox() {
+  const [query, setQuery] = useState("");
+  const { run, cancel, data, error, loading } = useAbort(searchAPI);
+
+  // Debounced search with automatic cancellation
+  useEffect(() => {
+    if (query.trim()) {
+      const timer = setTimeout(() => run(query), 300);
+      return () => clearTimeout(timer);
+    }
+  }, [query, run]);
+
+  return (
+    <div>
+      <input
+        value={query}
+        onChange={(e) => setQuery(e.target.value)}
+        placeholder="Search..."
+      />
+      <button onClick={cancel} disabled={!loading}>
+        Cancel
+      </button>
+      {loading && <div>Searching...</div>}
+      {error && <div>Error: {error.message}</div>}
+      {data && <div>Results: {data.results.length}</div>}
+    </div>
+  );
+}
+```
+
+### With Axios
+
+```tsx
+import axios from "axios";
+import { useAbort } from "use-abort";
+
+const fetchData = async (signal: AbortSignal, endpoint: string) => {
+  const { data } = await axios.get(endpoint, { signal });
+  return data;
+};
+
+function DataFetcher() {
+  const { run, data, error, loading } = useAbort(fetchData);
+
+  useEffect(() => {
+    run("/api/data");
+  }, [run]);
+
+  // Component rendering...
+}
+```
+
+### With Custom Headers
+
+```tsx
+const fetchWithAuth = async (
+  signal: AbortSignal,
+  url: string,
+  token: string,
+) => {
+  const response = await fetch(url, {
+    signal,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+    },
+  });
+  return response.json();
+};
+
+function ProtectedData({ token }: { token: string }) {
+  const { run, data, error, loading } = useAbort(fetchWithAuth);
+
+  useEffect(() => {
+    run("/api/protected", token);
+  }, [token, run]);
+
+  // Component rendering...
+}
+```
+
+## API
+
+### `useAbort<TArgs, TData>(asyncFunction)`
+
+#### Parameters
+
+- **`asyncFunction`**: `(signal: AbortSignal, ...args: TArgs) => Promise<TData>`
+  - An async function that accepts an `AbortSignal` as its first parameter
+  - Can accept any number of additional arguments
+  - Must return a Promise
+
+#### Returns
+
+An object with the following properties:
+
+- **`run`**: `(...args: TArgs) => Promise<void>`
+  - Executes the async function with the provided arguments
+  - Automatically cancels any previous pending request
+  - Passes an `AbortSignal` as the first argument
+
+- **`cancel`**: `() => void`
+  - Manually cancels the currently running request
+  - Safe to call even if no request is running
+
+- **`data`**: `TData | null`
+  - The data returned from the most recent successful request
+  - `null` if no request has completed successfully yet
+
+- **`error`**: `Error | null`
+  - The error from the most recent failed request
+  - `null` if no error has occurred or request is in progress
+  - Abort errors are automatically filtered out
+
+- **`loading`**: `boolean`
+  - `true` when a request is in progress
+  - `false` otherwise
+
+## TypeScript Support
+
+The hook is fully typed and provides excellent type inference:
+
+```tsx
+// Type inference works automatically
+const fetchUser = async (signal: AbortSignal, id: number) => {
+  const response = await fetch(`/api/users/${id}`, { signal });
+  return response.json() as Promise<User>;
+};
+
+// TypeScript knows that:
+// - run() expects a number argument
+// - data is User | null
+const { run, data } = useAbort(fetchUser);
+
+run(123); // ✅ Correct
+run("123"); // ❌ Type error
+```
+
+## How It Works
+
+1. **Automatic Abort**: When `run()` is called, any previous request is automatically aborted before starting the new one
+2. **Unmount Cleanup**: The hook automatically aborts pending requests when the component unmounts
+3. **Stale Response Prevention**: Uses request IDs to ensure only the latest request can update state
+4. **Error Filtering**: Automatically filters out `AbortError` to avoid showing errors for intentionally cancelled requests
+
+## Best Practices
+
+1. **Always pass AbortSignal to your API calls**:
+
+   ```tsx
+   fetch(url, { signal }); // ✅ Good
+   fetch(url); // ❌ Won't be cancellable
+   ```
+
+2. **Memoize the async function if needed**:
+
+   ```tsx
+   const fetchData = useCallback(
+     async (signal: AbortSignal, id: string) => {
+       // ...
+     },
+     [dependency],
+   );
+   const { run } = useAbort(fetchData);
+   ```
+
+3. **Handle errors appropriately**:
+   ```tsx
+   if (error) {
+     // Show user-friendly error message
+     return <ErrorMessage error={error} />;
+   }
+   ```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Type for async functions that accept an AbortSignal
+ */
+export type AbortableAsyncFunction<TArgs extends any[], TData> = (signal: AbortSignal, ...args: TArgs) => Promise<TData>;
+/**
+ * Return type of the useAbort hook
+ */
+export interface UseAbortReturn<TArgs extends any[], TData> {
+    /** Execute the async function with given arguments */
+    run: (...args: TArgs) => Promise<void>;
+    /** Cancel the currently running request */
+    cancel: () => void;
+    /** Data returned from the async function */
+    data: TData | null;
+    /** Error that occurred during execution (excluding abort errors) */
+    error: Error | null;
+    /** Whether a request is currently in progress */
+    loading: boolean;
+}
+/**
+ * A React hook for safely handling async API calls with AbortController.
+ *
+ * Automatically:
+ * - Aborts previous requests when a new one starts
+ * - Aborts requests on component unmount
+ * - Prevents stale responses from updating state
+ * - Handles errors gracefully (ignoring abort errors)
+ *
+ * @param asyncFunction - An async function that accepts an AbortSignal as its first parameter
+ * @returns Object containing run, cancel, data, error, and loading
+ *
+ * @example
+ * ```tsx
+ * const fetchUser = async (signal: AbortSignal, userId: string) => {
+ *   const response = await fetch(`/api/users/${userId}`, { signal });
+ *   return response.json();
+ * };
+ *
+ * function UserProfile({ userId }: { userId: string }) {
+ *   const { run, cancel, data, error, loading } = useAbort(fetchUser);
+ *
+ *   useEffect(() => {
+ *     run(userId);
+ *   }, [userId]);
+ *
+ *   if (loading) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *   if (data) return <div>{data.name}</div>;
+ *   return null;
+ * }
+ * ```
+ */
+export declare function useAbort<TArgs extends any[], TData>(asyncFunction: AbortableAsyncFunction<TArgs, TData>): UseAbortReturn<TArgs, TData>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,MAAM,sBAAsB,CAAC,KAAK,SAAS,GAAG,EAAE,EAAE,KAAK,IAAI,CAC/D,MAAM,EAAE,WAAW,EACnB,GAAG,IAAI,EAAE,KAAK,KACX,OAAO,CAAC,KAAK,CAAC,CAAC;AAEpB;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,KAAK,SAAS,GAAG,EAAE,EAAE,KAAK;IACxD,sDAAsD;IACtD,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,2CAA2C;IAC3C,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,4CAA4C;IAC5C,IAAI,EAAE,KAAK,GAAG,IAAI,CAAC;IACnB,oEAAoE;IACpE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,iDAAiD;IACjD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,QAAQ,CAAC,KAAK,SAAS,GAAG,EAAE,EAAE,KAAK,EACjD,aAAa,EAAE,sBAAsB,CAAC,KAAK,EAAE,KAAK,CAAC,GAClD,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,CAmF9B"}

package/dist/index.esm.js

@@ -0,0 +1,113 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { useCallback, useEffect, useRef, useState } from "react";
+/**
+ * A React hook for safely handling async API calls with AbortController.
+ *
+ * Automatically:
+ * - Aborts previous requests when a new one starts
+ * - Aborts requests on component unmount
+ * - Prevents stale responses from updating state
+ * - Handles errors gracefully (ignoring abort errors)
+ *
+ * @param asyncFunction - An async function that accepts an AbortSignal as its first parameter
+ * @returns Object containing run, cancel, data, error, and loading
+ *
+ * @example
+ * ```tsx
+ * const fetchUser = async (signal: AbortSignal, userId: string) => {
+ *   const response = await fetch(`/api/users/${userId}`, { signal });
+ *   return response.json();
+ * };
+ *
+ * function UserProfile({ userId }: { userId: string }) {
+ *   const { run, cancel, data, error, loading } = useAbort(fetchUser);
+ *
+ *   useEffect(() => {
+ *     run(userId);
+ *   }, [userId]);
+ *
+ *   if (loading) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *   if (data) return <div>{data.name}</div>;
+ *   return null;
+ * }
+ * ```
+ */
+export function useAbort(asyncFunction) {
+    const [data, setData] = useState(null);
+    const [error, setError] = useState(null);
+    const [loading, setLoading] = useState(false);
+    // Keep track of the current AbortController
+    const abortControllerRef = useRef(null);
+    // Keep track of the latest request ID to prevent stale updates
+    const requestIdRef = useRef(0);
+    /**
+     * Cancel the currently running request
+     */
+    const cancel = useCallback(() => {
+        if (abortControllerRef.current) {
+            abortControllerRef.current.abort();
+            abortControllerRef.current = null;
+            setLoading(false);
+        }
+    }, []);
+    /**
+     * Execute the async function with automatic abort handling
+     */
+    const run = useCallback((...args) => __awaiter(this, void 0, void 0, function* () {
+        // Cancel any previous request
+        cancel();
+        // Create a new AbortController for this request
+        const controller = new AbortController();
+        abortControllerRef.current = controller;
+        // Increment and capture the current request ID
+        requestIdRef.current += 1;
+        const currentRequestId = requestIdRef.current;
+        // Reset error and set loading state
+        setError(null);
+        setLoading(true);
+        try {
+            // Execute the async function with the abort signal
+            const result = yield asyncFunction(controller.signal, ...args);
+            // Only update state if this is still the latest request
+            if (currentRequestId === requestIdRef.current) {
+                setData(result);
+                setLoading(false);
+            }
+        }
+        catch (err) {
+            // Only update state if this is still the latest request
+            if (currentRequestId === requestIdRef.current) {
+                // Ignore abort errors
+                if (err instanceof Error && err.name === "AbortError") {
+                    setLoading(false);
+                    return;
+                }
+                // Handle other errors
+                setError(err instanceof Error ? err : new Error(String(err)));
+                setLoading(false);
+            }
+        }
+    }), [asyncFunction, cancel]);
+    // Clean up on unmount
+    useEffect(() => {
+        return () => {
+            cancel();
+        };
+    }, [cancel]);
+    return {
+        run,
+        cancel,
+        data,
+        error,
+        loading,
+    };
+}

package/dist/index.js

@@ -0,0 +1,116 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useAbort = useAbort;
+const react_1 = require("react");
+/**
+ * A React hook for safely handling async API calls with AbortController.
+ *
+ * Automatically:
+ * - Aborts previous requests when a new one starts
+ * - Aborts requests on component unmount
+ * - Prevents stale responses from updating state
+ * - Handles errors gracefully (ignoring abort errors)
+ *
+ * @param asyncFunction - An async function that accepts an AbortSignal as its first parameter
+ * @returns Object containing run, cancel, data, error, and loading
+ *
+ * @example
+ * ```tsx
+ * const fetchUser = async (signal: AbortSignal, userId: string) => {
+ *   const response = await fetch(`/api/users/${userId}`, { signal });
+ *   return response.json();
+ * };
+ *
+ * function UserProfile({ userId }: { userId: string }) {
+ *   const { run, cancel, data, error, loading } = useAbort(fetchUser);
+ *
+ *   useEffect(() => {
+ *     run(userId);
+ *   }, [userId]);
+ *
+ *   if (loading) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *   if (data) return <div>{data.name}</div>;
+ *   return null;
+ * }
+ * ```
+ */
+function useAbort(asyncFunction) {
+    const [data, setData] = (0, react_1.useState)(null);
+    const [error, setError] = (0, react_1.useState)(null);
+    const [loading, setLoading] = (0, react_1.useState)(false);
+    // Keep track of the current AbortController
+    const abortControllerRef = (0, react_1.useRef)(null);
+    // Keep track of the latest request ID to prevent stale updates
+    const requestIdRef = (0, react_1.useRef)(0);
+    /**
+     * Cancel the currently running request
+     */
+    const cancel = (0, react_1.useCallback)(() => {
+        if (abortControllerRef.current) {
+            abortControllerRef.current.abort();
+            abortControllerRef.current = null;
+            setLoading(false);
+        }
+    }, []);
+    /**
+     * Execute the async function with automatic abort handling
+     */
+    const run = (0, react_1.useCallback)((...args) => __awaiter(this, void 0, void 0, function* () {
+        // Cancel any previous request
+        cancel();
+        // Create a new AbortController for this request
+        const controller = new AbortController();
+        abortControllerRef.current = controller;
+        // Increment and capture the current request ID
+        requestIdRef.current += 1;
+        const currentRequestId = requestIdRef.current;
+        // Reset error and set loading state
+        setError(null);
+        setLoading(true);
+        try {
+            // Execute the async function with the abort signal
+            const result = yield asyncFunction(controller.signal, ...args);
+            // Only update state if this is still the latest request
+            if (currentRequestId === requestIdRef.current) {
+                setData(result);
+                setLoading(false);
+            }
+        }
+        catch (err) {
+            // Only update state if this is still the latest request
+            if (currentRequestId === requestIdRef.current) {
+                // Ignore abort errors
+                if (err instanceof Error && err.name === "AbortError") {
+                    setLoading(false);
+                    return;
+                }
+                // Handle other errors
+                setError(err instanceof Error ? err : new Error(String(err)));
+                setLoading(false);
+            }
+        }
+    }), [asyncFunction, cancel]);
+    // Clean up on unmount
+    (0, react_1.useEffect)(() => {
+        return () => {
+            cancel();
+        };
+    }, [cancel]);
+    return {
+        run,
+        cancel,
+        data,
+        error,
+        loading,
+    };
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "use-abort",
+  "version": "1.0.0",
+  "description": "A React hook for safely handling async API calls with AbortController",
+  "main": "dist/index.js",
+  "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "npm run build:cjs && npm run build:esm && npm run build:types",
+    "build:cjs": "tsc",
+    "build:esm": "tsc --module esnext --outDir dist/esm && mv dist/esm/index.js dist/index.esm.js && rm -rf dist/esm",
+    "build:types": "tsc --emitDeclarationOnly --declaration --outDir dist",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "react",
+    "hooks",
+    "abort",
+    "abortcontroller",
+    "async",
+    "fetch",
+    "cancel",
+    "typescript"
+  ],
+  "author": "Suraj Sharma",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "react": "^18.2.0",
+    "typescript": "^5.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourusername/use-abort.git"
+  }
+}