vigor-fetch 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2024] [Uav1010 / Your Full Name]
+
+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,59 @@
+# vigor-fetch 🚀
+
+**Vigor** is a lightweight, zero-dependency HTTP client designed for resilience. It intelligently handles server rate limits (429 Too Many Requests) and network instability with built-in retry mechanisms.
+
+## ✨ Features
+
+- 🛡️ **Smart Resilience:** Automatically handles 429 errors by respecting `Retry-After` headers.
+- 📈 **Exponential Backoff & Jitter:** Prevents server hammering by increasing wait times with random variation.
+- ⚡ **Zero Dependencies:** Built using native Fetch API and AbortController.
+- 🎯 **Fully Type-Safe:** Written in TypeScript for excellent developer experience and auto-completion.
+
+## 📦 Installation
+
+npm install vigor-fetch
+
+## 🚀 Quick Start
+```import Vigor from 'vigor-fetch';
+
+const api = new Vigor("https://api.example.com")
+  .path("/v1/data")
+  .method("POST")
+  .headers({ "X-API-KEY": "123" })
+  .query({ limit: 10, page: 1 })
+  .body({ name: "Uav1010" })
+  .count(5)
+  .max(5000)
+  .wait(10000)
+  .backoff(1.5)
+  .jitter(500)
+  .unretry([401, 404])
+  .parse("json")
+  .beforeRequest((opt) => {
+    console.log("Sending...");
+  })
+  .afterResponse((res) => {
+    return { ...res, timestamp: Date.now() };
+  });
+
+const data = await api.request();```
+
+## 🛠️ API Reference
+
+| Method | Type | Description |
+| :--- | :--- | :--- |
+| .path(string) | string | Appends path to origin. |
+| .method(string) | string | Sets HTTP method (GET, POST, etc). |
+| .query(object) | Record | Key-value pairs for URL search params. |
+| .headers(object) | Record | Custom HTTP headers. |
+| .body(any) | any | Request payload (auto-detects JSON). |
+| .count(number) | number | Max retry attempts (Default: 5). |
+| .max(ms) | number | Timeout for each fetch attempt (Default: 5000ms). |
+| .wait(ms) | number | Max delay allowed. If exceeded, throws error. |
+| .backoff(number) | number | Retry interval multiplier (Default: 1.3). |
+| .jitter(ms) | number | Randomness to avoid thundering herd (Default: 500ms). |
+| .unretry(codes[]) | number[] | Status codes that stop retrying (e.g. 404). |
+| .original(bool) | boolean | If true, returns raw Response object. |
+| .parse(type) | string | json, text, blob, arrayBuffer, formData. |
+| .beforeRequest() | function | Async hook to modify options before fetch. |
+| .afterResponse() | function | Async hook to transform data after fetch. |

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+interface VigorConfig {
+    path: string;
+    method: string | null;
+    offset: RequestInit;
+    headers: Record<string, string>;
+    body: any;
+    count: number;
+    max: number;
+    wait: number;
+    backoff: number;
+    unretry: Set<number>;
+    original: boolean;
+    parse: keyof Response | null;
+    beforeRequest: ((option: RequestInit) => Promise<RequestInit | void> | RequestInit | void)[];
+    afterResponse: ((res: any) => Promise<any> | any)[];
+    query: Record<string, string | number | boolean | null | undefined>;
+    jitter: number;
+}
+export default class Vigor {
+    private _origin;
+    private _config;
+    constructor(origin: string, config?: VigorConfig);
+    private _next;
+    path(arg: string): Vigor;
+    method(arg: string): Vigor;
+    offset(arg: RequestInit): Vigor;
+    headers(arg: Record<string, string>): Vigor;
+    body(arg: any): Vigor;
+    count(arg: number): Vigor;
+    max(arg: number): Vigor;
+    wait(arg: number): Vigor;
+    backoff(arg: number): Vigor;
+    unretry(arg: number[]): Vigor;
+    original(arg: boolean): Vigor;
+    beforeRequest(...arg: VigorConfig['beforeRequest']): Vigor;
+    afterResponse(...arg: VigorConfig['afterResponse']): Vigor;
+    parse(arg: VigorConfig['parse']): Vigor;
+    query(arg: VigorConfig['query']): Vigor;
+    jitter(arg: number): Vigor;
+    request<T = any>(): Promise<T>;
+}
+export {};

