@fuman/fetch 0.0.1

package/addons/rate-limit.js

@@ -0,0 +1,65 @@
+import { sleep } from "@fuman/utils";
+const defaultIsRejected = (res) => res.status === 429;
+const defaultGetReset = (res) => res.headers.get("x-ratelimit-reset");
+function tryParseDate(str) {
+  if (str == null) return null;
+  if (typeof str === "number") return str * 1e3;
+  const asNum = Number(str);
+  if (!Number.isNaN(asNum)) return asNum * 1e3;
+  const asDate = new Date(str);
+  if (asDate.toString() === "Invalid Date") return null;
+  return asDate.getTime();
+}
+function rateLimitMiddleware(options) {
+  const {
+    isRejected = defaultIsRejected,
+    getReset = defaultGetReset,
+    defaultWaitTime = 3e4,
+    maxWaitTime = 3e5,
+    jitter = 5e3,
+    maxRetries = 5,
+    onRateLimitExceeded
+  } = options;
+  return async (req, next) => {
+    let attempts = 0;
+    while (true) {
+      if (attempts > maxRetries) throw new Error("Rate limit exceeded, maximum retries exceeded");
+      attempts += 1;
+      const res = await next(req);
+      const rejected = await isRejected(res);
+      if (!rejected) return res;
+      const reset = tryParseDate(await getReset(res));
+      let waitTime;
+      if (reset == null) {
+        waitTime = defaultWaitTime;
+      } else {
+        waitTime = reset - Date.now() + jitter;
+        if (waitTime < 0) {
+          waitTime = void 0;
+        } else if (waitTime > maxWaitTime) {
+          throw new Error(`Rate limit exceeded, reset time is too far in the future: ${new Date(reset).toISOString()}`, { cause: res });
+        }
+      }
+      if (waitTime == null) {
+        onRateLimitExceeded?.(res, 0);
+        continue;
+      }
+      onRateLimitExceeded?.(res, waitTime);
+      await sleep(waitTime);
+    }
+  };
+}
+function rateLimitHandler() {
+  return {
+    beforeRequest: (ctx) => {
+      if (ctx.options.rateLimit != null || ctx.baseOptions.rateLimit != null) {
+        const options = { ...ctx.baseOptions.rateLimit, ...ctx.options.rateLimit };
+        ctx.options.middlewares ??= [];
+        ctx.options.middlewares?.push(rateLimitMiddleware(options));
+      }
+    }
+  };
+}
+export {
+  rateLimitHandler
+};

package/addons/retry.cjs

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const utils = require("@fuman/utils");
+class RetriesExceededError extends Error {
+  constructor(retries, request) {
+    super(`Retries (${retries}) exceeded for ${request.url}`);
+    this.retries = retries;
+    this.request = request;
+  }
+}
+function defaultRetryDelay(retryCount) {
+  if (retryCount >= 5) return 5e3;
+  return retryCount * 1e3;
+}
+function retryMiddleware(options) {
+  const {
+    maxRetries = 5,
+    retryDelay = defaultRetryDelay,
+    onResponse = (response) => response.status < 500,
+    returnLastResponse = false,
+    onError,
+    onRetry,
+    skip
+  } = options;
+  return async (request, next) => {
+    if (skip?.(request)) {
+      return next(request);
+    }
+    let retries = 0;
+    while (true) {
+      onRetry?.(retries, request);
+      try {
+        const res = await next(request);
+        if (onResponse(res, request)) {
+          return res;
+        }
+      } catch (err) {
+        if (onError && !onError(err, request)) {
+          throw err;
+        }
+      }
+      if (retries++ >= maxRetries) {
+        throw new RetriesExceededError(maxRetries, request);
+      }
+      await utils.sleep(typeof retryDelay === "function" ? retryDelay(retries) : retryDelay);
+    }
+  };
+}
+function retry() {
+  return {
+    beforeRequest: (ctx) => {
+      if (ctx.options.retry != null || ctx.baseOptions.retry != null) {
+        let options;
+        if (ctx.baseOptions.retry != null) {
+          if (ctx.options.retry === false) {
+            return;
+          }
+          options = ctx.options.retry ? {
+            ...ctx.baseOptions.retry,
+            ...ctx.options.retry
+          } : ctx.baseOptions.retry;
+        } else if (ctx.options.retry === false) {
+          return;
+        } else {
+          options = ctx.options.retry;
+        }
+        ctx.options.middlewares ??= [];
+        ctx.options.middlewares.push(retryMiddleware(options));
+      }
+    }
+  };
+}
+exports.RetriesExceededError = RetriesExceededError;
+exports.retry = retry;

