jiren 1.4.5 → 1.5.0

package/README.md

@@ -47,6 +47,7 @@ console.log(users);
 - [Response Caching](#response-caching)
 - [Anti-Bot Protection](#anti-bot-protection)
 - [Request Interceptors](#request-interceptors)
+- [Metrics & Observability](#metrics--observability)
 - [Advanced Features](#advanced-features)
 - [Performance](#performance)
 - [API Reference](#api-reference)
@@ -226,13 +227,12 @@ Bypass Cloudflare and other bot protection using Chrome TLS fingerprinting:
 const client = new JirenClient({
   warmup: {
     protected: "https://cloudflare-protected-site.com",
+    antibot: true,
   },
 });
 
 // Enable anti-bot mode for this request
-const response = await client.url.protected.get({
-  antibot: true, // Uses curl-impersonate with Chrome 120 fingerprint
-});
+const response = await client.url.protected.get();
 ```
 
 **How it works:**
@@ -294,6 +294,171 @@ client.use({
 
 ---
 
+## Metrics & Observability
+
+Track performance, cache efficiency, and request statistics with built-in metrics collection:
+
+### Basic Metrics
+
+```typescript
+const client = new JirenClient({
+  warmup: {
+    api: {
+      url: "https://api.example.com",
+      cache: true,
+    },
+  },
+});
+
+// Make some requests
+await client.url.api.get({ path: "/users" });
+await client.url.api.get({ path: "/users" }); // Cache hit
+
+// Get endpoint metrics
+const metrics = client.metrics.get("api");
+console.log(metrics);
+/*
+{
+  endpoint: "api",
+  requests: {
+    total: 2,
+    success: 2,
+    failed: 0
+  },
+  statusCodes: { 200: 2 },
+  timing: {
+    avgMs: 50.5,
+    minMs: 0.01,
+    maxMs: 101,
+    p50Ms: 50.5,
+    p95Ms: 101,
+    p99Ms: 101
+  },
+  cache: {
+    l1Hits: 1,
+    l1Misses: 1,
+    l2Hits: 0,
+    l2Misses: 1,
+    hitRate: "50.00%"
+  },
+  deduplication: {
+    hits: 0,
+    misses: 2,
+    hitRate: "0.00%"
+  },
+  bytes: {
+    sent: 0,
+    received: 0
+  },
+  errors: {},
+  lastRequestAt: 1234567890000
+}
+*/
+```
+
+### Global Metrics
+
+```typescript
+// Get aggregated metrics across all endpoints
+const global = client.metrics.getGlobal();
+console.log(global);
+/*
+{
+  totalRequests: 8,
+  totalSuccess: 8,
+  totalFailed: 0,
+  avgResponseTimeMs: 125.5,
+  totalBytesSent: 1024,
+  totalBytesReceived: 4096,
+  overallCacheHitRate: "62.50%",
+  overallDeduplicationRate: "25.00%",
+  endpoints: 2,
+  uptime: 60000
+}
+*/
+```
+
+### All Endpoints
+
+```typescript
+// Get metrics for all endpoints
+const allMetrics = client.metrics.getAll();
+for (const [endpoint, metrics] of Object.entries(allMetrics)) {
+  console.log(`${endpoint}: ${metrics.cache.hitRate} cache hit rate`);
+}
+```
+
+### Export Metrics
+
+```typescript
+// Export all metrics as JSON
+const json = client.metrics.export();
+console.log(json); // Pretty-printed JSON string
+
+// Save to file or send to monitoring service
+await Bun.write("metrics.json", json);
+```
+
+### Reset Metrics
+
+```typescript
+// Reset specific endpoint
+client.metrics.reset("api");
+
+// Reset all metrics
+client.metrics.reset();
+```
+
+### Tracked Metrics
+
+| Category     | Metrics                                                    |
+| ------------ | ---------------------------------------------------------- |
+| **Requests** | Total, success, failed, status code distribution           |
+| **Timing**   | Average, min, max, P50, P95, P99 response times            |
+| **Cache**    | L1/L2 hits & misses, overall hit rate                      |
+| **Dedupe**   | Deduplication hits/misses for identical in-flight requests |
+| **Bytes**    | Total sent/received                                        |
+| **Errors**   | Error counts by type                                       |
+| **Other**    | Last request timestamp, client uptime                      |
+
+### Use Cases
+
+**Performance Monitoring:**
+
+```typescript
+// Track P99 latency
+setInterval(() => {
+  const metrics = client.metrics.getGlobal();
+  if (metrics.avgResponseTimeMs > 1000) {
+    console.warn("High latency detected!");
+  }
+}, 60000);
+```
+
+**Cache Optimization:**
+
+```typescript
+// Monitor cache effectiveness
+const metrics = client.metrics.get("api");
+console.log(`Cache hit rate: ${metrics.cache.hitRate}`);
+if (parseFloat(metrics.cache.hitRate) < 50) {
+  console.log("Consider increasing cache TTL");
+}
+```
+
+**Debugging:**
+
+```typescript
+// Export metrics for debugging
+if (process.env.DEBUG) {
+  process.on("exit", () => {
+    console.log(client.metrics.export());
+  });
+}
+```
+
+---
+
 ## Advanced Features
 
 ### TypeScript Generics

package/components/client-node-native.ts

@@ -6,7 +6,7 @@ import type {
   RequestOptions,
   JirenResponse,
   JirenResponseBody,
-  WarmupUrlConfig,
+  TargetUrlConfig,
   UrlRequestOptions,
   UrlEndpoint,
   CacheConfig,
@@ -32,8 +32,8 @@ 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[]
+  T extends readonly TargetUrlConfig[] | Record<string, UrlConfig> =
+    | readonly TargetUrlConfig[]
     | Record<string, UrlConfig>
 > {
   /** URLs to warmup on client creation (pre-connect + handshake) */
@@ -45,8 +45,8 @@ export interface JirenClientOptions<
 
 /** Helper to extract keys from Warmup Config */
 export type ExtractWarmupKeys<
-  T extends readonly WarmupUrlConfig[] | Record<string, UrlConfig>
-> = T extends readonly WarmupUrlConfig[]
+  T extends readonly TargetUrlConfig[] | Record<string, UrlConfig>
+> = T extends readonly TargetUrlConfig[]
   ? T[number]["key"]
   : T extends Record<string, UrlConfig>
   ? keyof T
@@ -54,7 +54,7 @@ export type ExtractWarmupKeys<
 
 /** Type-safe URL accessor - maps keys to UrlEndpoint objects */
 export type UrlAccessor<
-  T extends readonly WarmupUrlConfig[] | Record<string, UrlConfig>
+  T extends readonly TargetUrlConfig[] | Record<string, UrlConfig>
 > = {
   [K in ExtractWarmupKeys<T>]: UrlEndpoint;
 };
@@ -62,15 +62,15 @@ export type UrlAccessor<
 /**
  * Helper function to define warmup URLs with type inference.
  */
-export function defineUrls<const T extends readonly WarmupUrlConfig[]>(
+export function defineUrls<const T extends readonly TargetUrlConfig[]>(
   urls: T
 ): T {
   return urls;
 }
 
 export class JirenClient<
-  T extends readonly WarmupUrlConfig[] | Record<string, UrlConfig> =
-    | readonly WarmupUrlConfig[]
+  T extends readonly TargetUrlConfig[] | Record<string, UrlConfig> =
+    | readonly TargetUrlConfig[]
     | Record<string, UrlConfig>
 > {
   private ptr: any = null; // Koffi pointer (Buffer or External)
@@ -105,8 +105,8 @@ export class JirenClient<
           if (typeof item === "string") {
             urls.push(item);
           } else {
-            // WarmupUrlConfig with key and optional cache
-            const config = item as WarmupUrlConfig;
+            // TargetUrlConfig with key and optional cache
+            const config = item as TargetUrlConfig;
             urls.push(config.url);
             this.urlMap.set(config.key, config.url);