fastfetch-api-fetch-enhancer 2.0.0

package/.idea/FastFetch-Smart-API-Fetcher.iml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="WEB_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <excludeFolder url="file://$MODULE_DIR$/.tmp" />
+      <excludeFolder url="file://$MODULE_DIR$/temp" />
+      <excludeFolder url="file://$MODULE_DIR$/tmp" />
+    </content>
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

package/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/FastFetch-Smart-API-Fetcher.iml" filepath="$PROJECT_DIR$/.idea/FastFetch-Smart-API-Fetcher.iml" />
+    </modules>
+  </component>
+</project>

package/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
+  </component>
+</project>

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Keshav-005
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# FastFetch API Enhancer
+
+FastFetch is a production-grade, enterprise-ready HTTP client built around the native `fetch` API. It transforms simple HTTP requests into robust network architecture by introducing advanced resilience patterns, high-concurrency request management, and real-time streaming capabilities without excessive boilerplate.
+
+## Architecture & Features
+
+FastFetch v2 provides seven core execution pipelines directly into your fetch workflow:
+
+- **Strict Typed Error Hierarchy:** Explicit errors for `TimeoutError`, `NetworkError`, `HttpError`, and `CircuitOpenError` enabling robust try/catch control flow.
+- **Koa-Style Middleware Pipeline:** A powerful `.use(async (ctx, next) => {})` onion-model interceptor architecture for modifying request metadata or observing response execution duration.
+- **Finite State Machine Circuit Breaker:** Stops cascading failures to downstream services by automatically failing fast when failure thresholds are breached, entering a `HALF_OPEN` state after the configured timeout.
+- **Priority-Aware Concurrency Queue:** Protects API rate limits by enforcing a strict `maxConcurrent` ceiling across all ongoing requests while maintaining execution priority.
+- **Offline Mutation Buffering:** Automatically buffers mutating requests (`POST`, `PUT`, `PATCH`, `DELETE`) internally if the browser detects an offline state, sequentially replaying them upon reconnection.
+- **Real-Time Telemetry & Metrics:** Maintains rolling windows on p50, p95, and p99 latency percentiles alongside exact endpoint success and failure ratios.
+- **Server-Sent Events (SSE) Native Streaming:** A built-in high-performance stream consumer utilizing `api.stream()` for interacting with AI models and event-driven backends natively over HTTP.
+
+## Installation
+
+```bash
+npm install fastfetch-api-fetch-enhancer
+```
+
+## Basic Usage
+
+A minimal example utilizing the `createClient` factory method:
+
+```typescript
+import { createClient } from 'fastfetch-api-fetch-enhancer';
+
+// Instantiate your global HTTP client
+const api = createClient({
+  baseURL: 'https://api.example.com/v1',
+  headers: { 'Authorization': 'Bearer <token>' },
+  timeout: 10000,
+  retries: 3,
+  retryDelay: 1000,
+  maxConcurrent: 50,
+  circuitBreaker: {
+    threshold: 5,
+    timeout: 30000
+  }
+});
+
+// Koa-style middleware injection
+api.use(async (ctx, next) => {
+  ctx.init.headers['X-Request-Id'] = crypto.randomUUID();
+  await next();
+  console.log(`[HTTP ${ctx.response?.status}] ${ctx.method} ${ctx.url} - ${ctx.duration}ms`);
+});
+
+// Start making requests
+async function execute() {
+  try {
+    // Standard JSON shorthand
+    const user = await api.json('/users/me');
+    
+    // Auto-serialization for payload delivery
+    await api.post('/events', { action: 'login', timestamp: Date.now() });
+    
+  } catch (error) {
+    // Typed catch boundaries
+    if (error instanceof HttpError) {
+      console.error('API Rejected Request:', error.status);
+    } else if (error instanceof TimeoutError) {
+      console.error('Request timed out at:', error.timeout);
+    } else {
+      console.error('Catastrophic failure:', error);
+    }
+  }
+}
+```
+
+## Advanced Streaming (SSE)
+
+Consume AI generation pipelines directly over HTTP using the `stream` handler:
+
+```typescript
+const signal = new AbortController();
+
+await api.stream(
+  '/ai/generate-text',
+  (event) => {
+    process.stdout.write(event.data);
+  },
+  { signal: signal.signal }
+);
+```
+
+## Monitoring & Telemetry
+
+Evaluate application stability at any time by accessing the built-in system telemetry map:
+
+```typescript
+const telemetry = api.metrics.snapshot();
+console.table(telemetry.byEndpoint);
+console.log('p99 global latency:', telemetry.globalLatencies.p99);
+```
+
+## License
+
+FastFetch is open-source software licensed under the MIT License.

