Galaxis Fetch

A Galaxis network interface that uses Fetch API, extended with types and custom body data.

Installation

yarn add @galaxis/fetch

You need to install Galaxis Core as well, directly or indirectly.

The library is compiled to modern JS, but it should work in all reasonable browsers with the help of properly configured Babel.

Public API

⚠ Anything that is not documented here is not considered a part of public API and may change at any time.

request()

Returns a request function that can be used in query or mutation.

const query: AppQuery = {
    requestParams: { foo: 'foo' },
    request: request({ processResponse, root, fetch }),
};

Arguments

RequestOptions

Name	Type	Description	Required
processResponse	(response: Response) => TData	A function that takes Response and returns request data or throws an error, preferably the ResponseError.	Yes
root	string	A URL part that is common for all requests, e.g. 'https://jsonplaceholder.typicode.com'.	No
fetch	typeof fetch	fetch function to use instead of built-in fetch.	No

Return value

(resource: FetchResource, abortSignal?: AbortSignal) => Promise<TData>;

requestId()

Returns a requestId function that can be passed to the Client. Generates request id in the form of [url]:[resource-hash].

const client = new Client({
    cache: new MyCache(),
    requestId: requestId({ hash }),
});

Arguments

RequestIdOptions

Name	Type	Description	Required
hash	(resource: FetchResource) => string	A function that takes hash from a FetchResource object.	Yes

Return value

(resource: FetchResource) => string;

processResponseJson()

This function can be used as processResponse parameter for the request() function.

It expects the Response to be in JSON format. If response code is not in 200-299 range, it throws a ResponseError.

CustomData

This is an abstract class for representing formats of data that are not natively supported by Fetch API. A CustomData instance has the following fields:

Name	Type	Description
data	T	Some data.
contentType	string	Value for the Content-Type header.
serialize	() => string	A function that serializes internal data field to string.

JsonData

This class implements CustomData and allows usage of JSON.

const jsonData = new JsonData({ foo: 'foo' });

ResponseError

This constructor should be used to throw an error during response processing.

throw new ResponseError(response, code, message);

Arguments

Name	Type	Description	Required
response	T	Some data associated with the response, usually response body.	Yes
code	number	Response code.	Yes
message	string	Human-readable error message for development purposes.	No

Return value

Extends Error.

Name	Type	Description
name	string	Always has a value of 'ResponseError'.
code	number	Response code.
response	T	Some data associated with the response, usually response body.

Important types

Constraints

Name	Type	Description
PathConstraint	Record<string, string | number>	Path parameters.
QueryConstraint	StringifiableRecord	Query parameters.
HeadersConstraint	HeadersInit	Headers.
BodyConstraint	CustomData | BodyInit | null	Body.

FetchVariablesConstraint

Name	Type	Required
pathParams	PathConstraint	No
queryParams	QueryConstraint	No
headers	HeadersConstraint	No
body	BodyConstraint	No

FetchVariables

It's a generic that takes the given type T, which is constrained by FetchVariablesConstraint, and adds fields from RequestInit, omitting body and headers. RequestInit comes from Fetch API.

It describes the part of resource that is dynamic. Note how all fields are optional by default.

export type FetchVariables<T extends FetchVariablesConstraint = FetchVariablesConstraint> = T &
    Omit<RequestInit, 'body' | 'headers'>;

FetchResource

It's just an intersection of FetchVariables and Resource.

Note that the name field (that came from Resource) represents the path to the given resource, e.g. '/entity/:id'. It is processed by path-to-regexp.