@alexfalconflores/safe-fetch 2.0.0 → 2.0.1

package/README.md

@@ -1,12 +1,12 @@
 <h1 align="center">
-    safeFetch
+  safeFetch
   <br />
   <img src="https://github.com/alexfalconflores/safe-fetch/blob/4fd0a9af158b69fa3bab5861ce13c552203845d9/logo.svg" alt="safeFetch logo" width="150"/>
 </h1>
 
 <p align="center">
-    <strong>The production-ready, typed HTTP client for modern TypeScript apps.</strong><br />
-      A lightweight, zero-dependency wrapper around <code>fetch</code> with built-in retries, timeouts, interceptors, and strong typing.
+<strong>Typed, production‑ready HTTP client for modern TypeScript apps.</strong><br />
+A lightweight, zero‑dependency wrapper around <code>fetch</code> with retries, timeouts, interceptors, abortAll and strong typing.
 </p>
 
 <p align="center">
@@ -25,15 +25,26 @@
 
 ## 🚀 Why safeFetch?
 
-Native `fetch` is great, but it lacks features needed for real-world apps. **safeFetch** solves this without the bloat of Axios.
+Native ‎`fetch` is great, but in real apps we always end up writing the same things:
 
-- ✨ **Smart & Typed:** Generics support `<T>` for return types.
-- 🔄 **Auto-Retries:** Automatically retries on network errors or 5xx responses.
-- ⏱️ **Timeouts:** Native timeout support that plays nice with manual cancellation.
-- 🛑 **AbortAll:** Cancel all pending requests at once (perfect for React `useEffect` cleanup).
-- 🪝 **Interceptors:** Hooks for `onRequest`, `onResponse`, and `onResponseError` (great for token refresh).
-- 🔍 **Debug Mode:** Generates copy-pasteable **cURL** commands when requests fail.
-- 🍬 **Sugar Syntax:** `.get()`, `.post()`, `.put()`, `.delete()`, `.patch()`.
+- Repetitive error handling.
+- Converting responses to JSON.
+- Adding common headers.
+- Dealing with timeouts, retries, AbortController, etc.
+
+safeFetch solves all of this without the heaviness of Axios.
+
+- ✨ Strong typing with ‎`<T>` generics on responses.
+- 🔄 Automatic retries on network errors or 5xx responses.
+- ⏱️ Per‑request configurable timeouts.
+- 🛑 ‎`abortAll()` to cancel all pending requests for an instance.
+- 🪝 Interceptors (‎`onRequest`, ‎`onResponse`, ‎`onResponseError`).
+- 🧠 HTTP status handlers (on200, on401, on500, etc).
+- 🔍 Debug mode with ready‑to‑paste cURL commands.
+- 🍬 Sugar syntax: ‎`.get()`, ‎`.post()`, ‎`.put()`, ‎`.delete()`, ‎`.patch()`.
+- 📦 Typed headers for common cases (‎`Content-Type`, ‎`Authorization`, ‎`Accept`, etc).
+
+---
 
 ## 📦 Installation
 
@@ -43,11 +54,13 @@ npm install @alexfalconflores/safe-fetch
 bun add @alexfalconflores/safe-fetch
 ```
 
-## 💻 Usage
+---
+
+## 💻 Basic usage
 
-### 1. Quick Start (Singleton)
+### 1. Default singleton
 
-Use the default instance for quick requests.
+For simple cases, use the default ‎`safeFetch` instance:
 
 ```ts
 import safeFetch from "@alexfalconflores/safe-fetch";
@@ -57,161 +70,522 @@ interface User {
   name: string;
 }
 
-// Automatic JSON parsing + Typing
+/**
+ * 1) Sugar syntax (get/post)
+ *    Great for most day‑to‑day use cases.
+ */
+
+// Typed GET + automatic JSON parsing
 const users = await safeFetch.get<User[]>("/api/users");
 
-// Automatic Body serialization
+// POST with body automatically serialized to JSON
 await safeFetch.post("/api/users", { name: "Alex" });
