exFetch (ES)

⚖️ MIT

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

🌟 Feature

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.

🎯 Target

Bun ^ v1.0.0
Cloudflare Workers
Deno >= v1.35.0 / >= v1.41.1 (For JSR Only)
🛡️ Require Permission
- Network (allow-net)
NodeJS >= v18.12.0

🔰 Usage

Via JSR With `node_modules`

🎯 Supported Target

Bun

Cloudflare Workers

NodeJS

Install via:

Bun
```
bunx jsr add @hugoalh/exfetch[@${Tag}]
```
NPM
```
npx jsr add @hugoalh/exfetch[@${Tag}]
```

PNPM

pnpm dlx jsr add @hugoalh/exfetch[@${Tag}]

Yarn

yarn dlx jsr add @hugoalh/exfetch[@${Tag}]

Import at the script:
```
import ... from "@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 import the module with tag for immutability.

Via JSR With Specifier

🎯 Supported Target

Deno

Import at the script:

import ... from "jsr:@hugoalh/exfetch[@${Tag}]";

ℹ️ 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 import the module with tag for immutability.

Via NPM With `node_modules`

🎯 Supported Target

Cloudflare Workers

NodeJS

Install via:

NPM
```
npm install @hugoalh/exfetch[@${Tag}]
```
PNPM
```
pnpm add @hugoalh/exfetch[@${Tag}]
```
Yarn
```
yarn add @hugoalh/exfetch[@${Tag}]
```

Import at the script:
```
import ... from "@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 import the module with tag for immutability.

Via NPM With Specifier

🎯 Supported Target

Bun

Deno

Import at the script:

import ... from "npm:@hugoalh/exfetch[@${Tag}]";

ℹ️ 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 import the module with tag for immutability.

Via Remote Import

🎯 Supported Target

Deno

Import at the script via:

Deno Land

import ... from "https://deno.land/x/exfetch[@${Tag}]/mod.ts";

GitHub Raw (Require Tag)

import ... from "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 import the module with tag for immutability.

🧩 API

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?: Parameters<typeof fetch>[1]): Promise<Response>;
  fetchPaginate(input: string | URL, init?: Parameters<typeof fetch>[1], optionsOverride: ExFetchPaginateOptions = {}): Promise<Response[]>;
  static fetch(input: string | URL, init?: Parameters<typeof fetch>[1], options: ExFetchOptions = {}): Promise<Response>;
  static fetchPaginate(input: string | URL, init?: Parameters<typeof fetch>[1], options: ExFetchOptions = {}): Promise<Response[]>;
}

```
const userAgentDefault: string;
```

function exFetch(input: string | URL, init?: Parameters<typeof fetch>[1], options: ExFetchOptions = {}): Promise<Response>;

function exFetchPaginate(input: string | URL, init?: Parameters<typeof fetch>[1], 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 {@linkcode ExFetch.addHTTPStatusCodeRetryable} and/or {@linkcode 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:

Deno CLI deno doc

Deno Land

JSR

✍️ Example

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
]
*/

exFetch (ES)

🌟 Feature

🎯 Target

🔰 Usage

Via JSR With node_modules

Via JSR With Specifier

Via NPM With node_modules

Via NPM With Specifier

Via Remote Import

🧩 API

✍️ Example

Via JSR With `node_modules`

Via NPM With `node_modules`