package/addons/retry.d.ts

@@ -0,0 +1,58 @@
+import { FfetchAddon } from './types.js';
+export declare class RetriesExceededError extends Error {
+    readonly retries: number;
+    readonly request: Request;
+    constructor(retries: number, request: Request);
+}
+export interface RetryOptions {
+    /**
+     * max number of retries
+     * @default 5
+     */
+    maxRetries?: number;
+    /**
+     * delay between retries
+     * @default retryCount * 1000, up to 5000
+     */
+    retryDelay?: number | ((retryCount: number) => number);
+    /**
+     * function that will be called before starting the retry loop.
+     * if it returns false, the retry loop will be skipped and
+     * the error will be thrown immediately
+     *
+     * @default () => false
+     */
+    skip?: (request: Request) => boolean;
+    /**
+     * function that will be called before a retry is attempted,
+     * and can be used to modify the request before proceeding
+     *
+     * @param attempt  current retry attempt (starts at 0)
+     */
+    onRetry?: (attempt: number, request: Request) => Request | void;
+    /**
+     * function that will be called whenever a response is received,
+     * and should return whether the response is valid (i.e. should be returned and not retried)
+     *
+     * @default  `response => response.status < 500`
+     */
+    onResponse?: (response: Response, request: Request) => boolean;
+    /**
+     * function that will be called if an error is thrown while calling
+     * the rest of the middleware chain,
+     * and should return whether the error should be retried
+     *
+     * @default  `() => true`
+     */
+    onError?: (err: unknown, request: Request) => boolean;
+    /**
+     * if true, the last response will be returned if the number of retries is exceeded
+     * instead of throwing {@link RetriesExceededError}
+     *
+     * @default false
+     */
+    returnLastResponse?: boolean;
+}
+export declare function retry(): FfetchAddon<{
+    retry?: RetryOptions | false;
+}, object>;

package/addons/retry.js

@@ -0,0 +1,74 @@
+import { sleep } from "@fuman/utils";
+class RetriesExceededError extends Error {
+  constructor(retries, request) {
+    super(`Retries (${retries}) exceeded for ${request.url}`);
+    this.retries = retries;
+    this.request = request;
+  }
+}
+function defaultRetryDelay(retryCount) {
+  if (retryCount >= 5) return 5e3;
+  return retryCount * 1e3;
+}
+function retryMiddleware(options) {
+  const {
+    maxRetries = 5,
+    retryDelay = defaultRetryDelay,
+    onResponse = (response) => response.status < 500,
+    returnLastResponse = false,
+    onError,
+    onRetry,
+    skip
+  } = options;
+  return async (request, next) => {
+    if (skip?.(request)) {
+      return next(request);
+    }
+    let retries = 0;
+    while (true) {
+      onRetry?.(retries, request);
+      try {
+        const res = await next(request);
+        if (onResponse(res, request)) {
+          return res;
+        }
+      } catch (err) {
+        if (onError && !onError(err, request)) {
+          throw err;
+        }
+      }
+      if (retries++ >= maxRetries) {
+        throw new RetriesExceededError(maxRetries, request);
+      }
+      await sleep(typeof retryDelay === "function" ? retryDelay(retries) : retryDelay);
+    }
+  };
+}
+function retry() {
+  return {
+    beforeRequest: (ctx) => {
+      if (ctx.options.retry != null || ctx.baseOptions.retry != null) {
+        let options;
+        if (ctx.baseOptions.retry != null) {
+          if (ctx.options.retry === false) {
+            return;
+          }
+          options = ctx.options.retry ? {
+            ...ctx.baseOptions.retry,
+            ...ctx.options.retry
+          } : ctx.baseOptions.retry;
+        } else if (ctx.options.retry === false) {
+          return;
+        } else {
+          options = ctx.options.retry;
+        }
+        ctx.options.middlewares ??= [];
+        ctx.options.middlewares.push(retryMiddleware(options));
+      }
+    }
+  };
+}
+export {
+  RetriesExceededError,
+  retry
+};