package/__tests__/demo.test.ts

@@ -0,0 +1,216 @@
+import {
+  fastFetch,
+  clearCache,
+  createClient,
+  HttpError,
+  TimeoutError,
+  CircuitOpenError,
+} from "../src/index.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const POKE_BASE = "https://pokeapi.co/api/v2";
+const DITTO_URL = `${POKE_BASE}/pokemon/ditto`;
+
+// ---------------------------------------------------------------------------
+// 1. Core fastFetch & v1.x capabilities
+// ---------------------------------------------------------------------------
+describe("fastFetch — core & TTL Cache & Dedup", () => {
+  beforeEach(() => clearCache());
+
+  it("makes a basic GET and returns ok response", async () => {
+    const res = await fastFetch(DITTO_URL);
+    expect(res.ok).toBe(true);
+    const data = await res.json();
+    expect(data).toHaveProperty("name", "ditto");
+  });
+
+  it("deduplicates identical in-flight requests", async () => {
+    const [res1, res2] = await Promise.all([
+      fastFetch(DITTO_URL),
+      fastFetch(DITTO_URL),
+    ]);
+    const [d1, d2] = await Promise.all([res1.json(), res2.json()]);
+    expect(d1.name).toBe("ditto");
+    expect(d2.name).toBe("ditto");
+  });
+
+  it("returns a cached response on second call", async () => {
+    const res1 = await fastFetch(DITTO_URL, { fastCache: true, cacheTTL: 60_000 });
+    expect(res1.ok).toBe(true);
+
+    const res2 = await fastFetch(DITTO_URL, { fastCache: true, cacheTTL: 60_000 });
+    expect(res2.ok).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 2. Typed Error Hierarchy
+// ---------------------------------------------------------------------------
+describe("FastFetch v2.0 — Typed Errors", () => {
+  it("throws TimeoutError on abort", async () => {
+    let error: any;
+    try {
+      await fastFetch(DITTO_URL, { timeout: 1 });
+    } catch (e) {
+      error = e;
+    }
+    expect(error).toBeDefined();
+    expect(error).toBeInstanceOf(TimeoutError);
+    expect((error as TimeoutError).timeout).toBe(1);
+  });
+
+  it("throws HttpError when throwOnError is enabled via Client", async () => {
+    const api = createClient({ baseURL: POKE_BASE, throwOnError: true, retries: 0 });
+    let error: any;
+    try {
+      await api.get("/pokemon/invalid_pokemon_xyz123");
+    } catch (e) {
+      error = e;
+    }
+    expect(error).toBeDefined();
+    expect(error).toBeInstanceOf(HttpError);
+    expect((error as HttpError).status).toBe(404);
+    expect((error as HttpError).response).toBeDefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 3. Koa-style Middleware
+// ---------------------------------------------------------------------------
+describe("FastFetch v2.0 — Middleware Pipeline", () => {
+  it("executes in onion model order (down then up)", async () => {
+    const api = createClient({ baseURL: POKE_BASE });
+    const order: string[] = [];
+
+    api.use(async (ctx, next) => {
+      order.push("mw1_down");
+      ctx.init.headers = { ...ctx.init.headers, "X-Trace": "1" };
+      await next();
+      order.push("mw1_up");
+    });
+
+    api.use(async (ctx, next) => {
+      order.push("mw2_down");
+      expect((ctx.init.headers as any)["X-Trace"]).toBe("1");
+      await next();
+      order.push("mw2_up");
+      expect(ctx.response?.status).toBe(200);
+    });
+
+    await api.get("/pokemon/ditto");
+
+    expect(order).toEqual(["mw1_down", "mw2_down", "mw2_up", "mw1_up"]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 4. Circuit Breaker
+// ---------------------------------------------------------------------------
+describe("FastFetch v2.0 — Circuit Breaker", () => {
+  it("transitions CLOSED -> OPEN -> HALF_OPEN -> CLOSED", async () => {
+    const api = createClient({
+      baseURL: "http://localhost:1", // guaranteed network failure
+      circuitBreaker: { threshold: 2, timeout: 50 },
+      retries: 0,
+    });
+
+    const cb = api.circuitBreaker!;
+    expect(cb.state).toBe("CLOSED");
+
+    // Failure 1
+    await expect(api.get("/")).rejects.toThrow();
+    expect(cb.state).toBe("CLOSED");
+    expect(cb.failures).toBe(1);
+
+    // Failure 2 -> Opens circuit
+    await expect(api.get("/")).rejects.toThrow();
+    expect(cb.state).toBe("OPEN");
+
+    // Circuit is OPEN, requests immediately throw (no network delay)
+    let error: any;
+    try {
+      await api.get("/");
+    } catch (e) {
+      error = e;
+    }
+    expect(error).toBeDefined();
+    expect(error).toBeInstanceOf(CircuitOpenError);
+
+    // Wait for timeout -> HALF_OPEN
+    await new Promise(r => setTimeout(r, 60));
+    expect(cb.state).toBe("HALF_OPEN");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 5. Concurrency Queue
+// ---------------------------------------------------------------------------
+describe("FastFetch v2.0 — Concurrency Queue", () => {
+  it("limits active in-flight requests", async () => {
+    const maxConcurrent = 2;
+    const api = createClient({ baseURL: POKE_BASE, maxConcurrent });
+
+    // Fire 6 requests simultaneously
+    const p1 = api.get("/pokemon/1");
+    const p2 = api.get("/pokemon/2");
+    const p3 = api.get("/pokemon/3");
+    const p4 = api.get("/pokemon/4");
+    const p5 = api.get("/pokemon/5");
+    const p6 = api.get("/pokemon/6");
+
+    // Immediately check queue stats (2 active, 4 pending)
+    expect(api.queue!.active).toBe(2);
+    expect(api.queue!.pending).toBe(4);
+
+    await Promise.all([p1, p2, p3, p4, p5, p6]);
+
+    // All done
+    expect(api.queue!.active).toBe(0);
+    expect(api.queue!.pending).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 6. Metrics
+// ---------------------------------------------------------------------------
+describe("FastFetch v2.0 — Metrics", () => {
+  it("records success rates and normalises URLs", async () => {
+    const api = createClient({ baseURL: POKE_BASE });
+    
+    await api.get("/pokemon/1");
+    await api.get("/pokemon/2");
+
+    const snap = api.metrics.snapshot();
+    expect(snap.totalRequests).toBe(2);
+    
+    // Normalisation replaces numeric segments with /:id
+    const keys = Object.keys(snap.byEndpoint);
+    expect(keys[0]).toContain("/pokemon/:id");
+    expect(snap.byEndpoint[keys[0]].count).toBe(2);
+    expect(snap.byEndpoint[keys[0]].successRate).toBe(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 7. Auto Body Serialization
+// ---------------------------------------------------------------------------
+describe("FastFetch v2.0 — Auto Body Serialization", () => {
+  it("serialises plain objects to JSON automatically", async () => {
+    const api = createClient({ baseURL: POKE_BASE });
+
+    api.use(async (ctx, next) => {
+      // Intercept and assert the mutation before it goes out
+      expect(ctx.init.body).toBe('{"name":"bulbasaur"}');
+      expect((ctx.init.headers as any)["Content-Type"]).toBe("application/json");
+      
+      // Stub the response so we don't actually POST to PokeAPI
+      ctx.response = new Response("ok", { status: 200 });
+      // do not await next() so we skip the network call
+    });
+
+    const res = await api.post("/pokemon", { name: "bulbasaur" });
+    expect(res.status).toBe(200);
+  });
+});