fetch-as

fetch-as

Simple fetch helper with type resolver

---

Minimal helper to resolve fetch with specified response type. In case of failure, an error will return instead.

Table of contents

• Fetch API
  • Install node-fetch
  • Make fetch available globally
• Usage
• API Reference
  • FetchAsInfo
  • FetchAsReturnType
  • fetchAs
  • fetchAsArrayBuffer(url[, options])
  • fetchAsBlob(url[, options])
  • fetchAsJson(url[, options])
  • fetchAsText(url[, options])
• License

Fetch API

Please make sure fetch API is available globally for Node.js. node-fetch is a very good alternative.

Install node-fetch

$ npm i node-fetch

Make fetch available globally

const fetch = require('node-fetch');
global.fetch = fetch;

Usage

/** Available options: arrayBuffer, blob, json, text */
import { json } from 'nodemod/dist/fetch-as/index.js';

(async () => {
  /** Same function signature as native Fetch API, without the need to await .json() */
  const d = await json('http://www.mocky.io/v2/5a50cfa82f000085158d5315', { method: 'GET' });

  console.log(d); /** { status: 200, message: 'OK', by: 'fetch-as' }; */
})();

API Reference

FetchAsInfo

// Interface
interface FetchAsInfo {
  size: number;
  timeout: number;
  type: "basic"|"cors"|"default"|"error"|"opaque"|"opaqueredirect";
  headers: {
    [key: string]: any;
  };
}

FetchAsReturnType

// Interface
interface FetchAsReturnType<T = any, U = any> {
  status: number;
  info: FetchAsInfo;

  data?: T;
  error?: U;
}

• status <string> HTTP response status code. Any response that has a HTTP status greater than 399 can be regarded as an error response.

• info <Object> This contains additional information you might need from a response. See FetchAsInfo for the detailed interface.

  • size <number> Response size.
  • timeout <number> Response timeout.
  • type <string> Response type. Possible values are: basic, cors, default, error, opaque, opaqueredirect.
  • headers <Object> Response headers, e.g. { 'content-type': 'application/json' }.

• data <?any> This contains the successful response data of the user-specified type, for instance, MyReturnData in the example shown above. Only shows when the HTTP response status code is less than 400.

• error <?any> This contains the error response data of type T. Only shows when the HTTP response status code is greater than 399.

Each return type have default Generics type of any which means it can be any type in JavaScript and is overridable by user defined type via TypeScript's Generics.

// e.g. Overridable Generics
interface SuccessData {
  message: string;
}

...
const d = await FetchAsJson<SuccessData>(...);

// d will have the type of `FetchAsReturnType<SuccessData, any>>`
assert(d.data.message, '...'); // OK
...

---

fetchAs

This contains a collection of methods that will convert the response into the specified data type:

• .arrayBuffer(url[, options]) Method which will return a ArrayBuffer.
• .blob(url[,options]) Method which will return a Blob.
• .json(url[, options]) Method which will return a JSON data which can consumed by JavaScript as Object.
• .text(url[, options]) Method which will return a text string.

fetchAsArrayBuffer(url[, options])

• url <string> A string representing the URL for fetching.
• options <?Object> Options for HTTP(S) request, see fetch's init parameter.
• returns: <Promise<FetchAsReturnType<ArrayBuffer>> Promise which resolves with a FetchAsReturnType of type ArrayBuffer.

fetchAsBlob(url[, options])

• url <string> A string representing the URL for fetching.
• options <?Object> Options for HTTP(S) request, see fetch's init parameter.
• returns: <Promise<FetchAsReturnType<Blob>> Promise which resolves with a FetchAsReturnType of type Blob.

fetchAsJson(url[, options])

• url <string> A string representing the URL for fetching.
• options <?Object> Options for HTTP(S) request, see fetch's init parameter.
• returns: <Promise<FetchAsReturnType<Object>> Promise which resolves with a FetchAsReturnType of type JSON which can consumed by JavaScript as Object.

fetchAsText(url[, options])

• url <string> A string representing the URL for fetching.
• options <?Object> Options for HTTP(S) request, see fetch's init parameter.
• returns: <Promise<FetchAsReturnType<string>> Promise which resolves with a FetchAsReturnType of type string.

License

MIT License © Rong Sen Ng