cod-smart-fetch 1.0.0

package/LICENSE

@@ -0,0 +1,7 @@
+ISC License
+
+Copyright (c) 2026 COD Innovations
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# use-smart-fetch
+
+A professional, type-safe, and feature-rich React hook for data fetching. It simplifies network requests by handling loading states, errors, data caching, debouncing, and more, all while providing a modern API for both automatic and manual execution.
+
+## Features
+
+- **Built-in State Management**: Automatically handles `isLoading`, `error`, and `data` states.
+- **Auto-Fetch**: Trigger requests immediately when a component mounts or dependencies change.
+- **Debounce Support**: Native support for debounced requests (perfect for search inputs).
+- **Global Configuration**: Set base URLs, default headers, and interceptors once for your entire app.
+- **Interceptors**: Powerful request and response interception for logging, auth tokens, or error handling.
+- **Smart File Uploads**: Simplified API for uploading files and `FormData`.
+- **TypeScript First**: Written in TypeScript with full type inference for request bodies and responses.
+
+## Installation
+
+```bash
+npm install use-smart-fetch
+# or
+yarn add use-smart-fetch
+```
+
+## Quick Start
+
+### 1. Automatic Fetching (GET)
+Ideal for loading data when a component mounts.
+
+```tsx
+import { useSmartFetch } from 'use-smart-fetch';
+
+interface User {
+  id: number;
+  name: string;
+}
+
+const UserProfile = () => {
+  const { data, isLoading, error } = useSmartFetch<User>({
+    url: 'https://jsonplaceholder.typicode.com/users/1',
+    autoFetch: true
+  });
+
+  if (isLoading) return <p>Loading...</p>;
+  if (error) return <p>Error: {error.message}</p>;
+
+  return <div>User: {data?.name}</div>;
+};
+```
+
+### 2. Manual Execution (POST)
+Ideal for form submissions or actions triggered by user interaction.
+
+```tsx
+import { useSmartFetch } from 'use-smart-fetch';
+
+const CreatePost = () => {
+  const { post, isLoading } = useSmartFetch();
+
+  const handleSubmit = async () => {
+    const response = await post('https://jsonplaceholder.typicode.com/posts', {
+      title: 'New Post',
+      body: 'This is the content'
+    });
+    
+    if (response) {
+      alert('Post Created!');
+    }
+  };
+
+  return (
+    <button onClick={handleSubmit} disabled={isLoading}>
+      {isLoading ? 'Creating...' : 'Create Post'}
+    </button>
+  );
+};
+```
+
+## Advanced Features
+
+### Global Configuration
+You can configure a base URL and global headers (like Authorization tokens) using the `SmartFetchProvider`.
+
+```tsx
+// app.tsx
+import { SmartFetchProvider } from 'use-smart-fetch';
+
+const App = () => (
+  <SmartFetchProvider config={{
+    baseUrl: 'https://api.my-app.com/v1',
+    headers: { 
+      'Authorization': 'Bearer my-token' 
+    }
+  }}>
+    <MyComponent />
+  </SmartFetchProvider>
+);
+```
+
+### Interceptors
+Interceptors allow you to modify requests before they are sent or responses before they are processed. This is useful for logging logic or global error handling (e.g., redirecting to login on 401).
+
+```tsx
+<SmartFetchProvider config={{
+  baseUrl: 'https://api.my-app.com',
+  interceptors: {
+    request: async (options) => {
+      console.log('Requesting:', options.method, options.url);
+      return options;
+    },
+    response: async (response) => {
+      if (response.status === 401) {
+        window.location.href = '/login';
+      }
+      return response;
+    }
+  }
+}}>
+  <App />
+</SmartFetchProvider>
+```
+
+### Debounced Requests (Search)
+Easily implement "search-as-you-type" functionality without extra libraries.
+
+```tsx
+const [search, setSearch] = useState('');
+const { data } = useSmartFetch({
+  url: `/search?q=${search}`,
+  autoFetch: true,
+  debounce: 500 // Wait 500ms after user stops typing
+});
+```
+
+### File Uploads
+The `upload` helper automatically detects files and handles `FormData` conversion and headers for you.
+
+```tsx
+const { upload } = useSmartFetch();
+
+const handleUpload = async (file: File) => {
+  // Uploads as multipart/form-data
+  await upload('/avatars', file);
+};
+```
+
+## API Documentation
+
+### `useSmartFetch<T>(options?: UseSmartFetchOptions)`
+
+#### Configuration Options
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `url` | `string` | `undefined` | The endpoint URL. Required if `autoFetch` is true. |
+| `method` | `'GET' \| 'POST' ...` | `'GET'` | The HTTP method to use. |
+| `headers` | `HeadersInit` | `{}` | Custom headers. merged with global headers. |
+| `body` | `any` | `undefined` | The request payload. |
+| `autoFetch` | `boolean` | `false` | If true, executes the request immediately on mount. |
+| `debounce` | `number` | `undefined` | Milliseconds to delay execution (only for `autoFetch`). |
+
+#### Return Values
+| Property | Type | Description |
+|----------|------|-------------|
+| `data` | `T \| null` | The parsed JSON response. |
+| `error` | `Error \| null` | The error object if the request fails. |
+| `isLoading` | `boolean` | `true` while a request is pending. |
+| `execute` | `(opts) => Promise<T>` | Manually triggers the request with merged options. |
+| `get` | `(url, headers?)` | Helper for GET requests. |
+| `post` | `(url, body, headers?)` | Helper for POST requests. |
+| `put` | `(url, body, headers?)` | Helper for PUT requests. |
+| `patch` | `(url, body, headers?)` | Helper for PATCH requests. |
+| `remove` | `(url, headers?)` | Helper for DELETE requests. |
+| `upload` | `(url, files, name?)` | Helper for file uploads. |

