jiren 1.1.5 → 1.2.5

package/components/cache.ts

@@ -0,0 +1,181 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { gzipSync, gunzipSync } from "zlib";
+import { createHash } from "crypto";
+import { join } from "path";
+import type { JirenResponse } from "./types";
+
+interface CacheEntry {
+  response: JirenResponse;
+  timestamp: number;
+  ttl: number;
+}
+
+export class ResponseCache {
+  private cacheDir: string;
+  private maxSize: number;
+
+  constructor(maxSize = 100, cacheDir = ".cache/jiren") {
+    this.maxSize = maxSize;
+    this.cacheDir = cacheDir;
+
+    // Create cache directory if it doesn't exist
+    if (!existsSync(this.cacheDir)) {
+      mkdirSync(this.cacheDir, { recursive: true });
+    }
+  }
+
+  /**
+   * 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 || {});
+    const key = `${method}:${fullUrl}:${headers}`;
+
+    // Hash the key to create a valid filename
+    return createHash("md5").update(key).digest("hex");
+  }
+
+  /**
+   * Get cache file path (compressed .gz file)
+   */
+  private getCacheFilePath(key: string): string {
+    return join(this.cacheDir, `${key}.json.gz`);
+  }
+
+  /**
+   * Get cached response if valid
+   */
+  get(url: string, path?: string, options?: any): JirenResponse | null {
+    const key = this.generateKey(url, path, options);
+    const filePath = this.getCacheFilePath(key);
+
+    if (!existsSync(filePath)) return null;
+
+    try {
+      // Read compressed file
+      const compressed = readFileSync(filePath);
+
+      // Decompress
+      const decompressed = gunzipSync(compressed);
+      const data = decompressed.toString("utf-8");
+      const entry: CacheEntry = JSON.parse(data);
+
+      // Check if expired
+      const now = Date.now();
+      if (now - entry.timestamp > entry.ttl) {
+        // Delete expired cache file
+        try {
+          require("fs").unlinkSync(filePath);
+        } catch {}
+        return null;
+      }
+
+      return entry.response;
+    } catch (error) {
+      // Invalid cache file, delete it
+      try {
+        require("fs").unlinkSync(filePath);
+      } catch {}
+      return null;
+    }
+  }
+
+  /**
+   * Store response in cache as compressed JSON file
+   */
+  set(
+    url: string,
+    response: JirenResponse,
+    ttl: number,
+    path?: string,
+    options?: any
+  ): void {
+    const key = this.generateKey(url, path, options);
+    const filePath = this.getCacheFilePath(key);
+
+    const entry: CacheEntry = {
+      response,
+      timestamp: Date.now(),
+      ttl,
+    };
+
+    try {
+      // Convert to JSON
+      const json = JSON.stringify(entry);
+
+      // Compress with gzip
+      const compressed = gzipSync(json);
+
+      // Write compressed file
+      writeFileSync(filePath, compressed);
+    } catch (error) {
+      // Silently fail if can't write cache
+      console.warn("Failed to write cache:", error);
+    }
+  }
+
+  /**
+   * Clear cache for a specific URL or all
+   */
+  clear(url?: string): void {
+    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();
+    } else {
+      this.clearAll();
+    }
+  }
+
+  /**
+   * Clear all cache files
+   */
+  private clearAll(): void {
+    try {
+      const fs = require("fs");
+      const files = fs.readdirSync(this.cacheDir);
+      for (const file of files) {
+        if (file.endsWith(".json.gz")) {
+          fs.unlinkSync(join(this.cacheDir, file));
+        }
+      }
+    } catch (error) {
+      // Silently fail
+    }
+  }
+
+  /**
+   * Get cache statistics
+   */
+  stats() {
+    try {
+      const fs = require("fs");
+      const files = fs.readdirSync(this.cacheDir);
+      const cacheFiles = files.filter((f: string) => f.endsWith(".json.gz"));
+
+      // Calculate total size
+      let totalSize = 0;
+      for (const file of cacheFiles) {
+        const stats = fs.statSync(join(this.cacheDir, file));
+        totalSize += stats.size;
+      }
+
+      return {
+        size: cacheFiles.length,
+        maxSize: this.maxSize,
+        cacheDir: this.cacheDir,
+        totalSizeKB: (totalSize / 1024).toFixed(2),
+      };
+    } catch {
+      return {
+        size: 0,
+        maxSize: this.maxSize,
+        cacheDir: this.cacheDir,
+        totalSizeKB: "0",
+      };
+    }
+  }
+}

package/components/client-node.ts

