Skip to main content

A module to extend `fetch`.

Works with
This package works with Bun
This package works with Cloudflare Workers
This package works with Node.js
This package works with Deno
It is unknown whether this package works with Browsers
JSR Score
100%
Published
2 weeks ago

exFetch (ES)

⚖ī¸ MIT

Deno Land: exfetch GitHub: hugoalh-studio/exfetch-es JSR: @hugoalh/exfetch NPM: @hugoalh/exfetch

An ES (JavaScript & TypeScript) module to extend fetch.

🌟 Features

  • Ability to cache suitable Request-Responses to reduce network usage and response time.
  • Automatically retry on failure requests, preferentially obey the response header Retry-After.
  • Redirect fine control.
  • Simplify URL paginate requests.

🔰 Begin

đŸŽ¯ Targets

Registry - JSR Registry - NPM Remote Import
Bun >= v1.1.0 ✔ī¸ node_modules ✔ī¸ Specifier npm: ❌
Cloudflare Workers ✔ī¸ node_modules ✔ī¸ node_modules ❌
Deno >= v1.42.0 ✔ī¸ Specifier jsr: ✔ī¸ Specifier npm: ✔ī¸
NodeJS >= v18.12.0 ✔ī¸ node_modules ✔ī¸ node_modules ❌

ℹī¸ Note

It is possible to use this module in other methods/ways which not listed in here, however it is not officially supported.

#ī¸âƒŖ Registries Identifier

  • JSR:
    @hugoalh/exfetch
    
  • NPM:
    @hugoalh/exfetch
    

ℹī¸ Note

  • Although it is recommended to import the entire module, it is also able to import part of the module with sub path if available, please visit file jsr.jsonc property exports for available sub paths.
  • It is recommended to use this module with tag for immutability.

#ī¸âƒŖ Remote Import Paths

  • Deno Land:
    https://deno.land/x/exfetch[@${Tag}]/mod.ts
    
  • GitHub Raw: (Require Tag)
    https://raw.githubusercontent.com/hugoalh-studio/exfetch-es/${Tag}/mod.ts
    

ℹī¸ Note

  • Although it is recommended to import the entire module with the main path mod.ts, it is also able to import part of the module with sub path if available, but do not import if:

    • it's file path has an underscore prefix (e.g.: _foo.ts, _util/bar.ts), or
    • it is a benchmark or test file (e.g.: foo.bench.ts, foo.test.ts), or
    • it's symbol has an underscore prefix (e.g.: export function _baz() {}).

    These elements are not considered part of the public API, thus no stability is guaranteed for them.

  • Although there have 3rd party services which provide enhanced, equal, or similar methods/ways to remote import the module, beware these services maybe inject unrelated elements and thus affect the security.

  • It is recommended to use this module with tag for immutability.

🛡ī¸ Permissions

Target Type Coverage
Deno Network (allow-net) Resource

