@scirexs/fetchy 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 scirexs
+
+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,329 @@
+# fetchy
+
+A lightweight, type-safe fetch wrapper with built-in retry logic, timeout handling, and automatic body parsing.
+
+## Features
+
+- **Lightweight** - Zero dependencies, works in Deno, Node.js, and browsers
+- **Simple API** - Drop-in replacement for native fetch with enhanced capabilities
+- **Timeout Support** - Configurable request timeouts with automatic cancellation
+- **Smart Retry Logic** - Exponential backoff with Retry-After header support
+- **Type-Safe** - Full TypeScript support with generic type inference
+- **Bearer Token Helper** - Built-in Authorization header management
+- **Jitter Support** - Prevent thundering herd with randomized delays
+- **Auto Body Parsing** - Automatic JSON serialization and Content-Type detection
+
+## Installation
+```bash
+# npm
+npm install @scirexs/fetchy
+
+# JSR (Deno)
+deno add jsr:@scirexs/fetchy
+```
+
+## Quick Start
+```ts
+import { fetchy, fetchyb } from "@scirexs/fetchy";
+
+// Simple GET request with timeout
+const response = await fetchy("https://api.example.com/data", {
+  timeout: 10
+});
+
+// Auto-parsed JSON response
+interface User {
+  id: number;
+  name: string;
+}
+
+const user = await fetchyb<User>("https://api.example.com/user/1", "json");
+console.log(user?.name);
+```
+
+## API Reference
+
+### `fetchy(url, options?)`
+
+Performs an HTTP request and returns the raw Response object.
+
+#### Parameters
+- `url`: string | URL | Request - The request URL
+- `options`: FetchyOptions (optional) - Configuration options
+
+#### Returns
+`Promise<Response | null>`
+
+#### Example
+```ts
+const response = await fetchy("https://api.example.com/data", {
+  method: "POST",
+  body: { key: "value" },
+  timeout: 10,
+  retry: { max: 3, interval: 2 },
+  bearerToken: "your-token-here"
+});
+
+if (response?.ok) {
+  const data = await response.json();
+}
+```
+
+### `fetchyb(url, type?, options?)`
+
+Performs an HTTP request and automatically parses the response body.
+
+#### Parameters
+- `url`: string | URL | Request - The request URL
+- `type`: "text" | "json" | "bytes" | "auto" (default: "auto") - Response parsing type
+- `options`: FetchyOptions (optional) - Configuration options
+
+#### Returns
+`Promise<T | string | Uint8Array | null>`
+
+#### Example
+```ts
+// Automatic type detection from Content-Type header
+const data = await fetchyb("https://api.example.com/data");
+
+// Explicit JSON parsing with type assertion
+interface Product {
+  id: number;
+  name: string;
+  price: number;
+}
+const product = await fetchyb<Product>("https://api.example.com/product/1", "json");
+
+// Text content
+const html = await fetchyb("https://example.com", "text");
+
+// Binary data
+const image = await fetchyb("https://example.com/image.png", "bytes");
+```
+
+## Configuration Options
+
+### FetchyOptions
+```ts
+interface FetchyOptions {
+  // Standard fetch options (method, headers, etc.)
+  method?: string;
+  headers?: HeadersInit;
+  
+  // Request body (auto-serializes JSON)
+  body?: JSONValue | FormData | URLSearchParams | Blob | ArrayBuffer | string;
+  
+  // Timeout in seconds (default: 15)
+  timeout?: number;
+  
+  // Retry configuration
+  retry?: {
+    max?: number;           // Max retry attempts (default: 3)
+    interval?: number;      // Base interval in seconds (default: 3)
+    maxInterval?: number;   // Max interval cap (default: 30)
+    byHeader?: boolean;     // Respect Retry-After header (default: true)
+  } | false;  // Set to false to disable retry
+  
+  // Bearer token (auto-adds "Bearer " prefix)
+  bearerToken?: string;
+  
+  // Error throwing behavior
+  throwError?: {
+    onError?: boolean;        // Throw on native errors (default: true)
+    onErrorStatus?: boolean;  // Throw on 4xx/5xx status (default: false)
+  } | boolean;  // Set to true to throw all errors
+  
+  // Initial jitter delay in seconds
+  jitter?: number;
+  
+  // Manual abort controller (if timeout occur, reason is set to "timeout")
+  abort?: AbortController;
+  
+  // Redirect behavior
+  redirect?: "follow" | "error" | "manual";
+}
+```
+
+### Default Values
+```ts
+{
+  timeout: 15,           // 15 seconds
+  jitter: 0,             // No jitter
+  retry: {
+    max: 3,              // 3 retry attempts
+    interval: 3,         // 3 seconds base interval
+    maxInterval: 30,     // 30 seconds max interval
+    byHeader: true       // Respect Retry-After header
+  },
+  throwError: {
+    onError: true,       // Throw parsing errors
+    onErrorStatus: false // Don't throw on HTTP errors
+  },
+  redirect: "follow"     // Follow redirects
+}
+```
+
+## Usage Examples
+
+### Basic Requests
+```ts
+import { fetchy, fetchyb } from "@scirexs/fetchy";
+
+// GET request
+const data = await fetchyb("https://api.example.com/data", "json");
+
+// POST with JSON body
+const result = await fetchyb("https://api.example.com/create", "json", {
+  body: { name: "John", email: "john@example.com" }
+});
+
+// Custom headers
+const response = await fetchy("https://api.example.com/data", {
+  headers: {
+    "X-Custom-Header": "value"
+  }
+});
+```
+
+### Authentication
+```ts
+// Bearer token authentication
+const user = await fetchyb<User>("https://api.example.com/me", "json", {
+  bearerToken: "your-access-token"
+});
+
+// Custom authorization
+const data = await fetchyb("https://api.example.com/data", "json", {
+  headers: {
+    "Authorization": "Basic " + btoa("user:pass")
+  }
+});
+```
+
+### Timeout and Retry
+```ts
+// Custom timeout
+const response = await fetchy("https://slow-api.example.com", {
+  timeout: 30  // 30 seconds
+});
+
+// Retry with exponential backoff
+const data = await fetchyb("https://api.example.com/data", "json", {
+  retry: {
+    max: 5,           // Retry up to 5 times
+    interval: 2,      // Start with 2 seconds
+    maxInterval: 60,  // Cap at 60 seconds
+    byHeader: true    // Respect Retry-After header
+  }
+});
+
+// Disable retry
+const response = await fetchy("https://api.example.com/data", {
+  retry: false
+});
+```
+
+### Error Handling
+```ts
+import { fetchy, HTTPStatusError, RedirectError } from "@scirexs/fetchy";
+
+// Return null on error (default)
+const data = await fetchyb("https://api.example.com/data", "json");
+if (data === null) {
+  console.log("Request failed");
+}
+
+// Throw on error
+try {
+  const data = await fetchyb("https://api.example.com/data", "json", {
+    throwError: true
+  });
+} catch (error) {
+  console.error("Request failed:", error);
+}
+
+// Throw only on HTTP errors
+try {
+  const data = await fetchyb("https://api.example.com/data", "json", {
+    throwError: { onErrorStatus: true }
+  });
+} catch (error) {
+  if (error instanceof HTTPStatusError) {
+    console.error("HTTP error:", error.message);  // e.g., "404 Not Found"
+  }
+}
+
+// Handle redirects
+try {
+  const response = await fetchy("https://example.com/redirect", {
+    redirect: "error"
+  });
+} catch (error) {
+  if (error instanceof RedirectError) {
+    console.error("Unexpected redirect:", error.message);
+  }
+}
+```
+
+### Advanced Usage
+```ts
+// Jitter to prevent thundering herd
+const response = await fetchy("https://api.example.com/data", {
+  jitter: 2,  // Random delay up to 2 seconds before request
+  retry: { max: 3 }
+});
+
+// Manual abort control
+const controller = new AbortController();
+
+setTimeout(() => controller.abort(), 5000);  // Abort after 5 seconds
+
+const response = await fetchy("https://api.example.com/data", {
+  abort: controller
+});
+
+// Form data
+const formData = new FormData();
+formData.append("file", blob);
+formData.append("name", "example");
+
+const response = await fetchy("https://api.example.com/upload", {
+  body: formData
+});
+
+// URL-encoded form
+const params = new URLSearchParams();
+params.append("key", "value");
+
+const response = await fetchy("https://api.example.com/form", {
+  body: params
+});
+```
+
+### Type-Safe API Responses
+```ts
+interface ApiResponse<T> {
+  success: boolean;
+  data: T;
+  error?: string;
+}
+
+interface Todo {
+  id: number;
+  title: string;
+  completed: boolean;
+}
+
+const response = await fetchyb<ApiResponse<Todo>>(
+  "https://api.example.com/todos/1",
+  "json"
+);
+
+if (response?.success) {
+  console.log(response.data.title);  // Fully typed
+}
+```
+
+## License
+
+MIT

