@scirexs/fetchy 0.5.0 → 0.7.0

package/README.md

@@ -4,21 +4,22 @@
 [![JSR](https://img.shields.io/jsr/v/%40scirexs/fetchy)](https://jsr.io/@scirexs/fetchy)
 [![license](https://img.shields.io/github/license/scirexs/fetchy)](https://github.com/scirexs/fetchy/blob/main/LICENSE)
 
-A lightweight, type-safe fetch wrapper with built-in retry logic, timeout handling, and automatic body parsing.
+A lightweight, type-safe fetch wrapper with built-in retry logic, timeout handling, and automatic body parsing. Works in Deno, Node.js, and modern browsers.
 
 ## Features
 
-- **Lightweight** - Zero dependencies, works in Deno, Node.js, and browsers
+- **Lightweight** - Bundle size is ~5KB uncompressed, ~2KB gzipped, zero dependencies
 - **Simple API** - Drop-in replacement for native fetch with enhanced capabilities
+- **Promise-like Interface** - Chain parsing methods directly on fetch results
 - **Timeout Support** - Configurable request timeouts with automatic cancellation
 - **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
-- **Automatic Body Parsing** - Automatic JSON serialization and Content-Type detection
+- **Fluent Interface** - Class-based API with both instance and static methods
+- **HTTP Method Shortcuts** - Convenient methods for GET, POST, PUT, PATCH, DELETE
 
 ## Installation
-
 ```bash
 # npm
 npm install @scirexs/fetchy
@@ -28,151 +29,246 @@ deno add jsr:@scirexs/fetchy
 ```
 
 ## Quick Start
-
 ```ts
-import { fetchy, fetchyb } from "@scirexs/fetchy";
+import { fetchy, sfetchy, Fetchy, fy } from "@scirexs/fetchy";
 
-// Simple GET request with timeout
-const response = await fetchy("https://api.example.com/data", {
-  timeout: 10
-});
+// Simple GET request with automatic JSON parsing
+const user = await fetchy("https://api.example.com/user/1").json<User>();
 
-// Auto-parsed JSON response
-interface User {
-  id: number;
-  name: string;
+// Safe error handling - returns null on failure
+const data = await sfetchy("https://api.example.com/data").json<Data>();
+if (data !== null) {
+  console.log(data);
 }
 
-const user = await fetchyb<User>("https://api.example.com/user/1", "json");
-console.log(user?.name);
+// Fluent API with reusable configuration
+const client = fy({
+  bearer: "token",
+  timeout: 10,
+  retry: { maxAttempts: 5 }
+});
+const posts = await client.get("/posts").json<Post[]>();
 ```
 
 ## API Reference
 
-### `fetchy(url, options?)`
+### `fetchy(url?, options?)`
 
-Performs an HTTP request and returns the raw Response object.
+Performs an HTTP request with enhanced features. Returns a promise-like object that can be awaited directly or chained with parsing methods.
 
 #### Parameters
 
-- `url`: `string | URL | Request | null` - The request URL
+- `url`: `string | URL | Request | null` - The request URL (can be null if `options.url` is provided)
 - `options`: `FetchyOptions` (optional) - Configuration options
 
 #### Returns
 
-`Promise<Response>`; If `onError.onNative` is configured as `false`, returns `Promise<Response | null>`
+`FetchyResponse` - A promise-like object that extends `Promise<Response>` with the following methods:
 
-#### Example
+- `text()` → `Promise<string>` - Parse response as text
+- `json<T>()` → `Promise<T>` - Parse response as JSON
+- `bytes()` → `Promise<Uint8Array>` - Parse response as byte array
+- `blob()` → `Promise<Blob>` - Parse response as Blob
+- `arrayBuffer()` → `Promise<ArrayBuffer>` - Parse response as ArrayBuffer
+- `formData()` → `Promise<FormData>` - Parse response as FormData
 
+#### Example
 ```ts
-const response = await fetchy("https://api.example.com/data", {
+// Get Response object
+const response = await fetchy("https://api.example.com/data");
+
+// Chain JSON parsing
+const user = await fetchy("https://api.example.com/user").json<User>();
+
+// POST with automatic body serialization
+const result = await fetchy("https://api.example.com/create", {
   method: "POST",
-  body: { key: "value" },
-  timeout: 10,
-  retry: { maxAttempts: 3, interval: 2 },
-  bearer: "your-token-here"
-});
+  body: { name: "John", age: 30 },
+  bearer: "token"
+}).json();
 
-if (response?.ok) {
-  const data = await response.json();
-}
+// Binary data
+const image = await fetchy("https://api.example.com/image.png").bytes();
 ```
 
-### `fetchyb(url, type?, options?)`
+### `sfetchy(url?, options?)`
 
-Performs an HTTP request and automatically parses the response body.
+Performs an HTTP request with safe error handling. Returns `null` on any failure instead of throwing.
 
 #### Parameters
 
-- `url`: `string | URL | Request | null` - The request URL
-- `type`: `"text" | "json" | "bytes" | "auto"` (default: `"auto"`) - Response parsing type
-- `options`: `FetchyOptions` (optional) - Configuration options
+Same as `fetchy()`.
 
 #### Returns
 
-`Promise<T | string | Uint8Array>`; If `onError.onNative` is configured as `false`, returns `Promise<T | string | Uint8Array | null>`
+`FetchySafeResponse` - A promise-like object that extends `Promise<Response | null>` with the same parsing methods as `FetchyResponse`.
 
-#### Example
+- `text()` → `Promise<string | null>` - Safe text parsing (returns null on error)
+- `json<T>()` → `Promise<T | null>` - Safe JSON parsing (returns null on error)
+- `bytes()` → `Promise<Uint8Array | null>` - Safe bytes parsing
+- `blob()` → `Promise<Blob | null>` - Safe blob parsing
+- `arrayBuffer()` → `Promise<ArrayBuffer | null>` - Safe buffer parsing
+- `formData()` → `Promise<FormData | null>` - Safe form data parsing
 
+#### Example
 ```ts
-// Automatic type detection from Content-Type header
-const data = await fetchyb("https://api.example.com/data");
+// Returns null instead of throwing on error
+const response = await sfetchy("https://api.example.com/data");
+if (response === null) {
+  console.log("Request failed gracefully");
+} else {
+  const data = await response.json();
+}
 
-// Explicit JSON parsing with type assertion
-interface Product {
-  id: number;
-  name: string;
-  price: number;
+// Safe parsing still available
+const data = await sfetchy("https://api.example.com/data").json<Data>();
+if (data !== null) {
+  // Handle successful response
 }
-const product = await fetchyb<Product>("https://api.example.com/product/1", "json");
+```
 
-// Text content
-const html = await fetchyb("https://example.com", "text");
+### `Fetchy` Class
 
-// Binary data
-const image = await fetchyb("https://example.com/image.png", "bytes");
+A fluent HTTP client class that provides instance methods.
+
+#### Constructor
+```ts
+const client = new Fetchy(options?: FetchyOptions);
 ```
 
-## Configuration
+#### Instance Methods
+```ts
+const client = new Fetchy(options);
+
+// Main fetch method
+await client.fetch(url?)      // Returns FetchyResponse
+
+// HTTP method shortcuts
+await client.get(url?)        // GET request, returns FetchyResponse
+await client.post(url?)       // POST request, returns FetchyResponse
+await client.put(url?)        // PUT request, returns FetchyResponse
+await client.patch(url?)      // PATCH request, returns FetchyResponse
+await client.delete(url?)     // DELETE request, returns FetchyResponse
+await client.head(url?)       // HEAD request, returns Promise<Response>
+
+// Safe mode methods
+await client.safe(url?)       // Returns FetchySafeResponse
+await client.sget(url?)       // Safe GET, returns FetchySafeResponse
+await client.spost(url?)      // Safe POST, returns FetchySafeResponse
+await client.sput(url?)       // Safe PUT, returns FetchySafeResponse
+await client.spatch(url?)     // Safe PATCH, returns FetchySafeResponse
+await client.sdelete(url?)    // Safe DELETE, returns FetchySafeResponse
+await client.shead(url?)      // Safe HEAD, returns Promise<Response | null>
+```
+
+All methods can be chained with parsing methods:
+```ts
+await client.get("/users").json<User[]>();
+await client.post("/create").json<Result>();
+await client.safe("/data").text();
+```
 
-### API Options
+#### Example
+```ts
+// Instance usage - reuse configuration
+const client = new Fetchy({
+  base: "https://api.example.com",
+  bearer: "token123",
+  timeout: 10,
+  retry: { maxAttempts: 3 }
+});
 
-#### `FetchyOptions`
+const user = await client.get("/user").json<User>();
+const posts = await client.get("/posts").json<Post[]>();
 
+// POST with body
+const result = await client.post("/create", {
+  body: { name: "John" }
+}).json();
+
+// Safe mode
+const data = await client.sget("/data").json<Data>();
+if (data !== null) {
+  // Handle successful response
+}
+```
+
+### `fy(options?)` Function
+
+Shorthand for creating a new `Fetchy` instance.
+```ts
+const client = fy({
+  base: "https://api.example.com",
+  bearer: "token"
+});
+
+const user = await client.get("/user").json<User>();
+```
+
+Equivalent to:
 ```ts
-interface FetchyOptions extends RequestInit {
-  // Standard fetch options (method, headers, etc.)
-  method?: string;
-  headers?: HeadersInit;
+const client = new Fetchy({
+  base: "https://api.example.com",
+  bearer: "token"
+});
+```
+
+## Configuration
+
+### `FetchyOptions`
+```ts
+interface FetchyOptions extends Omit<RequestInit, "body"> {
+  // Request URL (allows null url parameter with this option)
+  url?: string | URL | Request;
+  
+  // Base URL prepended to request URL (only for string/URL, not Request)
+  base?: string | URL;
   
-  // Request body (auto-serializes JSON; ReadableStream is NOT supported)
-  // type JSONValue = string | number | boolean | null | JSONValue[] | { [key: string]: JSONValue };
-  body?: JSONValue | FormData | URLSearchParams | Blob | ArrayBuffer | string;
+  // Request body (auto-serializes JSON objects)
+  body?: JSONValue | BodyInit;
   
   // Timeout in seconds (default: 15)
-  timeout?: number;  // Set to 0 to disable timeout
+  timeout?: number;
   
-  // Retry configuration
-  retry?: {
-    maxAttempts?: number;  // Maximum retry attempts (default: 3)
-    interval?: number;     // Base interval in seconds (default: 3)
-    maxInterval?: number;  // Maximum interval cap in seconds (default: 30)
-    retryAfter?: boolean;  // Respect Retry-After header (default: true)
-  } | false;  // Set to false to disable retry
+  // Retry configuration (set to false to disable)
+  retry?: RetryOptions | false;
   
   // Bearer token (automatically adds "Bearer " prefix)
   bearer?: string;
   
-  // Error throwing behavior
-  onError?: {
-    onNative?: boolean;  // Throw on native errors (default: true)
-    onStatus?: boolean;  // Throw on 4xx/5xx status (default: true)
-  } | boolean;  // Set to true to throw on all errors
+  // Maximum jitter delay in seconds before request (default: 0)
+  jitter?: number;
   
-  // Initial jitter delay in seconds
-  delay?: number;
-
-  // URL for fetch (allows reusing FetchyOptions as preset configuration)
-  url?: string | URL;
+  // Use native fetch error behavior (no HTTPStatusError on 4xx/5xx)
+  native?: boolean;
 }
+
+interface RetryOptions {
+  maxAttempts?: number;       // Maximum retry attempts (default: 3)
+  interval?: number;          // Base interval in seconds (default: 3)
+  maxInterval?: number;       // Maximum interval cap (default: 30)
+  retryOnTimeout?: boolean;   // Retry on timeout (default: true)
+  idempotentOnly?: boolean;   // Only retry idempotent methods (default: false)
+  statusCodes?: number[];     // Status codes to retry (default: [500, 502, 503, 504, 408, 429])
+  respectHeaders?: string[];  // Headers to respect for retry timing
+}                             // (default: ["retry-after", "ratelimit-reset", "x-ratelimit-reset"])
 ```
 
 #### Default Values
-
 ```ts
 {
   timeout: 15,        // 15 seconds
-  delay: 0,           // No jitter delay
+  jitter: 0,          // No jitter delay
+  native: false,      // Throws HTTPStatusError on non-OK status
   retry: {
     maxAttempts: 3,   // 3 retry attempts
     interval: 3,      // 3 seconds base interval
     maxInterval: 30,  // 30 seconds maximum interval
-    retryAfter: true  // Respect Retry-After header
-  },
-  onError: {
-    onNative: true,   // Throw native errors
-    onStatus: true   // Don't throw on HTTP errors
-  },
+    retryOnTimeout: true,     // Retry on timeout
+    idempotentOnly: false,    // Retry all methods
+    statusCodes: [500, 502, 503, 504, 408, 429],
+    respectHeaders: ["retry-after", "ratelimit-reset", "x-ratelimit-reset"]
+  }
 }
 ```
 
@@ -180,88 +276,118 @@ interface FetchyOptions extends RequestInit {
 
 #### Method
 
-If a body is provided without specifying a method, the method defaults to `"POST"`. When a Request object is passed as the `url` argument, its method is used.
+- If body is provided without method: defaults to `"POST"`
+- If Request object is passed: uses its method
+- Otherwise: defaults to `"GET"`
 
 #### Headers
 
 The following headers are automatically set if not specified:
 
 - **Accept**: `application/json, text/plain`
-- **Content-Type**: Automatically determined based on the body type:
-  - `string`, `URLSearchParams`, `FormData`, `Blob` with type: Not set by this package; [`fetch` will set it automatically](https://fetch.spec.whatwg.org/#concept-bodyinit-extract).
-  - `JSONValue`: `application/json`
-  - `Blob` without type: `application/octet-stream`
-  - `ArrayBuffer`: `application/octet-stream` 
-- **Authorization**: Set to `Bearer ${options.bearer}` if `options.bearer` is provided.
-
-**Note 1:** If you pass serialized JSON as the body (i.e., a string), Content-Type will be set to `text/plain;charset=UTF-8`. To ensure Content-Type is set to `application/json`, pass the JSON object directly instead of a serialized string.
+- **Content-Type**: Automatically determined based on body type:
+  - `string`, `URLSearchParams`, `FormData`, `Blob` with type: Not set (native fetch handles it)
+  - `JSONValue` (objects, arrays, numbers, booleans): `application/json`
+  - `Blob` without type, `ArrayBuffer`: `application/octet-stream`
+- **Authorization**: `Bearer ${options.bearer}` if bearer is provided
 
-**Note 2:** If you pass a body through a Request object, Content-Type will NOT be set automatically by this package.
+**Note:** Headers from Request objects are preserved and merged with option headers.
 
 ## Error Handling
 
-### Timeout
+### HTTPStatusError
 
-If the timeout duration specified in the `timeout` option is exceeded, the request is aborted using the standard `AbortSignal.timeout()` method. Note that there is no specific error class for timeout errors; they will be thrown as standard `AbortError`s.
+Thrown when response status is not OK (4xx, 5xx) unless `native: true` is set.
+```ts
+import { fetchy, HTTPStatusError } from "@scirexs/fetchy";
 
-### HTTPStatusError
+try {
+  await fetchy("https://api.example.com/data");
+} catch (error) {
+  if (error instanceof HTTPStatusError) {
+    console.error(error.status);    // 404
+    console.error(error.response);  // Response object
+    console.error(error.message);   // "404 https://api.example.com/data"
+  }
+}
+```
 
-If `onStatus` is set to `true` (default), an `HTTPStatusError` will be thrown when the response status is outside the 2xx range. You can access the status and body through this error object. The error message format is: `404 Not Found: (no response body)`.
+### Native Errors
 
-### RedirectError
+Other errors (network failures, timeout, abort) are thrown as standard errors:
+- `TypeError`: Network error, DNS resolution failure
+- `DOMException`: Timeout or abort via AbortSignal
 
-If `redirect` is set to `"error"`, a `RedirectError` will be thrown when the response status is in the 3xx range. You can access the status through this error object. The error message format is: `301 Moved Permanently`.
+### Safe Error Handling
 
-### Other Errors
+Use `sfetchy()` or safe methods to return `null` instead of throwing:
+```ts
+// Safe fetch - returns null on any error
+const response = await sfetchy("https://api.example.com/data");
+if (response === null) {
+  // Handle error gracefully
+}
 
-If the `onNative` option is set to `true`, any other errors that occur will be thrown directly.
+// Safe parsing methods - return null on error
+const data = await fetchy("https://api.example.com/data").json<Data>();
+if (data !== null) {
+  // Process data
+}
+```
+
+### Native Mode
+
+Set `native: true` to disable HTTPStatusError and get native fetch behavior:
+```ts
+const response = await fetchy("https://api.example.com/data", {
+  native: true
+});
+// Returns Response even for 4xx/5xx status codes
+if (!response.ok) {
+  console.error("Request failed");
+}
+```
 
 ## Usage Examples
 
 ### Basic Requests
-
 ```ts
-import { fetchy, fetchyb } from "@scirexs/fetchy";
+import { fetchy, sfetchy } from "@scirexs/fetchy";
 
-// GET request
-const data = await fetchyb("https://api.example.com/data", "json");
+// GET with automatic JSON parsing
+const users = await fetchy("https://api.example.com/users").json<User[]>();
 
 // POST with JSON body
-const result = await fetchyb("https://api.example.com/create", "json", {
+const result = await fetchy("https://api.example.com/create", {
+  method: "POST",
   body: { name: "John", email: "john@example.com" }
-});
+}).json();
 
 // Custom headers
 const response = await fetchy("https://api.example.com/data", {
-  headers: {
-    "X-Custom-Header": "value"
-  }
+  headers: { "X-Custom-Header": "value" }
 });
 
-// Reuse options as preset configuration (avoids Request object limitations)
-const options = { url: "https://api.example.com/data", retry: false };
-await fetchy(null, options);
-await fetchy(null, options);
+// Using base URL
+const data = await fetchy("/users", {
+  base: "https://api.example.com"
+}).json();
 ```
 
 ### Authentication
-
 ```ts
 // Bearer token authentication
-const user = await fetchyb<User>("https://api.example.com/me", "json", {
+const user = await fetchy("https://api.example.com/me", {
   bearer: "your-access-token"
-});
+}).json<User>();
 
 // Custom authorization
-const data = await fetchyb("https://api.example.com/data", "json", {
-  headers: {
-    "Authorization": "Basic " + btoa("user:pass")
-  }
-});
+const data = await fetchy("https://api.example.com/data", {
+  headers: { "Authorization": "Basic " + btoa("user:pass") }
+}).json();
 ```
 
 ### Timeout and Retry
-
 ```ts
 // Custom timeout
 const response = await fetchy("https://slow-api.example.com", {
@@ -269,15 +395,20 @@ const response = await fetchy("https://slow-api.example.com", {
 });
 
 // Retry with exponential backoff
-// Retry intervals: 1s, 3s (3^1), 9s (3^2), 27s (3^3), 60s (capped at maxInterval)
-const data = await fetchyb("https://api.example.com/data", "json", {
+// Intervals: 3s, 6s, 12s, 24s (capped at maxInterval)
+const data = await fetchy("https://api.example.com/data", {
   retry: {
-    maxAttempts: 5,   // Retry up to 5 times
-    interval: 3,      // Base interval for exponential backoff (interval^n)
-    maxInterval: 60,  // Cap at 60 seconds
-    retryAfter: true  // Respect Retry-After header
+    maxAttempts: 5,
+    interval: 3,
+    maxInterval: 60
   }
-});
+}).json();
+
+// Retry only idempotent methods (GET, HEAD, PUT, DELETE, OPTIONS, TRACE)
+const result = await fetchy("https://api.example.com/update", {
+  method: "POST",
+  retry: { idempotentOnly: true }  // Won't retry POST
+}).json();
 
 // Disable retry
 const response = await fetchy("https://api.example.com/data", {
@@ -285,94 +416,159 @@ const response = await fetchy("https://api.example.com/data", {
 });
 ```
 
-### Error Handling
-
+### Error Handling Patterns
 ```ts
-import { fetchy, HTTPStatusError, RedirectError } from "@scirexs/fetchy";
+import { fetchy, sfetchy, HTTPStatusError } from "@scirexs/fetchy";
 
-// Throw on error and not ok response (default behavior)
+// Default: throws on error
 try {
-  const response = await fetchy("https://api.example.com/data");
+  const data = await fetchy("https://api.example.com/data").json();
 } catch (error) {
   if (error instanceof HTTPStatusError) {
-    console.error("HTTP error:", error.message);  // e.g., "404 Not Found: (no response body)"
-    console.error("Status:", error.status);
-    console.error("Body:", error.body);
+    console.error(`HTTP ${error.status}:`, error.response);
   }
 }
 
-// Return null on error
+// Safe mode: returns null
+const data = await sfetchy("https://api.example.com/data").json();
+if (data === null) {
+  console.log("Request failed, using default");
+}
+
+// Native mode: no HTTPStatusError
 const response = await fetchy("https://api.example.com/data", {
-  onError: false,
+  native: true
 });
-if (response === null) {
-  console.log("Request failed");
+if (!response.ok) {
+  console.error("Request failed with status", response.status);
 }
+```
 
-// Throw only on native errors
-try {
-  const response = await fetchy("https://api.example.com/data", {
-    onError: { onNative: true, onStatus: false } as const
-  });
-} catch (error) {
-  console.error("Request failed:", error);
-}
+### Fluent API with HTTP Methods
+```ts
+import { Fetchy, fy } from "@scirexs/fetchy";
 
-// 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);
-    console.error("Status:", error.status);
-  }
+// Create reusable client
+const api = fy({
+  base: "https://api.example.com",
+  bearer: "token",
+  timeout: 10,
+  retry: { maxAttempts: 3 }
+});
+
+// HTTP method shortcuts
+const users = await api.get("/users").json<User[]>();
+const post = await api.get("/posts/1").json<Post>();
+const created = await api.post("/posts", {
+  body: { title: "New Post" }
+}).json();
+const updated = await api.put("/posts/1", {
+  body: { title: "Updated" }
+}).json();
+const patched = await api.patch("/posts/1", {
+  body: { views: 100 }
+}).json();
+await api.delete("/posts/1");
+
+// Safe methods
+const data = await api.sget("/maybe-fails").json();
+if (data !== null) {
+  // Process data
 }
+
+// Override instance options per request
+const text = await api.get("/readme.txt", {
+  timeout: 5
+}).text();
 ```
 
 ### Advanced Usage
 
+#### Jitter for Load Distribution
 ```ts
-// Jitter to prevent thundering herd
+// Add randomized delay to prevent thundering herd
 const response = await fetchy("https://api.example.com/data", {
-  delay: 2,  // Random delay up to 2 seconds before request
+  jitter: 2,  // Random delay up to 2 seconds before each request
   retry: { maxAttempts: 3 }
 });
+```
 
-// Combined abort signals
-const controller1 = new AbortController();
-const controller2 = new AbortController();
-const request = new Request("https://api.example.com/data", {
-  signal: controller1.signal
+#### Abort Signals
+```ts
+// Manual abort control
+const controller = new AbortController();
+const promise = fetchy("https://api.example.com/data", {
+  signal: controller.signal
 });
 
-setTimeout(() => controller1.abort(), 5000);  // Abort after 5 seconds
+setTimeout(() => controller.abort(), 5000);
+
+try {
+  await promise;
+} catch (error) {
+  // Aborted after 5 seconds
+}
 
-const response = await fetchy(request, {
-  signal: controller2.signal
+// Combining timeout with manual abort
+const controller = new AbortController();
+await fetchy("https://api.example.com/data", {
+  timeout: 10,
+  signal: controller.signal
 });
+// Request will abort after 10 seconds OR when controller.abort() is called
+```
 
+#### Form Data and File Uploads
+```ts
 // Form data upload
 const formData = new FormData();
-formData.append("file", blob);
+formData.append("file", blob, "filename.png");
 formData.append("name", "example");
 
-const response = await fetchy("https://api.example.com/upload", {
+await fetchy("https://api.example.com/upload", {
+  method: "POST",
   body: formData
 });
 
 // URL-encoded form
-const params = new URLSearchParams();
-params.append("key", "value");
-
-const response = await fetchy("https://api.example.com/form", {
+const params = new URLSearchParams({ key: "value", foo: "bar" });
+await fetchy("https://api.example.com/form", {
+  method: "POST",
   body: params
 });
 ```
 
-### Type-Safe API Responses
+#### Streaming with ReadableStream
+```ts
+// ReadableStream can be used via Request object
+const stream = new ReadableStream({
+  start(controller) {
+    controller.enqueue(new TextEncoder().encode("chunk 1\n"));
+    controller.enqueue(new TextEncoder().encode("chunk 2\n"));
+    controller.close();
+  }
+});
 
+const response = await fetchy("https://api.example.com/stream", {
+  method: "POST",
+  body: stream
+});
+```
+
+#### Retry-After Header Respect
+```ts
+// Automatically respects Retry-After, RateLimit-Reset, X-RateLimit-Reset headers
+const data = await fetchy("https://api.example.com/rate-limited", {
+  retry: {
+    maxAttempts: 5,
+    interval: 1,  // Minimum interval if header not present
+    respectHeaders: ["retry-after", "ratelimit-reset"]
+  }
+}).json();
+// If response has "Retry-After: 10", will wait 10 seconds before retry
+```
+
+### Type-Safe API Responses
 ```ts
 interface ApiResponse<T> {
   success: boolean;
@@ -386,46 +582,88 @@ interface Todo {
   completed: boolean;
 }
 
-const response = await fetchyb<ApiResponse<Todo>>(
-  "https://api.example.com/todos/1",
-  "json"
-);
+const response = await fetchy("https://api.example.com/todos/1")
+  .json<ApiResponse<Todo>>();
 
 if (response.success) {
   console.log(response.data.title);  // Fully typed
 }
-```
 
-## Limitations
+// With safe parsing
+const result = await sfetchy("https://api.example.com/todos/1")
+  .json<ApiResponse<Todo>>();
 
-### Return Type Inference
+if (result !== null && result.success) {
+  console.log(result.data.completed);
+}
+```
 
-When setting the `onError` property in `FetchyOptions`, the return type will include `null` even if you set it to `true` or `{ onNative: true }`. To prevent this and ensure a non-nullable return type, add `as const` to the `onError` property value:
+## Best Practices
 
+### 1. Use Base URL for API Clients
 ```ts
-interface User {
-  id: number;
-  name: string;
-}
+const api = fy({
+  base: "https://api.example.com",
+  bearer: process.env.API_TOKEN,
+  timeout: 10
+});
 
-const options = { timeout: 5, onError: { onNative: true, onStatus: false } as const };  // Add `as const`
-const response = await fetchy("https://api.example.com/todos/1", "json", options);
-// `response` is User (not User | null)
+// All requests are relative to base
+await api.get("/users").json();
+await api.post("/posts", { body: data }).json();
 ```
 
-### Content-Type Header with Request Objects
+### 2. Choose Safe vs. Throwing Behavior
+```ts
+// For critical operations: use regular methods (throws on error)
+try {
+  const result = await fetchy(url).json();
+  // Process result
+} catch (error) {
+  // Handle error explicitly
+}
 
-When a body is set in a Request object, the Content-Type header is NOT set automatically by this package. Therefore, when using Request objects, you must explicitly set the Content-Type header for any body types other than those automatically handled by the native `fetch` API.
+// For optional data: use safe methods (returns null)
+const data = await fetchy(url).sjson();
+if (data !== null) {
+  // Process data
+}
+// Continue regardless of result
+```
 
-This limitation can be avoided by using the `url` property in `FetchyOptions` instead of Request objects. This approach allows you to benefit from all automatic header configuration features while still maintaining reusable preset configurations. See the "Reuse options as preset configuration" example in the [Basic Requests](#basic-requests) section.
+### 3. Configure Retry for Resilience
+```ts
+// Aggressive retry for critical operations
+const result = await fetchy(url, {
+  retry: {
+    maxAttempts: 5,
+    interval: 2,
+    maxInterval: 30,
+    retryOnTimeout: true
+  }
+}).json();
 
-### ReadableStream as Body
+// No retry for operations that must be fast
+const data = await fetchy(url, {
+  retry: false,
+  timeout: 2
+}).json();
+```
 
-`FetchyOptions` does not accept ReadableStream as a body. If you need to use ReadableStream, create a Request object with the stream and pass it to `fetchy()`.
+### 4. Use Method Shortcuts for Clarity
+```ts
+const api = fy({ base: "https://api.example.com" });
 
-### Redirect Error Handling
+// Clear and concise
+await api.get("/users").json();
+await api.post("/users", { body: newUser }).json();
+await api.delete("/users/123");
 
-When `redirect` is set to `"error"`, this package throws a custom `RedirectError` (instead of the native TypeError) to enable proper retry handling for redirect responses.
+// Instead of
+await api.fetch("/users", { method: "GET" }).json();
+await api.fetch("/users", { method: "POST", body: newUser }).json();
+await api.fetch("/users/123", { method: "DELETE" });
+```
 
 ## License