React API Loader

A lightweight, type-safe React library that abstracts API-related infrastructure code, significantly reducing component complexity. React API Loader provides centralized state management for API operations, enables request cancellation, and offers reusable UI components to simplify handling loading, error, and success states.

Installation

``bash


Using npm

2. Standard Example - A more comprehensive implementation that demonstrates:
- Recommended folder structure for larger applications
- Integration with global state management
- The useMessage hook for centralized error handling
- Styling and UI component organization
- Authentication flow integration

The examples below are based on the minimal implementation. For more advanced patterns, explore the standard example in the repository.

$3

First, import the library and define your client and error types:

`typescript
import {
type AppKey,
type ClientAdapter,
type ClientFactory,
createLoaderApi,
} from 'react-apiloader';

// Define the error type for your API
type ClientError = {
description: string | string[];
status?: number;
data?: unknown;
};

// Define your API client interface
interface IFetchClient {
get(url: string, params?: unknown, settings?: RequestInit): Promise;
post(url: string, data?: D, params?: unknown, settings?: RequestInit): Promise;
}

// Create your API loader context and extract the hooks you need
const {
createApiHook,
createApiHookWithState,
createApiHookWithExternalState,
LoaderContextProvider,
useLoaderInfo,
} = createLoaderApi();
`

$3

Create a client factory that returns a client implementation and its adapter:

`typescript
const createClientFactory =
(baseUrl: string): ClientFactory => () => {
const controller = new AbortController();

// Client implementation
const client: IFetchClient = {
get: async (url: string, params?: Record, settings?: RequestInit) =>
fetch(createUrl(url, params), {
method: 'GET',
headers: { 'Content-Type': 'application/json' },
signal: controller.signal,
...settings,
})
.then((response) => handleResponse(response)),

post: async (
url: string,
data?: D,
params?: Record,
settings?: RequestInit,
) => {
return fetch(createUrl(url, params), {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(data),
signal: controller.signal,
...settings,
})
.then((response) => handleResponse(response));
},
};

// Client adapter for handling cancellation and errors
const adapter: ClientAdapter = {
cancel: () => controller.abort(),
isCanceled: (error: unknown) => error instanceof DOMException && error.name === 'AbortError',
parseError: (error: unknown) => {
console.error('# ERROR #', error);
// Your error parsing logic
return {
description: (error as Error)?.message ?? 'Unknown error',
};
},
};

return [client, adapter];
};

// Create a client factory instance
const clientFactory = createClientFactory('https://jsonplaceholder.typicode.com/');
`

$3

The library provides three types of API hooks for different use cases:

#### 1. createApiHook - Stateless Hook

For operations without internal state, like creating/updating resources:

`typescript
// Define a model for your data
interface TodoModel {
userId: number;
id: number;
title: string;
completed: boolean;
}

// Create a hook for saving todos
const useSaveTodo = createApiHook(
(http, params) =>
http.post(todos, params).then((data) => {
// Transform data if needed before returning
return data;
}),
);

// Usage in a component
const saveTodoApi = useSaveTodo();
const saveTodo = useCallback(
(todo: TodoModel) => {
// The second parameter sets the mode for parallel requests
void saveTodoApi(todo, todo.id)
.then((result) => {
if (result.isSuccess) {
console.log('Save success:', result.data);
} else if (result.isCanceled) {
console.log('Save canceled');
} else if (result.isError) {
console.log('Error saving:', result.error);
}
});
},
[saveTodoApi],
);
`

#### 2. createApiHookWithState - Hook with Internal State

For fetching data with internal state management:

`typescript
// Create a hook for fetching todos with internal state
const useGetTodos = createApiHookWithState(
(http, params) =>
http.get(todos, { userId: params.userId }).then((data) => {
// Transform data if needed
return data;
}),
undefined, // Initial state value
);

// Usage in a component
const [todos, getTodosApi] = useGetTodos();
const getTodos = useCallback(() => {
if (user) {
void getTodosApi({ userId: user.id });
}
}, [getTodosApi, user]);

// Call the API on component mount
useEffect(() => void getTodos(), [getTodos]);

// Render the data
return (


`typescript
interface UserModel {
id: number;
username: string;
}

