jiren 1.4.5 → 1.5.5

package/README.md

@@ -1,282 +1,296 @@
 # 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?
+---
+
+## ✨ Why Jiren?
 
-- ⚡ **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
+| Feature                  | Benefit                                           |
+| ------------------------ | ------------------------------------------------- |
+| ⚡ **Blazing Fast**      | 2-3x faster than native `fetch`                   |
+| � **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
+## 📦 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: {
     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)
-- [Advanced Features](#advanced-features)
-- [Performance](#performance)
-- [API Reference](#api-reference)
+That's it! 🎉
 
 ---
 
-## Basic Usage
+## 📖 Table of Contents
+
+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)
+
+---
 
-### 1. Create a Client
+## 🌐 Making Requests
 
-**Warmup is mandatory** - define your URLs upfront for optimal performance:
+### 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" },
+});
 
-// GET with path and headers
-const user = await client.url.github.get({
-  path: "/users/octocat",
-  headers: { Authorization: "token YOUR_TOKEN" },
+// PUT
+await client.url.api.put(JSON.stringify({ name: "Updated" }), {
+  path: "/users/123",
 });
+
+// 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: {
     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: {
     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
-
-- ✅ **Persistent** - Survives process restarts
-- ✅ **Compressed** - Gzip-compressed JSON files (`.cache/jiren/*.json.gz`)
-- ✅ **Automatic expiration** - Respects TTL
-- ✅ **Fast** - ~100x faster than real requests
-
 ### Cache Performance
 
-| 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               |
+| Request Type   | Speed  | Improvement        |
+| -------------- | ------ | ------------------ |
+| First request  | ~150ms | -                  |
+| Cached request | ~1-2ms | **100x faster** ⚡ |
 
-**💡 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",
+    protected: "https://protected-site.com",
   },
+  antibot: true,
 });
 
