Request

Request

Read the API Reference »

---

Introduction

Request is a class that creates a template for requests and all the necessary information needed for their creation. Its strength is its strict and predictable data structure. This lets us dump data, save it to storage as a JSON, and recreate it later. This approach allows you to develop a full persistence flow; you can easily persist request dumps between sessions.

Request contains information about its behavior in the queues or cache, data on the server, and information necessary to execute a valid request. In combination with TypeScript, this results in a very friendly flow that’s resistant to mistakes.

You can trigger a request with the send method, which adds a request to the queue and returns the response.

---

Purpose

• Configures request templates
• Standardizes the system’s data schema
• Sends requests via dispatchers

---

Initialization

Request should be initialized from the Client instance with createRequest method. This passes a shared reference to the place that manages communication in the application.

caution

Hyper Fetch currently uses currying in the createRequest method to achieve auto-generated types for the endpoint string. This solution will be changed once this TypeScript issue is resolved.

import { client } from "./client";

export const getUsers = client.createRequest<UserModel[]>()({
  method: "GET",
  endpoint: "/users",
});

export const getUser = client.createRequest<UserModel>()({
  method: "GET",
  endpoint: "/users/:userId",
});

export const postUser = client.createRequest<UserModel, UserPostDataType>()({
  method: "POST",
  endpoint: "/users",
});

export const patchUser = client.createRequest<UserModel, Partial<UserPostDataType>>()({
  method: "PATCH",
  endpoint: "/users/:userId",
});

export const deleteUser = client.createRequest<null>()({
  method: "DELETE",
  endpoint: "/users/:userId",
});

---

Request building

Initialize

The process begins with request initialization. At this point, you can configure how the request will behave, but most of the configurations are optional. You can also prepare a global configuration in the Client and avoid copying the setup between requests.

const postUser = client.createRequest<null>()({
  endpoint: "/some-endpoint",
  headers: {},
  auth: true,
  method: "POST"
  cancelable: false,
  retry: 2,
  retryTime: 1000,
  cache: false,
  cacheTime: 50000
  queued: false,
  deduplicate: false,
  offline: false,
  options: {}, // Adapter options
  disableRequestInterceptors: false,
  disableResponseInterceptors: false,
});

Request Data

Use the setData method to instruct any data to be sent to the server.

// Regular data
postUser.setData({ name: "John", age: 18 })

// Form data
const data = new FormData();
...
postFile.setData(data)

Parameters

Parameters must be defined in request endpoint using :

const getNote = client.createRequest()({
  endpoint: "/note/:noteId";
})
const getCategory = client.createRequest()({
  endpoint: "/category/:categoryId";
})
const getCategoryNote = client.createRequest()({
  endpoint: "/category/:noteId";
})

When you have properly prepared requests that expect parameters, you can add parameters using the setParams method. In generic TypeScript, these parameters will match the endpoint parameters by using literal types and will require literal types.

getNote.setParams({ noteId: 1 });
getCategory.setParams({ categoryId: 2 });
getCategoryNote.setParams({ categoryId: 2, noteId: 1 });

Query parameters

You can set query params with the setQueryParams method. With TypeScript, you can set it up to be accepted as strings, objects, or a strict interface. The encoding type for arrays and other options can be set up in the Client. You can also provide your own encoding logic.

getUsers.setQueryParams({ search: "John", sort: "age" });

Trigger request

You can perform a request with the send method.

// Simple Send
getNotes.send();

// Chained Send
getUsers.setQueryParams({ search: "John", sort: "age" }).send();

// Multiple chained Send
getCategory.setParams({ categoryId: 2 }).setQueryParams({ sortNotes: "age" }).send();

For usage with React checkout our hooks docs.

---

Features

You can read more in the API reference and guides.

Cancellation

Queueing

Offline

Deduplication

Authentication

Data Mapping

---

Methods

Using methods on a request is different from other classes in Hyper Fetch. This is to ensure isolation between different uses, which allows you to avoid overwriting previously-prepared requests and to dynamically generate keys for queues or the cache.

danger

Using any method on request returns its clone! We don't return a reference!

// ❌ WRONG

const request = getUser;

request.setParams({ userId: 1 }); // Returns CLONED request with assigned params

request.send(); // Server error - no params

// ✅ Good

const request = getUser;

const requestWithParams = request.setParams({ userId: 1 }); // Returns CLONED request with assigned params

requestWithParams.send(); // Success

---

Keys

Each request gets its identifiers – queueKey, cacheKey, abortKey, and effectKey. They are needed to determine under which key items will be cached, queued, canceled or handled by Effects. By default, keys are auto-generated based on the current parameters and endpoint and method values. However, you can overwrite these values with other methods as needed.

---

Typescript

Client has four generic types built in: Response, Payload, Local Error Response, and QueryParams.

type Response = { name: string }; // What's returned from request
type Payload = { email: string }; // What's send with request
type LocalError = { nameMessage: string }; // Additional "local" errors like errors for particular form
type QueryParams = { sort: string; search: string }; // Query params interface

const someRequest = client.createRequest<Response, Payload, LocalError, QueryParams>()({
  endpoint: "category/:categoryId",
});

someRequest.setData(); // Require the 'Payload' type
someRequest.setParams(); // Require { categoryId: Param } type
someRequest.setQueryParams(); // Require the 'QueryParams' type

const [data, error] = someRequest.send();

data; // Has 'Response' type
error; // Has 'GlobalError' or 'LocalError' type

---

Parameters

Configuration options

{
  abortKey: string;
  auth: boolean;
  cache: boolean;
  cacheKey: string;
  cacheTime: number;
  cancelable: boolean;
  deduplicate: boolean;
  deduplicateTime: number;
  disableRequestInterceptors: boolean;
  disableResponseInterceptors: boolean;
  effectKey: string;
  endpoint: GenericEndpoint;
  garbageCollection: number;
  headers: HeadersInit;
  method: RequestMethods;
  offline: boolean;
  options: AdapterOptions;
  queueKey: string;
  queued: boolean;
  retry: number;
  retryTime: number;
}