Type-safe fetching with gretchen

Almost every real-world application relies on data fetching and some sort of asynchronous interaction with an external API. Just like any programming problem, there are quite a number of ways to solve this; some are simple, others are complex. One common theme, however, is that the solutions usually have one or more features missing, like interpolation, re-fetch, etc.

In the browser environment, we are provided with the fetch API, which is simple and relatively flexible. However, it comes with a problem: it assumes all non-success (≥4xx) exceptions and throws them. Hence we are limited to catching these exceptions with a Promise.catch or the try/catch in an async/await pattern.

The issue with this is that those thrown exceptions are notoriously difficult to type since they could be of any shape. In retrospect, we know that we usually have an idea of the shape of our errors if we are allowed to deal with them. Here comes gretchen.

gretchen offers a sound parity with fetch out of the box, which makes it easily adaptable in legacy codebases. It offers resilience to common request/response issues like errors and inconsistent responses returned from APIs. This is handled via built-in timeout handling, configurable retry logic, and error normalization. It also offers good browser support as far back as Internet Explorer 11.

Getting started

Installation

You can install via either yarn or npm

npm install gretchen

OR

yarn add gretchen

Usage

With fetch, you would have something like:

const request = await fetch("/api/dogs/1");
const dog = await request.json();

Similarly, with gretchen, you’d have:

import { gretch } from "gretchen";
const { data: dog1} = await gretch("/api/dog/1").json();

You will notice this provides just enough abstraction, baking in the ease of use of fetch without sacrificing flexibility. One other important difference to note is how you can resolve to JSON within one statement.

Fetching with gretchen

gretchen really begins to shine and differentiate itself from native fetch in error handling. The most common option is to return a typed entity upon which you can then make assertions. This will give TypeScript an opportunity to understand what we are dealing with.

try {
  const cats = await getAllCats();
 return  cats
} catch (e) {
  if (error instanceof ErrorType) {
    // handle Error
  }
}

The problem with this is that you have to manually check whether it satisfies the condition. Admittedly, you could write a middleware to perform this check, but that is an unnecessary additional step and adds boilerplate. The ideal solution would be to not have to perform this check at all, and to do that elegantly, with less code.

Another option would be to not throw any exceptions. fetch works this way by default. So we are able to configure our response based on whether we get the required data — that is, for success and error responses, we can abstract away the assertion and handle the response elegantly. This is similar to the RESULT type in Rust.

enum Result<T, E> {
   Ok(T), // success data
   Err(E), // error
}

We could then have something like this for handling responses:

if (response.status < 300) {return Result.Ok(response);
} else {
return Result.Err(response);
}

While this pattern might be appealing, it introduces a layer of complexity that might not be intuitive for newcomers. gretchen tries to simplify this by providing a much clearer abstraction in the absence of exceptions.

Instead of returning an object with methods for checking the type of the discriminated union, gretchen has employed a pattern similar to the error handling found in Go. Both halves of the union are returned as separate entities:

const { error, data } = await getEndpoint();

if (error) {
  // handle error
} else {
  // handle data
}

GET requests

const response = await fetch("/user/12345");

const { ok, status } = response;

You can then handle the response if error is not ok or handle a success response.

Non-GET requests

Non-GET requests are quite similar to GET requests, but just like fetch, you will need to pass in the method option to fetch, like so:

const { status, error, data: user } = await gretch("/note/create", {
  method: "POST",
  json: {
    title: "Take over",
 text: "We are the world"
  }
}).json();

if (error) {
  // handle error
} else {
  // handle user
}

Internally, gretchen already resolved most of the boilerplate you’d encounter with fetch, like awaiting response and then converting to JSON like arrayBuffer, blob, formData, json, and text.

Other niceties

Automatically retrying some failed requests

By default, gretchen will retry GET requests that return 408, 413, or 429 two times. Failure can occur due to network issues or server load. This gives you the flexibility to retry these requests, and you can, of course, override the default number of retries like so:

await gretch("/notes", {
  method: "POST",
  retry: {
    attempts: 9, // number of retry
    methods: ["POST"]
  }, 
  json: {
        title: "Take over",
       text: "We are the world"
  }
}).json();

Handling request timeouts

This is similar to retrying a request. A request is timed out by default after 10 seconds. You can optionally configure the timeout time.

gretchen with TypeScript

You can specify the type of both your error and response. This is straightforward with the generic interface that gretchen allows.

The typing in the gretchen source code looks something like this:

gretch<T = DefaultGretchResponse, A = DefaultGretchError>

You will notice that a default response and error type are included, hence, you can pass your error and data response type in the same manner. For instance:

interface Note {
id: number
author: string
title: string
text: string
}
interface CustomError {
  message: string
code: number
};

const { error, data } = await gretch<Note, CustomeError>(
  "/note/1"
).json();

Tying this together, you should have a robust response-error handling that looks like this:

interface Note {
id: number
author: string
title: string
text: string
}
interface CustomError {
  message: string
code: number
};

const { error, data } = await gretch<Note, CustomeError>(
  "/note/1"
).json();

error ? handleError() : handleSuccess()

In conclusion

But why gretchen, I hear you ask? We already have similar abstractions that do similar jobs. That is not entirely true. gretchen goes a few steps further by allowing type-safe fetching by providing a very subtle abstraction over the already popular fetch syntax that you already know and love.

Additionally, gretchen makes it easy to elegantly type both the expected data and any errors that might occur. This might not seem important at first, but as your application grows in complexity, the ability to safely type your API response goes a long way in providing clarity to any client consuming them.