🧩 APIs

  • class ExFetch {
      constructor(options: ExFetchOptions = {}): ExFetch;
      addHTTPStatusCodeRetryable(value: number): this;
      addHTTPStatusCodeRetryable(values: number[]): this;
      addHTTPStatusCodeRetryable(...values: number[]): this;
      deleteHTTPStatusCodeRetryable(value: number): this;
      deleteHTTPStatusCodeRetryable(values: number[]): this;
      deleteHTTPStatusCodeRetryable(...values: number[]): this;
      fetch(input: string | URL, init?: RequestInit): Promise<Response>;
      fetchPaginate(input: string | URL, init?: RequestInit, optionsOverride: ExFetchPaginateOptions = {}): Promise<Response[]>;
      static fetch(input: string | URL, init?: RequestInit, options: ExFetchOptions = {}): Promise<Response>;
      static fetchPaginate(input: string | URL, init?: RequestInit, options: ExFetchOptions = {}): Promise<Response[]>;
    }
    
  • const userAgentDefault: string;
    
  • function exFetch(input: string | URL, init?: RequestInit, options: ExFetchOptions = {}): Promise<Response>;
    
  • function exFetchPaginate(input: string | URL, init?: RequestInit, options: ExFetchOptions = {}): Promise<Response[]>;
    
  • interface ExFetchDelayOptions {
      /**
       * Maximum time per delay, by milliseconds.
       */
      maximum?: number;
      /**
       * Minimum time per delay, by milliseconds.
       */
      minimum?: number;
    }
    
  • interface ExFetchEventCommonPayload {
      /**
       * Status code of the current response.
       */
      statusCode: Response["status"];
      /**
       * Status text of the current response.
       */
      statusText: Response["statusText"];
    }
    
  • interface ExFetchEventPaginatePayload {
      /**
       * Current count of the paginates, begin from `1`.
       */
      countCurrent: number;
      /**
       * Maximum number of the paginates allowed.
       */
      countMaximum: number;
      /**
       * Will paginate to the next page after this amount of time, by milliseconds.
       */
      paginateAfter: number;
      /**
       * Will paginate to this URL.
       */
      paginateURL: URL;
    }
    
  • interface ExFetchEventRedirectPayload extends ExFetchEventCommonPayload {
      /**
       * Current count of the redirects, begin from `1`.
       */
      countCurrent: number;
      /**
       * Maximum number of the redirects allowed.
       */
      countMaximum: number;
      /**
       * Will redirect after this amount of time, by milliseconds.
       */
      redirectAfter: number;
      /**
       * Will redirect to this URL.
       */
      redirectURL: URL;
    }
    
  • interface ExFetchEventRetryPayload extends ExFetchEventCommonPayload {
      /**
       * Current count of the retries, begin from `1`.
       */
      countCurrent: number;
      /**
       * Maximum number of the retries allowed.
       */
      countMaximum: number;
      /**
       * Will retry after this amount of time, by milliseconds.
       */
      retryAfter: number;
      /**
       * Will retry this URL.
       */
      retryURL: URL;
    }
    
  • interface ExFetchOptions {
      /**
       * **\[đŸ§Ē EXPERIMENTAL\]** Whether to cache suitable `Request`-`Response`s.
       * 
       * - `false`: Disable cache.
       * - `true`: Enable cache with default name, manage automatically.
       * - `<string>`: Enable cache with custom name, manage automatically.
       * - `<Cache>`: Enable cache, manage manually.
       * @default false
       */
      cacheStorage?: boolean | string | Cache;
      /**
       * Custom HTTP status codes that retryable.
       * 
       * > **⚠ī¸ Warning**
       * >
       * > This will override the default when defined; To add and/or delete some of the HTTP status codes, use methods `ExFetch.addHTTPStatusCodeRetryable` | ExFetch.addHTTPStatusCodeRetryable and/or `ExFetch.deleteHTTPStatusCodeRetryable` | ExFetch.deleteHTTPStatusCodeRetryable instead.
       * @default undefined
       */
      httpStatusCodesRetryable?: number[] | Set<number>;
      /**
       * Paginate options.
       */
      paginate?: ExFetchPaginateOptions;
      /**
       * Redirect options. This only apply when define property `redirect` as `"follow"` in the request, and define property `maximum` in this option.
       */
      redirect?: ExFetchRedirectOptions;
      /**
       * Retry options.
       */
      retry?: ExFetchRetryOptions;
      /**
       * Timeout of the request (include the redirects and the retries), by milliseconds. This only apply when have not define property `signal` in the request.
       * @default Infinity // Disable
       */
      timeout?: number;
      /**
       * Custom user agent. This only apply when have not define HTTP header `User-Agent` in the request.
       * @default `${RuntimeSlug} exFetch/${ExFetchVersion}`.
       */
      userAgent?: string;
    }
    
  • interface ExFetchPaginateLinkUpPayload {
      /**
       * Header link of the current page.
       */
      currentHeaderLink: HTTPHeaderLink;
      /**
       * URL of the current page.
       */
      currentURL: URL;
    }
    
  • interface ExFetchPaginateOptions {
      /**
       * Amount of time to delay between the paginates, by milliseconds.
       * @default 0
       */
      delay?: number | ExFetchDelayOptions;
      /**
       * Custom function for correctly link up to the next page, useful for the endpoints which not correctly return an absolute or relative URL.
       * @param {ExFetchPaginateLinkUpPayload} param Link up payload of the paginate.
       * @returns {URL | null | undefined} URL of the next page.
       */
      linkUpNextPage?(param: ExFetchPaginateLinkUpPayload): URL | null | undefined;
      /**
       * Maximum amount of paginates to allow.
       * @default Infinity // Unlimited
       */
      maximum?: number;
      /**
       * Event listener for the paginates.
       * @param {ExFetchEventPaginatePayload} param Event payload of the paginate.
       * @returns {void}
       */
      onEvent?(param: ExFetchEventPaginatePayload): void;
      /**
       * Whether to throw an error when the latest page response provide an invalid HTTP header `Link`.
       * @default true
       */
      throwOnInvalidHeaderLink?: boolean;
    }
    
  • interface ExFetchRedirectOptions {
      /**
       * Amount of time to delay between the redirects, by milliseconds.
       * @default 0
       */
      delay?: number | ExFetchDelayOptions;
      /**
       * Maximum amount of redirects to allow.
       * @default Infinity
       */
      maximum?: number;
      /**
       * Event listener for the redirects.
       * @param {ExFetchEventRedirectPayload} param Event payload of the redirect.
       * @returns {void}
       */
      onEvent?(param: ExFetchEventRedirectPayload): void;
    }
    
  • interface ExFetchRetryOptions {
      /**
       * Amount of time to delay between the attempts, by milliseconds. This only apply when the endpoint have not provide any retry information in the response.
       * @default
       * {
       *   maximum: 60000,
       *   minimum: 1000
       * }
       */
      delay?: number | ExFetchDelayOptions;
      /**
       * Maximum amount of attempts to allow.
       * @default 4
       */
      maximum?: number;
      /**
       * Event listener for the retries.
       * @param {ExFetchEventRetryPayload} param Event payload of the retry.
       * @returns {void}
       */
      onEvent?(param: ExFetchEventRetryPayload): void;
    }
    

