xfetch

xfetch

A light-weight module that brings window.fetch to Node.js (with HTTP_PROXY support).

• API
• Configuration
• Behaviour
  • HTTP proxy
  • Throws an error if response code is non-2xx
• Cookbook
  • Retry request
  • Validate response

API

/**
 * @see https://github.com/tim-kos/node-retry#retrytimeoutsoptions
 */
type RetryConfigurationType = {
  factor?: number,
  maxTimeout?: number,
  minTimeout?: number,
  randomize?: boolean,
  retries?: number
};

type ValidateResponseType = (response: ResponseType) => boolean | Promise<boolean>;

type HeadersConfigurationType = {
  [key: string]: string | number
};

type ConfigurationType = {
  +agent?: Object,
  +body?: string | Buffer | Blob | ReadableStream,
  +compress?: boolean,
  +follow?: number,
  +headers?: HeadersConfigurationType,
  +method?: string,
  +redirect?: 'follow' | 'manual' | 'error',
  +retry?: RetryConfigurationType,
  +size?: number,
  +timeout?: number,
  +validateResponse?: ValidateResponseType
};

type RawHeadersType = {|
  [key: string]: Array<string>
|};

type HeadersType = {|
  +raw: () => RawHeadersType,
  +get: (name: string) => string
|};

type ResponseType = {|
  +headers: HeadersType,
  +json: () => Promise<Object>,
  +status: number,
  +text: () => Promise<string>
|};

type fetch = (url: string, configuration?: ConfigurationType) => Promise<ResponseType>;

Configuration

Name	Value
retry	Used to retry requests that produce response that does not pass validation. Refer to Retry request and Validating response.
validateResponse	Used to validate response. Refer to Validate response.

For other configuration properties, refer to node-fetch documentation.

Behaviour

HTTP proxy

Uses HTTP_PROXY (http://host:port) environment variable value to configure HTTP proxy.

Note: You must also configure NODE_TLS_REJECT_UNAUTHORIZED=0. This is a lazy workaround to enable the proxy to work with TLS.

Throws an error if response code is non-2xx

Throws UnexpectedResponseCodeError error if response code is non-2xx.

This behaviour can be overrode using validateResponse configuration.

Cookbook

Retry request

Requests that result in non-2xx response will be retried.

retry option is used to configure request retry strategy.

The retry configuration shape matches configuration of the retry module.

Validate response

Define a custom validator function to force use the request retry strategy.

A custom validator is configured using validateResponse configuration, e.g.

import xfetch, {
  UnexpectedResponseError
};

const validateResponse = async (response) => {
  const body = await response.text();

  if (body.includes('rate error')) {
    throw new UnexpectedResponseError(response);
  }

  return true;
}

xfetch('http://gajus.com', {validateResponse});

A custom validator must return a boolean flag indicating whether the response is valid. A custom validator can throw an error that extends UnexpectedResponseError error.

xfetch default validator can be imported and used to extend a custom validator, e.g.

import xfetch, {
  UnexpectedResponseError,
  validateResponse as defaultValidateResponse
};

const validateResponse = async (response) => {
  const responseIsValid = await defaultValidateResponse(response);

  if (!responseIsValid) {
    return responseIsValid;
  }

  const body = await response.text();

  if (body.includes('rate error')) {
    throw new UnexpectedResponseError(response);
  }

  return true;
}

xfetch('http://gajus.com', {validateResponse});