package/esm/main.js

@@ -0,0 +1,441 @@
+export { _correctNumber, _fetchWithJitter, _fetchWithRetry, _fetchWithTimeout, _getBody, _getContentType, _getHeaders, _getNextInterval, _getOptions, _getRequestInit, _getRetryOption, _handleRedirectResponse, _isBool, _isJSONObject, _isNumber, _isPlainObject, _isString, _parseRetryAfter, _shouldNotRetry, _shouldRedirect, _throwError, _wait, DEFAULT, fetchy, fetchyb, HTTPStatusError, RedirectError, };
+/*=============== Constant Values ===============*/
+/**
+ * Default configuration values for fetchy.
+ * These values are used when corresponding options are not specified.
+ */
+const DEFAULT = {
+    timeout: 15,
+    jitter: 0,
+    interval: 3,
+    maxInterval: 30,
+    max: 3,
+    byHeader: true,
+    onError: true,
+    onErrorStatus: false,
+    userRedirect: "follow",
+};
+/*=============== Main Code =====================*/
+/**
+ * Error thrown when HTTP response has a non-OK status code (4xx, 5xx).
+ * Only thrown when throwError.onErrorStatus is set to true.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await fetchy("https://api.example.com/data", {
+ *     throwError: { onErrorStatus: true }
+ *   });
+ * } catch (error) {
+ *   if (error instanceof HTTPStatusError) {
+ *     console.error("HTTP error:", error.message); // e.g., "404 Not Found"
+ *   }
+ * }
+ * ```
+ */
+class HTTPStatusError extends Error {
+    constructor(msg) {
+        super(msg);
+        this.name = "HTTPStatusError";
+    }
+}
+/**
+ * Error thrown when a redirect response is received and redirect option is set to "error".
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await fetchy("https://example.com/redirect", {
+ *     redirect: "error"
+ *   });
+ * } catch (error) {
+ *   if (error instanceof RedirectError) {
+ *     console.error("Unexpected redirect:", error.message);
+ *   }
+ * }
+ * ```
+ */
+class RedirectError extends Error {
+    constructor(msg) {
+        super(msg);
+        this.name = "RedirectError";
+    }
+}
+async function fetchyb(url, type = "auto", options) {
+    const resp = await fetchy(url, options);
+    if (!resp || !resp.ok)
+        return null;
+    const btype = resp.headers.get("Content-Type") ?? "";
+    try {
+        if (type === "text" || (type === "auto" && btype.startsWith("text/")))
+            return await resp.text();
+        if (type === "json" || (type === "auto" && btype === "application/json"))
+            return await resp.json();
+        return await resp.bytes();
+    }
+    catch (e) {
+        if (_throwError("onError", options?.throwError))
+            throw e;
+        return null;
+    }
+}
+/**
+ * Performs an HTTP request with enhanced features like timeout, retry, and automatic header management.
+ * Returns the raw Response object or null on failure, unless throwError is configured.
+ *
+ * @param url - The URL to fetch. Can be a string, URL object, or Request object.
+ * @param options - Configuration options for the request.
+ * @returns Response object or null on failure.
+ *
+ * @example
+ * ```ts
+ * import { fetchy } from "@scirexs/fetchy";
+ *
+ * // Simple GET request
+ * const response = await fetchy("https://api.example.com/data");
+ * if (response?.ok) {
+ *   const data = await response.json();
+ * }
+ *
+ * // POST request with JSON body
+ * const response = await fetchy("https://api.example.com/create", {
+ *   body: { name: "John", age: 30 },
+ *   bearerToken: "your-token"
+ * });
+ *
+ * // With retry and timeout
+ * const response = await fetchy("https://api.example.com/data", {
+ *   timeout: 10,
+ *   retry: { max: 5, interval: 2 },
+ *   throwError: { onErrorStatus: true }
+ * });
+ * ```
+ */
+async function fetchy(url, options) {
+    try {
+        const opts = _getOptions(options);
+        const init = _getRequestInit(options, opts.abort);
+        const resp = await _fetchWithRetry(url, init, opts);
+        if (!resp.ok && opts.onErrorStatus)
+            throw new HTTPStatusError(`${resp.status} ${resp.statusText}`.trim());
+        return resp;
+    }
+    catch (e) {
+        if (_throwError("onError", options?.throwError))
+            throw e;
+        return null;
+    }
+}
+/*=============== Helper Code ===================*/
+/**
+ * Checks if a value is a string.
+ * @internal
+ * @param v - Value to check.
+ * @returns True if the value is a string.
+ */
+function _isString(v) {
+    return typeof v === "string";
+}
+/**
+ * Checks if a value is a number.
+ * @internal
+ * @param v - Value to check.
+ * @returns True if the value is a number.
+ */
+function _isNumber(v) {
+    return typeof v === "number";
+}
+/**
+ * Checks if a value is a boolean.
+ * @internal
+ * @param v - Value to check.
+ * @returns True if the value is a boolean.
+ */
+function _isBool(v) {
+    return typeof v === "boolean";
+}
+/**
+ * Checks if a value is a plain object (not array, null, or other object types).
+ * @internal
+ * @param v - Value to check.
+ * @returns True if the value is a plain object.
+ */
+function _isPlainObject(v) {
+    return Boolean(v &&
+        typeof v === "object" &&
+        Object.prototype.toString.call(v).slice(8, -1) === "Object" &&
+        v.constructor === Object);
+}
+/**
+ * Determines whether to throw an error based on configuration.
+ * @internal
+ * @param prop - The error option property to check.
+ * @param options - Error configuration or boolean flag.
+ * @returns True if error should be thrown.
+ */
+function _throwError(prop, options) {
+    return Boolean((options === void 0 && DEFAULT[prop]) ||
+        (typeof options === "boolean" && options) ||
+        (typeof options === "object" && (options[prop] ?? DEFAULT[prop])));
+}
+/**
+ * Corrects a number to be non-negative, using default if invalid.
+ * @internal
+ * @param dflt - Default value to use if number is invalid.
+ * @param num - Number to validate.
+ * @param integer - Whether to truncate to integer.
+ * @returns Corrected number.
+ */
+function _correctNumber(dflt, num, integer = false) {
+    if (num === void 0 || num < 0)
+        return dflt;
+    return integer ? Math.trunc(num) : num;
+}
+function _getRetryOption(prop, off, options) {
+    if (_isBool(options))
+        return off;
+    if (options === void 0 || options[prop] === void 0)
+        return DEFAULT[prop];
+    if (_isNumber(options[prop]))
+        return _correctNumber(DEFAULT[prop], options[prop], prop === "max");
+    return options[prop];
+}
+/**
+ * Converts FetchyOptions to internal Options format with validated values.
+ * @internal
+ * @param options - User-provided options.
+ * @returns Normalized internal options.
+ */
+function _getOptions(options) {
+    const timeout = _correctNumber(DEFAULT.timeout, options?.timeout);
+    return {
+        timeout,
+        jitter: _correctNumber(DEFAULT.jitter, options?.jitter),
+        interval: _getRetryOption("interval", 0, options?.retry),
+        maxInterval: _getRetryOption("maxInterval", 0, options?.retry),
+        max: _getRetryOption("max", 0, options?.retry),
+        byHeader: _getRetryOption("byHeader", false, options?.retry),
+        onErrorStatus: _throwError("onErrorStatus", options?.throwError),
+        abort: options?.abort ?? (timeout ? new AbortController() : undefined),
+        userRedirect: options?.redirect ?? DEFAULT.userRedirect,
+    };
+}
+/**
+ * Converts FetchyOptions to standard RequestInit format.
+ * @internal
+ * @param options - User-provided options.
+ * @param optsAbort - AbortController for timeout handling.
+ * @returns Standard RequestInit object.
+ */
+function _getRequestInit(options, optsAbort) {
+    const { body, timeout, retry, bearerToken, throwError, jitter, abort, redirect, ...rest } = options ?? {};
+    return {
+        method: body === void 0 ? "GET" : "POST",
+        headers: _getHeaders(options),
+        ...(redirect && { redirect: redirect === "error" ? "manual" : redirect }),
+        ...(optsAbort && { signal: optsAbort.signal }),
+        ...(body && { body: _getBody(body) }),
+        ...rest,
+    };
+}
+/**
+ * Converts FetchyBody to standard BodyInit format.
+ * @internal
+ * @param body - Body content to convert.
+ * @returns Standard BodyInit or undefined.
+ */
+function _getBody(body) {
+    return _isJSONObject(body) ? JSON.stringify(body) : body;
+}
+/**
+ * Checks if a value should be treated as JSON object for serialization.
+ * @internal
+ * @param arg - Value to check.
+ * @returns True if value should be JSON stringified.
+ */
+function _isJSONObject(arg) {
+    return Boolean(arg === null || _isNumber(arg) || _isBool(arg) || Array.isArray(arg) || _isPlainObject(arg));
+}
+/**
+ * Constructs request headers with automatic Content-Type and Authorization.
+ * @internal
+ * @param options - User-provided options.
+ * @returns Headers object.
+ */
+function _getHeaders(options) {
+    const type = _getContentType(options?.body);
+    return {
+        "Accept": "application/json, text/plain",
+        ...(type && { "Content-Type": type }),
+        ...(options?.bearerToken && { "Authorization": `Bearer ${options.bearerToken}` }),
+        ...options?.headers,
+    };
+}
+/**
+ * Determines Content-Type header based on body type.
+ * @internal
+ * @param body - Request body content.
+ * @returns Content-Type string or undefined.
+ */
+function _getContentType(body) {
+    if (body === void 0 || body instanceof FormData)
+        return;
+    if (_isString(body))
+        return "text/plain";
+    if (body instanceof URLSearchParams)
+        return "application/x-www-form-urlencoded";
+    if (_isJSONObject(body))
+        return "application/json";
+    return "application/octet-stream";
+}
+/**
+ * Waits for specified seconds with optional randomization.
+ * @internal
+ * @param sec - Seconds to wait.
+ * @param random - Whether to randomize the delay.
+ */
+async function _wait(sec, random = true) {
+    if (sec <= 0)
+        return;
+    const delay = Math.trunc((random ? Math.random() : 1) * sec * 1000);
+    await new Promise((resolve) => setTimeout(resolve, delay));
+}
+/**
+ * Checks if response is a redirect (3xx status).
+ * @internal
+ * @param resp - Response to check.
+ * @returns True if response is a redirect.
+ */
+function _shouldRedirect(resp) {
+    return resp.status < 400 && resp.status >= 300;
+}
+/**
+ * Determines if retry should stop based on conditions and waits if continuing.
+ * @internal
+ * @param count - Current retry attempt number.
+ * @param opts - Internal options.
+ * @param resp - Response from previous attempt.
+ * @returns True if retry should stop.
+ */
+async function _shouldNotRetry(count, opts, resp) {
+    if (count >= opts.max || resp?.ok)
+        return true;
+    if (resp && _shouldRedirect(resp)) {
+        if (opts.userRedirect === "manual")
+            return true;
+        if (opts.userRedirect === "error") {
+            opts.max = 0;
+            throw new RedirectError(`Received redirect response: ${resp.status}`);
+        }
+    }
+    const interval = _getNextInterval(count, opts, resp);
+    if (interval > opts.maxInterval)
+        return true;
+    await _wait(interval, false);
+    return false;
+}
+/**
+ * Calculates next retry interval using exponential backoff or Retry-After header.
+ * @internal
+ * @param count - Current retry attempt number.
+ * @param opts - Internal options.
+ * @param resp - Response from previous attempt.
+ * @returns Next retry interval in seconds.
+ */
+function _getNextInterval(count, opts, resp) {
+    return opts.byHeader && resp
+        ? Math.max(_parseRetryAfter(resp.headers.get("Retry-After")?.trim() ?? ""), opts.interval)
+        : Math.min(Math.pow(Math.max(1, opts.interval), count), opts.maxInterval);
+}
+/**
+ * Parses Retry-After header value to seconds.
+ * @internal
+ * @param value - Retry-After header value (seconds or HTTP date).
+ * @returns Retry delay in seconds, or Infinity if invalid.
+ */
+function _parseRetryAfter(value) {
+    if (!value)
+        return Infinity;
+    const sec1 = Number.parseInt(value, 10);
+    if (!Number.isNaN(sec1))
+        return sec1;
+    const sec2 = Math.ceil((new Date(value).getTime() - Date.now()) / 1000);
+    if (!Number.isNaN(sec2))
+        return sec2;
+    return Infinity;
+}
+/**
+ * Updates URL and method for redirect responses.
+ * @internal
+ * @param url - Original request URL.
+ * @param init - Request initialization object.
+ * @param resp - Redirect response.
+ * @returns Updated URL for next request.
+ */
+function _handleRedirectResponse(url, init, resp) {
+    if (!resp.redirected)
+        return url;
+    if (resp.status === 303)
+        init.method = "GET";
+    return url instanceof Request ? new Request(resp.url, url) : resp.url;
+}
+/**
+ * Executes fetch with retry logic and exponential backoff.
+ * @internal
+ * @param url - Request URL.
+ * @param init - Request initialization object.
+ * @param opts - Internal options.
+ * @returns Response from successful request.
+ */
+async function _fetchWithRetry(url, init, opts) {
+    if (!opts.max)
+        return await _fetchWithTimeout(url, init, opts);
+    for (let i = 1; i <= opts.max; i++) {
+        try {
+            const resp = await (opts.jitter ? _fetchWithJitter(url, init, opts) : _fetchWithTimeout(url, init, opts));
+            if (await _shouldNotRetry(i, opts, resp))
+                return resp;
+            url = _handleRedirectResponse(url, init, resp);
+            continue;
+        }
+        catch (e) {
+            if (await _shouldNotRetry(i, opts))
+                throw e;
+            continue;
+        }
+    }
+    throw new Error("never reach");
+}
+/**
+ * Executes fetch with initial jitter delay.
+ * @internal
+ * @param url - Request URL.
+ * @param init - Request initialization object.
+ * @param opts - Internal options.
+ * @returns Response from request.
+ */
+async function _fetchWithJitter(url, init, opts) {
+    await _wait(opts.jitter);
+    return await _fetchWithTimeout(url, init, opts);
+}
+/**
+ * Executes fetch with timeout handling.
+ * @internal
+ * @param url - Request URL.
+ * @param init - Request initialization object.
+ * @param opts - Internal options.
+ * @returns Response from request.
+ */
+async function _fetchWithTimeout(url, init, opts) {
+    const req = url instanceof Request ? url.clone() : url;
+    const id = opts.abort ? setTimeout(() => opts.abort?.abort("timeout"), opts.timeout * 1000) : 0;
+    try {
+        return await fetch(req, init);
+    }
+    catch (e) {
+        throw e;
+    }
+    finally {
+        clearTimeout(id);
+    }
+}