+
+/**
+ * 2) Core usage (no sugar)
+ *    Same instance, but calling the underlying request function directly.
+ *    Useful if you want full control over method, body and options.
+ */
+
+// Equivalent GET without .get()
+const usersCore = await safeFetch("/api/users", {
+  method: "GET",
+  timeout: 5000, // 5 segundos
+  // You can also add headers, params, timeout, etc. here
+});
+
+// Equivalent POST without .post()
+await safeFetch("/api/users", {
+  method: "POST",
+  body: { name: "Alex" }, // Will be JSON‑stringified automatically
+  headers: {
+    "Content-Type": "application/json",
+  },
+});
 ```
 
-### 2. The Factory Pattern (Recommended)
+Under the hood:
+
+- If the method is not ‎`GET`/‎`HEAD` and the body is an object, it will be serialized as JSON.
+- If you don’t define ‎`Content-Type`, ‎`"application/json"` is used by default.
+
+---
+
+## 🏭 Recommended pattern: ‎`createSafeFetch
 
-Create isolated instances for different APIs (e.g., Backend, ThirdParty).
+The ideal setup is to create **isolated instances per API** (backend, third‑party services, etc).
 
 ```ts
 import { createSafeFetch } from "@alexfalconflores/safe-fetch";
 
-const api = createSafeFetch({
-  baseUrl: "[https://api.myapp.com/v1](https://api.myapp.com/v1)",
+export const api = createSafeFetch({
+  debug: true, // Imprime logs y cURL cuando algo falla
+  baseUrl: "https://api.myapp.com/v1",
   headers: {
-    "Authorization": "Bearer initial-token",
-    "Content-Type": "application/json" // Default
+    "Content-Type": "application/json",
+  },
+  onRequest: async (url, config) => {
+    const session = await getSession();
+    config.headers = {
+      ...config.headers,
+      Authorization: `Bearer ${session?.backend_token}`,
+      ...(await buildAuditHeaders()),
+    };
+    return config;
+  },
+  on401: async () => {
+    console.error("Unauthorized: Redirecting to login page.");
   },
-  debug: true, // Prints cURL on error
 });
 
-// Usage
-const data = await api.get<MyData>("/dashboard");
+// Ejemplo de uso
+interface DashboardResponse {
+  stats: {
+    users: number;
+    sales: number;
+  };
+}
+
+// Sin Azucar
+const res = await api("/dashboard", {
+  method: "GET",
+  timeout: TIMEOUT,
+  next: { tags: [GET_BRANDS_TAG], revalidate: CRUD_REVALIDATE_SECONDS }, // Si usas Next.js
+});
+
+const data = await api.get<DashboardResponse>("/dashboard");
+console.log(data.stats.users);
 ```
 
-### 3. Advanced Features
+### Update configuration on the fly
 
-🔄 Retries & Timeouts
+You can update ‎`baseUrl`, ‎`headers` and ‎`handlers` without creating a new instance.
 
-Configure per-request or globally.
+A common pattern (especially in frameworks like Next.js) is to configure ‎`safeFetch` once and then simply import it wherever you need it.
 
 ```ts
-const data = await api.get("/flaky-endpoint", {
-  timeout: 5000,     // Abort after 5s
-  retries: 3,        // Retry 3 times on 5xx or Network Error
-  retryDelay: 1000,  // Wait 1s between retries
+// config.ts
+// Global configuration for the default safeFetch instance
+
+import safeFetch from "@alexfalconflores/safe-fetch";
+import { getSession } from "./auth";
+import { buildAuditHeaders } from "./audit";
+
+safeFetch.configure({
+  baseUrl: "http://localhost:8000/api/v1",
+  headers: {
+    "Content-Type": "application/json",
+  },
+  onRequest: async (url, config) => {
+    const session = await getSession();
+    config.headers = {
+      ...config.headers,
+      Authorization: session?.backend_token
+        ? `Bearer ${session.backend_token}`
+        : undefined,
+      ...(await buildAuditHeaders()),
+    };
+    return config;
+  },
+  on401: async () => {
+    console.error("Unauthorized: Redirecting to login page.");
+    // redirectToLogin(); // your logic here
+  },
+});
+```
+
+Then import this configuration once at the top level of your app (so it runs before any requests):
+
+> `app/layout.tsx` (or your main entry file)
+
+```ts
+import "./config.ts";
+```
+
+From that point on, you can use the already configured ‎`safeFetch` anywhere in your code:
+
+```ts
+import safeFetch from "@alexfalconflores/safe-fetch";
+
+const usersCore = await safeFetch("/api/users", {
+  method: "GET",
+  timeout: 5000, // 5 segundos
+  // You can also add headers, params, timeout, etc. here
 });
 ```
 
-🪝 Interceptors (Middleware)
+---
 
