Fetchy is a zero dependency wrapper for JavaScript's fetch method that automatically throws an error on non 200-300 statuses and accepts TypeScript generics for type-safe returns. It also provides error handling that allows you to easily execute different callbacks for different types of errors.
IMPORTANT: The library currently only handles responses with text or JSON (or no) content types. I'll be adding support for other content types in the future.
- Install the package with
npm i @gladknee/fetchy - Import the default fetchy export from the library.
- The fetchy object provides four functions for making requests:
get,post,put,delete. - A successful request returns a native
Responsewith an additionaldatakey containing any parsed JSON or text.
import fetchy from "@gladknee/fetchy"
// async await method
async function yourFunction() {
try {
const { data } = await fetchy.get("https://server.com/api/endpoint")
} catch (e: any) {}
}
// Chaining method
fetchy
.get("https://server.com/api/endpoint")
.then(({ data }) => {})
.catch((e: any) => {})type FetchyResponse<T> = Response & { data: T }
function get<T = any>(
url: string,
options?: Omit<RequestInit, "method">
): Promise<FetchyResponse<T>> {}
function post<T = any>(
url: string,
options?: Omit<RequestInit, "method">
): Promise<FetchyResponse<T>> {}
function put<T = any>(
url: string,
options?: Omit<RequestInit, "method">
): Promise<FetchyResponse<T>> {}
function delete<T = any>(
url: string,
options?: Omit<RequestInit, "method">
): Promise<FetchyResponse<T>> {}We have a User type and greetUser() function that accepts a User. We'll create a getUser() function that makes a GET request to fetch the user and pass it to the greetUser function.
type User = { id: number; name: string }
function greetUser(user: User) {
alert(`Hello ${user.name}`)
}
async function getUser() {
const { data } = await fetchy.get<User>("https://server.com/api/users/me", {
headers: { Authorization: "Bearer XXXXXX" },
})
return data
}
async function getAndGreetUser() {
try {
const user = await getUser()
greetUser(user)
} catch (e: any) {
// handle error
}
}Import the handleError function from the library. You can then call this function inside your catch block by passing two required parameters: the error and your error handling callback configuration.
import fetchy, { handleError } from "@gladknee/fetchy"
async function someRequest() {
try {
const { data } = await fetchy.get("https://server.com/api")
} catch (e: any) {
handleError(e, callbackConfig)
}
}async function getAndGreetUser() {
try {
const user = await getUser()
greetUser(user)
} catch (e: any) {
handleError(e, {
status: {
401: (e) => {
/* Do something if 401 response */
},
500: (e) => {
/* Do something if 500 response */
},
other: (e) => {
/* Do something on any other non 200-300 statuses */
},
all: (e) => {
/* Do something on any non 200-300 status */
},
},
})
}
}async function getAndGreetUser() {
try {
const user = await getUser()
greetUser(user)
} catch (e: any) {
handleError(e, {
body: {
fieldName: (e, value) => {
switch (value) {
case "SOME_VALUE":
// Do something if response includes { fieldName: "SOME_VALUE" }
break
case "SOME_OTHER_VALUE":
// Do something if response includes { fieldName: "SOME_OTHER_VALUE "}
break
default:
// Do something if response includes { fieldName: <anything else> }
}
},
},
})
}
}async function getAndGreetUser() {
try {
const user = await getUser()
greetUser(user)
} catch (e: any) {
handleError(e, {
client: {
fetch: (e) => {
/* Do something if fetch failed */
},
network: (e) => {
/* Do something if network error */
},
abort: (e) => {
/* Do something if user aborted */
},
security: (e) => {
/* Do something if security error */
},
syntax: (e) => {
/* Do something if syntax error */
},
all: (e) => {
/* Do something if any client-side error */
},
},
})
}
}async function getAndGreetUser() {
try {
const user = await getUser()
greetUser(user)
} catch (e: any) {
handleError(e, {
status: {
401: (e) => {
/* Do something if 401 response */
},
},
other: (e) => {
/* Do something if any other error is thrown */
},
})
}
}You can also execute a callback on any error. This will be executed along with any other triggered callbacks. So in this example, on a 401 or 409 error, the user is redirected and the error is logged.
async function getAndGreetUser() {
try {
const user = await getUser()
greetUser(user)
} catch (e: any) {
handleError(e, {
status: {
401: () => redirect("/auth"),
402: () => redirect("/upgrade"),
},
all: (e) => {
logError(e)
},
})
}
}NOTE: If multiple error handling conditions are triggered, each of their callbacks will be executed.
async function getAndGreetUser() {
try {
const user = await getUser()
greetUser(user)
} catch (e: any) {
handleError(e, {
status: {
401: () => redirect("/auth"),
},
body: {
errorMessage: (e, value) => {
switch (value) {
case "USER_NOT_ACTIVE":
alert("Your account is no longer active.")
break
default:
alert(`Error: ${value}`)
}
},
},
client: {
network: () => alert("There was a network error."),
},
all: (e) => logError(e),
})
}
}Here's the full type definition of a callback configuration:
type CallbackConfig = {
status?: {
[key: number]: (e?: any) => void
other?: (e?: any) => void
all?: (e?: any) => void
}
body?: {
[key: string | number]: (e?: any, value?: any) => void
}
client?: {
fetch?: (e?: any) => void
network?: (e?: any) => void
abort?: (e?: any) => void
security?: (e?: any) => void
syntax?: (e?: any) => void
all?: (e?: any) => void
}
other?: (e?: any) => void
all?: (e?: any) => void
}As you can see in the previous example, combining multiple types of error handling can lead to bulky code. One helpful tip is to separate out your error handling logic into their own object(s) and pass them in to your handleError callbacks.
Example:
const handleStatusErrors = {
401: () => router.push("/auth/signin"),
402: () => router.push("/upgrade"),
500: (e: any?) => logInternalServerError(e),
// ...etc
}
const handleClientErrors = {
fetch: () => alert("Please check your internet connection."),
network: () => alert("We experienced a network error. Please try again."),
}
const handleErrorMessages = (e: any, message: string) => {
switch (message) {
case "USER_NOT_FOUND":
alert("You do not have an account.")
break
case "USER_DEACTIVED":
alert("Your account has been deactivated.")
break
default:
alert(`Error: ${message}`)
}
}
function logError(e: any) {
// do something to log any errors
}
const myErrorHandlers = {
status: handleStatusErrors,
client: handleClientErrors,
body: {
errorMessage: handleErrorMessages,
},
all: logError,
}
async function someRequest() {
try {
const { data } = await fetchy.get("url")
} catch (e: any) {
handleErrors(e, myErrorHandlers)
}
}Fetchy works great with Tanstack Query. Below is a popular implementation.
export async function getUser() {
const { data } = await fetchy.get("https://server.com/api/users/me")
return data
}
export function SomeComponent() {
const { data, isError, error } = useQuery({
queryKey: ["yourkey"],
queryFn: getUser,
})
useEffect(() => {
if (isError) {
handleError(error, callbackConfig)
}
}, [isError, error])
}