jiren 1.5.5 → 1.6.5

package/README.md

@@ -1,22 +1,54 @@
 # Jiren 🚀
 
-**The fastest HTTP client for JavaScript** - Simple, type-safe, and blazingly fast.
+**The fastest HTTP client for JavaScript** — Native Zig core, type-safe, batteries included.
 
 [![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)
 
 ---
 
+## ⚡ Performance
+
+Jiren beats every major HTTP client — **52% faster than Bun Fetch**.
+
+### Concurrent Benchmark (mitata)
+
+| Client     | Avg Latency | Req/sec      | vs Jiren       |
+| ---------- | ----------- | ------------ | -------------- |
+| **Jiren**  | **20.9 µs** | **47,800/s** | 🏆 **Fastest** |
+| Bun Fetch  | 31.7 µs     | 31,500/s     | 52% slower     |
+| Node-Fetch | 29.4 µs     | 34,000/s     | 41% slower     |
+| Undici     | 37.1 µs     | 27,000/s     | 77% slower     |
+| Ky         | 36.5 µs     | 27,400/s     | 75% slower     |
+| Axios      | 59.5 µs     | 16,800/s     | 185% slower    |
+| Got        | 61.3 µs     | 16,300/s     | 193% slower    |
+
+### Sequential Benchmark
+
+| Client     | Avg Latency | Req/sec      | vs Jiren       |
+| ---------- | ----------- | ------------ | -------------- |
+| **Jiren**  | **20.7 µs** | **48,300/s** | 🏆 **Fastest** |
+| Bun Fetch  | 27.9 µs     | 35,800/s     | 35% slower     |
+| Node-Fetch | 29.8 µs     | 33,600/s     | 44% slower     |
+| Undici     | 30.6 µs     | 32,700/s     | 48% slower     |
+| Ky         | 35.6 µs     | 28,100/s     | 72% slower     |
+| Axios      | 56.6 µs     | 17,700/s     | 173% slower    |
+| Got        | 59.9 µs     | 16,700/s     | 189% slower    |
+
+> Benchmarked on Apple M4, Bun 1.3.0
+
+---
+
 ## ✨ Why Jiren?
 
-| 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                  |
+- ⚡ **52% Faster Than Bun** — Native Zig core, zero overhead
+- 🔄 **HTTP/2 & HTTP/3** — Automatic protocol upgrade
+- 💾 **Smart Caching** — L1 memory + L2 disk, 100x faster repeat requests
+- 📝 **Type-Safe** — Full TypeScript with autocomplete
+- 🔒 **Anti-Bot Mode** — Bypass Cloudflare & bot protections
+- 📊 **Built-in Metrics** — Track latency, cache hits, and more
+- 🔌 **Interceptors** — Add auth, logging, error handling
+- 🎯 **Zero Config** — Just works out of the box
 
 ---
 
@@ -24,11 +56,27 @@
 
 ```bash
 bun add jiren
+# or
+npm install jiren
 ```
 
 ---
 
-## 🚀 Quick Start
+## � Table of Contents
+
+1. [Quick Start](#-quick-start)
+2. [Making Requests](#-making-requests)
+3. [Response Handling](#-response-handling)
+4. [Caching](#-caching)
+5. [Anti-Bot Protection](#-anti-bot-protection)
+6. [Interceptors](#-interceptors)
+7. [Metrics](#-metrics)
+8. [TypeScript Support](#-typescript-support)
+9. [Framework Integration](#-framework-integration)
+
+---
+
+## �🚀 Quick Start
 
 ### Step 1: Create Your Client
 
@@ -36,7 +84,7 @@ bun add jiren
 import { JirenClient } from "jiren";
 
 const client = new JirenClient({
-  warmup: {
+  targets: {
     api: "https://api.example.com",
     github: "https://api.github.com",
   },
@@ -61,19 +109,6 @@ That's it! 🎉
 
 ---
 
-## 📖 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)
-
----
-
 ## 🌐 Making Requests
 
 ### GET Requests
@@ -136,13 +171,11 @@ const buffer = await response.body.arrayBuffer();
 
 ### Auto-Parse (Recommended)
 
-Let Jiren parse the response automatically:
-
 ```typescript
-// Auto-parse JSON
-const users = await client.url.api.get({
+// Auto-parse JSON - returns parsed data directly!
+const users = await client.url.api.get<User[]>({
   path: "/users",
-  responseType: "json", // ← Returns parsed data directly!
+  responseType: "json",
 });
 
 // Auto-parse text
@@ -165,104 +198,92 @@ console.log(response.redirected); // false
 
 ---
 
-## 💾 Caching
+## � TypeScript Support
+
+### Type-Safe Responses
 
-Enable caching for instant responses on repeated requests:
+```typescript
+// Define your types
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
 
-### Enable Caching
+// Get typed responses
+const users = await client.url.api.get<User[]>({
+  path: "/users",
+  responseType: "json",
+});
+
+// users is typed as User[]!
+users.forEach((user) => console.log(user.name));
+```
+
+### Type-Safe Target URLs
 
 ```typescript
+import { JirenClient } from "jiren";
+
+// Use object targets for typed URL endpoints
 const client = new JirenClient({
-  warmup: {
-    api: {
-      url: "https://api.example.com",
-      cache: true, // ← Enable caching (60s default)
-    },
+  targets: {
+    api: "https://api.example.com",
+    github: "https://api.github.com",
+    stripe: "https://api.stripe.com",
   },
 });
+
+// All targets are typed and autocomplete-enabled!
+await client.url.api.get({ path: "/users" });
+await client.url.github.get({ path: "/repos" });
+await client.url.stripe.post(body, { path: "/charges" });
 ```
 
-### Custom Cache Duration
+## 💾 Caching
 
 ```typescript
 const client = new JirenClient({
-  warmup: {
+  targets: {
     api: {
       url: "https://api.example.com",
-      cache: { ttl: 300000 }, // 5 minutes
-    },
-    cdn: {
-      url: "https://cdn.example.com",
-      cache: { ttl: 3600000 }, // 1 hour
+      cache: true, // Enable (60s default)
+      // cache: { ttl: 300000 },      // Custom TTL (5 min)
     },
   },
 });
-```
-
-### Cache Performance
-
-| Request Type   | Speed  | Improvement        |
-| -------------- | ------ | ------------------ |
-| First request  | ~150ms | -                  |
-| Cached request | ~1-2ms | **100x faster** ⚡ |
-
-### Refresh Cache
 
-```typescript
-// Force refresh cached data
-await client.url.api.prefetch({ path: "/users" });
+// First request: ~100ms
+// Cached request: ~1ms (100x faster!)
 ```
 
-> 💡 **Tip:** Add `.cache/` to your `.gitignore`
-
 ---
 
 ## 🔒 Anti-Bot Protection
 
-Bypass Cloudflare and other bot protections:
-
 ```typescript
 const client = new JirenClient({
-  warmup: {
+  targets: {
     protected: "https://protected-site.com",
   },
   antibot: true,
 });
-
-const response = await client.url.protected.get();
 ```
 
 ---
 
 ## 🔄 Interceptors
 
-Add middleware to modify requests/responses:
-
-### Add Authentication
-
 ```typescript
 const client = new JirenClient({
-  warmup: { api: "https://api.example.com" },
+  targets: { api: "https://api.example.com" },
   interceptors: {
     request: [
       (ctx) => ({
         ...ctx,
-        headers: {
-          ...ctx.headers,
-          Authorization: `Bearer ${getToken()}`,
-        },
+        headers: { ...ctx.headers, Authorization: `Bearer ${token}` },
       }),
     ],
-  },
-});
-```
-
-### Log Responses
-
-```typescript
-const client = new JirenClient({
-  warmup: { api: "https://api.example.com" },
-  interceptors: {
     response: [
       (ctx) => {
         console.log(`${ctx.response.status} ${ctx.request.url}`);
@@ -273,239 +294,41 @@ const client = new JirenClient({
 });
 ```
 
-### 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
-client.use({
-  request: [
-    (ctx) => ({ ...ctx, headers: { ...ctx.headers, "X-Custom": "value" } }),
-  ],
-});
-```
-
 ---
 
 ## 📊 Metrics
 
-Track performance and cache efficiency:
-
-### Get Endpoint Metrics
-
 ```typescript
 const metrics = client.metrics.get("api");
-
-console.log(metrics.requests.total); // Total requests made
-console.log(metrics.timing.avgMs); // Average response time
-console.log(metrics.cache.hitRate); // Cache hit percentage
-```
-
-### Get Global Metrics
-
-```typescript
-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
-```
-
-### Export & Reset
-
-```typescript
-// Export as JSON
-const json = client.metrics.export();
-
-// Reset metrics
-client.metrics.reset();
+console.log(metrics.requests.total);
+console.log(metrics.timing.avgMs);
+console.log(metrics.cache.hitRate);
 ```
 
 ---
 
-## 🔷 TypeScript Support
-
-### Type-Safe Responses
-
-```typescript
-interface User {
-  id: number;
-  name: string;
-  email: string;
-}
-
-// TypeScript knows the response type!
-const user = await client.url.api.get<User>({
-  path: "/users/123",
-  responseType: "json",
-});
-
-console.log(user.name); // ✅ Autocomplete works!
-```
+## 🏗️ Framework Integration
 
-### Typed URL Keys
+### Next.js
 
 ```typescript
-const client = new JirenClient({
-  warmup: {
-    api: "https://api.example.com",
-    cdn: "https://cdn.example.com",
-  },
-});
-
-client.url.api.get(); // ✅ Valid
-client.url.cdn.get(); // ✅ Valid
-client.url.foo.get(); // ❌ TypeScript error!
+// next.config.ts
+const nextConfig = {
+  serverExternalPackages: ["jiren", "koffi"],
+};
 ```
 
----
-
-## 📚 API Reference
-
-### Creating a Client
-
 ```typescript
-new JirenClient({
-  warmup: {
-    // Simple URL
-    api: "https://api.example.com",
-
-    // With caching
-    cdn: {
-      url: "https://cdn.example.com",
-      cache: true, // or { ttl: 60000 }
-    },
-  },
-
-  // Optional settings
-  antibot: false, // Enable anti-bot protection
-  benchmark: false, // Benchmark mode
-  interceptors: {}, // Request/response interceptors
-});
-```
-
-### Request Methods
-
-| 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
-{
-  path?: string;                    // URL path to append
-  headers?: Record<string, string>; // Request headers
-  responseType?: "json" | "text";   // Auto-parse response
-  maxRedirects?: number;            // Max redirects (default: 5)
-}
-```
-
-### Response Object
-
-```typescript
-{
-  url: string;
-  status: number;
-  statusText: string;
-  headers: Record<string, string>;
-  ok: boolean;
-  redirected: boolean;
-  body: {
-    json<T>(): Promise<T>;
-    text(): Promise<string>;
-    arrayBuffer(): Promise<ArrayBuffer>;
-    blob(): Promise<Blob>;
-  };
-}
-```
-
----
-
-## 💡 Examples
-
-### API Client Pattern
-
-```typescript
-// lib/api.ts
+// app/api/data/route.ts
 import { JirenClient } from "jiren";
 
-export const api = new JirenClient({
-  warmup: {
-    backend: {
-      url: process.env.API_URL!,
-      cache: { ttl: 30000 },
-    },
-  },
-  interceptors: {
-    request: [
-      (ctx) => ({
-        ...ctx,
-        headers: {
-          ...ctx.headers,
-          Authorization: `Bearer ${getSession()?.token}`,
-        },
-      }),
-    ],
-  },
-});
-
-// Usage anywhere
-import { api } from "@/lib/api";
-const users = await api.url.backend.get({
-  path: "/users",
-  responseType: "json",
+const client = new JirenClient({
+  targets: { api: "https://api.example.com" },
 });
-```
-
-### React/Next.js Hook
-
-```typescript
-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]);
-
-  return { data, loading };
-}
 
-// 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>
-  );
+export async function GET() {
+  const res = await client.url.api.get({ path: "/users" });
+  return Response.json(await res.body.json());
 }
 ```
 
@@ -513,30 +336,17 @@ function UserList() {
 
 ## 📋 Requirements
 
-- **Bun** v1.0.0+
+- **Bun** v1.0+ or **Node.js** v18+
+- **macOS** (ARM64/x64) or **Linux** (x64)
 
 ---
 
 ## 📄 License
 
-MIT © Vikash Khati
-
----
-
-## 🤝 Contributing
-
-Contributions welcome! Please open an issue or submit a pull request.
-
----
-
-## 🆘 Support
-
-- 📖 [Documentation](https://github.com/vikashkhati007/jiren)
-- 🐛 [Issue Tracker](https://github.com/vikashkhati007/jiren/issues)
-- 💬 [Discussions](https://github.com/vikashkhati007/jiren/discussions)
+MIT © VK
 
 ---
 
 <p align="center">
-  <strong>Made with ⚡ by Vikash Khati</strong>
+  <strong>Made with ⚡ by VK</strong>
 </p>

package/components/cache.ts

@@ -10,7 +10,7 @@ import {
 import { gzipSync, gunzipSync } from "zlib";
 import { createHash } from "crypto";
 import { join } from "path";
-import type { JirenResponse, JirenResponseBody } from "./types";
+import type { JirenResponse, JirenResponseBody } from "./types.js";
 
 /**
  * Serializable cache entry - stores raw body data for reconstruction