jiren 1.1.5 → 1.2.5

package/components/client.ts

@@ -1,5 +1,6 @@
 import { CString, toArrayBuffer, type Pointer } from "bun:ffi";
 import { lib } from "./native";
+import { ResponseCache } from "./cache";
 import type {
   RequestOptions,
   JirenResponse,
@@ -7,6 +8,7 @@ import type {
   WarmupUrlConfig,
   UrlRequestOptions,
   UrlEndpoint,
+  CacheConfig,
 } from "./types";
 
 const STATUS_TEXT: Record<number, string> = {
@@ -24,11 +26,14 @@ const STATUS_TEXT: Record<number, string> = {
   503: "Service Unavailable",
 };
 
+/** URL configuration with optional cache */
+export type UrlConfig = string | { url: string; cache?: boolean | CacheConfig };
+
 /** Options for JirenClient constructor */
 export interface JirenClientOptions<
-  T extends readonly WarmupUrlConfig[] | Record<string, string> =
+  T extends readonly WarmupUrlConfig[] | Record<string, UrlConfig> =
     | readonly WarmupUrlConfig[]
-    | Record<string, string>
+    | Record<string, UrlConfig>
 > {
   /** URLs to warmup on client creation (pre-connect + handshake) */
   warmup?: string[] | T;
@@ -39,16 +44,16 @@ export interface JirenClientOptions<
 
 /** Helper to extract keys from Warmup Config */
 export type ExtractWarmupKeys<
-  T extends readonly WarmupUrlConfig[] | Record<string, string>
+  T extends readonly WarmupUrlConfig[] | Record<string, UrlConfig>
 > = T extends readonly WarmupUrlConfig[]
   ? T[number]["key"]
-  : T extends Record<string, string>
+  : T extends Record<string, UrlConfig>
   ? keyof T
   : never;
 
 /** Type-safe URL accessor - maps keys to UrlEndpoint objects */
 export type UrlAccessor<
-  T extends readonly WarmupUrlConfig[] | Record<string, string>
+  T extends readonly WarmupUrlConfig[] | Record<string, UrlConfig>
 > = {
   [K in ExtractWarmupKeys<T>]: UrlEndpoint;
 };
@@ -79,12 +84,15 @@ export function defineUrls<const T extends readonly WarmupUrlConfig[]>(
 }
 
 export class JirenClient<
-  T extends readonly WarmupUrlConfig[] | Record<string, string> =
+  T extends readonly WarmupUrlConfig[] | Record<string, UrlConfig> =
     | readonly WarmupUrlConfig[]
-    | Record<string, string>
+    | Record<string, UrlConfig>
 > {
   private ptr: Pointer | null;
   private urlMap: Map<string, string> = new Map();
+  private cacheConfig: Map<string, { enabled: boolean; ttl: number }> =
+    new Map();
+  private cache: ResponseCache;
 
   /** Type-safe URL accessor for warmed-up URLs */
   public readonly url: UrlAccessor<T>;
@@ -93,6 +101,9 @@ export class JirenClient<
     this.ptr = lib.symbols.zclient_new();
     if (!this.ptr) throw new Error("Failed to create native client instance");
 
+    // Initialize cache
+    this.cache = new ResponseCache(100);
+
     // Enable benchmark mode if requested
     if (options?.benchmark) {
       lib.symbols.zclient_set_benchmark_mode(this.ptr, true);
@@ -108,17 +119,42 @@ export class JirenClient<
           if (typeof item === "string") {
             urls.push(item);
           } else {
-            // WarmupUrlConfig with key
+            // WarmupUrlConfig with key and optional cache
             const config = item as WarmupUrlConfig;
             urls.push(config.url);
             this.urlMap.set(config.key, config.url);
+
+            // Store cache config
+            if (config.cache) {
+              const cacheConfig =
+                typeof config.cache === "boolean"
+                  ? { enabled: true, ttl: 60000 }
+                  : { enabled: true, ttl: config.cache.ttl || 60000 };
+              this.cacheConfig.set(config.key, cacheConfig);
+            }
           }
         }
       } else {
-        // Record<string, string>
-        for (const [key, url] of Object.entries(warmup)) {
-          urls.push(url as string);
-          this.urlMap.set(key, url as string);
+        // Record<string, UrlConfig>
+        for (const [key, urlConfig] of Object.entries(warmup)) {
+          if (typeof urlConfig === "string") {
+            // Simple string URL
+            urls.push(urlConfig);
+            this.urlMap.set(key, urlConfig);
+          } else {
+            // URL config object with cache
+            urls.push(urlConfig.url);
+            this.urlMap.set(key, urlConfig.url);
+
+            // Store cache config
+            if (urlConfig.cache) {
+              const cacheConfig =
+                typeof urlConfig.cache === "boolean"
+                  ? { enabled: true, ttl: 60000 }
+                  : { enabled: true, ttl: urlConfig.cache.ttl || 60000 };
+              this.cacheConfig.set(key, cacheConfig);
+            }
+          }
         }
       }
 
@@ -159,12 +195,46 @@ export class JirenClient<
           get: async <R = any>(
             options?: UrlRequestOptions
           ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
-            return self.request<R>("GET", buildUrl(options?.path), null, {
-              headers: options?.headers,
-              maxRedirects: options?.maxRedirects,
-              responseType: options?.responseType,
-              antibot: options?.antibot,
-            });
+            // Check if caching is enabled for this URL
+            const cacheConfig = self.cacheConfig.get(prop);
+
+            if (cacheConfig?.enabled) {
+              // Try to get from cache
+              const cached = self.cache.get(baseUrl, options?.path, options);
+              if (cached) {
+                return cached as any;
+              }
+            }
+
+            // Make the request
+            const response = await self.request<R>(
+              "GET",
+              buildUrl(options?.path),
+              null,
+              {
+                headers: options?.headers,
+                maxRedirects: options?.maxRedirects,
+                responseType: options?.responseType,
+                antibot: options?.antibot,
+              }
+            );
+
+            // Store in cache if enabled
+            if (
+              cacheConfig?.enabled &&
+              typeof response === "object" &&
+              "status" in response
+            ) {
+              self.cache.set(
+                baseUrl,
+                response as JirenResponse,
+                cacheConfig.ttl,
+                options?.path,
+                options
+              );
+            }
+
+            return response;
           },
 
           post: async <R = any>(
@@ -250,6 +320,25 @@ export class JirenClient<
               antibot: options?.antibot,
             });
           },
+
+          /**
+           * Prefetch/refresh cache for this URL
+           * Clears existing cache and makes a fresh request
+           */
+          prefetch: async (options?: UrlRequestOptions): Promise<void> => {
+            // Clear cache for this URL
+            self.cache.clear(baseUrl);
+
+            // Make fresh request to populate cache
+            const cacheConfig = self.cacheConfig.get(prop);
+            if (cacheConfig?.enabled) {
+              await self.request("GET", buildUrl(options?.path), null, {
+                headers: options?.headers,
+                maxRedirects: options?.maxRedirects,
+                antibot: options?.antibot,
+              });
+            }
+          },
         } as UrlEndpoint;
       },
     });
