jiren 1.4.0 → 1.4.5

package/README.md

@@ -46,6 +46,7 @@ console.log(users);
 - [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)
@@ -242,6 +243,57 @@ const response = await client.url.protected.get({
 
 ---
 
+## Request Interceptors
+
+Add middleware to intercept requests and responses for logging, auth injection, and more:
+
+### Basic Interceptors
+
+```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()}` },
+      }),
+    ],
+    // Transform responses after receiving
+    response: [
+      (ctx) => {
+        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()`
+
+```typescript
+// Add interceptors after client creation
+client.use({
+  request: [
+    (ctx) => ({ ...ctx, headers: { ...ctx.headers, "X-Custom": "value" } }),
+  ],
+});
+```
+
+### 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

package/components/cache.ts

@@ -1,8 +1,36 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  unlinkSync,
+  readdirSync,
+  statSync,
+} from "fs";
 import { gzipSync, gunzipSync } from "zlib";
 import { createHash } from "crypto";
 import { join } from "path";
-import type { JirenResponse } from "./types";
+import type { JirenResponse, JirenResponseBody } from "./types";
+
+/**
+ * Serializable cache entry - stores raw body data for reconstruction
+ */
+interface SerializableCacheEntry {
+  // Store serializable parts of response
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+  url: string;
+  ok: boolean;
+  redirected: boolean;
+  type: "basic" | "cors" | "default" | "error" | "opaque" | "opaqueredirect";
+  // Store raw body as base64 string (for binary compatibility)
+  bodyData: string;
+  bodyIsText: boolean;
+  // Cache metadata
+  timestamp: number;
+  ttl: number;
+}
 
 interface CacheEntry {
   response: JirenResponse;
@@ -10,12 +38,224 @@ interface CacheEntry {
   ttl: number;
 }
 
+/**
+ * Reconstruct body methods from raw data
+ */
+function reconstructBody(bodyData: string, isText: boolean): JirenResponseBody {
+  let buffer: ArrayBuffer;
+
+  if (isText) {
+    // Text data stored directly
+    const encoder = new TextEncoder();
+    buffer = encoder.encode(bodyData).buffer as ArrayBuffer;
+  } else {
+    // Binary data stored as base64
+    const binaryString = atob(bodyData);
+    const bytes = new Uint8Array(binaryString.length);
+    for (let i = 0; i < binaryString.length; i++) {
+      bytes[i] = binaryString.charCodeAt(i);
+    }
+    buffer = bytes.buffer as ArrayBuffer;
+  }
+
+  return {
+    bodyUsed: false,
+    text: async () => {
+      if (isText) return bodyData;
+      const decoder = new TextDecoder();
+      return decoder.decode(buffer);
+    },
+    json: async () => {
+      const text = isText ? bodyData : new TextDecoder().decode(buffer);
+      return JSON.parse(text);
+    },
+    arrayBuffer: async () => buffer,
+    blob: async () => new Blob([buffer]),
+  };
+}
+
+/**
+ * L1 In-Memory LRU Cache Node
+ */
+interface LRUNode {
+  key: string;
+  entry: CacheEntry;
+  prev: LRUNode | null;
+  next: LRUNode | null;
+}
+
+/**
+ * L1 In-Memory LRU Cache
+ * Provides ~0.001ms access time (vs ~5ms for disk)
+ */
+class L1MemoryCache {
+  private capacity: number;
+  private cache: Map<string, LRUNode> = new Map();
+  private head: LRUNode | null = null; // Most recently used
+  private tail: LRUNode | null = null; // Least recently used
+
+  // Stats
+  public hits = 0;
+  public misses = 0;
+
+  constructor(capacity = 100) {
+    this.capacity = capacity;
+  }
+
+  /**
+   * Get from L1 cache (O(1) lookup + LRU update)
+   */
+  get(key: string): CacheEntry | null {
+    const node = this.cache.get(key);
+    if (!node) {
+      this.misses++;
+      return null;
+    }
+
+    // Check if expired
+    const now = Date.now();
+    if (now - node.entry.timestamp > node.entry.ttl) {
+      this.delete(key);
+      this.misses++;
+      return null;
+    }
+
+    // Move to front (most recently used)
+    this.moveToFront(node);
+    this.hits++;
+    return node.entry;
+  }
+
+  /**
+   * Set in L1 cache with LRU eviction
+   */
+  set(key: string, entry: CacheEntry): void {
+    // If key exists, update and move to front
+    const existing = this.cache.get(key);
+    if (existing) {
+      existing.entry = entry;
+      this.moveToFront(existing);
+      return;
+    }
+
+    // Create new node
+    const node: LRUNode = {
+      key,
+      entry,
+      prev: null,
+      next: this.head,
+    };
+
+    // Add to front
+    if (this.head) {
+      this.head.prev = node;
+    }
+    this.head = node;
+    if (!this.tail) {
+      this.tail = node;
+    }
+
+    this.cache.set(key, node);
+
+    // Evict LRU if over capacity
+    if (this.cache.size > this.capacity) {
+      this.evictLRU();
+    }
+  }
+
+  /**
+   * Delete from L1 cache
+   */
+  delete(key: string): void {
+    const node = this.cache.get(key);
+    if (!node) return;
+
+    this.removeNode(node);
+    this.cache.delete(key);
+  }
+
+  /**
+   * Clear all L1 cache
+   */
+  clear(): void {
+    this.cache.clear();
+    this.head = null;
+    this.tail = null;
+  }
+
+  /**
+   * Get L1 cache stats
+   */
+  stats() {
+    return {
+      size: this.cache.size,
+      capacity: this.capacity,
+      hits: this.hits,
+      misses: this.misses,
+      hitRate:
+        this.hits + this.misses > 0
+          ? ((this.hits / (this.hits + this.misses)) * 100).toFixed(2) + "%"
+          : "0%",
+    };
+  }
+
+  private moveToFront(node: LRUNode): void {
+    if (node === this.head) return; // Already at front
+
+    this.removeNode(node);
+
+    // Add to front
+    node.prev = null;
+    node.next = this.head;
+    if (this.head) {
+      this.head.prev = node;
+    }
+    this.head = node;
+    if (!this.tail) {
+      this.tail = node;
+    }
+  }
+
+  private removeNode(node: LRUNode): void {
+    if (node.prev) {
+      node.prev.next = node.next;
+    } else {
+      this.head = node.next;
+    }
+
+    if (node.next) {
+      node.next.prev = node.prev;
+    } else {
+      this.tail = node.prev;
+    }
+  }
+
+  private evictLRU(): void {
+    if (!this.tail) return;
+
+    const key = this.tail.key;
+    this.removeNode(this.tail);
+    this.cache.delete(key);
+  }
+}
+
+/**
+ * Two-Tier Response Cache
+ *
+ * L1: In-Memory LRU Cache (~0.001ms access) - hot data
+ * L2: Disk Cache with gzip (~5ms access) - persistence
+ *
+ * Read path:  L1 → L2 → Network
+ * Write path: L1 + L2 (write-through)
+ */
 export class ResponseCache {
+  private l1: L1MemoryCache;
   private cacheDir: string;
-  private maxSize: number;
+  private maxDiskSize: number;
 
-  constructor(maxSize = 100, cacheDir = ".cache/jiren") {
-    this.maxSize = maxSize;
+  constructor(l1Capacity = 100, cacheDir = ".cache/jiren", maxDiskSize = 100) {
+    this.l1 = new L1MemoryCache(l1Capacity);
+    this.maxDiskSize = maxDiskSize;
     this.cacheDir = cacheDir;
 
     // Create cache directory if it doesn't exist
@@ -45,10 +285,58 @@ export class ResponseCache {
   }
 
   /**
-   * Get cached response if valid
+   * Preload L2 disk cache entry into L1 memory cache.
+   * Call this during initialization to ensure first request hits L1.
+   * @param url - Base URL to preload
+   * @param path - Optional path
+   * @param options - Optional request options
+   * @returns true if entry was preloaded, false if not found/expired
+   */
+  preloadL1(url: string, path?: string, options?: any): boolean {
+    const key = this.generateKey(url, path, options);
+
+    // Check if already in L1
+    if (this.l1.get(key)) {
+      return true;
+    }
+
+    // Try to load from L2 disk
+    const l2Entry = this.getFromDisk(key);
+    if (l2Entry) {
+      this.l1.set(key, l2Entry);
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Get cached response - checks L1 first, then L2
    */
   get(url: string, path?: string, options?: any): JirenResponse | null {
     const key = this.generateKey(url, path, options);
+
+    // L1: Check in-memory cache first (~0.001ms)
+    const l1Entry = this.l1.get(key);
+    if (l1Entry) {
+      return l1Entry.response;
+    }
+
+    // L2: Check disk cache (~5ms)
+    const l2Entry = this.getFromDisk(key);
+    if (l2Entry) {
+      // Promote to L1 for faster future access
+      this.l1.set(key, l2Entry);
+      return l2Entry.response;
+    }
+
+    return null;
+  }
+
+  /**
+   * Get from L2 disk cache
+   */
+  private getFromDisk(key: string): CacheEntry | null {
     const filePath = this.getCacheFilePath(key);
 
     if (!existsSync(filePath)) return null;
@@ -60,30 +348,46 @@ export class ResponseCache {
       // Decompress
       const decompressed = gunzipSync(compressed);
       const data = decompressed.toString("utf-8");
-      const entry: CacheEntry = JSON.parse(data);
+      const serialized: SerializableCacheEntry = JSON.parse(data);
 
       // Check if expired
       const now = Date.now();
-      if (now - entry.timestamp > entry.ttl) {
+      if (now - serialized.timestamp > serialized.ttl) {
         // Delete expired cache file
         try {
-          require("fs").unlinkSync(filePath);
+          unlinkSync(filePath);
         } catch {}
         return null;
       }
 
-      return entry.response;
+      // Reconstruct the response with working body methods
+      const response: JirenResponse = {
+        status: serialized.status,
+        statusText: serialized.statusText,
+        headers: serialized.headers,
+        url: serialized.url,
+        ok: serialized.ok,
+        redirected: serialized.redirected,
+        type: serialized.type || "default",
+        body: reconstructBody(serialized.bodyData, serialized.bodyIsText),
+      };
+
+      return {
+        response,
+        timestamp: serialized.timestamp,
+        ttl: serialized.ttl,
+      };
     } catch (error) {
       // Invalid cache file, delete it
       try {
-        require("fs").unlinkSync(filePath);
+        unlinkSync(filePath);
       } catch {}
       return null;
     }
   }
 
   /**
-   * Store response in cache as compressed JSON file
+   * Store response in both L1 and L2 (write-through)
    */
   set(
     url: string,
@@ -93,7 +397,6 @@ export class ResponseCache {
     options?: any
   ): void {
     const key = this.generateKey(url, path, options);
-    const filePath = this.getCacheFilePath(key);
 
     const entry: CacheEntry = {
       response,
@@ -101,9 +404,59 @@ export class ResponseCache {
       ttl,
     };
 
+    // L1: Store in memory (~0.001ms)
+    this.l1.set(key, entry);
+
+    // L2: Store on disk (async-ish, for persistence)
+    this.setToDisk(key, entry);
+  }
+
+  /**
+   * Write to L2 disk cache
+   */
+  private async setToDisk(key: string, entry: CacheEntry): Promise<void> {
+    const filePath = this.getCacheFilePath(key);
+
     try {
+      // Extract body text for serialization
+      let bodyData: string;
+      let bodyIsText = true;
+
+      try {
+        bodyData = await entry.response.body.text();
+      } catch {
+        // If text fails, try arrayBuffer and convert to base64
+        try {
+          const buffer = await entry.response.body.arrayBuffer();
+          const bytes = new Uint8Array(buffer);
+          let binary = "";
+          for (let i = 0; i < bytes.length; i++) {
+            binary += String.fromCharCode(bytes[i]!);
+          }
+          bodyData = btoa(binary);
+          bodyIsText = false;
+        } catch {
+          bodyData = "";
+        }
+      }
+
+      // Create serializable entry
+      const serialized: SerializableCacheEntry = {
+        status: entry.response.status,
+        statusText: entry.response.statusText,
+        headers: entry.response.headers as Record<string, string>,
+        url: entry.response.url,
+        ok: entry.response.ok,
+        redirected: entry.response.redirected,
+        type: entry.response.type || "default",
+        bodyData,
+        bodyIsText,
+        timestamp: entry.timestamp,
+        ttl: entry.ttl,
+      };
+
       // Convert to JSON
-      const json = JSON.stringify(entry);
+      const json = JSON.stringify(serialized);
 
       // Compress with gzip
       const compressed = gzipSync(json);
@@ -120,26 +473,29 @@ export class ResponseCache {
    * Clear cache for a specific URL or all
    */
   clear(url?: string): void {
+    // Clear L1
+    this.l1.clear();
+
+    // Clear L2
     if (url) {
       // Clear all cache files for this URL
       // This is approximate since we hash the keys
       // For now, just clear all to be safe
-      this.clearAll();
+      this.clearAllDisk();
     } else {
-      this.clearAll();
+      this.clearAllDisk();
     }
   }
 
   /**
-   * Clear all cache files
+   * Clear all L2 disk cache files
    */
-  private clearAll(): void {
+  private clearAllDisk(): void {
     try {
-      const fs = require("fs");
-      const files = fs.readdirSync(this.cacheDir);
+      const files = readdirSync(this.cacheDir);
       for (const file of files) {
         if (file.endsWith(".json.gz")) {
-          fs.unlinkSync(join(this.cacheDir, file));
+          unlinkSync(join(this.cacheDir, file));
         }
       }
     } catch (error) {
@@ -148,34 +504,35 @@ export class ResponseCache {
   }
 
   /**
-   * Get cache statistics
+   * Get combined cache statistics
    */
   stats() {
+    const l1Stats = this.l1.stats();
+
+    // L2 disk stats
+    let diskSize = 0;
+    let diskFiles = 0;
+    let totalDiskBytes = 0;
+
     try {
-      const fs = require("fs");
-      const files = fs.readdirSync(this.cacheDir);
+      const files = readdirSync(this.cacheDir);
       const cacheFiles = files.filter((f: string) => f.endsWith(".json.gz"));
+      diskFiles = cacheFiles.length;
 
-      // Calculate total size
-      let totalSize = 0;
       for (const file of cacheFiles) {
-        const stats = fs.statSync(join(this.cacheDir, file));
-        totalSize += stats.size;
+        const stats = statSync(join(this.cacheDir, file));
+        totalDiskBytes += stats.size;
       }
+    } catch {}
 
-      return {
-        size: cacheFiles.length,
-        maxSize: this.maxSize,
-        cacheDir: this.cacheDir,
-        totalSizeKB: (totalSize / 1024).toFixed(2),
-      };
-    } catch {
-      return {
-        size: 0,
-        maxSize: this.maxSize,
+    return {
+      l1: l1Stats,
+      l2: {
+        size: diskFiles,
+        maxSize: this.maxDiskSize,
         cacheDir: this.cacheDir,
-        totalSizeKB: "0",
-      };
-    }
+        totalSizeKB: (totalDiskBytes / 1024).toFixed(2),
+      },
+    };
   }
 }

package/components/client-node-native.ts

@@ -77,6 +77,7 @@ export class JirenClient<
   private urlMap: Map<string, string> = new Map();
   private cacheConfig: Map<string, { enabled: boolean; ttl: number }> =
     new Map();
+  private antibotConfig: Map<string, boolean> = new Map();
   private cache: ResponseCache;
 
   /** Type-safe URL accessor for warmed-up URLs */
@@ -117,6 +118,11 @@ export class JirenClient<
                   : { enabled: true, ttl: config.cache.ttl || 60000 };
               this.cacheConfig.set(config.key, cacheConfig);
             }
+
+            // Store antibot config
+            if (config.antibot) {
+              this.antibotConfig.set(config.key, true);
+            }
           }
         }
       } else {
@@ -139,6 +145,11 @@ export class JirenClient<
                   : { enabled: true, ttl: urlConfig.cache.ttl || 60000 };
               this.cacheConfig.set(key, cacheConfig);
             }
+
+            // Store antibot config
+            if ((urlConfig as { antibot?: boolean }).antibot) {
+              this.antibotConfig.set(key, true);
+            }
           }
         }
       }
@@ -146,12 +157,30 @@ export class JirenClient<
       if (urls.length > 0) {
         this.warmup(urls);
       }
+
+      // Preload L2 disk cache entries into L1 memory for cached endpoints
+      // This ensures user's first request hits L1 (~0.001ms) instead of L2 (~5ms)
+      for (const [key, config] of this.cacheConfig.entries()) {
+        if (config.enabled) {
+          const url = this.urlMap.get(key);
+          if (url) {
+            this.cache.preloadL1(url);
+          }
+        }
+      }
     }
 
     // Create proxy for type-safe URL access
     this.url = this.createUrlAccessor();
   }
 
+  /**
+   * Wait for warmup to complete
+   */
+  public async waitForWarmup(): Promise<void> {
+    // Native warmup is synchronous, so this is effectively a no-op
+  }
+
   /**
    * Creates a proxy-based URL accessor for type-safe access.
    */
@@ -180,6 +209,10 @@ export class JirenClient<
           ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
             const cacheConfig = self.cacheConfig.get(prop);
 
+            // Check if antibot is enabled for this URL (from warmup config or per-request)
+            const useAntibot =
+              options?.antibot ?? self.antibotConfig.get(prop) ?? false;
+
             if (cacheConfig?.enabled) {
               const cached = self.cache.get(baseUrl, options?.path, options);
               if (cached) {
@@ -195,7 +228,7 @@ export class JirenClient<
                 headers: options?.headers,
                 maxRedirects: options?.maxRedirects,
                 responseType: options?.responseType,
-                antibot: options?.antibot,
+                antibot: useAntibot,
               }
             );
 

package/components/client-node.ts

@@ -58,6 +58,7 @@ export class JirenClient<
   private urlMap: Map<string, string> = new Map();
   private cacheConfig: Map<string, { enabled: boolean; ttl: number }> =
     new Map();
+  private antibotConfig: Map<string, boolean> = new Map();
   private cache: ResponseCache;
 
   /** Type-safe URL accessor for warmed-up URLs */
@@ -90,6 +91,11 @@ export class JirenClient<
                   : { enabled: true, ttl: config.cache.ttl || 60000 };
               this.cacheConfig.set(config.key, cacheConfig);
             }
+
+            // Store antibot config
+            if (config.antibot) {
+              this.antibotConfig.set(config.key, true);
+            }
           }
         }
       } else {
@@ -112,6 +118,11 @@ export class JirenClient<
                   : { enabled: true, ttl: urlConfig.cache.ttl || 60000 };
               this.cacheConfig.set(key, cacheConfig);
             }
+
+            // Store antibot config
+            if ((urlConfig as { antibot?: boolean }).antibot) {
+              this.antibotConfig.set(key, true);
+            }
           }
         }
       }
@@ -119,12 +130,30 @@ export class JirenClient<
       if (urls.length > 0) {
         this.warmup(urls);
       }
+
+      // Preload L2 disk cache entries into L1 memory for cached endpoints
+      // This ensures user's first request hits L1 (~0.001ms) instead of L2 (~5ms)
+      for (const [key, config] of this.cacheConfig.entries()) {
+        if (config.enabled) {
+          const url = this.urlMap.get(key);
+          if (url) {
+            this.cache.preloadL1(url);
+          }
+        }
+      }
     }
 
     // Create proxy for type-safe URL access
     this.url = this.createUrlAccessor();
   }
 
+  /**
+   * Wait for warmup to complete (no-op for fetch client)
+   */
+  public async waitForWarmup(): Promise<void> {
+    // No-op - fetch client warmup is fire-and-forget
+  }
+
   /**
    * Creates a proxy-based URL accessor for type-safe access.
    */
@@ -153,6 +182,10 @@ export class JirenClient<
           ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
             const cacheConfig = self.cacheConfig.get(prop);
 
+            // Check if antibot is enabled for this URL (from warmup config or per-request)
+            const useAntibot =
+              options?.antibot ?? self.antibotConfig.get(prop) ?? false;
+
             if (cacheConfig?.enabled) {
               const cached = self.cache.get(baseUrl, options?.path, options);
               if (cached) return cached as any;
@@ -166,7 +199,7 @@ export class JirenClient<
                 headers: options?.headers,
                 maxRedirects: options?.maxRedirects,
                 responseType: options?.responseType,
-                antibot: options?.antibot,
+                antibot: useAntibot,
               }
             );
 

package/components/client.ts

@@ -10,6 +10,12 @@ import type {
   UrlEndpoint,
   CacheConfig,
   RetryConfig,
+  Interceptors,
+  RequestInterceptor,
+  ResponseInterceptor,
+  ErrorInterceptor,
+  InterceptorRequestContext,
+  InterceptorResponseContext,
 } from "./types";
 
 const STATUS_TEXT: Record<number, string> = {
@@ -27,8 +33,10 @@ const STATUS_TEXT: Record<number, string> = {
   503: "Service Unavailable",
 };
 
-/** URL configuration with optional cache */
-export type UrlConfig = string | { url: string; cache?: boolean | CacheConfig };
+/** URL configuration with optional cache and antibot */
+export type UrlConfig =
+  | string
+  | { url: string; cache?: boolean | CacheConfig; antibot?: boolean };
 
 /** Options for JirenClient constructor */
 export interface JirenClientOptions<
@@ -44,6 +52,9 @@ export interface JirenClientOptions<
 
   /** Global retry configuration */
   retry?: number | RetryConfig;
+
+  /** Request/response interceptors */
+  interceptors?: Interceptors;
 }
 
 /** Helper to extract keys from Warmup Config */
@@ -96,9 +107,15 @@ export class JirenClient<
   private urlMap: Map<string, string> = new Map();
   private cacheConfig: Map<string, { enabled: boolean; ttl: number }> =
     new Map();
+  private antibotConfig: Map<string, boolean> = new Map();
   private cache: ResponseCache;
   private inflightRequests: Map<string, Promise<any>> = new Map();
   private globalRetry?: RetryConfig;
+  private requestInterceptors: RequestInterceptor[] = [];
+  private responseInterceptors: ResponseInterceptor[] = [];
+  private errorInterceptors: ErrorInterceptor[] = [];
+  private warmupPromise: Promise<void> | null = null;
+  private warmupComplete: Set<string> = new Set();
 
   /** Type-safe URL accessor for warmed-up URLs */
   public readonly url: UrlAccessor<T>;
@@ -138,6 +155,11 @@ export class JirenClient<
                   : { enabled: true, ttl: config.cache.ttl || 60000 };
               this.cacheConfig.set(config.key, cacheConfig);
             }
+
+            // Store antibot config
+            if (config.antibot) {
+              this.antibotConfig.set(config.key, true);
+            }
           }
         }
       } else {
@@ -160,12 +182,31 @@ export class JirenClient<
                   : { enabled: true, ttl: urlConfig.cache.ttl || 60000 };
               this.cacheConfig.set(key, cacheConfig);
             }
+
+            // Store antibot config
+            if ((urlConfig as { antibot?: boolean }).antibot) {
+              this.antibotConfig.set(key, true);
+            }
           }
         }
       }
 
       if (urls.length > 0) {
-        this.warmup(urls);
+        // Lazy warmup in background (always - it's faster)
+        this.warmupPromise = this.warmup(urls).then(() => {
+          urls.forEach((url) => this.warmupComplete.add(url));
+        });
+      }
+
+      // Preload L2 disk cache entries into L1 memory for cached endpoints
+      // This ensures user's first request hits L1 (~0.001ms) instead of L2 (~5ms)
+      for (const [key, config] of this.cacheConfig.entries()) {
+        if (config.enabled) {
+          const url = this.urlMap.get(key);
+          if (url) {
+            this.cache.preloadL1(url);
+          }
+        }
       }
     }
 
@@ -179,12 +220,27 @@ export class JirenClient<
           ? { count: options.retry, delay: 100, backoff: 2 }
           : options.retry;
     }
+
+    // Initialize interceptors
+    if (options?.interceptors) {
+      this.requestInterceptors = options.interceptors.request || [];
+      this.responseInterceptors = options.interceptors.response || [];
+      this.errorInterceptors = options.interceptors.error || [];
+    }
   }
 
   private async waitFor(ms: number) {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
 
+  /**
+   * Wait for lazy warmup to complete.
+   * Only needed if using lazyWarmup: true and want to ensure warmup is done.
+   */
+  public async waitForWarmup(): Promise<void> {
+    if (this.warmupPromise) await this.warmupPromise;
+  }
+
   /**
    * Creates a proxy-based URL accessor for type-safe access to warmed-up URLs.
    */
@@ -213,9 +269,18 @@ export class JirenClient<
           get: async <R = any>(
             options?: UrlRequestOptions
           ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
+            // Wait for warmup to complete if not yet done
+            if (self.warmupPromise && !self.warmupComplete.has(baseUrl)) {
+              await self.warmupPromise;
+            }
+
             // Check if caching is enabled for this URL
             const cacheConfig = self.cacheConfig.get(prop);
 
+            // Check if antibot is enabled for this URL (from warmup config or per-request)
+            const useAntibot =
+              options?.antibot ?? self.antibotConfig.get(prop) ?? false;
+
             if (cacheConfig?.enabled) {
               // Try to get from cache
               const cached = self.cache.get(baseUrl, options?.path, options);
@@ -247,7 +312,7 @@ export class JirenClient<
                     headers: options?.headers,
                     maxRedirects: options?.maxRedirects,
                     responseType: options?.responseType,
-                    antibot: options?.antibot,
+                    antibot: useAntibot,
                   }
                 );
 
@@ -409,6 +474,20 @@ export class JirenClient<
     }
   }
 
+  /**
+   * Register interceptors dynamically.
+   * @param interceptors - Interceptor configuration to add
+   * @returns this for chaining
+   */
+  public use(interceptors: Interceptors): this {
+    if (interceptors.request)
+      this.requestInterceptors.push(...interceptors.request);
+    if (interceptors.response)
+      this.responseInterceptors.push(...interceptors.response);
+    if (interceptors.error) this.errorInterceptors.push(...interceptors.error);
+    return this;
+  }
+
   /**
    * Warm up connections to URLs (DNS resolve + QUIC handshake) in parallel.
    * Call this early (e.g., at app startup) so subsequent requests are fast.
@@ -510,6 +589,20 @@ export class JirenClient<
       }
     }
 
+    // Build interceptor request context
+    let ctx: InterceptorRequestContext = { method, url, headers, body };
+
+    // Run request interceptors
+    for (const interceptor of this.requestInterceptors) {
+      ctx = await interceptor(ctx);
+    }
+
+    // Apply interceptor modifications
+    method = ctx.method;
+    url = ctx.url;
+    headers = ctx.headers;
+    body = ctx.body ?? null;
+
     const methodBuffer = Buffer.from(method + "\0");
     const urlBuffer = Buffer.from(url + "\0");
 
@@ -619,6 +712,16 @@ export class JirenClient<
 
         const response = this.parseResponse<T>(respPtr, url);
 
+        // Run response interceptors
+        let responseCtx: InterceptorResponseContext<T> = {
+          request: ctx,
+          response,
+        };
+        for (const interceptor of this.responseInterceptors) {
+          responseCtx = await interceptor(responseCtx);
+        }
+        const finalResponse = responseCtx.response;
+
         // Optional: Retry on specific status codes (e.g., 500, 502, 503, 504)
         // For now, we only retry on actual exceptions/network failures (null ptr)
         // or if we decide to throw on 5xx here.
@@ -626,15 +729,19 @@ export class JirenClient<
 
         // Auto-parse if requested
         if (responseType) {
-          if (responseType === "json") return response.body.json();
-          if (responseType === "text") return response.body.text();
+          if (responseType === "json") return finalResponse.body.json();
+          if (responseType === "text") return finalResponse.body.text();
           if (responseType === "arraybuffer")
-            return response.body.arrayBuffer();
-          if (responseType === "blob") return response.body.blob();
+            return finalResponse.body.arrayBuffer();
+          if (responseType === "blob") return finalResponse.body.blob();
         }
 
-        return response;
+        return finalResponse;
       } catch (err) {
+        // Run error interceptors
+        for (const interceptor of this.errorInterceptors) {
+          await interceptor(err as Error, ctx);
+        }
         lastError = err;
         if (attempts < maxAttempts) {
           // Wait before retrying
@@ -697,6 +804,27 @@ export class JirenClient<
       if (len > 0 && bodyPtr) {
         // Create a copy of the buffer because the native response is freed immediately after
         buffer = toArrayBuffer(bodyPtr, 0, len).slice(0);
+
+        // Handle GZIP decompression if needed
+        const bufferView = new Uint8Array(buffer);
+        // Check for gzip magic bytes (0x1f 0x8b)
+        if (
+          bufferView.length >= 2 &&
+          bufferView[0] === 0x1f &&
+          bufferView[1] === 0x8b
+        ) {
+          try {
+            // Use Bun's built-in gzip decompression
+            const decompressed = Bun.gunzipSync(bufferView);
+            buffer = decompressed.buffer.slice(
+              decompressed.byteOffset,
+              decompressed.byteOffset + decompressed.byteLength
+            );
+          } catch (e) {
+            // Decompression failed, keep original buffer
+            console.warn("[Jiren] gzip decompression failed:", e);
+          }
+        }
       }
 
       let bodyUsed = false;

package/components/index.ts

@@ -20,6 +20,12 @@ export type {
   UrlEndpoint,
   JirenResponse,
   JirenResponseBody,
+  Interceptors,
+  RequestInterceptor,
+  ResponseInterceptor,
+  ErrorInterceptor,
+  InterceptorRequestContext,
+  InterceptorResponseContext,
 } from "./types";
 
 // Remove broken exports

package/components/native-cache.ts

@@ -0,0 +1,181 @@
+import { toArrayBuffer, type Pointer } from "bun:ffi";
+import { lib } from "./native";
+import type { JirenResponse, JirenResponseBody } from "./types";
+
+/**
+ * Native Zig Cache wrapper
+ * Uses native HashMap for L1 (~0.001ms) and gzip disk storage for L2 (~2-5ms)
+ */
+export class NativeCache {
+  private ptr: Pointer | null;
+
+  constructor(l1Capacity = 100) {
+    this.ptr = lib.symbols.zcache_new(l1Capacity) as Pointer;
+    if (!this.ptr) throw new Error("Failed to create native cache");
+  }
+
+  /**
+   * Get cached response by key
+   */
+  get(url: string, path?: string, options?: any): JirenResponse | null {
+    if (!this.ptr) return null;
+
+    const key = this.generateKey(url, path, options);
+    const keyBuffer = Buffer.from(key + "\0");
+
+    const entryPtr = lib.symbols.zcache_get(this.ptr, keyBuffer) as Pointer;
+    if (!entryPtr) return null;
+
+    try {
+      // Read ZCacheEntry struct:
+      // The struct layout in memory (with alignment):
+      // u16 status (offset 0, 2 bytes)
+      // [6 bytes padding]
+      // ptr headers_ptr (offset 8, 8 bytes)
+      // usize headers_len (offset 16, 8 bytes)
+      // ptr body_ptr (offset 24, 8 bytes)
+      // usize body_len (offset 32, 8 bytes)
+
+      // Create a view of the entry struct
+      const entryBytes = toArrayBuffer(entryPtr, 0, 40);
+      const entryView = new DataView(entryBytes);
+      const status = entryView.getUint16(0, true);
+
+      // Read pointer values as numbers (Bun FFI specific)
+      const headersLen = Number(entryView.getBigUint64(16, true));
+      const bodyLen = Number(entryView.getBigUint64(32, true));
+
+      // For now, create minimal headers and body
+      // The data is stored in native memory - reading pointers across FFI is complex
+      // We'll use the cached lengths to construct placeholder data
+
+      // Create an empty but valid response
+      const headers: Record<string, string> = {};
+
+      // Create body with empty data for now
+      // In a full implementation, we'd need to properly read from native pointers
+      const bodyBuffer = new ArrayBuffer(0);
+
+      // Reconstruct body methods
+      const body: JirenResponseBody = {
+        bodyUsed: false,
+        text: async () => "",
+        json: async <R>() => ({} as R),
+        arrayBuffer: async () => bodyBuffer,
+        blob: async () => new Blob([bodyBuffer]),
+      };
+
+      return {
+        status,
+        statusText: status === 200 ? "OK" : String(status),
+        headers,
+        url,
+        ok: status >= 200 && status < 300,
+        redirected: false,
+        type: "default",
+        body,
+      };
+    } finally {
+      lib.symbols.zcache_entry_free(entryPtr);
+    }
+  }
+
+  /**
+   * Set response in cache
+   */
+  set(
+    url: string,
+    response: JirenResponse,
+    ttl: number,
+    path?: string,
+    options?: any
+  ): void {
+    if (!this.ptr) return;
+
+    const key = this.generateKey(url, path, options);
+    const keyBuffer = Buffer.from(key + "\0");
+
+    // Get body and headers as buffers
+    // We need to read body synchronously, so we'll need the original data
+    // For cached responses, we should store the raw data
+    // This is a simplified version - in production, handle async properly
+
+    // For now, skip if body is not immediately available
+    // The proper solution would be to call this after body is consumed
+  }
+
+  /**
+   * Set response with raw data (called after body is available)
+   */
+  async setWithData(
+    url: string,
+    status: number,
+    headers: string,
+    body: string,
+    ttl: number,
+    path?: string,
+    options?: any
+  ): Promise<void> {
+    if (!this.ptr) return;
+
+    const key = this.generateKey(url, path, options);
+    const keyBuffer = Buffer.from(key + "\0");
+
+    const headersBuffer = Buffer.from(headers);
+    const bodyBuffer = Buffer.from(body);
+
+    lib.symbols.zcache_set(
+      this.ptr,
+      keyBuffer,
+      status,
+      headersBuffer,
+      headersBuffer.length,
+      bodyBuffer,
+      bodyBuffer.length,
+      ttl
+    );
+  }
+
+  /**
+   * Preload L2 disk cache into L1 memory
+   */
+  preloadL1(url: string, path?: string, options?: any): boolean {
+    if (!this.ptr) return false;
+
+    const key = this.generateKey(url, path, options);
+    const keyBuffer = Buffer.from(key + "\0");
+
+    return lib.symbols.zcache_preload_l1(
+      this.ptr,
+      keyBuffer
+    ) as unknown as boolean;
+  }
+
+  /**
+   * Clear all cache
+   */
+  clear(url?: string): void {
+    if (!this.ptr) return;
+    lib.symbols.zcache_clear(this.ptr);
+  }
+
+  /**
+   * Free native resources
+   */
+  close(): void {
+    if (this.ptr) {
+      lib.symbols.zcache_free(this.ptr);
+      this.ptr = null;
+    }
+  }
+
+  /**
+   * Generate cache key from URL and options
+   */
+  private generateKey(url: string, path?: string, options?: any): string {
+    const fullUrl = path ? `${url}${path}` : url;
+    const method = options?.method || "GET";
+    const headers = JSON.stringify(options?.headers || {});
+    return `${method}:${fullUrl}:${headers}`;
+  }
+}

package/components/native-node.ts

@@ -85,6 +85,32 @@ export const symbols = {
     "void *",
     "bool",
   ]),
+
+  // =========================================================================
+  // CACHE FFI
+  // =========================================================================
+
+  zcache_new: lib.func("zcache_new", "void *", ["uint64_t"]),
+  zcache_free: lib.func("zcache_free", "void", ["void *"]),
+  zcache_get: lib.func("zcache_get", "void *", ["void *", "const char *"]),
+  zcache_entry_free: lib.func("zcache_entry_free", "void", ["void *"]),
+  zcache_set: lib.func("zcache_set", "void", [
+    "void *", // cache
+    "const char *", // key
+    "uint16_t", // status
+    "void *", // headers_ptr
+    "uint64_t", // headers_len
+    "void *", // body_ptr
+    "uint64_t", // body_len
+    "int64_t", // ttl
+  ]),
+  zcache_preload_l1: lib.func("zcache_preload_l1", "bool", [
+    "void *",
+    "const char *",
+  ]),
+  zcache_clear: lib.func("zcache_clear", "void", ["void *"]),
+  zcache_stats: lib.func("zcache_stats", "void *", ["void *"]),
+  zcache_stats_free: lib.func("zcache_stats_free", "void", ["void *"]),
 };
 
 // Export a wrapper that matches structure of bun:ffi lib

package/components/native.ts

@@ -81,6 +81,56 @@ export const ffiDef = {
     args: [FFIType.ptr, FFIType.bool],
     returns: FFIType.void,
   },
+
+  // =========================================================================
+  // CACHE FFI
+  // =========================================================================
+
+  zcache_new: {
+    args: [FFIType.u64], // l1_capacity
+    returns: FFIType.ptr,
+  },
+  zcache_free: {
+    args: [FFIType.ptr],
+    returns: FFIType.void,
+  },
+  zcache_get: {
+    args: [FFIType.ptr, FFIType.cstring], // cache, key
+    returns: FFIType.ptr, // ZCacheEntry*
+  },
+  zcache_entry_free: {
+    args: [FFIType.ptr],
+    returns: FFIType.void,
+  },
+  zcache_set: {
+    args: [
+      FFIType.ptr, // cache
+      FFIType.cstring, // key
+      FFIType.u16, // status
+      FFIType.ptr, // headers_ptr
+      FFIType.u64, // headers_len
+      FFIType.ptr, // body_ptr
+      FFIType.u64, // body_len
+      FFIType.i64, // ttl
+    ],
+    returns: FFIType.void,
+  },
+  zcache_preload_l1: {
+    args: [FFIType.ptr, FFIType.cstring], // cache, key
+    returns: FFIType.bool,
+  },
+  zcache_clear: {
+    args: [FFIType.ptr],
+    returns: FFIType.void,
+  },
+  zcache_stats: {
+    args: [FFIType.ptr],
+    returns: FFIType.ptr, // CacheStats*
+  },
+  zcache_stats_free: {
+    args: [FFIType.ptr],
+    returns: FFIType.void,
+  },
 } as const;
 
 export const lib = dlopen(libPath, ffiDef);

package/components/types.ts

@@ -98,6 +98,8 @@ export interface WarmupUrlConfig {
   url: string;
   /** Enable response caching for this URL (default: false) */
   cache?: boolean | CacheConfig;
+  /** Enable anti-bot protection for all requests to this URL (default: false) */
+  antibot?: boolean;
 }
 
 /** Cache configuration */
@@ -184,3 +186,41 @@ export interface UrlEndpoint {
 /** Type helper to extract keys from warmup config array */
 export type ExtractWarmupKeys<T extends readonly WarmupUrlConfig[]> =
   T[number]["key"];
+
+/** Context passed to request interceptors */
+export interface InterceptorRequestContext {
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  body?: string | null;
+  path?: string;
+}
+
+/** Context passed to response interceptors */
+export interface InterceptorResponseContext<T = any> {
+  request: InterceptorRequestContext;
+  response: JirenResponse<T>;
+}
+
+/** Request interceptor - can modify request before sending */
+export type RequestInterceptor = (
+  ctx: InterceptorRequestContext
+) => InterceptorRequestContext | Promise<InterceptorRequestContext>;
+
+/** Response interceptor - can transform response after receiving */
+export type ResponseInterceptor = <T>(
+  ctx: InterceptorResponseContext<T>
+) => InterceptorResponseContext<T> | Promise<InterceptorResponseContext<T>>;
+
+/** Error interceptor - handles errors thrown during request */
+export type ErrorInterceptor = (
+  error: Error,
+  ctx: InterceptorRequestContext
+) => void | Promise<void>;
+
+/** Interceptor configuration */
+export interface Interceptors {
+  request?: RequestInterceptor[];
+  response?: ResponseInterceptor[];
+  error?: ErrorInterceptor[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jiren",
-  "version": "1.4.0",
+  "version": "1.4.5",
   "author": "",
   "main": "index.ts",
   "module": "index.ts",