package/dist/context/SmartFetchContext.d.ts

@@ -0,0 +1,18 @@
+import React, { ReactNode } from 'react';
+export interface Interceptors {
+    request?: (options: RequestInit) => Promise<RequestInit> | RequestInit;
+    response?: (response: Response) => Promise<Response> | Response;
+}
+export interface SmartFetchConfig {
+    baseUrl?: string;
+    headers?: HeadersInit;
+    autoFetch?: boolean;
+    onSuccess?: (data: any) => void;
+    onError?: (error: Error) => void;
+    interceptors?: Interceptors;
+}
+export declare const SmartFetchProvider: ({ children, config }: {
+    children: ReactNode;
+    config: SmartFetchConfig;
+}) => React.JSX.Element;
+export declare const useSmartFetchConfig: () => SmartFetchConfig;

package/dist/context/SmartFetchContext.js

@@ -0,0 +1,44 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useSmartFetchConfig = exports.SmartFetchProvider = void 0;
+const react_1 = __importStar(require("react"));
+const SmartFetchContext = (0, react_1.createContext)({});
+const SmartFetchProvider = ({ children, config }) => {
+    return (react_1.default.createElement(SmartFetchContext.Provider, { value: config }, children));
+};
+exports.SmartFetchProvider = SmartFetchProvider;
+const useSmartFetchConfig = () => (0, react_1.useContext)(SmartFetchContext);
+exports.useSmartFetchConfig = useSmartFetchConfig;

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export interface UseSmartFetchOptions<T> {
+    url?: string;
+    method?: HttpMethod;
+    headers?: HeadersInit;
+    body?: any;
+    autoFetch?: boolean;
+    debounce?: number;
+}
+export interface FetchState<T> {
+    data: T | null;
+    error: Error | null;
+    isLoading: boolean;
+}
+export interface UseSmartFetchResult<T> extends FetchState<T> {
+    execute: (options?: UseSmartFetchOptions<T>) => Promise<T | null>;
+    get: (url: string, headers?: HeadersInit) => Promise<T | null>;
+    post: (url: string, body: any, headers?: HeadersInit) => Promise<T | null>;
+    put: (url: string, body: any, headers?: HeadersInit) => Promise<T | null>;
+    patch: (url: string, body: any, headers?: HeadersInit) => Promise<T | null>;
+    remove: (url: string, headers?: HeadersInit) => Promise<T | null>;
+    upload: (url: string, fileOrFiles: File | File[] | FormData, fieldName?: string, headers?: HeadersInit, method?: 'POST' | 'PUT') => Promise<T | null>;
+}
+export declare function useSmartFetch<T = any>(initialOptions?: UseSmartFetchOptions<T>): UseSmartFetchResult<T>;
+export { SmartFetchProvider } from './context/SmartFetchContext';
+export default useSmartFetch;

