Simple React Hooks Fetcher Library

A type-safe simple and lightweight fetch wrapper for React.js applications with convenient functions for crafting & handling a request.

Installation

1npm install @oaktree/react-fetcher

Quick Start

1// fetcher.js
2import { createFetcher } from "@oaktree/react-fetcher";
3
4const fetcher = createFetcher({
5  baseUrl: "https://myapi.com/v3/",
6  headers: () => ({
7    Authorization: `Bearer ${localStorage.getItem("token")}`,
8    // ...
9  }),
10});
11
12export default fetcher;

1// App.js
2
3...
4import fetcher from "./fetcher";
5
6export default function App() {
7  const posts = fetcher.useQuery("posts")
8
9  return (
10    ...
11    {posts.data.map(post => ...)}
12    ...
13  )
14}

API Reference

Methods

request

1async request<T>(
2  url: string,
3  opts: {
4    headers?: { [key: string]: string },
5    method?: "POST" | "GET" | "DELETE" | "PATCH" | "PUT",
6    body?: any,
7    params?: { [key: string]: any },
8  }
9): Promise<{
10    data: null | T,
11    error: null | {
12      status: number,
13      fetchResponse: Response | null,
14      data: T,
15    }
16  }>

• url (string): The URL path for the request.
• opts (optional object): Request options.
  • method (string): The HTTP method for the request (default: "GET").
  • headers (object): Headers to be included in the request.
  • body (any): The request body.
  • params (object): Query parameters to be included in the request.

Returns an object with data and error properties.

useQuery

1useQuery<T>(
2  url: string,
3  opts?: {
4    onSuccess?: (data: T) => void,
5    onError?: ({
6      status: number,
7      fetchResponse: Response | null,
8      data: T,
9    }) => void,
10    onLoadingStart?: () => void,
11    onLoadingEnd?: () => void,
12    headers?: { [key: string]: any },
13    method?: "POST" | "GET" | "DELETE" | "PATCH" | "PUT",,
14    params?: { [key: string]: any },
15  }
16): {
17    data: null | T,
18    error: null | {
19      status: number,
20      fetchResponse: Response | null,
21      data: T,
22    },
23    isLoading: boolean,
24    isError: boolean,
25    refetch: (params?: { [key: string]: any }) => Promise<{
26      data: null | T,
27      error: null | {
28        status: number,
29        fetchResponse: Response | null,
30        data: T,
31      },
32    }>,
33  }

• url (string): The URL path for the query.
• opts (optional object): Query options.
  • headers (object): Headers to be included in the request.
  • method (string): The HTTP method for the request (default: "GET").
  • params (object): Query parameters to be included in the request.
  • onLoadingStart (function): Callback function triggered when the request starts loading.
  • onLoadingEnd (function): Callback function triggered when the request finishes loading.
  • onError (function): Callback function triggered when an error occurs.
  • onSuccess (function): Callback function triggered when the request is successful.

Returns an object with the following properties:

• data (null | T): The query response data.
• error (object): The query response error.
• refetch (function): Function to manually trigger the query.
• isLoading (boolean): Indicates if the query is currently loading.
• isError (boolean): Indicates if the query encountered an error.

useMutation

1useMutation<T>(
2  url: string,
3  opts?: {
4    onSuccess?: (data: T) => void,
5    onError?: ({
6      status: number,
7      fetchResponse: Response | null,
8      data: T,
9    }) => void,
10    onLoadingStart?: () => void,
11    onLoadingEnd?: () => void,
12    headers?: { [key: string]: any },
13    method?: "POST" | "GET" | "DELETE" | "PATCH" | "PUT",,
14    params?: { [key: string]: any },
15  }
16): {
17    data: null | T,
18    error: null | {
19      status: number,
20      fetchResponse: Response | null,
21      data: T,
22    },
23    isLoading: boolean,
24    isError: boolean,
25    mutate: (body: any, params?: { [key: string]: string }) => Promise<{
26      data: null | T,
27      error: null | {
28        status: number,
29        fetchResponse: Response | null,
30        data: T,
31      },
32    }>,
33  }

• url (string): The URL path for the mutation.
• opts (optional object): Mutation options.
  • headers (object): Headers to be included in the request.
  • method (string): The HTTP method for the request (default: "POST").
  • params (object): Query parameters to be included in the request.
  • onLoadingStart (function): Callback function triggered when the request starts loading.
  • onLoadingEnd (function): Callback function triggered when the request finishes loading.
  • onError (function): Callback function triggered when an error occurs.
  • onSuccess (function): Callback function triggered when the request is successful.

Returns an object with the following properties:

• data (null | T): The mutation response data.
• error (object): The mutation response error.
• mutate (function): Function to manually trigger the mutation.
• isLoading (boolean): Indicates if the mutation is currently loading.
• isError (boolean): Indicates if the mutation encountered an error.

Creating Fetcher Instances

createFetcher

1createFetcher(opts: FetcherInit): Fetcher

• opts (object): Options for creating the Fetcher instance.
  • baseUrl (string): The base URL for the API.
  • headers (optional function): A function that returns an object containing headers to be included in the requests.

Returns a new instance of the Fetcher.