jiren 1.4.0 → 1.5.0

package/components/native.ts

@@ -81,6 +81,98 @@ export const ffiDef = {
     args: [FFIType.ptr, FFIType.bool],
     returns: FFIType.void,
   },
+
+  // =========================================================================
+  // OPTIMIZED SINGLE-CALL API
+  // =========================================================================
+
+  zclient_request_full: {
+    args: [
+      FFIType.ptr, // client
+      FFIType.cstring, // method
+      FFIType.cstring, // url
+      FFIType.cstring, // headers (nullable)
+      FFIType.cstring, // body (nullable)
+      FFIType.u8, // max_redirects
+      FFIType.bool, // antibot
+    ],
+    returns: FFIType.ptr, // ZFullResponse*
+  },
+  zclient_response_full_free: {
+    args: [FFIType.ptr],
+    returns: FFIType.void,
+  },
+  // Accessor functions for ZFullResponse
+  zfull_response_status: {
+    args: [FFIType.ptr],
+    returns: FFIType.u16,
+  },
+  zfull_response_body: {
+    args: [FFIType.ptr],
+    returns: FFIType.ptr,
+  },
+  zfull_response_body_len: {
+    args: [FFIType.ptr],
+    returns: FFIType.u64,
+  },
+  zfull_response_headers: {
+    args: [FFIType.ptr],
+    returns: FFIType.ptr,
+  },
+  zfull_response_headers_len: {
+    args: [FFIType.ptr],
+    returns: FFIType.u64,
+  },
+
+  // =========================================================================
+  // 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

@@ -90,14 +90,16 @@ export interface ParsedUrl {
   path: string;
 }
 
-/** Warmup URL with a key for type-safe access */
-export interface WarmupUrlConfig {
+/** Target URL with a key for type-safe access */
+export interface TargetUrlConfig {
   /** Unique key to access this URL via client.url[key] */
   key: string;
-  /** The URL to warmup */
+  /** The target URL */
   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 */
@@ -181,6 +183,104 @@ export interface UrlEndpoint {
   prefetch(options?: UrlRequestOptions): Promise<void>;
 }
 
-/** Type helper to extract keys from warmup config array */
-export type ExtractWarmupKeys<T extends readonly WarmupUrlConfig[]> =
+/** Type helper to extract keys from target config array */
+export type ExtractTargetKeys<T extends readonly TargetUrlConfig[]> =
   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[];
+}
+
+/** Metrics for a single endpoint */
+export interface EndpointMetrics {
+  endpoint: string;
+  requests: {
+    total: number;
+    success: number;
+    failed: number;
+  };
+  statusCodes: Record<number, number>;
+  timing: {
+    avgMs: number;
+    minMs: number;
+    maxMs: number;
+    p50Ms: number;
+    p95Ms: number;
+    p99Ms: number;
+  };
+  cache: {
+    l1Hits: number;
+    l1Misses: number;
+    l2Hits: number;
+    l2Misses: number;
+    hitRate: string;
+  };
+  deduplication: {
+    hits: number;
+    misses: number;
+    hitRate: string;
+  };
+  bytes: {
+    sent: number;
+    received: number;
+  };
+  errors: Record<string, number>;
+  lastRequestAt: number | null;
+}
+
+/** Global aggregated metrics across all endpoints */
+export interface GlobalMetrics {
+  totalRequests: number;
+  totalSuccess: number;
+  totalFailed: number;
+  avgResponseTimeMs: number;
+  totalBytesSent: number;
+  totalBytesReceived: number;
+  overallCacheHitRate: string;
+  overallDeduplicationRate: string;
+  endpoints: number;
+  uptime: number;
+}
+
+/** Public API for accessing metrics */
+export interface MetricsAPI {
+  get(endpoint: string): EndpointMetrics | null;
+  getAll(): Record<string, EndpointMetrics>;
+  getGlobal(): GlobalMetrics;
+  reset(endpoint?: string): void;
+  export(): string;
+}

package/package.json

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

package/components/client-node.ts

@@ -1,440 +0,0 @@
-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>;
-  }
-}