Skip to main content
Version: 2.x.x

Builder

Builder

Read the API Reference »

---

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({ url: "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.

We can modify received data with this interceptor before it will be emitted to other sub-systems.

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;
  cache: (builder: B) => C;
  client: (command: CommandInstance, requestId: string) => Promise<ClientResponseType<any, any>>;
  fetchDispatcher: (builder: B) => D;
  submitDispatcher: (builder: B) => D;
  url: string;
}