-// Enable anti-bot mode for this request
-const response = await client.url.protected.get({
-  antibot: true, // Uses curl-impersonate with Chrome 120 fingerprint
-});
+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" },
   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({
+  warmup: { 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({
+  warmup: { 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,215 +298,141 @@ 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)`        |
-
 ---
 
-## Advanced Features
-
-### TypeScript Generics
+## 📊 Metrics
 
-```typescript
-interface User {
-  id: number;
-  name: string;
-  email: string;
-}
-
-// Type-safe response
-const user = await client.url.api.get<User>({
-  path: "/users/123",
-  responseType: "json",
-});
-
-console.log(user.name); // TypeScript knows this is a string
-```
+Track performance and cache efficiency:
 
-### Multiple Warmup Formats
+### Get Endpoint Metrics
 
 ```typescript
-// Object format (recommended)
-const client1 = new JirenClient({
-  warmup: {
-    api: "https://api.example.com",
-    cdn: "https://cdn.example.com",
-  },
-});
+const metrics = client.metrics.get("api");
 
-// 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"],
-});
+console.log(metrics.requests.total); // Total requests made
+console.log(metrics.timing.avgMs); // Average response time
+console.log(metrics.cache.hitRate); // Cache hit percentage
 ```
 
-### Benchmark Mode
-
-Force HTTP/2 for consistent benchmarking:
+### Get Global Metrics
 
 ```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
+const global = client.metrics.getGlobal();
 
+console.log(global.totalRequests); // All requests
+console.log(global.avgResponseTimeMs); // Average across all endpoints
+console.log(global.overallCacheHitRate); // Overall cache performance
 ```
-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
+### Export & Reset
 
 ```typescript
-new JirenClient(options?: JirenClientOptions)
-```
-
-**Options:**
+// Export as JSON
+const json = client.metrics.export();
 
-| Option      | Type                                               | Description                  |
-| ----------- | -------------------------------------------------- | ---------------------------- |
-| `warmup`    | `Record<string, UrlConfig>` \| `WarmupUrlConfig[]` | URLs to pre-warm (required)  |
-| `benchmark` | `boolean`                                          | Force HTTP/2 mode (optional) |
-
-**UrlConfig:**
-
-```typescript
-type UrlConfig =
-  | string
-  | {
-      url: string;
-      cache?: boolean | { ttl: number };
-    };
+// Reset metrics
+client.metrics.reset();
 ```
 
-### URL Endpoint Methods
+---
 
-All methods are available on `client.url.<key>`:
+## 🔷 TypeScript Support
 
-#### `get(options?)`
+### Type-Safe Responses
 
 ```typescript
-get<T>(options?: UrlRequestOptions): Promise<JirenResponse<T>>
-```
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
 
-#### `post(body?, options?)`
+// TypeScript knows the response type!
+const user = await client.url.api.get<User>({
+  path: "/users/123",
+  responseType: "json",
+});
 
-```typescript
-post<T>(body?: string | null, options?: UrlRequestOptions): Promise<JirenResponse<T>>
+console.log(user.name); // ✅ Autocomplete works!
 ```
 
-#### `put(body?, options?)`
+### Typed URL Keys
 
 ```typescript
-put<T>(body?: string | null, options?: UrlRequestOptions): Promise<JirenResponse<T>>
-```
-
-#### `patch(body?, options?)`
+const client = new JirenClient({
+  warmup: {
+    api: "https://api.example.com",
+    cdn: "https://cdn.example.com",
+  },
+});
 
-```typescript
-patch<T>(body?: string | null, options?: UrlRequestOptions): Promise<JirenResponse<T>>
+client.url.api.get(); // ✅ Valid
+client.url.cdn.get(); // ✅ Valid
+client.url.foo.get(); // ❌ TypeScript error!
 ```
 
-#### `delete(body?, options?)`
+---
 
-```typescript
-delete<T>(body?: string | null, options?: UrlRequestOptions): Promise<JirenResponse<T>>
-```
+## 📚 API Reference
 
-#### `head(options?)`
+### Creating a Client
 
 ```typescript
-head(options?: UrlRequestOptions): Promise<JirenResponse<any>>
-```
+new JirenClient({
+  warmup: {
+    // 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?)`
-
-```typescript
-prefetch(options?: UrlRequestOptions): Promise<void>
-```
+### Request Methods
 
-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>;
@@ -502,89 +442,94 @@ 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({
+export const api = new JirenClient({
   warmup: {
     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";
-
-function UserProfile() {
-  const [user, setUser] = useState(null);
-
-  useEffect(() => {
-    // Fast! Uses cache if available
-    apiClient.url.backend
-      .get({ path: "/user/me", responseType: "json" })
-      .then(setUser);
-  }, []);
-
-  return <div>{user?.name}</div>;
-}
+// Usage anywhere
+import { api } from "@/lib/api";
+const users = await api.url.backend.get({
+  path: "/users",
+  responseType: "json",
+});
 ```
 
-### Polling with Cache
+### React/Next.js Hook
 
 ```typescript
-const client = new JirenClient({
-  warmup: {
-    api: {
-      url: "https://api.example.com",
-      cache: { ttl: 30000 }, // 30-second cache
-    },
-  },
-});
+function useApi<T>(path: string) {
+  const [data, setData] = useState<T | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    api.url.backend
+      .get<T>({ path, responseType: "json" })
+      .then(setData)
+      .finally(() => setLoading(false));
+  }, [path]);
 
-// 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",
-  });
+  return { data, loading };
+}
 
-  updateUI(notifications);
-}, 10000);
+// 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>
+  );
+}
 ```
 
 ---
 
-## Requirements
+## 📋 Requirements
 
-- **Bun** v1.0.0 or higher
+- **Bun** v1.0.0+
 
 ---
 
-## License
+## 📄 License
 
 MIT © Vikash Khati
 
 ---
 
-## 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)
@@ -592,4 +537,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 Vikash Khati</strong>
+</p>