@stripezilla/utils

Overview

@stripezilla/utils is a module designed to enhance the developer experience by providing common reusable functions, saving developer time and reducing code repetition across your projects.

Features

1. fetchApi
   • Key Features
   • Benefits
   • Setup
   • Usage
   • Overwrite the default error handlers for specific cases
     • Skip error handling
     • Execute custom error handler
     • Execute the default error handler if the custom handler fails
   • customGlobalErrorHandler example code
   • Type reference
2. Hooks
   • useLoader

fetchApi

fetchApi is a robust wrapper around the native fetch function that simplifies error handling and improves the overall API interaction process.

Key Features

• Centralized Error Handling: Configure 401 handler and other error responses for a wide range of HTTP status codes (e.g., 401, 403, etc) in one place. This saves time and ensures consistency across your application.
• Customizable Global Error Handlers: Overwrite or partially overwrite the default global error handler using customGlobalErrorHandler. For instance if you want to display error message coming from an api instead of predefined error messages based on error status code.
• Customizable Error Handlers: Overwrite or partially overwrite the default error handlers for specific cases by passing errorHandler as a props to useFetchApi methods. For instance, when checking if a username exists, a 404 error can be handled differently to indicate that the absence of a username is expected. Example code for reference
• Reusable Base Request Config: Define shared settings like credentials: 'include', custom headers, or other fetch options once using baseFetchRequestInit. These defaults are automatically merged into every API call, reducing repetition and ensuring consistent request behavior across your application.
• Aborted Requests: Automatically abort API requests when the user navigates to a different page, preventing irrelevant notifications from appearing in the new context.

Benefits

• Time-Saving: Avoid the repetitive task of writing error handling code for each API call. This is especially useful in larger projects where maintaining consistency can be challenging.
• Reduced Code Duplication: Keep your codebase clean and maintainable by centralizing error handling logic.

Note: Support for handling parallel multiple API error cases will be added in future!

Setup

1. Create a provider component for fetch api and provide the props of type FetchContextType:

   • updateErrorNotification: Callback function to handle error handler return. You could use this to update global store to display centralized error.

   • cleanupErrorNotification: Call back function to cleanup error messages (from central store). You can pass () => {} if this task is not required.

   • handle401Response: Callback function to define what happens when an api returns 401. Ideally, we should navigate the user to login page. If you are providing customGlobalErrorHandler and want to handle 401 response there you can use () => {}.

   • customGlobalErrorHandler: Overwrite default global error handler. Can be customised to fall back to default global error handler as needed.

   • baseFetchRequestInit: shared fetch options to be merged with every request like credentials: 'include', headers etc.

   • errorMessageByStatus: overwrite partially or fully default error messages by status code

     Working example: https://github.com/abhishek-kumar2-TA/ta-template/blob/main/src/store/FetchContextProviderComponent.tsx

Usage

useFetchApi provides fetchDataRaw, fetchDataJson, fetchDataText which you can use to make the api calls as needed.

const { fetchDataRaw, fetchDataJson, fetchDataText } = useFetchApi();

fetchDataJson: automatically sets header content-type: application/json and performs response.json() if api succeeds. Returns either null (error scenario) or FetchParsedBody.

fetchDataText: automatically sets header content-type: text/plain and performs response.text() if api succeeds. Returns either null (error scenario) or FetchParsedBody.

fetchDataRaw: returns either null or Response object. Use this when your content-type is neither application/json or text/plain.

The difference in syntax is very small in terms of usability. For ex:

| | fetch | fetchDataRaw (fetchApi) | fetchDataJson (fetchApi) | | --- | ------------------------------------- | --------------------------------------------------- | ---------------------------------------------------- | | Get | const res = fetch('https://api.example.com/data');if (res.ok) {const resData = await res.json();console.log(resData)} | const res = await fetchDataRaw({url: 'https://api.example.com/data'});if (res) {const resData = await res.json();console.log(resData)} | const res = await fetchDataJson({url: 'https://api.example.com/data'});if (res) {console.log(res.body);} | |GET with Request config | const res = fetch('https://api.example.com/data', { headers: { 'Content-Type': 'text/plain' } }) // process same as get | const res = fetchDataRaw({ url: 'https://api.example.com/data', fetchRequestInit: { headers: { 'Content-Type': 'text/plain' } }}) // process same as get|const res = fetchDataJson({ url: 'https://api.example.com/data', }) // process same as get| |POST | const res = fetch('https://api.example.com/data', method: 'POST', { headers: { 'Content-Type': 'application/json' } }, body: JSON.stringify({ name: 'John Doe' }) ) // process same as get | const res = fetchDataRaw({ url: 'https://api.example.com/data', fetchRequestInit: { method: 'POST', { headers: { 'Content-Type': 'application/json' } }, body: JSON.stringify({ name: 'John Doe' }) }}) // process same as get| const res = fetchDataJson({ url: 'https://api.example.com/data', fetchRequestInit: { method: 'POST', body: JSON.stringify({ name: 'John Doe' }) }}) // process same as get|

Other methods like PUT or DELETE will work similarly.

fetchDataText: works similar to fetchDataJson but for content-type: text/plain

Overwrite the default error handlers for specific cases

Skip error handling

Execute custom error handler

Execute the default error handler if the custom handler fails

Add return {message: ''} at the end of errorHandler. This will inform fetchApi to execute default error handler if custom error handler did not handled the current error status.

customGlobalErrorHandler example code

const customGlobalErrorHandler = (error: FetchParsedError) => {   // if status code is 400 and error body has error message to be displayed, handle the error   if(error.status === 400 && error.body.notification.message) {     return {message: error.body.notification.message} // you can also set title and meta if needed   // if status code is 500 or 502, fall back to default global error handler   } else if (error.status === 500 || error.status === 502) {     return { message: '' };   }   // for void return no further error handler will be performed };

Type reference

Type reference for useFetchApi

export interface FetchErrorMeta {   message: string;   title?: string;   meta?: any; }

Hooks

useLoader

useLoader is a custom hook designed to manage loading states more effectively during API calls.

Key Features:

• Threshold Loading Time: Ensures the loading state is true for a minimum threshold duration (default: 400ms). This prevents flickering when API calls return quickly.
• Enhanced User Experience: Provides a more polished user experience by displaying a loader overlay consistently, improving accessibility and reducing abrupt visual changes.

Benefits:

• Improved Accessibility: By maintaining the loading state for a minimum time, users are better informed about ongoing processes, making the application more user-friendly.