package/addons/timeout.cjs

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const utils = require("@fuman/utils");
+class TimeoutError extends Error {
+  constructor(timeout2) {
+    super(`Timeout exceeded: ${timeout2}ms`);
+    this.timeout = timeout2;
+  }
+}
+function timeoutMiddleware(timeout2) {
+  return async (request, next) => {
+    const controller = new AbortController();
+    const timer = utils.timers.setTimeout(() => {
+      controller.abort(new TimeoutError(timeout2));
+    }, timeout2);
+    if (request.signal != null) {
+      const signal = request.signal;
+      if (signal.aborted) {
+        throw signal.reason;
+      }
+      signal.addEventListener("abort", () => {
+        controller.abort(signal.reason);
+        utils.timers.clearTimeout(timer);
+      });
+    }
+    request = new Request(request, {
+      signal: controller.signal
+    });
+    try {
+      return await next(request);
+    } finally {
+      utils.timers.clearTimeout(timer);
+    }
+  };
+}
+function timeout() {
+  return {
+    beforeRequest: (ctx) => {
+      if (ctx.options.timeout != null || ctx.baseOptions.timeout != null) {
+        let timeout2 = ctx.options.timeout ?? ctx.baseOptions.timeout;
+        if (typeof timeout2 === "function") {
+          timeout2 = timeout2(ctx);
+        }
+        if (timeout2 === Infinity || timeout2 <= 0) {
+          return;
+        }
+        ctx.options.middlewares ??= [];
+        ctx.options.middlewares?.push(timeoutMiddleware(timeout2));
+      }
+    }
+  };
+}
+exports.TimeoutError = TimeoutError;
+exports.timeout = timeout;

package/addons/timeout.d.ts

@@ -0,0 +1,25 @@
+import { FetchAddonCtx, FfetchAddon } from './types.js';
+export declare class TimeoutError extends Error {
+    readonly timeout: number;
+    constructor(timeout: number);
+}
+export interface TimeoutAddon {
+    /**
+     * timeout for the request in ms
+     *
+     * pass `Infinity` or `0` to disable the default timeout from the base options
+     *
+     * when the timeout is reached, the request will be aborted
+     * and the promise will be rejected with a TimeoutError
+     */
+    timeout?: number | ((ctx: FetchAddonCtx<TimeoutAddon>) => number);
+}
+/**
+ * ffetch addon that allows setting a timeout for the request.
+ * when the timeout is reached, the request will be aborted
+ * and the promise will be rejected with a TimeoutError
+ *
+ * **note**: it is important to put this addon as the last one,
+ * otherwise other middlewares might be counted towards the timeout
+ */
+export declare function timeout(): FfetchAddon<TimeoutAddon, object>;

package/addons/timeout.js

@@ -0,0 +1,54 @@
+import { timers } from "@fuman/utils";
+class TimeoutError extends Error {
+  constructor(timeout2) {
+    super(`Timeout exceeded: ${timeout2}ms`);
+    this.timeout = timeout2;
+  }
+}
+function timeoutMiddleware(timeout2) {
+  return async (request, next) => {
+    const controller = new AbortController();
+    const timer = timers.setTimeout(() => {
+      controller.abort(new TimeoutError(timeout2));
+    }, timeout2);
+    if (request.signal != null) {
+      const signal = request.signal;
+      if (signal.aborted) {
+        throw signal.reason;
+      }
+      signal.addEventListener("abort", () => {
+        controller.abort(signal.reason);
+        timers.clearTimeout(timer);
+      });
+    }
+    request = new Request(request, {
+      signal: controller.signal
+    });
+    try {
+      return await next(request);
+    } finally {
+      timers.clearTimeout(timer);
+    }
+  };
+}
+function timeout() {
+  return {
+    beforeRequest: (ctx) => {
+      if (ctx.options.timeout != null || ctx.baseOptions.timeout != null) {
+        let timeout2 = ctx.options.timeout ?? ctx.baseOptions.timeout;
+        if (typeof timeout2 === "function") {
+          timeout2 = timeout2(ctx);
+        }
+        if (timeout2 === Infinity || timeout2 <= 0) {
+          return;
+        }
+        ctx.options.middlewares ??= [];
+        ctx.options.middlewares?.push(timeoutMiddleware(timeout2));
+      }
+    }
+  };
+}
+export {
+  TimeoutError,
+  timeout
+};

package/addons/tough-cookie.d.ts

