fetch-run

Fetch middleware for the modern minimalist.

• Install
• Usage
• Middlewares
  • Before/after concept
  • Execution order (LIFO)
• Http flavour
• API
• Included middleware
  • HTTP error
  • HTTP error (Metro bundler)
  • Log requests & responses (DEV)
  • XSRF-TOKEN cookie (CSRF)

Install

yarn add fetch-run

Usage

import { Api } from 'fetch-run';
import * as uses from 'fetch-run/use';

const api = Api.create('https://example.org/api/v1');

if (__DEV__) {
  api.use(uses.logger);
}

api.use(uses.error);

// Later in app
type LoginRes = { token: string };
type LoginReq = { email: string; password };
type User = { id: number; name: string };

api.post<LoginRes, LoginReq>('login', data);

api.get<User>(`users/${id}`).then((user) => {});

api.search<User[]>('users', { firstName: 'John' }).then((users) => {});

Middlewares

A simple implementation of the middleware pattern. It allows you to modify the Request object before your API call and use the Response object right after receiving the response from the server.

Here are some examples/implementations of the middleware pattern:

• Using Express middleware
• Middleware - Laravel
• Middleware - Redux

A good way to visualize the middleware pattern is to think of the Request/Response lifecycle as an onion. Every middleware added to the stack being a new onion layer on top of the previous one.

Every middleware takes a Request in and must give a Response out.

type Layer = (req: Request) => Promise<Response>;

type Middleware = (next: Layer) => Layer;

// src/http/my-middleware.ts

export const myMiddleware: Middleware =
  (next: Layer) => async (req: Request) => {
    // Before

    const res: Response = await next(req);

    // After

    return res; // Response
  };

Before/after concept

Let's write a simple middleware that remembers an "access token" and sets a "Bearer header" on the next Request once available.

// src/http/access-token.js

let accessToken;

export default (next) => async (req) => {
  //
  // BEFORE
  // Modify/Use Request
  //

  if (accessToken) {
    req.headers.set('Authorization', `Bearer ${accessToken}`);
  }

  const res = await next(req);

  //
  // AFTER
  // Modify/Use Response
  //

  if (res.access_token) {
    accessToken = res.access_token;
  }

  return res;
};

Execution order (LIFO)

Since everything is a middleware, the order of execution is important.

Middlewares are executed in LIFO order ("Last In, First Out").

Everytime you push a new middleware to the stack, it is added as a new onion layer on top of all existing ones.

Example

api.use(A);
api.use(B);

Execution order:

1. B "Before" logic
2. A "Before" logic
3. (actual fetch call)
4. A "After" logic
5. B "After" logic

Note: B is the most outer layer of the onion.

Http flavour

The library also exports an Http flavour that does not transform the Response to JSON.

import { Http } from 'fetch-run';

const http = new Http('https://example.org');

http.use(error);

http.get('index.html').then((res: Response) => {
  // https://developer.mozilla.org/en-US/docs/Web/API/Response
  res.blob();
  res.formData();
  res.json();
  res.text();
  // ...
});

API

constructor(baseUrl: string, defaultOptions?: RequestInit)

Creates a new instance of Api or Http.

const api = new Api('', { credentials: 'include' });

const http = new Http('https://example.org', {
  mode: 'no-cors',
  headers: { 'X-Foo': 'Bar' },
});

static create(baseUrl?: string, defaultOptions?: RequestInit)

Alternative & convenient way for creating an instance.

const api = Api.create('', { credentials: 'include' });

const http = Http.create('https://example.org', {
  mode: 'no-cors',
  headers: { 'X-Foo': 'Bar' },
});

Note

Api.create will add the following default headers:

{
  "Accept": "application/json",
  "Content-Type": "application/json"
}

new Api, new Http & Http.create do not.

use(middleware: Middleware)

Adds a middleware to the stack. See Middlewares and Execution order (LIFO) for more information.

type Layer = (req: Request) => Promise<Response>;
type Middleware = (next: Layer) => Layer;

get<Res>(path: string, options?: RequestInit)

Performs a GET request. If you need to pass query parameters to the URL, use search instead.

search<Res>(path: string, query: object, options?: RequestInit)

Performs a GET request with additional query parameters passed in URL.

post<Res, Req extends BodyData>(path: string, data?: Req, options?: RequestInit)

Performs a POST request.

type BodyData = FormData | object | void;

put<Res, Req extends BodyData>(path: string, data?: Req, options?: RequestInit)

Performs a PUT request.

patch<Res, Req extends BodyData>(path: string, data?: Req, options?: RequestInit)

Performs a PATCH request.

delete(path: string, options?: RequestInit)

Performs a DELETE request.

options?: RequestInit

All options are merged with the default options (constructor) and passed down to the Request object.

Included middleware

HTTP Error

• Catch HTTP responses with error status code (< 200 || >= 300 – a.k.a. response.ok)
• Create a custom err: HTTPError
• Set err.code = res.status
• Set err.message = res.statusText
• Set err.request = req
• Set err.response = res
• Throw HTTPError

import { error } from 'fetch-run/use';

api.use(error);

Later in app:

import { HTTPError } from 'fetch-run';

try {
  api.updateUser(123, { name: 'Tyron' });
} catch (err) {
  if (err instanceof HTTPError) {
    err.response.json(); //...
  } else {
    throw err;
  }
}

Note (order of execution)

All middlewares registered after the error middleware, will not be executed (error middleware throws).

This is why, for example, you need to register the logger middleware first, so it can log req & res before the error is thrown.

HTTP Error (Metro bundler)

The Metro bundler (React Native) fails with ENOENT error when throwing a custom Error:

Error: ENOENT: no such file or directory, open '<app-root>/HTTPError@http:/127.0.0.1:19000/node_modules/expo/AppEntry.bundle?platform=ios&dev=true&hot=false'

This is why we need to throw a "normal" Error and unfortunately not the custom HTTPError itself (yet?).

This prevents the use of instanceof HTTPError + requires to assert the type when using Typescript:

import { HTTPError } from 'fetch-run';

try {
  // ...
} catch (err: Error) {
  // if (err instanceof HTTPError) // Cannot...
  if (err.name === 'HTTPError') {
    // Assert type...
    (err as HTTPError).response.json(); // ...
  }
}

See source code for more details.

import { errorMetro } from 'fetch-run/use';

api.use(errorMetro);

Log requests & responses (DEV)

A simple Request & Response console logger for when you don't need (yet) the full Debug Remote JS capabilities.

import { logger } from 'fetch-run/use';

if (__DEV__) {
  api.use(logger);
}

// Note: To register before `error` middleware (throws)
// api.use(error)

Source code

XSRF-TOKEN cookie (CSRF)

For example when used with Laravel Sanctum.

• Get XSRF-TOKEN cookie value
• Set X-XSRF-TOKEN header

import { xsrf } from 'fetch-run/use';

api.use(xsrf);

Source code