Cloudflare Workers Fetch Helpers

A collection of chainable helpers to adapt the Fetch API.

Installation

npm install --save @glenstack/cf-workers-fetch-helpers

Usage

All methods exported from this library can be chained together and have the following usage:

import {
  fetchHelper,
  otherFetchHelper,
} from "@glenstack/cf-workers-fetch-helpers";

const fetch1 = fetchHelper(fetch, fetchHelperOptions); // `fetch` is the built-in fetch global
const fetch2 = otherFetchHelper(fetch1, otherFetchHelperOptions); // NOTE: `fetch1` is being chained here, such that `fetch2(request)` calls `fetch1(request)`, which calls `fetch(request)`

(async () => {
  const response = await fetch2("https://example.com");
})();

Where:

• fetch, fetch1 and fetch2 are all Fetch compatible functions,
• fetchHelper and otherFetchHelper are fictional functions in this library (see below for the real ones),
• fetchHelperOptions and otherFetchHelperOptions are the options for these fictional helper functions (again, the real functions and their options follow).

alterURL

Changes the Request URL.

Options Signature

type options =
  | {
      prepend?: string;
      append?: string;
    }
  | {
      mutate: (prevURL: string) => string;
    };

Options

| Option | Notes | | --------- | ------------------------------------------------------- | | prepend | Prepends the URL with a given string. | | append | Appends the URL with a given string. | | mutate | A function that, when given a URL, returns the new URL. |

Example Usage

import { alterURL } from "@glenstack/cf-workers-fetch-helpers";

const gitHubFetch = alterURL(fetch, { prepend: "https://api.github.com" });

(async () => {
  const response = await gitHubFetch("/meta");
})();

proxyHost

Replaces the host of a Request URL.

Options Signature

type options = {
  host: string;
};

Options

| Option | Notes | | ------ | ------------------------------------------- | | host | The new host to replace in the Request URL. |

Example Usage

import { proxyHost } from "@glenstack/cf-workers-fetch-helpers";

const proxiedFetch = proxyHost(fetch, { host: "about.gitlab.com" })(
  async () => {
    const response = await proxiedFetch("https://github.com/pricing");
  }
)();

addHeaders

Adds headers to the Request.

Options Signature

type options = {
  headers: RequestInit["headers"];
};

Options

| Option | Notes | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | headers | A Headers object, an object literal, or an array of two-item arrays to set request’s headers. |

Example Usage

import { addHeaders } from "@glenstack/cf-workers-fetch-helpers";

const gitHubFetch = addHeaders(fetch, {
  headers: { Authorization: "Basic xyz", "User-Agent": "Awesome-Octocat-App" },
});

(async () => {
  const response = await gitHubFetch("/meta");
})();

authorization

Adds an Authorization header. The following types of authorization are supported:

• Basic
• Bearer

Options Signature

type options =
  | {
      username?: string;
      password?: string;
    }
  | {
      bearere: string;
    };

Options

| Option | Notes | | ---------- | -------------------------------------------- | | username | Used in basic authorization. | | password | Used in basic authorization. | | bearer | A bearer token used in bearer authorization. |

Example Usage

import { authorization } from "@glenstack/cf-workers-fetch-helpers";

const gitHubFetch = authorization(fetch, { bearer: "aToken" });

(async () => {
  const response = await gitHubFetch("/meta");
})();

oauth2

A OAuth2 client which automatically refreshes tokens.

Options Signature

type options = {
  tokenRefreshed?: (options: {
    accessToken?: string;
    refreshToken: string;
  }) => Promise<void>;
  accessToken?: string;
  authorizationHasExpired?: (response: Response) => Promise<boolean>;
  refreshToken: string;
  tokenEndpoint: string;
  clientID: string;
  clientSecret: string;
  redirectURI?: string;
  scope?: string;
  refreshFetch?: typeof fetch;
};

Options

| Option | Notes | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | tokenRefreshed | A function called when a new token is generated. Useful if you wish to persist the latest valid tokens. | | accessToken | An Access Token. | | authorizationHasExpired | A function to evaluate if, given a Response, the Access Token is now invalid. Defaults to returning true if the Response status code is 401. | | refreshToken | A valid Refresh Token. | | tokenEndpoint | The URL of the authorization server which refreshes tokens. | | clientID | The application client ID. | | clientSecret | The application client secret. | | redirectURI | Although not in the specification, some authorization servers require a valid redirect URI when refreshing tokens. | | scope | The scope of the access token. | | refreshFetch | The fetch function to use when making calls to the authorization server. Defaults to the global fetch function. |

Example Usage

import { oauth2 } from "@glenstack/cf-workers-fetch-helpers";

const gitHubFetch = oauth2(fetch, {
  tokenRefreshed: async ({ accessToken, refreshToken }) => {
    console.log("Tokens have been refreshed!", { accessToken, refreshToken });
  },
  accessToken: "anAccessToken",
  refreshToken: "aRefreshToken",
  tokenEndpoint: "https://github.com/login/oauth/access_token",
  clientID: "anID",
  clientSecret: "aSecret",
});

(async () => {
  const response = await gitHubFetch("https://api.github.com/meta");
})();