Skip to main content

Builder


Introduction

Builder is a class that allows you to configure the server connection. It initializes the entire library’s subsystems, such as queues, caches, and interceptors. It also allows you to create (based on its settings) the commands necessary to execute requests. This way the data and information flow remains locked inside a given builder; it is isolated and does not affect other builders.

It was designed to be used as a singleton, where Builder helps us create a global structure for making server requests without duplicating logic in different parts of the application. In this approach, we can easily create a solid structure and architecture for an application. This also facilitates test maintenance by dividing the necessary configurations and types.


Purpose

  • Orchestrates the components and flow of the library
  • Creates commands to provide global setup and environment
  • Isolates builders from other builders and their events

Initialization

import { Builder } from "@hyper-fetch/core";

export const builder = new Builder({ baseUrl: "http://localhost:3000" });

Setting defaults

Because Hyper Fetch components are created inside Builder, you can set global or default system values on it.

Command default setup

We can use the setCommandConfig method to specify the defaults for every created command.


Features

Authentication

To send authenticated requests, set up the onAuth interceptor. Set up the command with the auth option set to true. Read more about authentication here.

Read More

Pre-Request Interceptor

Use the onRequest builder method if you need to use the pre-request interceptor to modify the command before it’s sent.

Post-Request Interceptors

There are several methods for intercepting a response from a command:

  • onError which is triggered on request error response.
  • onSuccess which is triggered on request success response.
  • onResponse which is triggered on any response.

Query Params

Builder has a built-in query params encoding function; you can modify its options or provide your own function. Use the setQueryParamsConfig method and the options listed below.

{
arrayFormat: bracket | index | comma | separator | bracket-separator | none;
arraySeparator: string;
encode: boolean;
skipEmptyString: boolean;
skipNull: boolean;
strict: boolean;
}

To change the encoding function, use the setStringifyQueryParams method.

builder.setStringifyQueryParams((value: string) => encode(value));

Header Mapper

By default, the header mapper behaves very simply: it checks if the content is FormData or JSON, and provides correct headers to the request. You can create much more advanced setups with the setHeaderMapper. It allows you to define custom logic that will be triggered before every request made in the builder.

Payload Mapper

The payload mapper’s default responsibility is to check if data is an instance of FormData or not. Based on this, you can stringify non-FormData values or just pass the FormData to the request to be made. This allows file upload to be supported out of the box.


Typescript

Builder has two generic types.

class Builder<GlobalErrorType, RequestConfigType>
  • GlobalErrorType defines the error type used in all the commands. It should consist of an Error type and your default ServerErrorType. For some command’s individual error types, you can set up a LocalErrorType for each command.

  • RequestConfigType is the generic responsible for shaping options passed to the client. Most likely you will change it only when you provide your custom client.


Components

Cache

Handles data storages and persistence. Can be adjusted with options when initializing Builder.


Client

Handles all requests within Builder. Can be replaced with setClient method.


SubmitDispatcher

Handles the mutation requests and queueing. Can be adjusted with options when initializing the builder.


FetchDispatcher

Handles the fetching requests and queueing. Can be adjusted with options when initializing the builder.


AppManager

Handles the app focus and online state. Can be adjusted with options when initializing the builder.


CommandManager

Handles additional events and cancellation of requests. Can be adjusted with options when initializing the builder.


LoggerManager

Handles the logging systems for debugging.


Parameters

Configuration options

{
appManager: (builder: B) => A;
baseUrl: string;
cache: (builder: B) => C;
client: (command: CommandInstance, requestId: string) => Promise<ClientResponseType<any, any>>;
fetchDispatcher: (builder: B) => D;
isNodeJS: boolean;
submitDispatcher: (builder: B) => D;
}