ℹī¸ Note

For the prettier documentation, can visit via:

✍ī¸ Examples

  • const responses: Response[] = await exFetchPaginate("https://api.github.com/repos/microsoft/vscode/labels?per_page=100");
    
    responses.map((response: Response) => {
      return response.ok;
    }).includes(false);
    //=> false (`false` when no broken page, otherwise `true`)
    
    const result = [];
    for (const response of responses) {
      result.push(...(await response.json()));
    }
    result;
    /*=>
    [
      {
        "id": 2339554941,
        "node_id": "MDU6TGFiZWwyMzM5NTU0OTQx",
        "url": "https://api.github.com/repos/microsoft/vscode/labels/:apple:%20si",
        "name": ":apple: si",
        "color": "e99695",
        "default": false,
        "description": "Issues related to apple silicon"
      },
      {
        "id": 421131022,
        "node_id": "MDU6TGFiZWw0MjExMzEwMjI=",
        "url": "https://api.github.com/repos/microsoft/vscode/labels/*as-designed",
        "name": "*as-designed",
        "color": "E2A1C2",
        "default": false,
        "description": "Described behavior is as designed"
      },
      {
        "id": 409283388,
        "node_id": "MDU6TGFiZWw0MDkyODMzODg=",
        "url": "https://api.github.com/repos/microsoft/vscode/labels/*caused-by-extension",
        "name": "*caused-by-extension",
        "color": "E2A1C2",
        "default": false,
        "description": "Issue identified to be caused by an extension"
      },
      {
        "id": 766755777,
        "node_id": "MDU6TGFiZWw3NjY3NTU3Nzc=",
        "url": "https://api.github.com/repos/microsoft/vscode/labels/*dev-question",
        "name": "*dev-question",
        "color": "E2A1C2",
        "default": false,
        "description": "VS Code Extension Development Question"
      },
      {
        "id": 366106217,
        "node_id": "MDU6TGFiZWwzNjYxMDYyMTc=",
        "url": "https://api.github.com/repos/microsoft/vscode/labels/*duplicate",
        "name": "*duplicate",
        "color": "E2A1C2",
        "default": false,
        "description": "Issue identified as a duplicate of another issue(s)"
      },
      ... +467
    ]
    */
    
Built and signed on
GitHub Actions
View transparency log

Add Package

deno add @hugoalh/exfetch

Import symbol

import * as mod from "@hugoalh/exfetch";

Add Package

npx jsr add @hugoalh/exfetch

Import symbol

import * as mod from "@hugoalh/exfetch";

Add Package

yarn dlx jsr add @hugoalh/exfetch

Import symbol

import * as mod from "@hugoalh/exfetch";

Add Package

pnpm dlx jsr add @hugoalh/exfetch

Import symbol

import * as mod from "@hugoalh/exfetch";

Add Package

bunx jsr add @hugoalh/exfetch

Import symbol

import * as mod from "@hugoalh/exfetch";