jiren 1.3.1 → 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),
+      },
+    };
   }
 }