jiren 1.5.0 → 1.6.0

package/README.md

@@ -1,282 +1,314 @@
 # Jiren 🚀
 
-**Ultra-fast HTTP client powered by native Zig** - Significantly faster than `fetch` and other HTTP clients.
+**The fastest HTTP client for JavaScript** - Simple, type-safe, and blazingly fast.
 
 [![npm version](https://img.shields.io/npm/v/jiren.svg)](https://www.npmjs.com/package/jiren)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Why Jiren?
+---
+
+## ⚡ Performance: Fastest in the World
+
+Jiren outperforms top clients in every metric—throughput, latency, and stability.
+
+| Client    | Avg Latency | P99 Latency | Throughput   | Relative Speed |
+| --------- | ----------- | ----------- | ------------ | -------------- |
+| **Jiren** | **21.6 µs** | **46.0 µs** | **46,000/s** | **🚀 Fastest** |
+| Bun Fetch | 30.7 µs     | 58.5 µs     | 32,500/s     | 1.4x Slower    |
+| Undici    | 34.1 µs     | 76.5 µs     | 29,300/s     | 1.6x Slower    |
+| Ky        | 37.2 µs     | 57.0 µs     | 26,900/s     | 1.7x Slower    |
+| Axios     | 59.6 µs     | 122.1 µs    | 16,700/s     | 2.8x Slower    |
 
-- ⚡ **2-3x faster** than Bun's native `fetch`
-- 🔒 **Anti-bot protection** - Bypass Cloudflare with Chrome TLS fingerprinting
-- 🚄 **HTTP/3 (QUIC)** support with automatic fallback to HTTP/2
-- 💾 **Smart caching** - Persistent gzip-compressed response cache
-- 🔌 **Connection pooling** - Reuse connections for maximum performance
-- 📝 **Type-safe** - Full TypeScript support with autocomplete
-- 🎯 **Zero dependencies** - Pure Zig native module
+---
+
+## ✨ Why Jiren?
 
-## Installation
+| Feature                 | Benefit                                           |
+| ----------------------- | ------------------------------------------------- |
+| ⚡ **Blazing Fast**     | Proven to be the fastest JS HTTP client           |
+| **HTTP/3 Support**      | Automatic protocol upgrade for faster connections |
+| 💾 **Built-in Caching** | Automatic response caching with zero config       |
+| 📝 **Type-Safe**        | Full TypeScript support with autocomplete         |
+| 🔒 **Anti-Bot Ready**   | Bypass common bot protections easily              |
+| 📊 **Built-in Metrics** | Track performance out of the box                  |
+
+---
+
+## 📦 Installation
 
 ```bash
 bun add jiren
 ```
 
-## Quick Start
+---
+
+## 🚀 Quick Start
+
+### Step 1: Create Your Client
 
 ```typescript
 import { JirenClient } from "jiren";
 
-// Create client with warmup URLs
 const client = new JirenClient({
-  warmup: {
+  targets: {
     api: "https://api.example.com",
-    cdn: "https://cdn.example.com",
+    github: "https://api.github.com",
   },
 });
+```
 
-// Make requests with full type safety
+### Step 2: Make Requests
+
+```typescript
+// GET request
 const response = await client.url.api.get({ path: "/users" });
 const users = await response.body.json();
 
-console.log(users);
+// POST request
+await client.url.api.post(JSON.stringify({ name: "John" }), {
+  path: "/users",
+  headers: { "Content-Type": "application/json" },
+});
 ```
 
-## Table of Contents
-
-- [Basic Usage](#basic-usage)
-- [Response Caching](#response-caching)
-- [Anti-Bot Protection](#anti-bot-protection)
-- [Request Interceptors](#request-interceptors)
-- [Metrics & Observability](#metrics--observability)
-- [Advanced Features](#advanced-features)
-- [Performance](#performance)
-- [API Reference](#api-reference)
+That's it! 🎉
 
 ---
 
-## Basic Usage
+## 📖 Table of Contents
 
-### 1. Create a Client
+1. [Making Requests](#-making-requests)
+2. [Response Handling](#-response-handling)
+3. [Caching](#-caching)
+4. [Anti-Bot Protection](#-anti-bot-protection)
+5. [Interceptors](#-interceptors)
+6. [Metrics](#-metrics)
+7. [TypeScript Support](#-typescript-support)
+8. [API Reference](#-api-reference)
+
+---
 
-**Warmup is mandatory** - define your URLs upfront for optimal performance:
+## 🌐 Making Requests
+
+### GET Requests
 
 ```typescript
-import { JirenClient } from "jiren";
+// Simple GET
+const response = await client.url.api.get();
 
-const client = new JirenClient({
-  warmup: {
-    github: "https://api.github.com",
-    google: "https://www.google.com",
-  },
+// GET with path
+const user = await client.url.github.get({ path: "/users/octocat" });
+
+// GET with headers
+const data = await client.url.api.get({
+  path: "/protected",
+  headers: { Authorization: "Bearer token123" },
 });
 ```
 
-### 2. Make GET Requests
+### POST, PUT, PATCH, DELETE
 
 ```typescript
-// Simple GET request
-const response = await client.url.github.get();
-console.log(response.status); // 200
+// POST
+await client.url.api.post(JSON.stringify({ name: "Jane" }), {
+  path: "/users",
+  headers: { "Content-Type": "application/json" },
+});
+
+// PUT
+await client.url.api.put(JSON.stringify({ name: "Updated" }), {
+  path: "/users/123",
+});
 
-// GET with path and headers
-const user = await client.url.github.get({
-  path: "/users/octocat",
-  headers: { Authorization: "token YOUR_TOKEN" },
+// PATCH
+await client.url.api.patch(JSON.stringify({ email: "new@email.com" }), {
+  path: "/users/123",
 });
+
+// DELETE
+await client.url.api.delete(null, { path: "/users/123" });
 ```
 
-### 3. Parse Responses
+---
+
+## 📤 Response Handling
+
+### Manual Parsing
 
 ```typescript
 const response = await client.url.api.get({ path: "/data" });
 
-// As JSON
+// Parse as JSON
 const json = await response.body.json();
 
-// As text
+// Parse as text
 const text = await response.body.text();
 
-// As ArrayBuffer
+// Get as buffer
 const buffer = await response.body.arrayBuffer();
 ```
 
-### 4. Auto-Parse with `responseType`
+### Auto-Parse (Recommended)
+
+Let Jiren parse the response automatically:
 
 ```typescript
-// Automatically parse JSON
+// Auto-parse JSON
 const users = await client.url.api.get({
   path: "/users",
-  responseType: "json", // Returns parsed JSON directly
+  responseType: "json", // ← Returns parsed data directly!
 });
 
-// Automatically get text
-const html = await client.url.google.get({
-  responseType: "text", // Returns string directly
+// Auto-parse text
+const html = await client.url.api.get({
+  path: "/page",
+  responseType: "text",
 });
 ```
 
-### 5. POST, PUT, PATCH, DELETE
+### Response Properties
 
 ```typescript
-// POST with JSON body
-const created = await client.url.api.post(
-  JSON.stringify({ name: "John Doe", email: "john@example.com" }),
-  {
-    path: "/users",
-    headers: { "Content-Type": "application/json" },
-    responseType: "json",
-  }
-);
-
-// PUT request
-await client.url.api.put(JSON.stringify({ name: "Jane Doe" }), {
-  path: "/users/123",
-  headers: { "Content-Type": "application/json" },
-});
-
-// PATCH request
-await client.url.api.patch(JSON.stringify({ email: "new@example.com" }), {
-  path: "/users/123",
-});
+const response = await client.url.api.get({ path: "/users" });
 
-// DELETE request
-await client.url.api.delete(null, { path: "/users/123" });
+console.log(response.status); // 200
+console.log(response.ok); // true
+console.log(response.headers); // { "content-type": "application/json", ... }
+console.log(response.redirected); // false
 ```
 
 ---
 
-## Response Caching
+## 💾 Caching
 
-Enable persistent file-based caching for **instant responses** on subsequent requests:
+Enable caching for instant responses on repeated requests:
 
-### Basic Caching
+### Enable Caching
 
 ```typescript
 const client = new JirenClient({
-  warmup: {
+  targets: {
     api: {
       url: "https://api.example.com",
-      cache: true, // Enable 60-second cache
+      cache: true, // ← Enable caching (60s default)
     },
   },
 });
-
-// First request: Real HTTP request (~150ms)
-const data1 = await client.url.api.get({ path: "/users" });
-
-// Second request: From cache (~1-2ms) - 100x faster! ⚡
-const data2 = await client.url.api.get({ path: "/users" });
 ```
 
-### Custom Cache TTL
+### Custom Cache Duration
 
 ```typescript
 const client = new JirenClient({
-  warmup: {
+  targets: {
     api: {
       url: "https://api.example.com",
-      cache: { ttl: 300000 }, // 5-minute cache
+      cache: { ttl: 300000 }, // 5 minutes
     },
     cdn: {
       url: "https://cdn.example.com",
-      cache: { ttl: 3600000 }, // 1-hour cache
+      cache: { ttl: 3600000 }, // 1 hour
     },
   },
 });
 ```
 
-### Manual Cache Refresh
-
-```typescript
-// Refresh cache for a specific endpoint
-await client.url.api.prefetch({ path: "/users" });
-
-// Now the next request will use fresh data
-const users = await client.url.api.get({ path: "/users" });
-```
-
-### Cache Features
+### Cache Performance
 
-- ✅ **Persistent** - Survives process restarts
-- ✅ **Compressed** - Gzip-compressed JSON files (`.cache/jiren/*.json.gz`)
-- ✅ **Automatic expiration** - Respects TTL
-- ✅ **Fast** - ~100x faster than real requests
+| Request Type   | Speed  | Improvement        |
+| -------------- | ------ | ------------------ |
+| First request  | ~150ms | -                  |
+| Cached request | ~1-2ms | **100x faster** ⚡ |
 
-### Cache Performance
+### 🚀 Performance Benchmark
 
-| Type         | Speed  | Use Case                                        |
-| ------------ | ------ | ----------------------------------------------- |
-| Real request | ~150ms | First request or cache miss                     |
-| File cache   | ~1-2ms | Subsequent requests (same or different process) |
-| Memory cache | ~0.1ms | Multiple requests in same process               |
+See the [top of this README](#-performance-fastest-in-the-world) for detailed benchmark results. Jiren consistently wins on throughput and tail latency.
 
-**💡 Tip:** Add `.cache/` to your `.gitignore`:
+### Refresh Cache
 
-```gitignore
-# Jiren cache
-.cache/
+```typescript
+// Force refresh cached data
+await client.url.api.prefetch({ path: "/users" });
 ```
 
+> 💡 **Tip:** Add `.cache/` to your `.gitignore`
+
 ---
 
-## Anti-Bot Protection
+## 🔒 Anti-Bot Protection
 
-Bypass Cloudflare and other bot protection using Chrome TLS fingerprinting:
+Bypass Cloudflare and other bot protections:
 
 ```typescript
 const client = new JirenClient({
-  warmup: {
-    protected: "https://cloudflare-protected-site.com",
-    antibot: true,
+  targets: {
+    protected: "https://protected-site.com",
   },
+  antibot: true,
 });
 
-// Enable anti-bot mode for this request
 const response = await client.url.protected.get();
 ```
 
-**How it works:**
-
-- Uses `curl-impersonate` to mimic Chrome 120 browser
-- Includes realistic TLS fingerprint and headers
-- Bypasses most bot detection systems
-
 ---
 
-## Request Interceptors
+## 🔄 Interceptors
 
-Add middleware to intercept requests and responses for logging, auth injection, and more:
+Add middleware to modify requests/responses:
 
-### Basic Interceptors
+### Add Authentication
 
 ```typescript
 const client = new JirenClient({
-  warmup: { api: "https://api.example.com" },
+  targets: { api: "https://api.example.com" },
   interceptors: {
-    // Modify requests before sending
     request: [
       (ctx) => ({
         ...ctx,
-        headers: { ...ctx.headers, Authorization: `Bearer ${getToken()}` },
+        headers: {
+          ...ctx.headers,
+          Authorization: `Bearer ${getToken()}`,
+        },
       }),
     ],
-    // Transform responses after receiving
+  },
+});
+```
+
+### Log Responses
+
+```typescript
+const client = new JirenClient({
+  targets: { api: "https://api.example.com" },
+  interceptors: {
     response: [
       (ctx) => {
-        console.log(`[${ctx.response.status}] ${ctx.request.url}`);
+        console.log(`${ctx.response.status} ${ctx.request.url}`);
         return ctx;
       },
     ],
-    // Handle errors
-    error: [(err, ctx) => console.error(`Failed: ${ctx.url}`, err)],
   },
 });
 ```
 
-### Dynamic Interceptors with `use()`
+### Handle Errors
+
+```typescript
+const client = new JirenClient({
+  targets: { api: "https://api.example.com" },
+  interceptors: {
+    error: [
+      (error, ctx) => {
+        console.error(`Request failed: ${ctx.url}`);
+      },
+    ],
+  },
+});
+```
+
+### Add Interceptors Later
 
 ```typescript
-// Add interceptors after client creation
 client.use({
   request: [
     (ctx) => ({ ...ctx, headers: { ...ctx.headers, "X-Custom": "value" } }),
@@ -284,184 +316,47 @@ client.use({
 });
 ```
 
-### Interceptor Types
-
-| Type       | Purpose                                          | Context                          |
-| ---------- | ------------------------------------------------ | -------------------------------- |
-| `request`  | Modify method, URL, headers, body before sending | `{ method, url, headers, body }` |
-| `response` | Transform response after receiving               | `{ request, response }`          |
-| `error`    | Handle errors centrally                          | `(error, requestContext)`        |
-
 ---
 
-## Metrics & Observability
+## 📊 Metrics
 
-Track performance, cache efficiency, and request statistics with built-in metrics collection:
+Track performance and cache efficiency:
 
-### Basic Metrics
+### Get Endpoint Metrics
 
 ```typescript
-const client = new JirenClient({
-  warmup: {
-    api: {
-      url: "https://api.example.com",
-      cache: true,
-    },
-  },
-});
-
-// Make some requests
-await client.url.api.get({ path: "/users" });
-await client.url.api.get({ path: "/users" }); // Cache hit
-
-// Get endpoint metrics
 const metrics = client.metrics.get("api");
-console.log(metrics);
-/*
-{
-  endpoint: "api",
-  requests: {
-    total: 2,
-    success: 2,
-    failed: 0
-  },
-  statusCodes: { 200: 2 },
-  timing: {
-    avgMs: 50.5,
-    minMs: 0.01,
-    maxMs: 101,
-    p50Ms: 50.5,
-    p95Ms: 101,
-    p99Ms: 101
-  },
-  cache: {
-    l1Hits: 1,
-    l1Misses: 1,
-    l2Hits: 0,
-    l2Misses: 1,
-    hitRate: "50.00%"
-  },
-  deduplication: {
-    hits: 0,
-    misses: 2,
-    hitRate: "0.00%"
-  },
-  bytes: {
-    sent: 0,
-    received: 0
-  },
-  errors: {},
-  lastRequestAt: 1234567890000
-}
-*/
+
+console.log(metrics.requests.total); // Total requests made
+console.log(metrics.timing.avgMs); // Average response time
+console.log(metrics.cache.hitRate); // Cache hit percentage
 ```
 
-### Global Metrics
+### Get Global Metrics
 
 ```typescript
-// Get aggregated metrics across all endpoints
 const global = client.metrics.getGlobal();
-console.log(global);
-/*
-{
-  totalRequests: 8,
-  totalSuccess: 8,
-  totalFailed: 0,
-  avgResponseTimeMs: 125.5,
-  totalBytesSent: 1024,
-  totalBytesReceived: 4096,
-  overallCacheHitRate: "62.50%",
-  overallDeduplicationRate: "25.00%",
-  endpoints: 2,
-  uptime: 60000
-}
-*/
-```
-
-### All Endpoints
 
-```typescript
-// Get metrics for all endpoints
-const allMetrics = client.metrics.getAll();
-for (const [endpoint, metrics] of Object.entries(allMetrics)) {
-  console.log(`${endpoint}: ${metrics.cache.hitRate} cache hit rate`);
-}
+console.log(global.totalRequests); // All requests
+console.log(global.avgResponseTimeMs); // Average across all endpoints
+console.log(global.overallCacheHitRate); // Overall cache performance
 ```
 
-### Export Metrics
+### Export & Reset
 
 ```typescript
-// Export all metrics as JSON
+// Export as JSON
 const json = client.metrics.export();
-console.log(json); // Pretty-printed JSON string
 
-// Save to file or send to monitoring service
-await Bun.write("metrics.json", json);
-```
-
-### Reset Metrics
-
-```typescript
-// Reset specific endpoint
-client.metrics.reset("api");
-
-// Reset all metrics
+// Reset metrics
 client.metrics.reset();
 ```
 
-### Tracked Metrics
-
-| Category     | Metrics                                                    |
-| ------------ | ---------------------------------------------------------- |
-| **Requests** | Total, success, failed, status code distribution           |
-| **Timing**   | Average, min, max, P50, P95, P99 response times            |
-| **Cache**    | L1/L2 hits & misses, overall hit rate                      |
-| **Dedupe**   | Deduplication hits/misses for identical in-flight requests |
-| **Bytes**    | Total sent/received                                        |
-| **Errors**   | Error counts by type                                       |
-| **Other**    | Last request timestamp, client uptime                      |
-
-### Use Cases
-
-**Performance Monitoring:**
-
-```typescript
-// Track P99 latency
-setInterval(() => {
-  const metrics = client.metrics.getGlobal();
-  if (metrics.avgResponseTimeMs > 1000) {
-    console.warn("High latency detected!");
-  }
-}, 60000);
-```
-
-**Cache Optimization:**
-
-```typescript
-// Monitor cache effectiveness
-const metrics = client.metrics.get("api");
-console.log(`Cache hit rate: ${metrics.cache.hitRate}`);
-if (parseFloat(metrics.cache.hitRate) < 50) {
-  console.log("Consider increasing cache TTL");
-}
-```
-
-**Debugging:**
-
-```typescript
-// Export metrics for debugging
-if (process.env.DEBUG) {
-  process.on("exit", () => {
-    console.log(client.metrics.export());
-  });
-}
-```
-
 ---
 
-## Advanced Features
+## 🔷 TypeScript Support
 
-### TypeScript Generics
+### Type-Safe Responses
 
 ```typescript
 interface User {
@@ -470,194 +365,92 @@ interface User {
   email: string;
 }
 
-// Type-safe response
+// TypeScript knows the response type!
 const user = await client.url.api.get<User>({
   path: "/users/123",
   responseType: "json",
 });
 
-console.log(user.name); // TypeScript knows this is a string
+console.log(user.name); // ✅ Autocomplete works!
 ```
 
-### Multiple Warmup Formats
+### Typed URL Keys
 
 ```typescript
-// Object format (recommended)
-const client1 = new JirenClient({
-  warmup: {
+const client = new JirenClient({
+  targets: {
     api: "https://api.example.com",
     cdn: "https://cdn.example.com",
   },
 });
 
-// Array format (with cache config)
-const client2 = new JirenClient({
-  warmup: [
-    { key: "api", url: "https://api.example.com", cache: true },
-    { key: "cdn", url: "https://cdn.example.com", cache: { ttl: 3600000 } },
-  ],
-});
-
-// Simple array
-const client3 = new JirenClient({
-  warmup: ["https://api.example.com", "https://cdn.example.com"],
-});
-```
-
-### Benchmark Mode
-
-Force HTTP/2 for consistent benchmarking:
-
-```typescript
-const client = new JirenClient({
-  warmup: { api: "https://api.example.com" },
-  benchmark: true, // Disables HTTP/3 probing, forces HTTP/2
-});
-```
-
-### Close Client
-
-```typescript
-// Clean up resources when done
-client.close();
-```
-
----
-
-## Performance
-
-### Benchmark Results
-
+client.url.api.get(); // ✅ Valid
+client.url.cdn.get(); // ✅ Valid
+client.url.foo.get(); // ❌ TypeScript error!
 ```
-Bun fetch:        ~300ms
-JirenClient:      ~120ms  (2.5x faster)
-JirenClient (cached): ~1-2ms  (150x faster)
-```
-
-### Performance Tips
-
-1. **Always use warmup** - Pre-establishes connections
-2. **Enable caching** - For data that doesn't change frequently
-3. **Reuse client instances** - Don't create new clients for each request
-4. **Use `responseType`** - Automatic parsing is faster
-5. **Batch requests** - Use `Promise.all()` for concurrent requests
-
-### Why So Fast?
-
-- **Native Zig implementation** - No JavaScript overhead
-- **HTTP/3 (QUIC) support** - Faster than HTTP/2 when available
-- **Connection pooling** - Reuses TCP/TLS connections
-- **Smart caching** - Compressed persistent cache
-- **Zero-copy operations** - Minimal memory allocations
-- **TCP keep-alive** - Prevents connection drops
 
 ---
 
-## API Reference
-
-### `JirenClient` Constructor
-
-```typescript
-new JirenClient(options?: JirenClientOptions)
-```
-
-**Options:**
-
-| Option      | Type                                               | Description                  |
-| ----------- | -------------------------------------------------- | ---------------------------- |
-| `warmup`    | `Record<string, UrlConfig>` \| `WarmupUrlConfig[]` | URLs to pre-warm (required)  |
-| `benchmark` | `boolean`                                          | Force HTTP/2 mode (optional) |
+## 📚 API Reference
 
-**UrlConfig:**
+### Creating a Client
 
 ```typescript
-type UrlConfig =
-  | string
-  | {
-      url: string;
-      cache?: boolean | { ttl: number };
-    };
-```
-
-### URL Endpoint Methods
-
-All methods are available on `client.url.<key>`:
-
-#### `get(options?)`
-
-```typescript
-get<T>(options?: UrlRequestOptions): Promise<JirenResponse<T>>
-```
-
-#### `post(body?, options?)`
-
-```typescript
-post<T>(body?: string | null, options?: UrlRequestOptions): Promise<JirenResponse<T>>
-```
-
-#### `put(body?, options?)`
-
-```typescript
-put<T>(body?: string | null, options?: UrlRequestOptions): Promise<JirenResponse<T>>
-```
-
-#### `patch(body?, options?)`
-
-```typescript
-patch<T>(body?: string | null, options?: UrlRequestOptions): Promise<JirenResponse<T>>
-```
-
-#### `delete(body?, options?)`
-
-```typescript
-delete<T>(body?: string | null, options?: UrlRequestOptions): Promise<JirenResponse<T>>
-```
-
-#### `head(options?)`
-
-```typescript
-head(options?: UrlRequestOptions): Promise<JirenResponse<any>>
-```
+new JirenClient({
+  targets: {
+    // Simple URL
+    api: "https://api.example.com",
 
-#### `options(options?)`
+    // With caching
+    cdn: {
+      url: "https://cdn.example.com",
+      cache: true, // or { ttl: 60000 }
+    },
+  },
 
-```typescript
-options(options?: UrlRequestOptions): Promise<JirenResponse<any>>
+  // Optional settings
+  antibot: false, // Enable anti-bot protection
+  benchmark: false, // Benchmark mode
+  interceptors: {}, // Request/response interceptors
+});
 ```
 
-#### `prefetch(options?)`
+### Request Methods
 
-```typescript
-prefetch(options?: UrlRequestOptions): Promise<void>
-```
-
-Clears cache and makes a fresh request to populate cache.
+| Method       | Signature                                          |
+| ------------ | -------------------------------------------------- |
+| `get()`      | `get<T>(options?): Promise<Response<T>>`           |
+| `post()`     | `post<T>(body?, options?): Promise<Response<T>>`   |
+| `put()`      | `put<T>(body?, options?): Promise<Response<T>>`    |
+| `patch()`    | `patch<T>(body?, options?): Promise<Response<T>>`  |
+| `delete()`   | `delete<T>(body?, options?): Promise<Response<T>>` |
+| `head()`     | `head(options?): Promise<Response>`                |
+| `options()`  | `options(options?): Promise<Response>`             |
+| `prefetch()` | `prefetch(options?): Promise<void>`                |
 
 ### Request Options
 
 ```typescript
-interface UrlRequestOptions {
-  path?: string; // Path to append to base URL
+{
+  path?: string;                    // URL path to append
   headers?: Record<string, string>; // Request headers
-  responseType?: "json" | "text"; // Auto-parse response
-  antibot?: boolean; // Enable anti-bot protection
-  maxRedirects?: number; // Max redirects to follow
+  responseType?: "json" | "text";   // Auto-parse response
+  maxRedirects?: number;            // Max redirects (default: 5)
 }
 ```
 
 ### Response Object
 
 ```typescript
-interface JirenResponse<T = any> {
+{
   url: string;
   status: number;
   statusText: string;
   headers: Record<string, string>;
   ok: boolean;
   redirected: boolean;
-  type: string;
   body: {
-    json<R = T>(): Promise<R>;
+    json<T>(): Promise<T>;
     text(): Promise<string>;
     arrayBuffer(): Promise<ArrayBuffer>;
     blob(): Promise<Blob>;
@@ -667,89 +460,132 @@ interface JirenResponse<T = any> {
 
 ---
 
-## Examples
+## 💡 Examples
 
-### Real-World React App
+### API Client Pattern
 
 ```typescript
-// api-client.ts
+// lib/api.ts
 import { JirenClient } from "jiren";
 
-export const apiClient = new JirenClient({
-  warmup: {
+export const api = new JirenClient({
+  targets: {
     backend: {
-      url: "https://api.myapp.com",
-      cache: true, // Cache API responses
-    },
-    cdn: {
-      url: "https://cdn.myapp.com",
-      cache: { ttl: 3600000 }, // 1-hour cache for static assets
+      url: process.env.API_URL!,
+      cache: { ttl: 30000 },
     },
   },
+  interceptors: {
+    request: [
+      (ctx) => ({
+        ...ctx,
+        headers: {
+          ...ctx.headers,
+          Authorization: `Bearer ${getSession()?.token}`,
+        },
+      }),
+    ],
+  },
 });
 
-// UserProfile.tsx
-import { apiClient } from "./api-client";
+// Usage anywhere
+import { api } from "@/lib/api";
+const users = await api.url.backend.get({
+  path: "/users",
+  responseType: "json",
+});
+```
 
-function UserProfile() {
-  const [user, setUser] = useState(null);
+### React/Next.js Hook
+
+```typescript
+function useApi<T>(path: string) {
+  const [data, setData] = useState<T | null>(null);
+  const [loading, setLoading] = useState(true);
 
   useEffect(() => {
-    // Fast! Uses cache if available
-    apiClient.url.backend
-      .get({ path: "/user/me", responseType: "json" })
-      .then(setUser);
-  }, []);
+    api.url.backend
+      .get<T>({ path, responseType: "json" })
+      .then(setData)
+      .finally(() => setLoading(false));
+  }, [path]);
+
+  return { data, loading };
+}
 
-  return <div>{user?.name}</div>;
+// Usage
+function UserList() {
+  const { data: users, loading } = useApi<User[]>("/users");
+  if (loading) return <Spinner />;
+  return (
+    <ul>
+      {users?.map((u) => (
+        <li key={u.id}>{u.name}</li>
+      ))}
+    </ul>
+  );
 }
 ```
 
-### Polling with Cache
+---
+
+## 🏗️ Framework Integration
+
+### Next.js (App Router)
+
+To use Jiren in Next.js, add it to `serverExternalPackages` in `next.config.ts`:
 
 ```typescript
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  // Required: Treat Jiren and Koffi as external native packages
+  serverExternalPackages: ["jiren", "koffi"],
+};
+
+export default nextConfig;
+```
+
+**Usage in API Routes:**
+
+```typescript
+// app/api/data/route.ts
+import { JirenClient } from "jiren";
+
 const client = new JirenClient({
-  warmup: {
-    api: {
-      url: "https://api.example.com",
-      cache: { ttl: 30000 }, // 30-second cache
-    },
-  },
+  targets: [{ key: "api", url: "https://api.example.com" }],
 });
 
-// Poll every 10 seconds
-setInterval(async () => {
-  // First 3 requests use cache, 4th request is fresh
-  const notifications = await client.url.api.get({
-    path: "/notifications",
-    responseType: "json",
-  });
-
-  updateUI(notifications);
-}, 10000);
+export async function GET() {
+  const response = await client.url.api.get({ path: "/users" });
+  return Response.json(await response.body.json());
+}
 ```
 
 ---
 
-## Requirements
+## 📋 Requirements
 
-- **Bun** v1.0.0 or higher
+- **Runtime**:
+  - **Bun** v1.0.0+
+  - **Node.js** v18.0.0+ (macOS/Linux)
+- **OS**: macOS (ARM64/x64) or Linux (x64)
 
 ---
 
-## License
+## 📄 License
 
-MIT © Vikash Khati
+MIT © VK
 
 ---
 
-## Contributing
+## 🤝 Contributing
 
-Contributions are welcome! Please open an issue or submit a pull request.
+Contributions welcome! Please open an issue or submit a pull request.
 
 ---
 
-## Support
+## 🆘 Support
 
 - 📖 [Documentation](https://github.com/vikashkhati007/jiren)
 - 🐛 [Issue Tracker](https://github.com/vikashkhati007/jiren/issues)
@@ -757,4 +593,6 @@ Contributions are welcome! Please open an issue or submit a pull request.
 
 ---
 
-**Made with ⚡ by the Jiren team**
+<p align="center">
+  <strong>Made with ⚡ by VK</strong>
+</p>