package/esm/mod.js

@@ -0,0 +1,5 @@
+/**
+ * Exports main functions and types for external.
+ * @module
+ */
+export { fetchy, fetchyb, HTTPStatusError, RedirectError } from "./main.js";

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/esm/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@scirexs/fetchy",
+  "version": "0.1.0",
+  "description": "A light fetch wrapper.",
+  "keywords": [
+    "fetch",
+    "typescript"
+  ],
+  "author": "scirexs",
+  "homepage": "https://github.com/scirexs/fetchy#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/scirexs/fetchy.git"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/scirexs/fetchy/issues"
+  },
+  "module": "./esm/mod.js",
+  "types": "./types/mod.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./types/mod.d.ts",
+        "default": "./esm/mod.js"
+      }
+    }
+  },
+  "scripts": {},
+  "type": "module",
+  "sideEffects": false,
+  "_generatedBy": "dnt@dev"
+}

package/types/main.d.ts

@@ -0,0 +1,305 @@
+export { _correctNumber, _fetchWithJitter, _fetchWithRetry, _fetchWithTimeout, _getBody, _getContentType, _getHeaders, _getNextInterval, _getOptions, _getRequestInit, _getRetryOption, _handleRedirectResponse, _isBool, _isJSONObject, _isNumber, _isPlainObject, _isString, _parseRetryAfter, _shouldNotRetry, _shouldRedirect, _throwError, _wait, DEFAULT, fetchy, fetchyb, HTTPStatusError, RedirectError, };
+import type { ErrorOptions, FetchyBody, FetchyOptions, RetryOptions } from "./types.js";
+/**
+ * Default configuration values for fetchy.
+ * These values are used when corresponding options are not specified.
+ */
+declare const DEFAULT: Options;
+/**
+ * Valid input types for fetch requests.
+ * @internal
+ */
+type Input = string | URL | Request;
+/**
+ * Internal normalized options used throughout the fetch process.
+ * @internal
+ */
+interface Options {
+    timeout: number;
+    jitter: number;
+    interval: number;
+    maxInterval: number;
+    max: number;
+    byHeader: boolean;
+    onError?: boolean;
+    onErrorStatus: boolean;
+    abort?: AbortController;
+    userRedirect: "follow" | "error" | "manual";
+}
+/**
+ * Error thrown when HTTP response has a non-OK status code (4xx, 5xx).
+ * Only thrown when throwError.onErrorStatus is set to true.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await fetchy("https://api.example.com/data", {
+ *     throwError: { onErrorStatus: true }
+ *   });
+ * } catch (error) {
+ *   if (error instanceof HTTPStatusError) {
+ *     console.error("HTTP error:", error.message); // e.g., "404 Not Found"
+ *   }
+ * }
+ * ```
+ */
+declare class HTTPStatusError extends Error {
+    constructor(msg: string);
+}
+/**
+ * Error thrown when a redirect response is received and redirect option is set to "error".
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await fetchy("https://example.com/redirect", {
+ *     redirect: "error"
+ *   });
+ * } catch (error) {
+ *   if (error instanceof RedirectError) {
+ *     console.error("Unexpected redirect:", error.message);
+ *   }
+ * }
+ * ```
+ */
+declare class RedirectError extends Error {
+    constructor(msg: string);
+}
+/**
+ * Performs an HTTP request and automatically parses the response body based on Content-Type or specified type.
+ * Returns null if the request fails or response is not OK, unless throwError is configured.
+ *
+ * @param url - The URL to fetch. Can be a string, URL object, or Request object.
+ * @param type - The expected response type. "auto" detects type from Content-Type header.
+ * @param options - Configuration options for the request.
+ * @returns Parsed response body or null on failure.
+ *
+ * @example
+ * ```ts
+ * import { fetchyb } from "@scirexs/fetchy";
+ *
+ * // Automatic type detection
+ * const data = await fetchyb("https://api.example.com/user");
+ *
+ * // Explicit JSON parsing with type assertion
+ * interface User { id: number; name: string; }
+ * const user = await fetchyb<User>("https://api.example.com/user", "json");
+ *
+ * // Text response
+ * const text = await fetchyb("https://example.com/page", "text");
+ *
+ * // Binary data
+ * const bytes = await fetchyb("https://example.com/image.png", "bytes");
+ * ```
+ */
+declare function fetchyb(url: Input, type: "text", options?: FetchyOptions): Promise<string | null>;
+declare function fetchyb<T>(url: Input, type: "json", options?: FetchyOptions): Promise<T | null>;
+declare function fetchyb(url: Input, type: "bytes", options?: FetchyOptions): Promise<Uint8Array | null>;
+declare function fetchyb<T>(url: Input, type?: "auto", options?: FetchyOptions): Promise<T | string | Uint8Array | null>;
+/**
+ * Performs an HTTP request with enhanced features like timeout, retry, and automatic header management.
+ * Returns the raw Response object or null on failure, unless throwError is configured.
+ *
+ * @param url - The URL to fetch. Can be a string, URL object, or Request object.
+ * @param options - Configuration options for the request.
+ * @returns Response object or null on failure.
+ *
+ * @example
+ * ```ts
+ * import { fetchy } from "@scirexs/fetchy";
+ *
+ * // Simple GET request
+ * const response = await fetchy("https://api.example.com/data");
+ * if (response?.ok) {
+ *   const data = await response.json();
+ * }
+ *
+ * // POST request with JSON body
+ * const response = await fetchy("https://api.example.com/create", {
+ *   body: { name: "John", age: 30 },
+ *   bearerToken: "your-token"
+ * });
+ *
+ * // With retry and timeout
+ * const response = await fetchy("https://api.example.com/data", {
+ *   timeout: 10,
+ *   retry: { max: 5, interval: 2 },
+ *   throwError: { onErrorStatus: true }
+ * });
+ * ```
+ */
+declare function fetchy(url: Input, options?: FetchyOptions): Promise<Response | null>;
+/**
+ * Checks if a value is a string.
+ * @internal
+ * @param v - Value to check.
+ * @returns True if the value is a string.
+ */
+declare function _isString(v: unknown): v is string;
+/**
+ * Checks if a value is a number.
+ * @internal
+ * @param v - Value to check.
+ * @returns True if the value is a number.
+ */
+declare function _isNumber(v: unknown): v is number;
+/**
+ * Checks if a value is a boolean.
+ * @internal
+ * @param v - Value to check.
+ * @returns True if the value is a boolean.
+ */
+declare function _isBool(v: unknown): v is boolean;
+/**
+ * Checks if a value is a plain object (not array, null, or other object types).
+ * @internal
+ * @param v - Value to check.
+ * @returns True if the value is a plain object.
+ */
+declare function _isPlainObject(v: unknown): v is object;
+/**
+ * Determines whether to throw an error based on configuration.
+ * @internal
+ * @param prop - The error option property to check.
+ * @param options - Error configuration or boolean flag.
+ * @returns True if error should be thrown.
+ */
+declare function _throwError(prop: keyof ErrorOptions, options?: ErrorOptions | boolean): boolean;
+/**
+ * Corrects a number to be non-negative, using default if invalid.
+ * @internal
+ * @param dflt - Default value to use if number is invalid.
+ * @param num - Number to validate.
+ * @param integer - Whether to truncate to integer.
+ * @returns Corrected number.
+ */
+declare function _correctNumber(dflt: number, num?: number, integer?: boolean): number;
+/**
+ * Gets retry option value from configuration with fallback to default.
+ * @internal
+ * @param prop - The retry option property to get.
+ * @param off - Fallback value when retry is disabled.
+ * @param options - Retry configuration.
+ * @returns The retry option value.
+ */
+declare function _getRetryOption(prop: keyof RetryOptions, off: number, options?: RetryOptions | false): number;
+declare function _getRetryOption(prop: keyof RetryOptions, off: boolean, options?: RetryOptions | false): boolean;
+/**
+ * Converts FetchyOptions to internal Options format with validated values.
+ * @internal
+ * @param options - User-provided options.
+ * @returns Normalized internal options.
+ */
+declare function _getOptions(options?: FetchyOptions): Options;
+/**
+ * Converts FetchyOptions to standard RequestInit format.
+ * @internal
+ * @param options - User-provided options.
+ * @param optsAbort - AbortController for timeout handling.
+ * @returns Standard RequestInit object.
+ */
+declare function _getRequestInit(options?: FetchyOptions, optsAbort?: AbortController): RequestInit;
+/**
+ * Converts FetchyBody to standard BodyInit format.
+ * @internal
+ * @param body - Body content to convert.
+ * @returns Standard BodyInit or undefined.
+ */
+declare function _getBody(body: FetchyBody): BodyInit | undefined;
+/**
+ * Checks if a value should be treated as JSON object for serialization.
+ * @internal
+ * @param arg - Value to check.
+ * @returns True if value should be JSON stringified.
+ */
+declare function _isJSONObject(arg?: FetchyBody): boolean;
+/**
+ * Constructs request headers with automatic Content-Type and Authorization.
+ * @internal
+ * @param options - User-provided options.
+ * @returns Headers object.
+ */
+declare function _getHeaders(options?: FetchyOptions): HeadersInit;
+/**
+ * Determines Content-Type header based on body type.
+ * @internal
+ * @param body - Request body content.
+ * @returns Content-Type string or undefined.
+ */
+declare function _getContentType(body?: FetchyBody): string | undefined;
+/**
+ * Waits for specified seconds with optional randomization.
+ * @internal
+ * @param sec - Seconds to wait.
+ * @param random - Whether to randomize the delay.
+ */
+declare function _wait(sec: number, random?: boolean): Promise<void>;
+/**
+ * Checks if response is a redirect (3xx status).
+ * @internal
+ * @param resp - Response to check.
+ * @returns True if response is a redirect.
+ */
+declare function _shouldRedirect(resp: Response): boolean;
+/**
+ * Determines if retry should stop based on conditions and waits if continuing.
+ * @internal
+ * @param count - Current retry attempt number.
+ * @param opts - Internal options.
+ * @param resp - Response from previous attempt.
+ * @returns True if retry should stop.
+ */
+declare function _shouldNotRetry(count: number, opts: Options, resp?: Response): Promise<boolean>;
+/**
+ * Calculates next retry interval using exponential backoff or Retry-After header.
+ * @internal
+ * @param count - Current retry attempt number.
+ * @param opts - Internal options.
+ * @param resp - Response from previous attempt.
+ * @returns Next retry interval in seconds.
+ */
+declare function _getNextInterval(count: number, opts: Options, resp?: Response): number;
+/**
+ * Parses Retry-After header value to seconds.
+ * @internal
+ * @param value - Retry-After header value (seconds or HTTP date).
+ * @returns Retry delay in seconds, or Infinity if invalid.
+ */
+declare function _parseRetryAfter(value: string): number;
+/**
+ * Updates URL and method for redirect responses.
+ * @internal
+ * @param url - Original request URL.
+ * @param init - Request initialization object.
+ * @param resp - Redirect response.
+ * @returns Updated URL for next request.
+ */
+declare function _handleRedirectResponse(url: Input, init: RequestInit, resp: Response): Input;
+/**
+ * Executes fetch with retry logic and exponential backoff.
+ * @internal
+ * @param url - Request URL.
+ * @param init - Request initialization object.
+ * @param opts - Internal options.
+ * @returns Response from successful request.
+ */
+declare function _fetchWithRetry(url: Input, init: RequestInit, opts: Options): Promise<Response>;
+/**
+ * Executes fetch with initial jitter delay.
+ * @internal
+ * @param url - Request URL.
+ * @param init - Request initialization object.
+ * @param opts - Internal options.
+ * @returns Response from request.
+ */
+declare function _fetchWithJitter(url: Input, init: RequestInit, opts: Options): Promise<Response>;
+/**
+ * Executes fetch with timeout handling.
+ * @internal
+ * @param url - Request URL.
+ * @param init - Request initialization object.
+ * @param opts - Internal options.
+ * @returns Response from request.
+ */
+declare function _fetchWithTimeout(url: Input, init: RequestInit, opts: Options): Promise<Response>;
+//# sourceMappingURL=main.d.ts.map

