jiren 1.1.0 → 1.1.5

package/README.md

@@ -1,19 +1,18 @@
-# jiren
+# Jiren
 
-> **⚠️ BUN ONLY**: This package requires [Bun](https://bun.sh) runtime. Node.js is not supported.
-
-Ultra-fast HTTP/HTTPS client.
+Ultra-fast HTTP/HTTPS client powered by native Zig (FFI).
 Designed to be significantly faster than `fetch` and other Node/Bun HTTP clients.
 
 ## Features
 
-- **Blazing Fast**: Native implementation with minimal overhead.
-- **HTTP/3 (QUIC) Support**: First-class support for modern, high-performance connections.
-- **Automatic Redirects**: Recursively follows redirects (301, 302, etc.) with cycle protection.
-- **Type-Safe API**: Strict options (`GetRequestOptions`, `PostRequestOptions`) for better DX.
-- **Helper Methods**: Built-in `.json<T>()` parser and header accessors.
+- **Native Performance**: Written in Zig for memory safety and speed.
+- **Anti-Bot Protection**: Bypass Cloudflare with curl-impersonate (Chrome TLS fingerprinting).
+- **HTTP/1.1, HTTP/2 & HTTP/3 (QUIC)**: Full support for modern protocols.
 - **Connection Pooling**: Reuse connections for maximum throughput.
-- **0-RTT Session Resumption**: Extremely fast subsequent requests.
+- **Mandatory Warmup**: Pre-warm connections for instant requests.
+- **Type-Safe URLs**: Define named endpoints with full TypeScript autocomplete.
+- **JSON & Text Helpers**: Easy response parsing.
+- **Automatic Gzip Decompression**: Handles compressed responses transparently.
 
 ## Installation
 
@@ -23,67 +22,221 @@ bun add jiren
 
 ## Usage
 
-### Basic Requests
+### Basic Usage (Type-Safe URLs)
+
+**Warmup is now mandatory** - you must define URLs in the constructor:
 
 ```typescript
 import { JirenClient } from "jiren";
 
-const client = new JirenClient();
+const client = new JirenClient({
+  warmup: {
+    google: "https://www.google.com",
+    github: "https://api.github.com",
+    myapi: "https://api.myservice.com",
+  },
+});
 
-// Simple GET
-const res = client.get("https://google.com");
-console.log(res.status); // 200
+// TypeScript knows about 'google', 'github', 'myapi' - full autocomplete!
+const res = await client.url.google.get();
+console.log(res.status);
+const text = await res.body.text();
+```
 
-// JSON Parsing Helper
-const data = res.json<{ message: string }>();
+### JSON Response
+
+```typescript
+interface User {
+  id: number;
+  name: string;
+}
+
+const client = new JirenClient({
+  warmup: {
+    api: "https://api.example.com",
+  },
+});
+
+const res = await client.url.api.get<User>({
+  path: "/user/1",
+  responseType: "json",
+});
+console.log(res.name); // Fully typed!
 ```
 
-### Advanced Options (Headers, Redirects, Body)
+### Anti-Bot Mode (NEW! �️)
 
-Jiren enforces type safety. You cannot pass a body to a GET request!
+Enable curl-impersonate for sites with bot protection:
 
 ```typescript
-// GET with Headers
-client.get("https://api.example.com", {
-  headers: { Authorization: "Bearer token" },
+const client = new JirenClient({
+  warmup: {
+    protected: "https://protected-site.com",
+  },
+});
+
+// Enable antibot mode for this request
+const res = await client.url.protected.get({
+  antibot: true, // Uses curl-impersonate with Chrome fingerprinting
 });
+```
+
+### POST, PUT, PATCH, DELETE
 
-// POST with JSON body
-client.post(
-  "https://api.example.com/users",
-  JSON.stringify({ name: "Jiren" }),
+```typescript
+const client = new JirenClient({
+  warmup: {
+    api: "https://api.myservice.com",
+  },
+});
+
+// POST with body
+const created = await client.url.api.post(
+  JSON.stringify({ name: "New Item" }),
   {
+    path: "/items",
     headers: { "Content-Type": "application/json" },
   }
 );
 
-// Follow Redirects (e.g., http -> https)
-client.get("http://google.com", {
-  maxRedirects: 5, // Automatically follows up to 5 hops
+// PUT, PATCH, DELETE
+await client.url.api.put(body, { path: "/items/1" });
+await client.url.api.patch(body, { path: "/items/1" });
+await client.url.api.delete(null, { path: "/items/1" });
+```
+
+### Response Helpers
+
+```typescript
+const res = await client.url.api.get({ path: "/data" });
+
+// Get as text
+const text = await res.body.text();
+
+// Get as JSON
+const json = await res.body.json();
+
+// Get as ArrayBuffer
+const buffer = await res.body.arrayBuffer();
+
+// Get as Blob
+const blob = await res.body.blob();
+
+// Or use responseType for automatic parsing
+const data = await client.url.api.get({
+  path: "/data",
+  responseType: "json", // Returns parsed JSON directly
 });
 ```
 
-### Prefetching
+## Why Jiren?
 
-Warm up DNS and TLS handshakes to ensure subsequent requests are instant.
+### Comparison with Other Clients
+
+| Feature              | **Jiren** | **Axios** | **ky** | **got** | **node-fetch** |
+| -------------------- | :-------: | :-------: | :----: | :-----: | :------------: |
+| Type-safe named URLs |    ✅     |    ❌     |   ❌   |   ❌    |       ❌       |
+| Mandatory warmup     |    ✅     |    ❌     |   ❌   |   ❌    |       ❌       |
+| HTTP/3 (QUIC)        |    ✅     |    ❌     |   ❌   |   ❌    |       ❌       |
+| Anti-bot protection  |    ✅     |    ❌     |   ❌   |   ❌    |       ❌       |
+| Native performance   |    ✅     |    ❌     |   ❌   |   ❌    |       ❌       |
+| Zero code generation |    ✅     |    ✅     |   ✅   |   ✅    |       ✅       |
+| Bun FFI optimized    |    ✅     |    ❌     |   ❌   |   ❌    |       ❌       |
+
+### What Makes Jiren Unique
+
+1. **🔥 Mandatory Warmup** - Pre-establishes connections at startup for instant requests
+2. **📝 Type-Safe URLs** - Full autocomplete without needing backend schemas or code generation
+3. **🚀 Native Speed** - Zig-powered core bypasses JavaScript overhead
+4. **🛡️ Anti-Bot Protection** - Bypass Cloudflare, TLS fingerprinting, and bot detection with curl-impersonate
+5. **⚡ HTTP/3 Support** - First-class QUIC support for modern protocols
+
+## Anti-Bot Protection
+
+The `antibot` option uses curl-impersonate to mimic Chrome's TLS fingerprint:
+
+- Bypass TLS fingerprinting protections (JA3/JA4) like Cloudflare
+- Chrome 120 browser impersonation
+- Proper header ordering and HTTP/2 settings
+- Automatic gzip decompression
+
+```typescript
+const res = await client.url.site.get({
+  antibot: true, // Enable for protected sites
+});
+```
+
+**Performance**: ~1-2s for first request, faster with connection reuse.
+
+## API Reference
+
+### `JirenClient`
+
+```typescript
+// Constructor options
+interface JirenClientOptions {
+  warmup: Record<string, string>; // Required! Map of key -> URL
+}
+
+// Create client (warmup is mandatory)
+const client = new JirenClient({
+  warmup: {
+    api: "https://api.example.com",
+    cdn: "https://cdn.example.com",
+  },
+});
+
+// Type-safe URL access
+client.url[key].get(options?)
+client.url[key].post(body?, options?)
+client.url[key].put(body?, options?)
+client.url[key].patch(body?, options?)
+client.url[key].delete(body?, options?)
+client.url[key].head(options?)
+client.url[key].options(options?)
+
+// Cleanup
+client.close()
+```
+
+### Request Options
 
 ```typescript
-// Prefetch connection (DNS + TLS Handshake)
-client.prefetch(["https://google.com", "https://cloudflare.com"]);
+interface UrlRequestOptions {
+  path?: string; // Path to append to base URL
+  headers?: Record<string, string>;
+  maxRedirects?: number;
+  responseType?: "json" | "text" | "arraybuffer" | "blob";
+  antibot?: boolean; // Enable curl-impersonate (default: false)
+}
+```
+
+### Response Object
 
-// ... later, requests are instant
-const res = client.get("https://google.com");
+```typescript
+interface JirenResponse<T> {
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+  ok: boolean;
+  body: {
+    text(): Promise<string>;
+    json<R = T>(): Promise<R>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    blob(): Promise<Blob>;
+  };
+}
 ```
 
-## Benchmarks
+## Performance
+
+Benchmark results:
+
+- **Bun fetch**: ~950-1780ms
+- **JirenClient**: ~480-1630ms
 
-**jiren** delivers native performance by bypassing the JavaScript engine overhead for network I/O.
+JirenClient is often **faster than Bun's native fetch** thanks to optimized connection pooling and native Zig implementation.
 
-| Client            | Requests/sec  | Relative Speed |
-| ----------------- | ------------- | -------------- |
-| **jiren**         | **1,550,000** | **1.0x**       |
-| Bun `fetch`       | 45,000        | 34x Slower     |
-| Node `http`       | 32,000        | 48x Slower     |
-| Python `requests` | 6,500         | 238x Slower    |
+## License
 
-> Benchmarks run on MacBook Pro M3 Max, localhost loopback.
+MIT