use-fetch-state 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alican Kahramaner
+
+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,188 @@
+# useFetchState
+
+![npm](https://img.shields.io/npm/v/use-fetch-state)
+![downloads](https://img.shields.io/npm/dm/use-fetch-state)
+![license](https://img.shields.io/npm/l/use-fetch-state)
+
+`useFetchState` is a lightweight and type-safe React hook for managing API requests and keeping response data in state.
+
+It provides:
+
+- 🚀 Loading state management
+- ❌ Error handling
+- 🔄 Manual request triggering
+- 🔁 Optional auto re-fetch on request change
+- 🧠 Fully generic & TypeScript friendly
+- 📦 Zero dependencies (except React)
+
+---
+
+## Installation
+
+```bash
+npm install use-fetch-state
+# or
+yarn add use-fetch-state
+```
+
+---
+
+# Quick Start
+
+```tsx
+import { useEffect } from "react";
+import { useFetchState } from "use-fetch-state";
+
+function MyComponent() {
+  const { loading, response, error, fetchData } = useFetchState({
+    fetcher: async (request) => {
+      const res = await fetch("/api/data", {
+        method: "POST",
+        body: JSON.stringify(request),
+      });
+
+      if (!res.ok) return false;
+
+      return await res.json();
+    },
+    initialRequest: { id: 1 },
+    initialResponse: null,
+  });
+
+  useEffect(() => {
+    fetchData();
+  }, []);
+
+  if (loading) return <p>Loading...</p>;
+  if (error) return <p>Error: {error.message}</p>;
+  if (response) return <pre>{JSON.stringify(response, null, 2)}</pre>;
+
+  return <p>No data.</p>;
+}
+```
+
+---
+
+# Dynamic Request Example
+
+```tsx
+import { useEffect, useState } from "react";
+import { useFetchState } from "use-fetch-state";
+
+function MyComponent() {
+  const [id, setId] = useState(1);
+
+  const {
+    loading,
+    response,
+    error,
+    fetchData,
+    setRequest,
+  } = useFetchState({
+    fetcher: async (request) => {
+      const res = await fetch(`/api/data?id=${request.id}`);
+      if (!res.ok) return false;
+      return await res.json();
+    },
+    initialRequest: { id: 1 },
+    initialResponse: null,
+    reFetchChangeRequest: true,
+  });
+
+  useEffect(() => {
+    fetchData();
+  }, []);
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const newId = parseInt(e.target.value);
+    setId(newId);
+    setRequest({ id: newId });
+  };
+
+  return (
+    <div>
+      <input type="number" value={id} onChange={handleChange} />
+
+      {loading && <p>Loading...</p>}
+      {error && <p>Error: {error.message}</p>}
+      {response && <pre>{JSON.stringify(response, null, 2)}</pre>}
+    </div>
+  );
+}
+```
+
+---
+
+# API Reference
+
+## Returned Values
+
+| Name | Type | Description |
+|------|------|-------------|
+| `loading` | `boolean` | Indicates whether the request is in progress |
+| `response` | `T \| null` | The successful API response |
+| `error` | `Error \| null` | Contains error if request fails |
+| `request` | `Req` | Current request parameters |
+| `fetchData()` | `() => Promise<void>` | Manually triggers the request |
+| `setRequest(newRequest)` | `(Req) => void` | Updates request parameters |
+
+---
+
+# Options
+
+| Option | Type | Default | Description |
+|--------|------|----------|-------------|
+| `fetcher` | `(request: Req) => Promise<T \| false>` | required | Function responsible for API request |
+| `initialRequest` | `Req` | required | Initial request parameters |
+| `initialResponse` | `T \| null` | required | Initial response state |
+| `waitCallback` | `boolean` | `false` | If true, skips initial execution |
+| `reFetchChangeRequest` | `boolean` | `false` | Automatically re-fetch when request changes |
+
+---
+
+# TypeScript Example
+
+```ts
+interface User {
+  id: number;
+  name: string;
+}
+
+const { response } = useFetchState<{ id: number }, User>({
+  fetcher: async (req) => {
+    const res = await fetch(`/api/user/${req.id}`);
+    return await res.json();
+  },
+  initialRequest: { id: 1 },
+  initialResponse: null,
+});
+```
+
+---
+
+# Error Handling
+
+If `fetcher` returns `false`, the hook will treat it as a failed request and update the `error` state.
+
+```ts
+if (!res.ok) {
+  return false;
+}
+```
+
+---
+
+# When to Use
+
+`useFetchState` is ideal when:
+
+- You need lightweight request management
+- You don't need full caching solutions like React Query
+- You want a minimal abstraction over fetch logic
+- You prefer full manual control
+
+---
+
+# License
+
+MIT

package/dist/index.cjs.js

@@ -0,0 +1,60 @@
+'use strict';
+
+var react = require('react');
+
+const useFetchState = function (options) {
+    const [request, setRequest] = react.useState(options.initialRequest);
+    const [response, setResponse] = react.useState(options.initialResponse);
+    const [loading, setLoading] = react.useState(true);
+    const [error, setError] = react.useState(null);
+    const fetchData = react.useCallback(async () => {
+        setError(null);
+        setLoading(true);
+        try {
+            const response = await options.fetcher(request);
+            if (response === false) {
+                setError(new Error("Fetch failed"));
+            }
+            else {
+                setResponse(response);
+            }
+        }
+        catch (err) {
+            setError(err);
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [setLoading, setError, setResponse, options, request]);
+    react.useEffect(() => {
+        if (!options.reFetchChangeRequest)
+            return;
+        fetchData();
+    }, [request, fetchData]);
+    const clear = react.useCallback(() => {
+        setError(null);
+        setLoading(false);
+        setRequest(options.initialRequest);
+        setResponse(options.initialResponse);
+    }, [setError, setLoading, setRequest, setResponse, options]);
+    react.useEffect(() => {
+        if (!options.waitCallback) {
+            fetchData();
+        }
+        return () => {
+            clear();
+        };
+    }, []);
+    return {
+        setRequest,
+        loading,
+        response,
+        error,
+        request,
+        fetchData,
+        clear
+    };
+};
+
+exports.useFetchState = useFetchState;
+//# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs.js","sources":["../src/useFetchState.ts"],"sourcesContent":["import { useCallback, useEffect, useState } from \"react\";\n\nexport type UseFetchStateProps<Req, Res> = {\n    fetcher: (request: Req) => Promise<Res | false>,\n    initialResponse: Res;\n    initialRequest: Req;\n    waitCallback?: boolean;\n    reFetchChangeRequest?: boolean;\n}\n\nexport const useFetchState = function <Request, Response>(options: UseFetchStateProps<Request, Response>) {\n\n    const [request, setRequest] = useState(options.initialRequest);\n    const [response, setResponse] = useState(options.initialResponse);\n    const [loading, setLoading] = useState(true);\n    const [error, setError] = useState<Error | null>(null);\n\n    const fetchData = useCallback(async () => {\n        setError(null);\n        setLoading(true)\n        try {\n            const response = await options.fetcher(request)\n\n            if (response === false) {\n                setError(new Error(\"Fetch failed\"));\n            } else {\n                setResponse(response);\n            }\n\n        } catch (err) {\n            setError(err as Error);\n        } finally {\n            setLoading(false);\n        }\n    }, [setLoading, setError, setResponse, options, request]);\n\n    useEffect(() => {\n        if (!options.reFetchChangeRequest) return;\n        fetchData();\n    }, [request, fetchData]);\n\n    const clear = useCallback(() => {\n        setError(null);\n        setLoading(false);\n        setRequest(options.initialRequest);\n        setResponse(options.initialResponse);\n    }, [setError, setLoading, setRequest, setResponse, options]);\n\n    useEffect(() => {\n        if (!options.waitCallback) {\n            fetchData();\n        }\n        return () => {\n            clear();\n        };\n    }, []);\n\n    return {\n        setRequest,\n        loading,\n        response,\n        error,\n        request,\n        fetchData,\n        clear\n    };\n}"],"names":["useState","useCallback","useEffect"],"mappings":";;;;AAUO,MAAM,aAAa,GAAG,UAA6B,OAA8C,EAAA;AAEpG,IAAA,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAGA,cAAQ,CAAC,OAAO,CAAC,cAAc,CAAC;AAC9D,IAAA,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,GAAGA,cAAQ,CAAC,OAAO,CAAC,eAAe,CAAC;IACjE,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAGA,cAAQ,CAAC,IAAI,CAAC;IAC5C,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAGA,cAAQ,CAAe,IAAI,CAAC;AAEtD,IAAA,MAAM,SAAS,GAAGC,iBAAW,CAAC,YAAW;QACrC,QAAQ,CAAC,IAAI,CAAC;QACd,UAAU,CAAC,IAAI,CAAC;AAChB,QAAA,IAAI;YACA,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC;AAE/C,YAAA,IAAI,QAAQ,KAAK,KAAK,EAAE;AACpB,gBAAA,QAAQ,CAAC,IAAI,KAAK,CAAC,cAAc,CAAC,CAAC;YACvC;iBAAO;gBACH,WAAW,CAAC,QAAQ,CAAC;YACzB;QAEJ;QAAE,OAAO,GAAG,EAAE;YACV,QAAQ,CAAC,GAAY,CAAC;QAC1B;gBAAU;YACN,UAAU,CAAC,KAAK,CAAC;QACrB;AACJ,IAAA,CAAC,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAEzDC,eAAS,CAAC,MAAK;QACX,IAAI,CAAC,OAAO,CAAC,oBAAoB;YAAE;AACnC,QAAA,SAAS,EAAE;AACf,IAAA,CAAC,EAAE,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;AAExB,IAAA,MAAM,KAAK,GAAGD,iBAAW,CAAC,MAAK;QAC3B,QAAQ,CAAC,IAAI,CAAC;QACd,UAAU,CAAC,KAAK,CAAC;AACjB,QAAA,UAAU,CAAC,OAAO,CAAC,cAAc,CAAC;AAClC,QAAA,WAAW,CAAC,OAAO,CAAC,eAAe,CAAC;AACxC,IAAA,CAAC,EAAE,CAAC,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;IAE5DC,eAAS,CAAC,MAAK;AACX,QAAA,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE;AACvB,YAAA,SAAS,EAAE;QACf;AACA,QAAA,OAAO,MAAK;AACR,YAAA,KAAK,EAAE;AACX,QAAA,CAAC;IACL,CAAC,EAAE,EAAE,CAAC;IAEN,OAAO;QACH,UAAU;QACV,OAAO;QACP,QAAQ;QACR,KAAK;QACL,OAAO;QACP,SAAS;QACT;KACH;AACL;;;;"}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import * as react from 'react';
+
+type UseFetchStateProps<Req, Res> = {
+    fetcher: (request: Req) => Promise<Res | false>;
+    initialResponse: Res;
+    initialRequest: Req;
+    waitCallback?: boolean;
+    reFetchChangeRequest?: boolean;
+};
+declare const useFetchState: <Request, Response>(options: UseFetchStateProps<Request, Response>) => {
+    setRequest: react.Dispatch<react.SetStateAction<Request>>;
+    loading: boolean;
+    response: Response;
+    error: Error | null;
+    request: Request;
+    fetchData: () => Promise<void>;
+    clear: () => void;
+};
+
+export { useFetchState };
+export type { UseFetchStateProps };

package/dist/index.esm.js

@@ -0,0 +1,58 @@
+import { useState, useCallback, useEffect } from 'react';
+
+const useFetchState = function (options) {
+    const [request, setRequest] = useState(options.initialRequest);
+    const [response, setResponse] = useState(options.initialResponse);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const fetchData = useCallback(async () => {
+        setError(null);
+        setLoading(true);
+        try {
+            const response = await options.fetcher(request);
+            if (response === false) {
+                setError(new Error("Fetch failed"));
+            }
+            else {
+                setResponse(response);
+            }
+        }
+        catch (err) {
+            setError(err);
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [setLoading, setError, setResponse, options, request]);
+    useEffect(() => {
+        if (!options.reFetchChangeRequest)
+            return;
+        fetchData();
+    }, [request, fetchData]);
+    const clear = useCallback(() => {
+        setError(null);
+        setLoading(false);
+        setRequest(options.initialRequest);
+        setResponse(options.initialResponse);
+    }, [setError, setLoading, setRequest, setResponse, options]);
+    useEffect(() => {
+        if (!options.waitCallback) {
+            fetchData();
+        }
+        return () => {
+            clear();
+        };
+    }, []);
+    return {
+        setRequest,
+        loading,
+        response,
+        error,
+        request,
+        fetchData,
+        clear
+    };
+};
+
+export { useFetchState };
+//# sourceMappingURL=index.esm.js.map

package/dist/index.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.esm.js","sources":["../src/useFetchState.ts"],"sourcesContent":["import { useCallback, useEffect, useState } from \"react\";\n\nexport type UseFetchStateProps<Req, Res> = {\n    fetcher: (request: Req) => Promise<Res | false>,\n    initialResponse: Res;\n    initialRequest: Req;\n    waitCallback?: boolean;\n    reFetchChangeRequest?: boolean;\n}\n\nexport const useFetchState = function <Request, Response>(options: UseFetchStateProps<Request, Response>) {\n\n    const [request, setRequest] = useState(options.initialRequest);\n    const [response, setResponse] = useState(options.initialResponse);\n    const [loading, setLoading] = useState(true);\n    const [error, setError] = useState<Error | null>(null);\n\n    const fetchData = useCallback(async () => {\n        setError(null);\n        setLoading(true)\n        try {\n            const response = await options.fetcher(request)\n\n            if (response === false) {\n                setError(new Error(\"Fetch failed\"));\n            } else {\n                setResponse(response);\n            }\n\n        } catch (err) {\n            setError(err as Error);\n        } finally {\n            setLoading(false);\n        }\n    }, [setLoading, setError, setResponse, options, request]);\n\n    useEffect(() => {\n        if (!options.reFetchChangeRequest) return;\n        fetchData();\n    }, [request, fetchData]);\n\n    const clear = useCallback(() => {\n        setError(null);\n        setLoading(false);\n        setRequest(options.initialRequest);\n        setResponse(options.initialResponse);\n    }, [setError, setLoading, setRequest, setResponse, options]);\n\n    useEffect(() => {\n        if (!options.waitCallback) {\n            fetchData();\n        }\n        return () => {\n            clear();\n        };\n    }, []);\n\n    return {\n        setRequest,\n        loading,\n        response,\n        error,\n        request,\n        fetchData,\n        clear\n    };\n}"],"names":[],"mappings":";;AAUO,MAAM,aAAa,GAAG,UAA6B,OAA8C,EAAA;AAEpG,IAAA,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,cAAc,CAAC;AAC9D,IAAA,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,eAAe,CAAC;IACjE,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC;IAC5C,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAe,IAAI,CAAC;AAEtD,IAAA,MAAM,SAAS,GAAG,WAAW,CAAC,YAAW;QACrC,QAAQ,CAAC,IAAI,CAAC;QACd,UAAU,CAAC,IAAI,CAAC;AAChB,QAAA,IAAI;YACA,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC;AAE/C,YAAA,IAAI,QAAQ,KAAK,KAAK,EAAE;AACpB,gBAAA,QAAQ,CAAC,IAAI,KAAK,CAAC,cAAc,CAAC,CAAC;YACvC;iBAAO;gBACH,WAAW,CAAC,QAAQ,CAAC;YACzB;QAEJ;QAAE,OAAO,GAAG,EAAE;YACV,QAAQ,CAAC,GAAY,CAAC;QAC1B;gBAAU;YACN,UAAU,CAAC,KAAK,CAAC;QACrB;AACJ,IAAA,CAAC,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAEzD,SAAS,CAAC,MAAK;QACX,IAAI,CAAC,OAAO,CAAC,oBAAoB;YAAE;AACnC,QAAA,SAAS,EAAE;AACf,IAAA,CAAC,EAAE,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;AAExB,IAAA,MAAM,KAAK,GAAG,WAAW,CAAC,MAAK;QAC3B,QAAQ,CAAC,IAAI,CAAC;QACd,UAAU,CAAC,KAAK,CAAC;AACjB,QAAA,UAAU,CAAC,OAAO,CAAC,cAAc,CAAC;AAClC,QAAA,WAAW,CAAC,OAAO,CAAC,eAAe,CAAC;AACxC,IAAA,CAAC,EAAE,CAAC,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;IAE5D,SAAS,CAAC,MAAK;AACX,QAAA,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE;AACvB,YAAA,SAAS,EAAE;QACf;AACA,QAAA,OAAO,MAAK;AACR,YAAA,KAAK,EAAE;AACX,QAAA,CAAC;IACL,CAAC,EAAE,EAAE,CAAC;IAEN,OAAO;QACH,UAAU;QACV,OAAO;QACP,QAAQ;QACR,KAAK;QACL,OAAO;QACP,SAAS;QACT;KACH;AACL;;;;"}

package/dist/types/index.d.ts

@@ -0,0 +1,2 @@
+export { useFetchState } from "./useFetchState";
+export type { UseFetchStateProps } from "./useFetchState";

package/dist/types/useFetchState.d.ts

@@ -0,0 +1,16 @@
+export type UseFetchStateProps<Req, Res> = {
+    fetcher: (request: Req) => Promise<Res | false>;
+    initialResponse: Res;
+    initialRequest: Req;
+    waitCallback?: boolean;
+    reFetchChangeRequest?: boolean;
+};
+export declare const useFetchState: <Request, Response>(options: UseFetchStateProps<Request, Response>) => {
+    setRequest: import("react").Dispatch<import("react").SetStateAction<Request>>;
+    loading: boolean;
+    response: Response;
+    error: Error | null;
+    request: Request;
+    fetchData: () => Promise<void>;
+    clear: () => void;
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "use-fetch-state",
+  "version": "0.1.0",
+  "description": "A lightweight React hook for managing async fetch state (data, loading, error) with automatic refetching.",
+  "keywords": [
+    "react",
+    "hook",
+    "fetch",
+    "async",
+    "state",
+    "loading",
+    "error",
+    "typescript"
+  ],
+  "author": {
+    "name": "Alican Kahramaner",
+    "email": "alicankahramaner@gmail.com",
+    "url": "https://alicankahramaner.github.io/"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alicankahramaner/use-fetch-state.git"
+  },
+  "homepage": "https://github.com/alicankahramaner/use-fetch-state#readme",
+  "bugs": {
+    "url": "https://github.com/alicankahramaner/use-fetch-state/issues"
+  },
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.cjs.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=16"
+  },
+  "scripts": {
+    "build": "rollup -c",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": "^17.0.0 || ^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@rollup/plugin-typescript": "^11.1.6",
+    "@types/react": "^18.3.1",
+    "rollup": "^4.18.0",
+    "rollup-plugin-dts": "^6.1.1",
+    "tslib": "^2.6.3",
+    "typescript": "^5.5.3"
+  }
+}