package/dist/index.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+class VigorError extends Error {
+    constructor(text, { url, status, message, data = null }) {
+        super(text);
+        this.name = "VigorError";
+        this.url = url;
+        this.status = status;
+        this.message = message;
+        this.data = data;
+    }
+}
+class Vigor {
+    constructor(origin, config) {
+        this._origin = origin;
+        this._config = config || {
+            path: "",
+            method: null,
+            offset: {},
+            headers: {},
+            body: null,
+            count: 5,
+            max: 5000,
+            wait: 10000,
+            backoff: 1.3,
+            unretry: new Set([400, 401, 403, 404, 405, 413, 422]),
+            original: false,
+            parse: null,
+            beforeRequest: [],
+            afterResponse: [],
+            query: {},
+            jitter: 500
+        };
+    }
+    _next(changes) {
+        return new Vigor(this._origin, { ...this._config, ...changes });
+    }
+    path(arg) { return this._next({ path: arg }); }
+    method(arg) { return this._next({ method: arg }); }
+    offset(arg) { return this._next({ offset: arg }); }
+    headers(arg) { return this._next({ headers: arg }); }
+    body(arg) { return this._next({ body: arg }); }
+    count(arg) { return this._next({ count: arg }); }
+    max(arg) { return this._next({ max: arg }); }
+    wait(arg) { return this._next({ wait: arg }); }
+    backoff(arg) { return this._next({ backoff: arg }); }
+    unretry(arg) { return this._next({ unretry: new Set(arg) }); }
+    original(arg) { return this._next({ original: arg }); }
+    beforeRequest(...arg) {
+        return this._next({ beforeRequest: [...this._config.beforeRequest, ...arg] });
+    }
+    afterResponse(...arg) {
+        return this._next({ afterResponse: [...this._config.afterResponse, ...arg] });
+    }
+    parse(arg) { return this._next({ parse: arg }); }
+    query(arg) { return this._next({ query: { ...this._config.query, ...arg } }); }
+    jitter(arg) { return this._next({ jitter: arg }); }
+    async request() {
+        const { path, method, offset, headers, body, count, max, wait, backoff, unretry, original, beforeRequest, afterResponse, parse, query, jitter } = this._config;
+        if (!/^(https?|data|blob|file|about):\/\//.test(this._origin)) {
+            throw new VigorError(`[vigor] ${this._origin} >> Invalid Protocol`, {
+                url: this._origin, status: 0, message: "Invalid Protocol"
+            });
+        }
+        const urlObj = new URL(path.replace(/^\//, ""), this._origin + "/");
+        Object.entries(query).forEach(([key, value]) => {
+            if (value !== null && value !== undefined) {
+                urlObj.searchParams.append(key, String(value));
+            }
+        });
+        const url = urlObj.href;
+        const isJson = Array.isArray(body) || (!!body && Object.getPrototypeOf(body) === Object.prototype);
+        const waitTimeout = (time) => new Promise(resolve => setTimeout(resolve, time));
+        let option = {
+            ...offset,
+            method: method || (body ? "POST" : "GET"),
+            headers: {
+                ...(isJson && { "Content-Type": "application/json" }),
+                ...headers
+            },
+            ...(body && { body: isJson ? JSON.stringify(body) : body }),
+        };
+        for (const hook of beforeRequest) {
+            const modified = await hook(option);
+            option = { ...option, ...(modified || {}) };
+        }
+        let req;
+        for (let i = 0; i < count; i++) {
+            const controller = new AbortController();
+            const abort = setTimeout(() => controller.abort(), max);
+            option.signal = controller.signal;
+            try {
+                req = await fetch(url, option);
+                if (req.ok) {
+                    clearTimeout(abort);
+                    break;
+                }
+            }
+            catch (error) {
+                clearTimeout(abort);
+                if (i === count - 1)
+                    throw new VigorError(`[vigor] ${url} >> Network Error`, {
+                        url, status: 0, message: "Network Error"
+                    });
+            }
+            finally {
+                clearTimeout(abort);
+            }
+            if (req) {
+                const status = req.status;
+                if (unretry.has(status))
+                    throw new VigorError(`[vigor] ${url} >> Unretry ${status}`, {
+                        url, status, message: "Unretry", data: status
+                    });
+                const basic = Math.min(Math.pow(backoff, i) * 1000, wait) + Math.random() * jitter;
+                if (status === 429) {
+                    const retryHeaders = ["retry-after", "ratelimit-reset", "x-ratelimit-reset", "x-retry-after", "x-amz-retry-after", "chrome-proxy-next-link"];
+                    const retryAfter = retryHeaders.map(h => req?.headers.get(h)).find(Boolean);
+                    const delay = (Number(retryAfter) * 1000 || (new Date(retryAfter).getTime() - Date.now()));
+                    const parsedDelay = Math.max(0, delay) + Math.random() * jitter;
+                    if (parsedDelay > wait)
+                        throw new VigorError(`[vigor] ${url} >> Timeouted ${parsedDelay}ms`, {
+                            url, status, message: "Timeouted", data: parsedDelay
+                        });
+                    await waitTimeout(parsedDelay || basic);
+                }
+                else {
+                    await waitTimeout(basic);
+                }
+            }
+        }
+        if (!req || !req.ok)
+            throw new VigorError(`[vigor] ${url} >> Failed`, {
+                url, status: req?.status || 0, message: "Failed"
+            });
+        let res = await (async () => {
+            if (original)
+                return req;
+            if (parse)
+                return await req[parse]();
+            const contentType = req.headers.get("Content-Type") || "";
+            if (/json/.test(contentType))
+                return await req.json();
+            if (/(image|video|audio|pdf)/.test(contentType))
+                return await req.blob();
+            if (/octet-stream/.test(contentType))
+                return await req.arrayBuffer();
+            if (/form-data/.test(contentType))
+                return await req.formData();
+            return await req.text();
+        })();
+        for (const hook of afterResponse) {
+            res = await hook(res);
+        }
+        return res;
+    }
+}
+exports.default = Vigor;

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "vigor-fetch",
+  "version": "1.0.0",
+  "description": "Smart, zero-dependency HTTP client with self-healing retries for rate-limited servers.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "fetch",
+    "retry",
+    "backoff",
+    "ratelimit",
+    "typescript",
+    "zero-dependency"
+  ],
+  "author": "Your Name",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}