nookfetch

A lightweight, flexible fetch wrapper written during the 2020 quarantine

Table of Contents

• Why
• Installation
• Documentation
  • createNookFetch
  • nookFetch
  • APIError

Why a fetch wrapper?

When hitting an endpoint, most developers want to focus on the response data. They don't want to have to worry about generalized error handling, Response parsing, or response-type validation. This project allows for simple set-up of these concerns, while being flexible enough to allow overrides for individual calls.

When starting this project, I could not find anything similar already available on NPM - so I wrote it myself!

Installation

npm i nookfetch --save

Documentation

createNookFetch

nookFetch factory - creates the nookFetch function and binds it to error handling.

Arguments

| Name | Type | Required | Default | Description | | -------------- | ------------------ | -------- | ---------------------------------------------- | ------------------------------------------------------------- | | onError | (e: Error) => void | true | - | callback function on error - could be API or validation error | | generalOptions | ParseOptionsType | - | See ParseOptionsType for default information | general settings for fetch functions |

ParseOptionsType

The ParseOptionsType is an object with the following properties:

| Name | Type | Required | Default | Description | | ------------------ | --------------------- | -------- | --------------- | --------------------------------------------------------- | | parseResponse | (e: Response) => void | - | parseReturnData | function to parse incoming data for a specific fetch call | | parseErrorResponse | boolean | - | - | function to parse error message for this specific call |

NOTE: The default parseResponse value will ONLY parse JSON data - it will return the Response object if the header is not application/json.

Returns

An nookFetch function that is bound to the onError function.

Usage

import createNookFetch from "nookfetch";

const onError = (e: Error) => {
  // some generic error handling here
  ...
};

const nookFetch = createNookFetch(onError);

export default nookFetch;

nookFetch Function

Fetch wrapper function

This function handles parsing, validation, and error handling for a fetch.

Arguments

| Name | Type | Required | Default | Description | | ------------ | ----------------- | -------- | ----------------------------------------- | --------------------------------------------------- | | url | string | true | - | the url to call | | validate | (input: any) => T | true | - | function to validate the return data from the fetch | | fetchOptions | FetchOptionsType | - | - | configuration options for the fetch call | | options | OptionsType | - | See OptionsType for default information | configuration options |

FetchOptionsType

The FetchOptionsType in typescript is as follows:

type FetchOptionsType = Omit<RequestInit, "body"> & {
  body?: object | FormData;
};

You can pass any options available to the fetch function.

NOTE: The body type has been changed - nookFetch will process it automatically into a type the fetch function can consume.

OptionsType

The OptionsType is an object with the following properties:

| Name | Type | Required | Default | Description | | ------------------ | --------------------- | -------- | ------------------------------------------------- | ----------------------------------------------------------------- | | useErrorHandling | boolean | - | true | toggles use of the onError function | | parseResponse | (e: Response) => void | - | parseReturnData OR the general parsing function | function to parse incoming data for a specific fetch call, if set | | parseErrorResponse | boolean | - | the general error parsing function, if set | function to parse error message for this specific call |

NOTE: The default parseResponse value will ONLY parse JSON data - it will return the Response object if the header is not application/json.

Returns

A promise that resolves to the output of the validation function.

Throws

API Error

• Error thrown by fetch
• Error thrown when api status is not in the 200 range

Validation Error

• Error thrown by validate function

Parsing Error

• Error thrown by the parsing function

Usage

import nookFetch from "file/with/createNookFetch";
import validate from "validation";

try {
  const info = nookFetch(
    "/testing/123",
    validate,
    {
      method: "POST",
      body: { foo: "bar" }
    },
    { useErrorHandling: true }
  );
} catch (e) {
  console.log("ERROR!!!!", e);
}

APIError

Class representing an API Error

Arguments

| Name | Type | Required | Default | Description | | ------- | ------ | -------- | ------- | ------------------- | | message | string | true | - | the error message | | status | number | true | - | the api status code |

Functions

getStatus

Function to get the status code of the API error.

Returns

Number that represents the API error code.