-Powerful hooks for authentication, logging, or error recovery.
+If you create a custom instance with ‎`createSafeFetch`, you can also re‑configure it:
 
 ```ts
+import { createSafeFetch } from "@alexfalconflores/safe-fetch";
+
 const api = createSafeFetch({
-  // 1. Inject Token before request
-  onRequest: async (url, config) => {
+  baseUrl: "https://api.myapp.com",
+});
+
+api.configure({
+  headers: {
+    Authorization: `Bearer ${token}`,
+  },
+});
+```
+
+> New configuration is merged with the existing one (headers are merged, not fully replaced).
+
+---
+
+## 🪝 Interceptores y manejo global
+
+### `onRequest`: inject token, tweak URL, etc.
+
+```ts
+const api = createSafeFetch({
+  baseUrl: "https://api.myapp.com",
+  async onRequest(url, config) {
     const token = localStorage.getItem("token");
-    if (token) {
-      config.headers = { ...config.headers, Authorization: `Bearer ${token}` };
-    }
-    return config;
+    return {
+      ...config,
+      headers: {
+        ...config.headers,
+        Authorization: token ? `Bearer ${token}` : undefined,
+      },
+    };
   },
+});
+```
 
-  // 2. Global Error Handling
-  onError: (err) => console.error("Network died:", err),
+### `onResponse`: global logging
 