@@ -267,17 +356,24 @@ export class JirenClient<
   }
 
   /**
-   * Warm up connections to URLs (DNS resolve + QUIC handshake).
+   * Warm up connections to URLs (DNS resolve + QUIC handshake) in parallel.
    * Call this early (e.g., at app startup) so subsequent requests are fast.
    * @param urls - List of URLs to warm up
    */
-  public warmup(urls: string[]): void {
+  public async warmup(urls: string[]): Promise<void> {
     if (!this.ptr) throw new Error("Client is closed");
 
-    for (const url of urls) {
-      const urlBuffer = Buffer.from(url + "\0");
-      lib.symbols.zclient_prefetch(this.ptr, urlBuffer);
-    }
+    // Warm up all URLs in parallel for faster startup
+    await Promise.all(
+      urls.map(
+        (url) =>
+          new Promise<void>((resolve) => {
+            const urlBuffer = Buffer.from(url + "\0");
+            lib.symbols.zclient_prefetch(this.ptr, urlBuffer);
+            resolve();
+          })
+      )
+    );
   }
 
   /**

package/components/types.ts

@@ -96,6 +96,16 @@ export interface WarmupUrlConfig {
   key: string;
   /** The URL to warmup */
   url: string;
+  /** Enable response caching for this URL (default: false) */
+  cache?: boolean | CacheConfig;
+}
+
+/** Cache configuration */
+export interface CacheConfig {
+  /** Cache TTL in milliseconds (default: 60000 = 1 minute) */
+  ttl?: number;
+  /** Maximum cache size (default: 100 entries) */
+  maxSize?: number;
 }
 
 /** Options for URL endpoint requests */
@@ -168,6 +178,9 @@ export interface UrlEndpoint {
 
   /** OPTIONS request */
   options(options?: UrlRequestOptions): Promise<JirenResponse<any>>;
+
+  /** Prefetch/refresh cache for this URL */
+  prefetch(options?: UrlRequestOptions): Promise<void>;
 }
 
 /** Type helper to extract keys from warmup config array */

package/index-node.ts

@@ -0,0 +1,18 @@
+/**
+ * jiren - Ultra-fast HTTP/HTTPS client (Node.js/Next.js Fallback)
+ *
+ * NOTE: This is the Node.js compatible version using standard fetch.
+ * For maximum performance with native Zig bindings, use Bun.
+ *
+ * @packageDocumentation
+ */
+
+// Main client (Node.js fallback)
+export {
+  JirenClient,
+  type JirenClientOptions,
+  type UrlAccessor,
+} from "./components/client-node";
+
+// Types
+export * from "./types";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jiren",
-  "version": "1.1.5",
+  "version": "1.2.5",
   "author": "",
   "main": "index.ts",
   "module": "index.ts",
@@ -14,6 +14,7 @@
   "description": "Jiren is a high-performance HTTP/HTTPS client, Faster than any other HTTP/HTTPS client.",
   "files": [
     "index.ts",
+    "index-node.ts",
     "types",
     "lib",
     "components"
@@ -39,5 +40,12 @@
     "node": ">=18.0.0",
     "bun": ">=1.1.0"
   },
-  "type": "module"
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./index.ts",
+      "default": "./index-node.ts"
+    },
+    "./package.json": "./package.json"
+  }
 }