package/types/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,QAAQ,EACR,eAAe,EACf,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,eAAe,EACf,uBAAuB,EACvB,OAAO,EACP,aAAa,EACb,SAAS,EACT,cAAc,EACd,SAAS,EACT,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,WAAW,EACX,KAAK,EACL,OAAO,EACP,MAAM,EACN,OAAO,EACP,eAAe,EACf,aAAa,GACd,CAAC;AAEF,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAGxF;;;GAGG;AACH,QAAA,MAAM,OAAO,EAAE,OAUL,CAAC;AAGX;;;GAGG;AACH,KAAK,KAAK,GAAG,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC;AAMpC;;;GAGG;AACH,UAAU,OAAO;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,aAAa,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,YAAY,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;CAC7C;AAGD;;;;;;;;;;;;;;;;GAgBG;AACH,cAAM,eAAgB,SAAQ,KAAK;gBACrB,GAAG,EAAE,MAAM;CAIxB;AACD;;;;;;;;;;;;;;;GAeG;AACH,cAAM,aAAc,SAAQ,KAAK;gBACnB,GAAG,EAAE,MAAM;CAIxB;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,iBAAe,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AAClG,iBAAe,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;AAChG,iBAAe,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;AACvG,iBAAe,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,CAAC,GAAG,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC,CAAC;AAcvH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,iBAAe,MAAM,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAWnF;AAGD;;;;;GAKG;AACH,iBAAS,SAAS,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,MAAM,CAE1C;AACD;;;;;GAKG;AACH,iBAAS,SAAS,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,MAAM,CAE1C;AACD;;;;;GAKG;AACH,iBAAS,OAAO,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,OAAO,CAEzC;AACD;;;;;GAKG;AACH,iBAAS,cAAc,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,MAAM,CAO/C;AACD;;;;;;GAMG;AACH,iBAAS,WAAW,CAAC,IAAI,EAAE,MAAM,YAAY,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,GAAG,OAAO,CAMxF;AACD;;;;;;;GAOG;AACH,iBAAS,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,OAAe,GAAG,MAAM,CAGpF;AACD;;;;;;;GAOG;AACH,iBAAS,eAAe,CAAC,IAAI,EAAE,MAAM,YAAY,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,KAAK,GAAG,MAAM,CAAC;AACxG,iBAAS,eAAe,CAAC,IAAI,EAAE,MAAM,YAAY,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,KAAK,GAAG,OAAO,CAAC;AAO1G;;;;;GAKG;AACH,iBAAS,WAAW,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAarD;AACD;;;;;;GAMG;AACH,iBAAS,eAAe,CAAC,OAAO,CAAC,EAAE,aAAa,EAAE,SAAS,CAAC,EAAE,eAAe,GAAG,WAAW,CAU1F;AACD;;;;;GAKG;AACH,iBAAS,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,SAAS,CAExD;AACD;;;;;GAKG;AACH,iBAAS,aAAa,CAAC,GAAG,CAAC,EAAE,UAAU,GAAG,OAAO,CAEhD;AACD;;;;;GAKG;AACH,iBAAS,WAAW,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,WAAW,CAQzD;AACD;;;;;GAKG;AACH,iBAAS,eAAe,CAAC,IAAI,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAM9D;AAED;;;;;GAKG;AACH,iBAAe,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,OAAc,iBAIvD;AACD;;;;;GAKG;AACH,iBAAS,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAEhD;AACD;;;;;;;GAOG;AACH,iBAAe,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAc9F;AACD;;;;;;;GAOG;AACH,iBAAS,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,QAAQ,GAAG,MAAM,CAI/E;AACD;;;;;GAKG;AACH,iBAAS,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO/C;AACD;;;;;;;GAOG;AACH,iBAAS,uBAAuB,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,GAAG,KAAK,CAIrF;AACD;;;;;;;GAOG;AACH,iBAAe,eAAe,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAc9F;AACD;;;;;;;GAOG;AACH,iBAAe,gBAAgB,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAG/F;AACD;;;;;;;GAOG;AACH,iBAAe,iBAAiB,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAUhG"}