-  // 3. Auto-Recovery (e.g., Refresh Token on 401)
-  onResponseError: async (response, attempt) => {
+```ts
+const api = createSafeFetch({
+  baseUrl: "https://api.myapp.com",
+  onResponse(response) {
+    console.log("[HTTP]", response.status, response.url);
+  },
+});
+```
+
+### `onResponseError`: refresh token / transparent retry
+
+```ts
+const api = createSafeFetch({
+  baseUrl: "https://api.myapp.com",
+  async onResponseError(response, attempt) {
+    // First 401 ➜ try to refresh token and retry
     if (response.status === 401 && attempt === 0) {
-      await refreshToken(); // Your logic
-      // Retry the request transparently
-      return api.request(response.url, { ...response }); 
+      await refreshToken(); // Tu lógica
+      // Retry the same URL with the new configuration
+      return api.request(response.url, {
+        method: response.request?.method ?? "GET",
+        // You can pass the original init here if you store it yourself
+        responseType: "response",
+      });
     }
-  }
+  },
 });
 ```
 
-🛑 Cancellation (Abort All)
+> Note: in a real app, it’s usually better to store the original ‎`init` so you can reuse it when retrying.
+
+---
 
-Stop all pending requests when a component unmounts.
+## 🧠 HTTP status handlers
+
+safeFetch lets you attach callbacks to specific HTTP status codes.
+
+Instead of doing ‎`console.log`, it’s more realistic to delegate to shared services (auth, notifications, monitoring, etc.).
+
+Example: centralize expired session handling, notifications and reporting.
+
+Assume you have three simple utilities:
 
 ```ts
-// React Example
-useEffect(() => {
-  api.get("/heavy-data").then(setData);
+// auth.ts
+export function forceLogout() {
+  // Clear tokens, global state, etc.
+  localStorage.removeItem("token");
+  // You can use your router here
+  window.location.href = "/login";
+}
 
-  return () => {
-    api.abortAll(); // Cancels pending requests immediately
-  };
-}, []);
+// notifications.ts
+export function notifyError(message: string) {
+  // Here you could integrate Sonner, Toastify, Radix, etc.
+  // Por ejemplo:
+  // toast.error(message);
+  console.error("[UI ERROR]", message);
+}
+
+// monitoring.ts
+export function reportError(error: unknown) {
+  // In a real project: send to Sentry, Datadog, LogRocket, etc.
+  console.error("[REPORT ERROR]", error);
+}
+```
+
+Ahora conectas todo desde ‎`createSafeFetch`:
+
+```ts
+import { createSafeFetch } from "@alexfalconflores/safe-fetch";
+import { forceLogout } from "./auth";
+import { notifyError } from "./notifications";
+import { reportError } from "./monitoring";
+
+const api = createSafeFetch({
+  baseUrl: "https://api.myapp.com",
+  // 4xx: errores de cliente
+  async on400(response) {
+    // Example: extract validation errors and show them in the UI
+    try {
+      const data = await response.json();
+      const message =
+        data?.message ?? "Tu solicitud contiene datos inválidos (400).";
+      notifyError(message);
+    } catch {
+      notifyError("Tu solicitud contiene datos inválidos (400).");
+    }
+  },
+  async on401() {
+    // Session expired ➜ force logout and redirect to login
+    notifyError("Tu sesión ha expirado. Ingresa nuevamente.");
+    forceLogout();
+  },
+  on403() {
+    // No permissions ➜ show generic message
+    notifyError("No tienes permisos para realizar esta acción (403).");
+  },
+  on404() {
+    // Resource not found ➜ you may update a routing store, etc.
+    notifyError("Recurso no encontrado (404).");
+  },
+  // 5xx: server errors
+  async on500(response) {
+    notifyError("Estamos teniendo problemas en el servidor. Inténtalo más tarde.");
+    reportError({
+      status: response.status,
+      url: response.url,
+    });
+  },
+  // Network error (no HTTP response)
+  onError(error) {
+    notifyError("Parece que no tienes conexión a Internet.");
+    reportError(error);
+  },
+});
+```
+
+In your business code you just use ‎`api` normally:
+```ts
+// Example in a domain service / React hook
+export async function fetchCurrentUser() {
+  const user = await api.get<User>("/me");
+  return user;
+}
+```
+>💡 This keeps all network logic in one place (safeFetch + handlers)
+and your UI only talks to utilities like ‎`notifyError`, ‎`forceLogout`, etc.
+
+Besides specific handlers (‎`on200`, ‎`on404`, ‎`on503`, etc.), you also have:
+
+- ‎`onError(error)`: when the network fails (no Internet, DNS, CORS, timeout, abort).
+- ‎`onResponse(response)`: runs whenever there is a response (2xx, 3xx, 4xx, 5xx).
+
+---
+
+## ⏱️ Timeouts and retries
+
+### Per‑request timeout
+
+```ts
+const user = await api.get<User>("/users/1", {
+  timeout: 5000, // 5 segundos
+});
+```
+
+If the timeout is exceeded:
+
+- The request is aborted.
+- An error is thrown with the message ‎`Request timeout after 5000ms`.
+
+### Retries on network / 5xx errors
+
+```ts
+const data = await api.get("/flaky-endpoint", {
+  retries: 3, // 3 retries
+  retryDelay: 1000, // 1s between retries
+  timeout: 4000, // Max 4s per attempt
+});
+```
+
+Execution flow:
+
+1. Attempt 1 → fails (network or 5xx) → wait 1s.
+2. Attempt 2 → fails → wait 1s.
+3. Attempt 3 → fails → throw the last captured error.
+
+---
+
+## 🛑 Cancel all requests (`abortAll`)
+
+Each ‎`safeFetch` instance keeps its own set of ‎`AbortController`s.
+
+This is perfect for React when unmounting components:
+
+```ts
+import { useEffect, useState } from "react";
+import { createSafeFetch } from "@alexfalconflores/safe-fetch";
+
+const api = createSafeFetch({
+  baseUrl: "https://api.myapp.com",
+});
+
+function HeavyComponent() {
+  const [data, setData] = useState<any>(null);
+
+  useEffect(() => {
+    api
+      .get("/heavy-data")
+      .then(setData)
+      .catch((err) => {
+        if (err.message === "Request aborted by safeFetch.abortAll()") return;
+        console.error(err);
+      });
+
+    return () => {
+      api.abortAll(); // Cancels ALL pending requests for this instance
+    };
+  }, []);
+
+  return <pre>{JSON.stringify(data, null, 2)}</pre>;
+}
 ```
 
-🔍 Query Params
+---
+
+## 🔍 Easy query params
 
-Forget about URLSearchParams. Pass a simple object.
+Forget about building ‎`URLSearchParams` manually:
 
 ```ts
-// GET /search?q=books&page=1&tags=a&tags=b
+// Genera: GET /search?q=books&page=2&tags=a&tags=b
 await api.get("/search", {
   params: {
     q: "books",
-    page: 1,
-    tags: ["a", "b"]
-  }
+    page: 2,
+    tags: ["a", "b"],
+  },
 });
 ```
 
-📦 API Reference
+- ‎`undefined` and ‎`null` are ignored.
+- Arrays become multiple query params.
+
+---
+
+## 📥 Response types (‎`responseType`)
+
+By default, safeFetch tries to parse the response as JSON (‎`responseType: "json"`).
+If the backend does not return valid JSON, it falls back to returning the raw ‎`text`.
+
+```ts
+// Plain text (HTML, CSV, etc.)
+const html = await api.get<string>("/page", {
+  responseType: "text",
+});
+
+// Blob (archivos, imágenes, PDFs)
+const file = await api.get<Blob>("/report.pdf", {
+  responseType: "blob",
+});
 
-`safeFetch` and `createSafeFetch` accept a configuration object:
+// ArrayBuffer (binary data for low‑level processing)
+const buffer = await api.get<ArrayBuffer>("/binary", {
+  responseType: "arrayBuffer",
+});
 
-|Opción         |Tipo       |Valor por defecto|Descripción                                 |
-|---------------|-----------|-----------------|--------------------------------------------|
-|baseUrl        |string     |`""`             |Base URL que se antepone a rutas relativas. |
-|headers        |HeadersType|`{}`             |Headers globales combinados en cada request.|
-|debug          |boolean    |`false`          |Registra comandos cURL cuando hay error.    |
-|onRequest      |function   |`undefined`      |Hook previo para modificar la configuración.|
-|onResponse     |function   |`undefined`      |Hook posterior para logging/analytics.      |
-|onResponseError|function   |`undefined`      |Hook de recuperación para errores 4xx/5xx.  |
+// Raw native Response (you handle parsing yourself)
+const response = await api.get<Response>("/raw", {
+  responseType: "response",
+});
+```
 
-Request Options (RequestInitExt)
-Extends standard RequestInit with:
+---
 
-- body: Accepts object (auto-stringified), FormData, Blob, etc.
-- params: Object for query string generation.
-- timeout: Number in ms.
-- retries: Number of retry attempts.
-- responseType: 'json' | 'text' | 'blob' | 'arrayBuffer' | 'response'.
+## 🧱 Typed headers (quality‑of‑life)
 
-🛠️ Utilities
-Join(...parts)
-Helper to join path segments or strings safely.
+‎`HeadersType` gives you autocomplete and type safety for most common HTTP headers:
+
+```ts
+import {
+  createSafeFetch,
+  type HeadersType,
+} from "@alexfalconflores/safe-fetch";
+
+const defaultHeaders: HeadersType = {
+  "Content-Type": "application/json",
+  Authorization: `Bearer ${myToken}`,
+  Accept: "application/json",
+  "Cache-Control": "no-cache",
+};
+
+const api = createSafeFetch({
+  baseUrl: "https://api.myapp.com",
+  headers: {
+    "Content-Type": "application/json",
+    // Headers custom siguen siendo válidos
+    "X-Request-Source": "dashboard-web",
+  },
+});
+```
+
+You still keep full flexibility for custom headers, while getting strong typing and autocomplete for the standard ones.
+
+---
+
+## 🛠 Utility: `Join`
+
+Small helper to join strings or arrays:
 
 ```ts
 import { Join } from "@alexfalconflores/safe-fetch";
-Join("-", "2025", "04", "19"); // "2025-04-19"
+
+const date = Join("-", "2025", "04", "19"); // "2025-04-19"
+const classes = Join(" ", "btn", ["btn-primary", "btn-lg"]); // "btn btn-primary btn-lg"
 ```
 
+---
+
 ## 🧩 Compatibility
 
 Works in all modern runtimes:
 
 - ✅ Browser (Chrome, Firefox, Safari, Edge)
-- ✅ Node.js (v18+ or with polyfill)
+- ✅ Node.js (v18+ or with a ‎`fetch` polyfill)
 - ✅ Bun
 - ✅ Deno
 
-## 👤 Autor
+---
+
+## 👤 Author
 
 Alex Stefano Falcon Flores
 
-- 🐙 GitHub: [alexstefano](https://github.com/alexfalconflores)
-- 💼 LinkedIn: [alexsfalconflores](https://www.linkedin.com/in/alexfalconflores/)
+- 🐙 GitHub: [alexfalconflores](https://github.com/alexfalconflores)
+- 💼 LinkedIn: [alexfalconflores](https://www.linkedin.com/in/alexfalconflores/)
+- 🌐 Website: [alexfalconflores](https://www.alexfalconflores.com/)
 
-## 📄 License
+---
 
-This project is licensed under the MIT license. See the [LICENSE](./LICENSE) file for more details.
+## 📄 Licencia
+
+This project is licensed under the MIT license. See the LICENSE ↗ file for more details.
 
 <p align="center">
-⭐ <strong>Love it?</strong> Give it a star on GitHub! 
+
+⭐ <strong>Find it useful?</strong> Give it a star on GitHub.<br />
+
 Built with ❤️ in Peru 🇵🇪
-</p>
 
-Give the repo a star to support the project!
-And if you use it in your projects, I'd love to see it! 🎉
+</p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexfalconflores/safe-fetch",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "The production-ready, typed HTTP client with built-in retries, timeouts, interceptors, and cancellation.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",