@foundatiofx/fetchclient 0.47.0

package/readme.md

@@ -0,0 +1,303 @@
+![Foundatio](https://raw.githubusercontent.com/foundatiofx/foundatio/master/media/foundatio-dark-bg.svg#gh-dark-mode-only "Foundatio")
+![Foundatio](https://raw.githubusercontent.com/foundatiofx/foundatio/master/media/foundatio.svg#gh-light-mode-only "Foundatio")
+
+[![NPM](https://img.shields.io/npm/v/%40foundatiofx%2Ffetchclient)](https://www.npmjs.com/package/@foundatiofx/fetchclient)
+[![JSR](https://jsr.io/badges/@foundatiofx/fetchclient)](https://jsr.io/@foundatiofx/fetchclient)
+[![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
+
+## Install
+
+```shell
+npm install --save @foundatiofx/fetchclient
+```
+
+## Docs
+
+[API Documentation](https://jsr.io/@foundatiofx/fetchclient/doc)
+
+## Usage
+
+### Typed Response
+
+```ts
+import { FetchClient } 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`,
+);
+
+const products = response.data;
+```
+
+### Functional
+
+```ts
+import { getJSON, postJSON } 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",
+  },
+);
+
+const product = await getJSON<Product>(
+  `https://dummyjson.com/products/${response.data!.id}`,
+);
+```
+
+### Model Validator
+
+```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;
+});
+
+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);
+}
+```
+
+### Caching
+
+```ts
+import { FetchClient } from "@foundatiofx/fetchclient";
+
+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
+  },
+);
+
+// invalidate programmatically
+client.cache.delete(["todos", "1"]);
+```
+
+### Middleware
+
+```ts
+import { FetchClient, useMiddleware } from "@foundatiofx/fetchclient";
+
+type Products = {
+  products: Array<{ id: number; name: string }>;
+};
+
+useMiddleware(async (ctx, next) => {
+  console.log("starting request");
+  await next();
+  console.log("completed request");
+});
+
+const client = new FetchClient();
+const response = await client.getJSON<Products>(
+  `https://dummyjson.com/products/search?q=iphone&limit=10`,
+);
+```
+
+### Rate Limiting
+
+```ts
+import { FetchClient, useRateLimit } from "@foundatiofx/fetchclient";
+
+// Enable rate limiting globally with 100 requests per minute
+useRateLimit({
+  maxRequests: 100,
+  windowSeconds: 60,
+});
+
+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
+
+```ts
+import { FetchClient } 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}`);
+});
+
+// Check current loading state
+console.log(client.isLoading);
+console.log(client.requestCount);
+```
+
+Also, take a look at the tests:
+
+[FetchClient Tests](src/FetchClient.test.ts)
+
+## Contributing
+
+Run tests:
+
+```shell
+deno run test
+```
+
+Lint code:
+
+```shell
+deno lint
+```
+
+Format code:
+
+```shell
+deno fmt
+```
+
+Type check code:
+
+```shell
+deno run check
+```
+
+## License
+
+MIT © [Foundatio](https://exceptionless.com)

package/script/mod.js

@@ -0,0 +1,27 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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;
+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");
+Object.defineProperty(exports, "ProblemDetails", { enumerable: true, get: function () { return ProblemDetails_js_1.ProblemDetails; } });
+var FetchClientCache_js_1 = require("./src/FetchClientCache.js");
+Object.defineProperty(exports, "FetchClientCache", { enumerable: true, get: function () { return FetchClientCache_js_1.FetchClientCache; } });
+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);

package/script/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/script/src/Counter.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Counter = void 0;
+const ObjectEvent_js_1 = require("./ObjectEvent.js");
+/**
+ * Represents a counter that can be incremented and decremented.
+ */
+class Counter {
+    #count = 0;
+    #onChange = new ObjectEvent_js_1.ObjectEvent();
+    /**
+     * Gets the current count.
+     */
+    get count() {
+        return this.#count;
+    }
+    /**
+     * Gets an event that is triggered when the count changes.
+     */
+    get changed() {
+        return this.#onChange.expose();
+    }
+    /**
+     * Increments the count by 1.
+     */
+    increment() {
+        const previous = this.#count;
+        this.#count++;
+        this.#onChange.trigger({ previous, value: this.#count });
+    }
+    /**
+     * Decrements the count by 1.
+     */
+    decrement() {
+        const previous = this.#count;
+        this.#count--;
+        this.#onChange.trigger({ previous, value: this.#count });
+    }
+}
+exports.Counter = Counter;

package/script/src/DefaultHelpers.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useFetchClient = useFetchClient;
+exports.getJSON = getJSON;
+exports.postJSON = postJSON;
+exports.putJSON = putJSON;
+exports.patchJSON = patchJSON;
+exports.deleteJSON = deleteJSON;
+exports.getCurrentProvider = getCurrentProvider;
+exports.setCurrentProviderFunc = setCurrentProviderFunc;
+exports.setBaseUrl = setBaseUrl;
+exports.setAccessTokenFunc = setAccessTokenFunc;
+exports.setModelValidator = setModelValidator;
+exports.useMiddleware = useMiddleware;
+exports.setRequestOptions = setRequestOptions;
+exports.useRateLimit = useRateLimit;
+exports.usePerDomainRateLimit = usePerDomainRateLimit;
+const FetchClientProvider_js_1 = require("./FetchClientProvider.js");
+let getCurrentProviderFunc = () => null;
+/**
+ * Gets a FetchClient instance from the current provider.
+ * @returns The FetchClient instance.
+ */
+function useFetchClient(options) {
+    return getCurrentProvider().getFetchClient(options);
+}
+/**
+ * Sends a GET request to the specified URL using the default client and provider and returns the response as JSON.
+ * @param url - The URL to send the GET request to.
+ * @param options - Optional request options.
+ * @returns A promise that resolves to the response as JSON.
+ */
+function getJSON(url, options) {
+    return useFetchClient().getJSON(url, options);
+}
+/**
+ * Sends a POST request with JSON payload using the default client and provider to the specified URL.
+ *
+ * @template T - The type of the response data.
+ * @param {string} url - The URL to send the request to.
+ * @param {object | string | FormData} [body] - The JSON payload or form data to send with the request.
+ * @param {RequestOptions} [options] - Additional options for the request.
+ * @returns {Promise<FetchClientResponse<T>>} - A promise that resolves to the response data.
+ */
+function postJSON(url, body, options) {
+    return useFetchClient().postJSON(url, body, options);
+}
+/**
+ * Sends a PUT request with JSON payload using the default client and provider to the specified URL.
+ *
+ * @template T - The type of the response data.
+ * @param {string} url - The URL to send the request to.
+ * @param {object | string} [body] - The JSON payload to send with the request.
+ * @param {RequestOptions} [options] - Additional options for the request.
+ * @returns {Promise<FetchClientResponse<T>>} - A promise that resolves to the response data.
+ */
+function putJSON(url, body, options) {
+    return useFetchClient().putJSON(url, body, options);
+}
+/**
+ * Sends a PATCH request with JSON payload using the default client and provider to the specified URL.
+ *
+ * @template T - The type of the response data.
+ * @param {string} url - The URL to send the request to.
+ * @param {object | string} [body] - The JSON payload to send with the request.
+ * @param {RequestOptions} [options] - Additional options for the request.
+ * @returns {Promise<FetchClientResponse<T>>} - A promise that resolves to the response data.
+ */
+function patchJSON(url, body, options) {
+    return useFetchClient().patchJSON(url, body, options);
+}
+/**
+ * Sends a DELETE request with JSON payload using the default client and provider to the specified URL.
+ *
+ * @template T - The type of the response data.
+ * @param {string} url - The URL to send the request to.
+ * @param {RequestOptions} [options] - Additional options for the request.
+ * @returns {Promise<FetchClientResponse<T>>} - A promise that resolves to the response data.
+ */
+function deleteJSON(url, options) {
+    return useFetchClient().deleteJSON(url, options);
+}
+/**
+ * Gets the current FetchClientProvider.
+ * @returns The current FetchClientProvider.
+ */
+function getCurrentProvider() {
+    if (getCurrentProviderFunc === null) {
+        return FetchClientProvider_js_1.defaultInstance;
+    }
+    return getCurrentProviderFunc() ?? FetchClientProvider_js_1.defaultInstance;
+}
+/**
+ * Sets the function that retrieves the current FetchClientProvider using whatever scoping mechanism is available.
+ * @param getProviderFunc - The function that retrieves the current FetchClientProvider.
+ * @returns void
+ */
+function setCurrentProviderFunc(getProviderFunc) {
+    getCurrentProviderFunc = getProviderFunc;
+}
+/**
+ * Sets the base URL for any FetchClient instances created by the current provider.
+ * @param baseUrl - The base URL to use for requests.
+ */
+function setBaseUrl(baseUrl) {
+    getCurrentProvider().setBaseUrl(baseUrl);
+}
+/**
+ * Sets the access token function for any FetchClient instances created by the current provider.
+ * @param accessTokenFunc - The function that retrieves the access token.
+ */
+function setAccessTokenFunc(accessTokenFunc) {
+    getCurrentProvider().setAccessTokenFunc(accessTokenFunc);
+}
+/**
+ * Sets the model validator function for any FetchClient instances created by the current provider.
+ * @param validate - The function that validates the model.
+ */
+function setModelValidator(validate) {
+    getCurrentProvider().setModelValidator(validate);
+}
+/**
+ * Adds a middleware to any FetchClient instances created by the current provider.
+ * @param middleware - The middleware function to be added.
+ */
+function useMiddleware(middleware) {
+    getCurrentProvider().useMiddleware(middleware);
+}
+/**
+ * Sets the default request options for any FetchClient instances created by the current provider.
+ * @param options - The options to set as the default request options.
+ */
+function setRequestOptions(options) {
+    getCurrentProvider().applyOptions({ defaultRequestOptions: options });
+}
+/**
+ * Enables rate limiting for any FetchClient instances created by the current provider.
+ * @param options - The rate limiting configuration options.
+ */
+function useRateLimit(options) {
+    getCurrentProvider().useRateLimit(options);
+}
+/**
+ * Enables per-domain rate limiting for any FetchClient instances created by the current provider.
+ * @param options - The rate limiting configuration options.
+ */
+function usePerDomainRateLimit(options) {
+    getCurrentProvider().usePerDomainRateLimit(options);
+}