// Using React's useState as an example of an external state
// In real apps, this could be a Redux store, Jotai atom, etc.
const useGetUser = createApiHookWithExternalState(
(http, params) => http.get(users, { id: params }).then((x) => x[0]),
useState, // External state hook
);

// Usage in a component
const [user, getUserApi] = useGetUser();
const getUser = useCallback(() => getUserApi(1), [getUserApi]);

// Call the API on component mount
useEffect(() => void getUser(), [getUser]);

// User state is automatically updated when API call succeeds
return

{'User: ' + (user?.username ?? 'Not found')}

`tsx
export type LoadingButtonProps = {
actionType: AppKey;
mode?: AppKey;
children: React.ReactNode;
disabled?: boolean;
onClick?: (e: React.MouseEvent) => void;
};

export const LoadingButton: FC = ({
actionType,
mode = undefined,
children,
disabled,
onClick,
}) => {
// Get the current state of the specified API call
const item = useLoaderInfo(actionType, mode);
const isDisabled = item?.isWaiting || disabled;
return (

{item?.isWaiting ? 'Loading...' : children}

);
};
`

#### RepeatPanel

A component that handles loading, error, and success states:

`tsx
interface RepeatPanelProps {
actionType: AppKey;
mode?: AppKey;
action: () => void;
children: React.ReactNode;
}

export const RepeatPanel: FC = ({ actionType, mode, action, children }) => {
// Get the current state of the specified API call
const item = useLoaderInfo(actionType, mode);

if (item?.isWaiting) return

return <>{children};
};
`

$3

Wrap your application with the LoaderContextProvider:

`tsx
// Root component
const App = () => {
// Your application components
return

React API Loader Example

// Render with the provider
ReactDOM.createRoot(document.getElementById('root') as Element).render(






,
);
`

$3

Here's a complete example showing how everything works together:

`tsx
const App = () => {
// User data with external state
const [user, getUserApi] = useGetUser();
const getUser = useCallback(() => getUserApi(1), [getUserApi]);
useEffect(() => void getUser(), [getUser]);

// Todos with internal state
const [todos, getTodosApi] = useGetTodos();
const getTodos = useCallback(() => {
if (user) {
void getTodosApi({ userId: user.id });
}
}, [getTodosApi, user]);
useEffect(() => void getTodos(), [getTodos]);

// Stateless API for saving todos
const saveTodoApi = useSaveTodo();
const saveTodo = useCallback(
(todo: TodoModel) => {
void saveTodoApi(todo, todo.id)
.then((x) => {
if (x.isSuccess) {
console.log('Save success:', x.data);
} else if (x.isCanceled) {
console.log('Save canceled');
} else if (x.isError) {
console.log('Error saving todo:', x.error);
}
});
},
[saveTodoApi],
);

return (
<>


React API Loader Minimal Example

`tsx
function SearchComponent() {
const searchApi = useSearch();

// This will automatically cancel pending search requests
// when the component unmounts
useCancellation(useSearch.id);

// Component implementation
}
`

$3

Manually cancel API calls from anywhere:

`tsx
function SearchWithCancel() {
const searchApi = useSearch();
const cancelAction = useCancelAction();

return (


`tsx
// Create an interceptor
const clientInterceptorHook: ClientInterceptorHook = () => {
return (result) => {
// Log all API responses
console.log('API response:', result);

// Handle specific errors globally
if (result.isError && result.error.status === 401) {
// Redirect to login page or show an auth error
window.location.href = '/login';
}
// Show a toast notification for errors
const [addToast] = useToaster();
if (result.isError) {
addToast({
type: 'error',
message: result.error.description,
});
}
// Return the result to continue processing
return result;
};
};

// Provide the interceptor to the context
clientFactory={clientFactory}
clientInterceptorHook={clientInterceptorHook}>


`

$3

The mode parameter allows handling multiple concurrent API calls of the same type:

`tsx
// Create a stateless hook
const useSearchProducts = createApiHook(
(client, params) => client.get(/search?q=${params.query}),
);

function SearchPage() {
const searchApi = useSearchProducts();

// Execute multiple parallel searches with different modes
const searchBooks = () => searchApi({ query: 'books' }, 'books');
const searchMovies = () => searchApi({ query: 'movies' }, 'movies');

return (


License

MIT © Max Grekhov