@togglecorp/toggle-request v0.0.2

Toggle Request

A simple request library using react hooks

Features

• Typesafe
• Lightweight

Installation

npm install @togglecorp/toggle-request
// or
yarn install @togglecorp/toggle-request

API

The request library exposes two react hooks to execute a request.

1. useRequest
2. useLazyRequest

useRequest

useRequest will immediately execute the request when your component renders and returns the result that can be used to render the UI.

// Example usage

const {
    response,
    pending,
    error,
} = useRequest({
    url: `/projects/${id}/`,
    query: {
        limit: 12,
        offset: 1,
    },
    method: 'GET',
    skip: !id,
    onSuccess: (response) => {
        // NOTE: response from the server
        console.info(`Fetched ${response.total} items from server`);
    }
    onFailure: () => {
        console.error('Could not fetch items');
    }
})

The request options for useRequest are listed below:

The result for useRequest are listed below:

useLazyRequest

useLazyRequest will only execute the request once user calls the trigger function. When triggering the request, user can define a context value which can be used to define request options: url, query, body, method and other. If there is no context value, user should trigger the request passing null value.

// Example usage

const {
    response,
    pending,
    error,
    trigger,
} = useRequest({
    method: 'PUT',
    url: (ctx) => `/projects/${ctx.id}/`,
    body: (ctx) => ctx.body,
    onSuccess: (response) => {
        // NOTE: response from the server
        console.info(`Updated item ${response.name}`);
    }
    onFailure: () => {
        console.error('Could not update item');
    }
})

const handleSave = useCallback(
    (id, body) => {
        trigger({
            id,
            body,
        });
    },
    [trigger],
);

The request options for useLazyRequest are listed below:

The result for useLazyRequest are listed below:

RequestContext

The RequestContext uses React Context API to define configurations available throughout all the child components. The context defines transformer functions to transform request url, request option, response and error.

const requestContextValue = {
    transformUrl: transformProjectUrls,
    transformOptions: transformProjectOptions,
    transformResponse: transformProjectResponse,
    transformError: transformProjectError,
};

return (
    <RequestContext.Provider value={requestContextValue}>
        <ProjectApp />
    </RequestContext.Provider>
)

Partially defining types

import { Error, OptionBase } from './my-project-typings';

// eslint-disable-next-line
const useMyLazyRequest: <R, C = null>(requestOptions: LazyRequestOptions<R, Error, C, OptionBase>) => {
    response: R | undefined;
    pending: boolean;
    error: Error | undefined;
    trigger: (ctx: C) => void;
    context: C | undefined,
} = useMyLazyRequest;

const useMyRequest: <R>(requestOptions: RequestOptions<R, Error, OptionBase>) => {
    response: R | undefined;
    pending: boolean;
    error: Error | undefined;
    retrigger: () => void;
} = useMyRequest;

In the example above:

• OptionBase defines extra property passed to request hooks, that are available on transformer functions.
• Error defines the error type received from the server

Detailed API

Unfortunately, there is no detailed api documentation yet. Please refer to the source code.

Development

Running locally

# Install dependencies
yarn install

# Build
yarn build

Linting

# Eslint
yarn lint

# Typescript
yarn typecheck