package/dist/index.js

@@ -0,0 +1,155 @@
+"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.SmartFetchProvider = void 0;
+exports.useSmartFetch = useSmartFetch;
+const react_1 = require("react");
+const SmartFetchContext_1 = require("./context/SmartFetchContext");
+function useSmartFetch(initialOptions = {}) {
+    const config = (0, SmartFetchContext_1.useSmartFetchConfig)();
+    const [state, setState] = (0, react_1.useState)({
+        data: null,
+        error: null,
+        isLoading: !!((initialOptions.autoFetch || config.autoFetch) && (initialOptions.url || config.baseUrl)),
+    });
+    const optionsRef = (0, react_1.useRef)(initialOptions);
+    const abortControllerRef = (0, react_1.useRef)(null);
+    (0, react_1.useEffect)(() => {
+        optionsRef.current = initialOptions;
+    }, [initialOptions]);
+    const execute = (0, react_1.useCallback)((...args_1) => __awaiter(this, [...args_1], void 0, function* (options = {}) {
+        var _a, _b;
+        const mergedOptions = Object.assign(Object.assign({}, optionsRef.current), options);
+        let { url, method = 'GET', headers = {}, body } = mergedOptions;
+        // Use baseUrl if provided and url is relative
+        if (config.baseUrl && url && !url.startsWith('http')) {
+            // Ensure no double slashes
+            const base = config.baseUrl.endsWith('/') ? config.baseUrl.slice(0, -1) : config.baseUrl;
+            const path = url.startsWith('/') ? url : `/${url}`;
+            url = `${base}${path}`;
+        }
+        if (!url) {
+            console.error("useSmartFetch: URL is required");
+            return null;
+        }
+        if (abortControllerRef.current) {
+            abortControllerRef.current.abort();
+        }
+        abortControllerRef.current = new AbortController();
+        setState(prev => (Object.assign(Object.assign({}, prev), { isLoading: true, error: null })));
+        try {
+            let fetchOptions = {
+                method,
+                headers: Object.assign(Object.assign({ 'Content-Type': 'application/json' }, config.headers), headers),
+                signal: abortControllerRef.current.signal,
+            };
+            if (body) {
+                if (body instanceof FormData) {
+                    // If body is FormData, let browser set Content-Type
+                    // We need to cast headers to any or Record to check/delete
+                    // But HeadersInit can be Headers object too.
+                    // Simplest way: don't include Content-Type if it's FormData
+                    if (fetchOptions.headers && 'Content-Type' in fetchOptions.headers) {
+                        delete fetchOptions.headers['Content-Type'];
+                    }
+                    // Also remove from global headers if merged? 
+                    // Better approach:
+                    const h = Object.assign(Object.assign({}, config.headers), headers);
+                    delete h['Content-Type'];
+                    fetchOptions.headers = h;
+                    fetchOptions.body = body;
+                }
+                else if (method !== 'GET') {
+                    fetchOptions.body = JSON.stringify(body);
+                }
+            }
+            // Request Interceptor
+            if ((_a = config.interceptors) === null || _a === void 0 ? void 0 : _a.request) {
+                fetchOptions = yield config.interceptors.request(fetchOptions);
+            }
+            let response = yield fetch(url, fetchOptions);
+            // Response Interceptor
+            if ((_b = config.interceptors) === null || _b === void 0 ? void 0 : _b.response) {
+                response = yield config.interceptors.response(response);
+            }
+            if (!response.ok) {
+                throw new Error(`HTTP error! status: ${response.status}`);
+            }
+            const data = yield response.json();
+            setState({ data, error: null, isLoading: false });
+            if (config.onSuccess)
+                config.onSuccess(data);
+            return data;
+        }
+        catch (error) {
+            if (error.name === 'AbortError') {
+                return null;
+            }
+            setState({ data: null, error, isLoading: false });
+            if (config.onError)
+                config.onError(error);
+            return null;
+        }
+    }), [config]);
+    const stringifiedOptions = JSON.stringify(initialOptions);
+    (0, react_1.useEffect)(() => {
+        const toggle = initialOptions.autoFetch || config.autoFetch;
+        if (toggle) {
+            if (initialOptions.url) {
+                const timeoutId = setTimeout(() => {
+                    execute();
+                }, initialOptions.debounce || 0);
+                return () => {
+                    clearTimeout(timeoutId);
+                    if (abortControllerRef.current) {
+                        abortControllerRef.current.abort();
+                    }
+                };
+            }
+        }
+        return () => {
+            if (abortControllerRef.current) {
+                abortControllerRef.current.abort();
+            }
+        };
+    }, [stringifiedOptions, execute, config.autoFetch]);
+    const get = (0, react_1.useCallback)((url, headers) => execute({ url, method: 'GET', headers }), [execute]);
+    const post = (0, react_1.useCallback)((url, body, headers) => execute({ url, method: 'POST', body, headers }), [execute]);
+    const put = (0, react_1.useCallback)((url, body, headers) => execute({ url, method: 'PUT', body, headers }), [execute]);
+    const patch = (0, react_1.useCallback)((url, body, headers) => execute({ url, method: 'PATCH', body, headers }), [execute]);
+    const remove = (0, react_1.useCallback)((url, headers) => execute({ url, method: 'DELETE', headers }), [execute]);
+    const upload = (0, react_1.useCallback)((url, fileOrFiles, fieldName = 'file', headers = {}, method = 'POST') => {
+        let body;
+        if (fileOrFiles instanceof FormData) {
+            body = fileOrFiles;
+        }
+        else {
+            body = new FormData();
+            if (Array.isArray(fileOrFiles)) {
+                fileOrFiles.forEach(file => body.append(fieldName, file));
+            }
+            else {
+                body.append(fieldName, fileOrFiles);
+            }
+        }
+        return execute({ url, method, body, headers });
+    }, [execute]);
+    return Object.assign(Object.assign({}, state), { execute,
+        get,
+        post,
+        put,
+        patch,
+        remove,
+        upload });
+}
+var SmartFetchContext_2 = require("./context/SmartFetchContext");
+Object.defineProperty(exports, "SmartFetchProvider", { enumerable: true, get: function () { return SmartFetchContext_2.SmartFetchProvider; } });
+exports.default = useSmartFetch;

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "cod-smart-fetch",
+  "version": "1.0.0",
+  "description": "A smart React hook for fetching data with built-in loading, error, and data states.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "tsc"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codinnovation/use-smart-fetch.git"
+  },
+  "keywords": [
+    "react",
+    "hook",
+    "fetch",
+    "api",
+    "data-fetch"
+  ],
+  "author": "COD Innovations",
+  "license": "ISC",
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "react": "^18.2.0",
+    "typescript": "^5.9.3"
+  },
+  "type": "commonjs",
+  "bugs": {
+    "url": "https://github.com/codinnovation/use-smart-fetch/issues"
+  },
+  "homepage": "https://github.com/codinnovation/use-smart-fetch#readme"
+}