@@ -0,0 +1,7 @@
+import { CookieJar } from 'tough-cookie';
+import { FfetchAddon } from './types.js';
+export interface FfetchToughCookieAddon {
+    /** cookie jar to use */
+    cookies?: CookieJar;
+}
+export declare function toughCookieAddon(): FfetchAddon<FfetchToughCookieAddon, object>;

package/addons/types.d.ts

@@ -0,0 +1,30 @@
+import { FfetchOptions, FfetchResult } from '../ffetch.js';
+/**
+ * context that is passed to each addon in the order they were added
+ * you can safely modify anything in this object
+ */
+export interface FetchAddonCtx<RequestMixin extends object> {
+    /** url of the request (with baseUrl already applied) */
+    url: string;
+    /** options of this specific request */
+    options: FfetchOptions & RequestMixin;
+    /** base options passed to `createFfetch` */
+    baseOptions: FfetchOptions & RequestMixin;
+}
+/** internals that are exposed to the functions in response mixin */
+export type FfetchResultInternals<RequestMixin extends object> = FfetchResult & {
+    /** final url of the request */
+    _url: string;
+    /** request init object that will be passed to fetch */
+    _init: RequestInit;
+    /** finalized and merged options */
+    _options: FfetchOptions & RequestMixin;
+    /** finalized and merged headers */
+    _headers?: Record<string, string>;
+};
+export interface FfetchAddon<RequestMixin extends object, ResponseMixin extends object> {
+    /** function that will be called before each request */
+    beforeRequest?: (ctx: FetchAddonCtx<RequestMixin>) => void;
+    /** mixin functions that will be added to the response promise */
+    response?: ResponseMixin;
+}

package/default.cjs

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const ffetch = require("./ffetch.cjs");
+const timeout = require("./addons/timeout.cjs");
+const query = require("./addons/query.cjs");
+const form = require("./addons/form.cjs");
+const multipart = require("./addons/multipart.cjs");
+const ffetchDefaultAddons = [
+  /* @__PURE__ */ timeout.timeout(),
+  /* @__PURE__ */ query.query(),
+  /* @__PURE__ */ form.form(),
+  /* @__PURE__ */ multipart.multipart()
+];
+const ffetchBase = /* @__PURE__ */ ffetch.createFfetch({
+  addons: ffetchDefaultAddons
+});
+exports.ffetchBase = ffetchBase;
+exports.ffetchDefaultAddons = ffetchDefaultAddons;

package/default.d.ts

@@ -0,0 +1,30 @@
+import { FfetchAddon, ffetchAddons } from './addons/index.js';
+import { Ffetch } from './ffetch.js';
+export declare const ffetchDefaultAddons: [
+    FfetchAddon<ffetchAddons.TimeoutAddon, object>,
+    FfetchAddon<ffetchAddons.QueryAddon, object>,
+    FfetchAddon<ffetchAddons.FormAddon, object>,
+    FfetchAddon<ffetchAddons.MultipartAddon, object>
+];
+/**
+ * the default ffetch instance with reasonable default set of addons
+ *
+ * you can use this as a base to create your project-specific fetch instance,
+ * or use this as is.
+ *
+ * this is not exported as `ffetch` because most of the time you will want to extend it,
+ * and exporting it as `ffetch` would make them clash in import suggestions,
+ * and will also make it prone to subtle bugs.
+ *
+ * @example
+ * ```ts
+ * import { ffetchBase } from '@fuman/fetch'
+ *
+ * const ffetch = ffetchBase.extend({
+ *   baseUrl: 'https://example.com',
+ *   headers: { ... },
+ *   addons: [ ... ],
+ * })
+ * ```
+ */
+export declare const ffetchBase: Ffetch<ffetchAddons.TimeoutAddon & ffetchAddons.QueryAddon & ffetchAddons.FormAddon & ffetchAddons.MultipartAddon, object>;

package/default.js

@@ -0,0 +1,18 @@
+import { createFfetch } from "./ffetch.js";
+import { timeout } from "./addons/timeout.js";
+import { query } from "./addons/query.js";
+import { form } from "./addons/form.js";
+import { multipart } from "./addons/multipart.js";
+const ffetchDefaultAddons = [
+  /* @__PURE__ */ timeout(),
+  /* @__PURE__ */ query(),
+  /* @__PURE__ */ form(),
+  /* @__PURE__ */ multipart()
+];
+const ffetchBase = /* @__PURE__ */ createFfetch({
+  addons: ffetchDefaultAddons
+});
+export {
+  ffetchBase,
+  ffetchDefaultAddons
+};