@@ -0,0 +1,440 @@
+import { ResponseCache } from "./cache";
+import type {
+  RequestOptions,
+  JirenResponse,
+  JirenResponseBody,
+  WarmupUrlConfig,
+  UrlRequestOptions,
+  UrlEndpoint,
+  CacheConfig,
+} from "./types";
+
+/** 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, UrlConfig> =
+    | readonly WarmupUrlConfig[]
+    | Record<string, UrlConfig>
+> {
+  /** URLs to warmup (pre-connect) */
+  warmup?: string[] | T;
+
+  /** Benchmark mode (Ignored in Node.js fallback) */
+  benchmark?: boolean;
+}
+
+/** Helper to extract keys from Warmup Config */
+export type ExtractWarmupKeys<
+  T extends readonly WarmupUrlConfig[] | Record<string, UrlConfig>
+> = T extends readonly WarmupUrlConfig[]
+  ? T[number]["key"]
+  : 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, UrlConfig>
+> = {
+  [K in ExtractWarmupKeys<T>]: UrlEndpoint;
+};
+
+/**
+ * Helper function to define warmup URLs with type inference.
+ */
+export function defineUrls<const T extends readonly WarmupUrlConfig[]>(
+  urls: T
+): T {
+  return urls;
+}
+
+export class JirenClient<
+  T extends readonly WarmupUrlConfig[] | Record<string, UrlConfig> =
+    | readonly WarmupUrlConfig[]
+    | Record<string, UrlConfig>
+> {
+  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>;
+
+  constructor(options?: JirenClientOptions<T>) {
+    // Initialize cache
+    this.cache = new ResponseCache(100);
+
+    // Process warmup URLs
+    if (options?.warmup) {
+      const urls: string[] = [];
+      const warmup = options.warmup;
+
+      if (Array.isArray(warmup)) {
+        for (const item of warmup) {
+          if (typeof item === "string") {
+            urls.push(item);
+          } else {
+            // 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, 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);
+            }
+          }
+        }
+      }
+
+      if (urls.length > 0) {
+        this.warmup(urls);
+      }
+    }
+
+    // Create proxy for type-safe URL access
+    this.url = this.createUrlAccessor();
+  }
+
+  /**
+   * Creates a proxy-based URL accessor for type-safe access.
+   */
+  private createUrlAccessor(): UrlAccessor<T> {
+    const self = this;
+
+    return new Proxy({} as UrlAccessor<T>, {
+      get(_target, prop: string) {
+        const baseUrl = self.urlMap.get(prop);
+        if (!baseUrl) {
+          throw new Error(
+            `URL key "${prop}" not found. Available keys: ${Array.from(
+              self.urlMap.keys()
+            ).join(", ")}`
+          );
+        }
+
+        const buildUrl = (path?: string) =>
+          path
+            ? `${baseUrl.replace(/\/$/, "")}/${path.replace(/^\//, "")}`
+            : baseUrl;
+
+        return {
+          get: async <R = any>(
+            options?: UrlRequestOptions
+          ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
+            const cacheConfig = self.cacheConfig.get(prop);
+
+            if (cacheConfig?.enabled) {
+              const cached = self.cache.get(baseUrl, options?.path, options);
+              if (cached) return cached as any;
+            }
+
+            const response = await self.request<R>(
+              "GET",
+              buildUrl(options?.path),
+              null,
+              {
+                headers: options?.headers,
+                maxRedirects: options?.maxRedirects,
+                responseType: options?.responseType,
+                antibot: options?.antibot,
+              }
+            );
+
+            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>(
+            body?: string | null,
+            options?: UrlRequestOptions
+          ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
+            return self.request<R>(
+              "POST",
+              buildUrl(options?.path),
+              body || null,
+              {
+                headers: options?.headers,
+                maxRedirects: options?.maxRedirects,
+                responseType: options?.responseType,
+              }
+            );
+          },
+
+          put: async <R = any>(
+            body?: string | null,
+            options?: UrlRequestOptions
+          ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
+            return self.request<R>(
+              "PUT",
+              buildUrl(options?.path),
+              body || null,
+              {
+                headers: options?.headers,
+                maxRedirects: options?.maxRedirects,
+                responseType: options?.responseType,
+              }
+            );
+          },
+
+          patch: async <R = any>(
+            body?: string | null,
+            options?: UrlRequestOptions
+          ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
+            return self.request<R>(
+              "PATCH",
+              buildUrl(options?.path),
+              body || null,
+              {
+                headers: options?.headers,
+                maxRedirects: options?.maxRedirects,
+                responseType: options?.responseType,
+              }
+            );
+          },
+
+          delete: async <R = any>(
+            body?: string | null,
+            options?: UrlRequestOptions
+          ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
+            return self.request<R>(
+              "DELETE",
+              buildUrl(options?.path),
+              body || null,
+              {
+                headers: options?.headers,
+                maxRedirects: options?.maxRedirects,
+                responseType: options?.responseType,
+              }
+            );
+          },
+
+          head: async (
+            options?: UrlRequestOptions
+          ): Promise<JirenResponse<any>> => {
+            return self.request("HEAD", buildUrl(options?.path), null, {
+              headers: options?.headers,
+              maxRedirects: options?.maxRedirects,
+              antibot: options?.antibot,
+            });
+          },
+
+          options: async (
+            options?: UrlRequestOptions
+          ): Promise<JirenResponse<any>> => {
+            return self.request("OPTIONS", buildUrl(options?.path), null, {
+              headers: options?.headers,
+              maxRedirects: options?.maxRedirects,
+              antibot: options?.antibot,
+            });
+          },
+
+          prefetch: async (options?: UrlRequestOptions): Promise<void> => {
+            self.cache.clear(baseUrl);
+            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;
+      },
+    });
+  }
+
+  public close(): void {
+    // No-op for fetch client
+  }
+
+  public async warmup(urls: string[]): Promise<void> {
+    // Basic prefetch for Node.js fallback (HEAD request)
+    await Promise.allSettled(
+      urls.map((url) =>
+        fetch(url, { method: "HEAD", signal: AbortSignal.timeout(2000) }).catch(
+          () => {}
+        )
+      )
+    );
+  }
+
+  /**
+   * @deprecated Use warmup() instead
+   */
+  public prefetch(urls: string[]): void {
+    this.warmup(urls);
+  }
+
+  public async request<T = any>(
+    method: string,
+    url: string,
+    body?: string | null,
+    options?: RequestOptions & { responseType: "json" }
+  ): Promise<T>;
+  public async request<T = any>(
+    method: string,
+    url: string,
+    body?: string | null,
+    options?: RequestOptions & { responseType: "text" }
+  ): Promise<string>;
+  public async request<T = any>(
+    method: string,
+    url: string,
+    body?: string | null,
+    options?: RequestOptions & { responseType: "arraybuffer" }
+  ): Promise<ArrayBuffer>;
+  public async request<T = any>(
+    method: string,
+    url: string,
+    body?: string | null,
+    options?: RequestOptions & { responseType: "blob" }
+  ): Promise<Blob>;
+  public async request<T = any>(
+    method: string,
+    url: string,
+    body?: string | null,
+    options?: RequestOptions
+  ): Promise<JirenResponse<T>>;
+  public async request<T = any>(
+    method: string,
+    url: string,
+    body?: string | null,
+    options?: RequestOptions | Record<string, string> | null
+  ): Promise<JirenResponse<T> | T | string | ArrayBuffer | Blob> {
+    // Normalize options
+    let headers: Record<string, string> = {};
+    let responseType: RequestOptions["responseType"] | undefined;
+
+    if (options) {
+      if (
+        "maxRedirects" in options ||
+        "headers" in options ||
+        "responseType" in options ||
+        "method" in options ||
+        "timeout" in options ||
+        "antibot" in options
+      ) {
+        const opts = options as RequestOptions;
+        if (opts.headers) headers = opts.headers;
+        if (opts.responseType) responseType = opts.responseType;
+      } else {
+        headers = options as Record<string, string>;
+      }
+    }
+
+    const fetchOptions: RequestInit = {
+      method,
+      headers: headers,
+      body: body || undefined,
+      redirect: "follow", // Native client follows redirects
+    };
+
+    const response = await fetch(url, fetchOptions);
+
+    // Auto-parse if requested
+    if (responseType) {
+      if (responseType === "json") return response.json() as Promise<T>;
+      if (responseType === "text") return response.text();
+      if (responseType === "arraybuffer") return response.arrayBuffer();
+      if (responseType === "blob") return response.blob();
+    }
+
+    // Construct JirenResponse
+    const responseHeaders: Record<string, string> = {};
+    response.headers.forEach((val, key) => {
+      responseHeaders[key] = val;
+    });
+
+    // Create a clone for each reading method to avoid "body used" error if user reads multiple times
+    // However, fetch body can only be read once. We replicate the behavior of the native client
+    // where we can read it. To do that we might need to buffer it OR just expose the raw response.
+    // The native client implementation buffers the whole body. Let's match that.
+
+    const buffer = await response.arrayBuffer();
+
+    let bodyUsed = false;
+    const consumeBody = () => {
+      bodyUsed = true;
+    };
+
+    const bodyObj: JirenResponseBody<T> = {
+      bodyUsed: false,
+      arrayBuffer: async () => {
+        consumeBody();
+        return buffer.slice(0);
+      },
+      blob: async () => {
+        consumeBody();
+        return new Blob([buffer]);
+      },
+      text: async () => {
+        consumeBody();
+        return new TextDecoder().decode(buffer);
+      },
+      json: async <R = T>(): Promise<R> => {
+        consumeBody();
+        const text = new TextDecoder().decode(buffer);
+        return JSON.parse(text);
+      },
+    };
+
+    Object.defineProperty(bodyObj, "bodyUsed", {
+      get: () => bodyUsed,
+    });
+
+    return {
+      url: response.url,
+      status: response.status,
+      statusText: response.statusText,
+      headers: responseHeaders,
+      ok: response.ok,
+      redirected: response.redirected,
+      type: response.type,
+      body: bodyObj,
+    } as JirenResponse<T>;
+  }
+}