Skip to main content

Builder


Introduction

Builder is a class that allows you to configure the connection to the server. It initializes the subsystems of the entire library - such as queues, caches, interceptors, and allows you to create, based on its settings, commands necessary to execute requests. In 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 the 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 of our application, which additionally facilitates the maintenance of tests by dividing the necessary configurations and types.


Purpose

  • Orchestration of the components and flow of the library
  • Creating commands to provide global setups and environment
  • Isolation from other builders and their events

Initialization

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

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

Setup of defaults

Due to the fact that the components in hyper fetch are created inside the builder, we can set global or default values for our system on it.

Command default setup

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

Client request options default setup

We can use the setRequestConfig method to specify the defaults for every request. This method is based on the builder typescript generic which allow you to pass any options you need for your client.


Features

Authentication

When we want to send authenticated request we have to setup the onAuth interceptor and setup the command with the auth option set to true.

Read More

Pre-Request Interceptor

When you need to use the pre-request interceptor to modify the command before it gets sent, you can use the onRequest builder method.

Post-Request Interceptors

There are several possibilities to intercept the response from command. You can do it with methods:

  • 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 the built in query params encoding function, you can modify it's options as you want or provide your own function.

You can change it's setup with setQueryParamsConfig method and options listed bellow.

Name Type Description
arrayFormat "bracket" | "index" | "comma" | "separator" | "bracket-separator" | "none" Array encoding type
arraySeparator string Array format separator
encode boolean Encode keys and values
skipEmptyString boolean Skip keys with empty string
skipNull boolean Skip keys with null values
strict boolean Strict URI encoding

To change the encoding function you can use setStringifyQueryParams method.

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

Header Mapper

By default header mapper behaves very simple. It checks for the content to be FormData or json, and provide correct headers to the request. You can do much advanced setups with the setHeaderMapper that allows you to define custom logic that will be triggered before every request made in the builder.

Payload Mapper

It's main default responsibility is to check if data is instance of FormData or not. Based on this details, we can stringify non-FormData values or just pass the FormData to the request to be made. This way file upload is supported out of the box.


Typescript

Builder has two generic types.

class Builder<GlobalErrorType, RequestConfigType>
  • GlobalErrorType defines the error type used in all of the commands it should consist of Error type and your default ServerErrorType. For the individual error types needed in some commands you can setup the LocalErrorType for each individual command.

  • RequestConfigType is the generic responsible for shaping the 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 builder.


FetchDispatcher

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


AppManager

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


CommandManager

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


LoggerManager

Handles the logging systems for debugging.


Parameters

Configuration options

Name Type Description
baseUrl string Url to your server
client ClientType Custom client initialization prop
isNodeJS boolean Disable the web event listeners and actions on window object
appManager (builder: B) => A Custom app manager initialization prop
cache (builder: B) => C Custom cache initialization prop
fetchDispatcher (builder: B) => D Custom fetch dispatcher initialization prop
submitDispatcher (builder: B) => D Custom submit dispatcher initialization prop