package/types/mod.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Exports main functions and types for external.
+ * @module
+ */
+export { fetchy, fetchyb, HTTPStatusError, RedirectError } from "./main.js";
+export type { ErrorOptions, FetchyBody, FetchyOptions, JSONValue, RetryOptions } from "./types.js";
+//# sourceMappingURL=mod.d.ts.map

package/types/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC5E,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/types/types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Represents a JSON-compatible value that can be serialized and deserialized.
+ * This type includes primitives, arrays, and plain objects with string keys.
+ */
+export type JSONValue = string | number | boolean | null | JSONValue[] | {
+    [key: string]: JSONValue;
+};
+/**
+ * Represents the body content that can be sent in a fetch request.
+ * Includes JSON-compatible values and standard BodyInit types except ReadableStream.
+ */
+export type FetchyBody = JSONValue | Exclude<BodyInit, ReadableStream>;
+/**
+ * Configuration options for fetchy requests.
+ * Extends standard RequestInit but provides additional features like timeout, retry, and error handling.
+ *
+ * @example
+ * ```ts
+ * import { fetchy } from "@scirexs/fetchy";
+ *
+ * const response = await fetchy("https://api.example.com/data", {
+ *   method: "POST",
+ *   body: { key: "value" },
+ *   timeout: 10,
+ *   retry: { max: 3, interval: 2 },
+ *   bearerToken: "your-token-here"
+ * });
+ * ```
+ */
+export interface FetchyOptions extends Omit<RequestInit, "body" | "signal"> {
+    /** Request body content. Automatically serializes JSON objects. */
+    body?: FetchyBody;
+    /** Request timeout in seconds. Default is 15 seconds. */
+    timeout?: number;
+    /** Retry configuration. Set to false to disable retry functionality. */
+    retry?: RetryOptions | false;
+    /** Bearer token for Authorization header. Automatically adds "Bearer " prefix. */
+    bearerToken?: string;
+    /** Error throwing behavior configuration. Set to true to throw all errors. */
+    throwError?: ErrorOptions | boolean;
+    /** Initial jitter delay in seconds before sending the request. Adds randomness to prevent thundering herd. */
+    jitter?: number;
+    /** AbortController for manual request cancellation. If not provided, an internal controller is created for timeout. */
+    abort?: AbortController;
+}
+/**
+ * Configuration options for retry behavior.
+ * Supports exponential backoff and respects Retry-After headers.
+ *
+ * @example
+ * ```ts
+ * const retryOptions: RetryOptions = {
+ *   interval: 3,
+ *   maxInterval: 30,
+ *   max: 5,
+ *   byHeader: true
+ * };
+ * ```
+ */
+export interface RetryOptions {
+    /** Base interval in seconds between retries. Used for exponential backoff calculation. Default is 3 seconds. */
+    interval?: number;
+    /** Maximum interval in seconds between retries. Caps the exponential backoff. Default is 30 seconds. */
+    maxInterval?: number;
+    /** Maximum number of retry attempts. Default is 3. */
+    max?: number;
+    /** Whether to respect Retry-After header from response. Default is true. */
+    byHeader?: boolean;
+}
+/**
+ * Configuration options for error throwing behavior.
+ * Allows fine-grained control over which errors should be thrown vs. returned as null.
+ */
+export interface ErrorOptions {
+    /** Whether to throw errors during response parsing (e.g., JSON parsing errors). Default is true. */
+    onError?: boolean;
+    /** Whether to throw HTTPStatusError for non-OK status codes (4xx, 5xx). Default is false. */
+    onErrorStatus?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/types/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEtG;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,OAAO,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;AAEvE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,aAAc,SAAQ,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,QAAQ,CAAC;IACzE,mEAAmE;IACnE,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,KAAK,CAAC,EAAE,YAAY,GAAG,KAAK,CAAC;IAC7B,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,UAAU,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC;IACpC,8GAA8G;IAC9G,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uHAAuH;IACvH,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,YAAY;IAC3B,gHAAgH;IAChH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wGAAwG;IACxG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,oGAAoG;IACpG,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,6FAA6F;IAC7F,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB"}