@foundatiofx/fetchclient 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foundatiofx/fetchclient",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A typed JSON fetch client with middleware support for Deno, Node and the browser.",
   "keywords": [
     "Fetch",
@@ -35,6 +35,16 @@
         "types": "./types/mod.d.ts",
         "default": "./script/mod.js"
       }
+    },
+    "./mocks": {
+      "import": {
+        "types": "./types/src/mocks/mod.d.ts",
+        "default": "./esm/src/mocks/mod.js"
+      },
+      "require": {
+        "types": "./types/src/mocks/mod.d.ts",
+        "default": "./script/src/mocks/mod.js"
+      }
     }
   },
   "scripts": {
@@ -43,7 +53,7 @@
   "devDependencies": {
     "@types/node": "^20.9.0",
     "picocolors": "^1.0.0",
-    "zod": "^4.1.4",
+    "zod": "^4.3.6",
     "@deno/shim-deno": "~0.18.0"
   },
   "_generatedBy": "dnt@dev"

package/readme.md

@@ -6,298 +6,153 @@
 [![Build status](https://github.com/foundatiofx/foundatio/workflows/Build/badge.svg)](https://github.com/foundatiofx/foundatio/actions)
 [![Discord](https://img.shields.io/discord/715744504891703319)](https://discord.gg/6HxgFCx)
 
-<!-- deno-fmt-ignore-file -->
-
-FetchClient is a library that makes it easier to use the fetch API for JSON
-APIs. It provides the following features:
-
-- [Typed Response](#typed-response) - Full TypeScript support with strongly
-  typed responses
-- [Functional](#functional) - Standalone functions for simple usage
-- [Model Validator](#model-validator) - Built-in validation with Problem Details
-  support
-- [Caching](#caching) - Response caching with TTL and programmatic invalidation
-- [Middleware](#middleware) - Extensible middleware pipeline for
-  request/response handling
-- [Rate Limiting](#rate-limiting) - Built-in rate limiting with per-domain
-  support
-- [Request Timeout](#request-timeout) - Configurable timeouts with AbortSignal
-  support
-- [Error Handling](#error-handling) - Comprehensive error handling with Problem
-  Details
-- [Authentication](#authentication) - Built-in Bearer token support
-- [Base URL](#base-url) - Global base URL configuration
-- [Loading State](#loading-state) - Track request loading state with events
+FetchClient is a tiny, typed wrapper around `fetch` with JSON helpers, caching,
+middleware, rate limiting, circuit breaker, timeouts, and friendly error
+handling.
+
+## Features
+
+- **Typed JSON helpers** - `getJSON`, `postJSON`, `putJSON`, `patchJSON`,
+  `deleteJSON`
+- **Two API styles** - Functional (no classes) or class-based - your choice
+- **Response caching** - TTL-based caching with tags for grouped invalidation
+- **Middleware** - Intercept requests/responses for logging, auth, transforms
+- **Rate limiting** - Per-domain rate limits with automatic header detection
+- **Circuit breaker** - Prevent cascading failures when services go down
+- **Timeouts** - Request timeouts with AbortSignal support
+- **Error handling** - RFC 7807 Problem Details support
+- **Testing** - MockRegistry for mocking HTTP in tests
 
 ## Install
 
-```shell
-npm install --save @foundatiofx/fetchclient
+```bash
+npm install @foundatiofx/fetchclient
 ```
 
-## Docs
+## Quick Example
 
-[API Documentation](https://jsr.io/@foundatiofx/fetchclient/doc)
+FetchClient works two ways - pick whichever style you prefer:
 
-## Usage
-
-### Typed Response
+### Functional API (no classes)
 
 ```ts
-import { FetchClient } from "@foundatiofx/fetchclient";
+import { getJSON, postJSON, setBaseUrl } from "@foundatiofx/fetchclient";
 
-type Products = {
-  products: Array<{ id: number; name: string }>;
-};
-
-const client = new FetchClient();
-const response = await client.getJSON<Products>(
-  `https://dummyjson.com/products/search?q=iphone&limit=10`,
-);
+// Optional: configure once at startup
+setBaseUrl("https://api.example.com");
 
-const products = response.data;
+// Use simple functions anywhere
+const { data: users } = await getJSON<User[]>("/users");
+const { data: created } = await postJSON<User>("/users", { name: "Alice" });
 ```
 
-### Functional
+Or use `getFetchClient()` to avoid multiple imports:
 
 ```ts
-import { getJSON, postJSON } from "@foundatiofx/fetchclient";
+import { getFetchClient, setBaseUrl } from "@foundatiofx/fetchclient";
 
-type Product = { id: number; title: string };
-type Products = { products: Product[] };
-
-const response = await postJSON<Product>(
-  "https://dummyjson.com/products/add",
-  {
-    name: "iPhone 13",
-  },
-);
+setBaseUrl("https://api.example.com");
 
-const product = await getJSON<Product>(
-  `https://dummyjson.com/products/${response.data!.id}`,
-);
+const client = getFetchClient();
+const { data: users } = await client.getJSON<User[]>("/users");
+const { data: created } = await client.postJSON<User>("/users", {
+  name: "Alice",
+});
 ```
 
-### Model Validator
+### Class-Based API
 
 ```ts
-import { FetchClient, setModelValidator } from "@foundatiofx/fetchclient";
-
-setModelValidator(async (data: object | null) => {
-  // use zod or any other validator
-  const problem = new ProblemDetails();
-  const d = data as { password: string };
-  if (d?.password?.length < 6) {
-    problem.errors.password = [
-      "Password must be longer than or equal to 6 characters.",
-    ];
-  }
-  return problem;
-});
+import { FetchClient } from "@foundatiofx/fetchclient";
 
-const client = new FetchClient();
-const data = {
-  email: "test@test",
-  password: "test",
-};
-
-const response = await client.postJSON(
-  "https://jsonplaceholder.typicode.com/todos/1",
-  data,
-);
-
-if (!response.ok) {
-  // check response problem
-  console.log(response.problem.detail);
-}
+const client = new FetchClient({ baseUrl: "https://api.example.com" });
+const { data } = await client.getJSON<User[]>("/users");
 ```
 
-### Caching
+All styles share the same configuration - the functional API wraps a
+[default provider](https://fetchclient.foundatio.dev/guide/provider#default-provider).
 
-```ts
-import { FetchClient } from "@foundatiofx/fetchclient";
+## Caching
 
-type Todo = { userId: number; id: number; title: string; completed: boolean };
-
-const client = new FetchClient();
-const response = await client.getJSON<Todo>(
-  `https://jsonplaceholder.typicode.com/todos/1`,
-  {
-    cacheKey: ["todos", "1"],
-    cacheDuration: 1000 * 60, // expires in 1 minute
-  },
-);
+```ts
+const response = await client.getJSON<User>("/api/users/1", {
+  cacheKey: ["users", "1"],
+  cacheDuration: 60000, // 1 minute
+  cacheTags: ["users"],
+});
 
-// invalidate programmatically
-client.cache.delete(["todos", "1"]);
+// Invalidate by tag
+client.cache.deleteByTag("users");
 ```
 
-### Middleware
+## Middleware
 
 ```ts
-import { FetchClient, useMiddleware } from "@foundatiofx/fetchclient";
-
-type Products = {
-  products: Array<{ id: number; name: string }>;
-};
+import { useMiddleware } from "@foundatiofx/fetchclient";
 
 useMiddleware(async (ctx, next) => {
-  console.log("starting request");
+  console.log("Request:", ctx.request.url);
   await next();
-  console.log("completed request");
+  console.log("Response:", ctx.response?.status);
 });
-
-const client = new FetchClient();
-const response = await client.getJSON<Products>(
-  `https://dummyjson.com/products/search?q=iphone&limit=10`,
-);
 ```
 
-### Rate Limiting
+## Rate Limiting
 
 ```ts
-import { FetchClient, useRateLimit } from "@foundatiofx/fetchclient";
+import { usePerDomainRateLimit } from "@foundatiofx/fetchclient";
 
-// Enable rate limiting globally with 100 requests per minute
-useRateLimit({
+usePerDomainRateLimit({
   maxRequests: 100,
   windowSeconds: 60,
+  updateFromHeaders: true, // Respect API rate limit headers
 });
-
-const client = new FetchClient();
-const response = await client.getJSON(
-  `https://api.example.com/data`,
-);
-```
-
-### Request Timeout
-
-```ts
-import { FetchClient } from "@foundatiofx/fetchclient";
-
-const client = new FetchClient();
-
-// Set timeout for individual requests
-const response = await client.getJSON(
-  `https://api.example.com/data`,
-  { timeout: 5000 }, // 5 seconds
-);
-
-// Use AbortSignal for cancellation
-const controller = new AbortController();
-setTimeout(() => controller.abort(), 1000);
-
-const response2 = await client.getJSON(
-  `https://api.example.com/data`,
-  { signal: controller.signal },
-);
 ```
 
-### Error Handling
+## Circuit Breaker
 
 ```ts
-import { FetchClient } from "@foundatiofx/fetchclient";
+import { FetchClientProvider } from "@foundatiofx/fetchclient";
 
-const client = new FetchClient();
-
-try {
-  const response = await client.getJSON(`https://api.example.com/data`);
-} catch (error) {
-  // Handle HTTP errors (4xx, 5xx)
-  if (error.problem) {
-    console.log(error.problem.title);
-    console.log(error.problem.detail);
-  }
-}
-
-// Or handle specific status codes
-const response = await client.getJSON(
-  `https://api.example.com/data`,
-  {
-    expectedStatusCodes: [404, 500],
-    errorCallback: (response) => {
-      if (response.status === 404) {
-        console.log("Resource not found");
-        return true; // Don't throw
-      }
-    },
-  },
-);
-```
-
-### Authentication
-
-```ts
-import { FetchClient, setAccessTokenFunc } from "@foundatiofx/fetchclient";
-
-// Set global access token function
-setAccessTokenFunc(() => localStorage.getItem("token"));
-
-const client = new FetchClient();
-const response = await client.getJSON(`https://api.example.com/data`);
-// Automatically adds Authorization: Bearer <token> header
-```
-
-### Base URL
-
-```ts
-import { FetchClient, setBaseUrl } from "@foundatiofx/fetchclient";
-
-// Set global base URL
-setBaseUrl("https://api.example.com");
-
-const client = new FetchClient();
-const response = await client.getJSON(`/users/123`);
-// Requests to https://api.example.com/users/123
-```
-
-### Loading State
-
-```ts
-import { FetchClient } from "@foundatiofx/fetchclient";
-
-const client = new FetchClient();
-
-// Track loading state
-client.loading.on((isLoading) => {
-  console.log(`Loading: ${isLoading}`);
+const provider = new FetchClientProvider();
+provider.useCircuitBreaker({
+  failureThreshold: 5, // Open after 5 failures
+  openDurationMs: 30000, // Stay open for 30 seconds
 });
 
-// Check current loading state
-console.log(client.isLoading);
-console.log(client.requestCount);
+// When API fails repeatedly, circuit opens
+// Requests return 503 immediately without hitting the API
 ```
 
-Also, take a look at the tests:
-
-[FetchClient Tests](src/FetchClient.test.ts)
-
-## Contributing
+## Testing
 
-Run tests:
-
-```shell
-deno run test
-```
-
-Lint code:
+```ts
+import { FetchClientProvider } from "@foundatiofx/fetchclient";
+import { MockRegistry } from "@foundatiofx/fetchclient/mocks";
 
-```shell
-deno lint
-```
+const mocks = new MockRegistry();
+mocks.onGet("/api/users").reply(200, [{ id: 1, name: "Alice" }]);
 
-Format code:
+const provider = new FetchClientProvider();
+mocks.install(provider);
 
-```shell
-deno fmt
+const client = provider.getFetchClient();
+const { data } = await client.getJSON("/api/users");
+// data = [{ id: 1, name: "Alice" }]
 ```
 
-Type check code:
+## Documentation
 
-```shell
-deno run check
-```
+- Guide & Examples: <https://fetchclient.foundatio.dev>
+  - [Getting Started](https://fetchclient.foundatio.dev/guide/getting-started)
+  - [Caching](https://fetchclient.foundatio.dev/guide/caching)
+  - [Middleware](https://fetchclient.foundatio.dev/guide/middleware)
+  - [Rate Limiting](https://fetchclient.foundatio.dev/guide/rate-limiting)
+  - [Circuit Breaker](https://fetchclient.foundatio.dev/guide/circuit-breaker)
+  - [Error Handling](https://fetchclient.foundatio.dev/guide/error-handling)
+  - [Testing](https://fetchclient.foundatio.dev/guide/testing)
+- API Reference: <https://jsr.io/@foundatiofx/fetchclient/doc>
 
-## License
+---
 
 MIT © [Foundatio](https://exceptionless.com)

package/script/mod.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FetchClientProvider = exports.defaultProviderInstance = exports.FetchClientCache = exports.ProblemDetails = exports.FetchClient = void 0;
+exports.createPerDomainCircuitBreakerMiddleware = exports.createCircuitBreakerMiddleware = exports.CircuitOpenError = exports.CircuitBreakerMiddleware = exports.circuitBreakerGroupByDomain = exports.CircuitBreaker = exports.FetchClientProvider = exports.defaultProviderInstance = exports.FetchClientCache = exports.ProblemDetails = exports.FetchClient = void 0;
 var FetchClient_js_1 = require("./src/FetchClient.js");
 Object.defineProperty(exports, "FetchClient", { enumerable: true, get: function () { return FetchClient_js_1.FetchClient; } });
 var ProblemDetails_js_1 = require("./src/ProblemDetails.js");
@@ -25,3 +25,11 @@ var FetchClientProvider_js_1 = require("./src/FetchClientProvider.js");
 Object.defineProperty(exports, "defaultProviderInstance", { enumerable: true, get: function () { return FetchClientProvider_js_1.defaultInstance; } });
 Object.defineProperty(exports, "FetchClientProvider", { enumerable: true, get: function () { return FetchClientProvider_js_1.FetchClientProvider; } });
 __exportStar(require("./src/DefaultHelpers.js"), exports);
+var CircuitBreaker_js_1 = require("./src/CircuitBreaker.js");
+Object.defineProperty(exports, "CircuitBreaker", { enumerable: true, get: function () { return CircuitBreaker_js_1.CircuitBreaker; } });
+Object.defineProperty(exports, "circuitBreakerGroupByDomain", { enumerable: true, get: function () { return CircuitBreaker_js_1.groupByDomain; } });
+var CircuitBreakerMiddleware_js_1 = require("./src/CircuitBreakerMiddleware.js");
+Object.defineProperty(exports, "CircuitBreakerMiddleware", { enumerable: true, get: function () { return CircuitBreakerMiddleware_js_1.CircuitBreakerMiddleware; } });
+Object.defineProperty(exports, "CircuitOpenError", { enumerable: true, get: function () { return CircuitBreakerMiddleware_js_1.CircuitOpenError; } });
+Object.defineProperty(exports, "createCircuitBreakerMiddleware", { enumerable: true, get: function () { return CircuitBreakerMiddleware_js_1.createCircuitBreakerMiddleware; } });
+Object.defineProperty(exports, "createPerDomainCircuitBreakerMiddleware", { enumerable: true, get: function () { return CircuitBreakerMiddleware_js_1.createPerDomainCircuitBreakerMiddleware; } });