soFetch.

A concise HTTP client
optimised for JSON apis

A POST request using fetch:

1const newUser = {
2    name:"Regina George", 
3    email:"regina@massive-deal.com"
4}
5
6const response = await fetch("/api/users", {
7  method: "POST",
8  headers: {
9    "Content-Type": "application/json"
10  },
11  body: JSON.stringify(newUser)
12})
13
14const success = await response.json() as Success
15

The same POST request in soFetch:

1const newUser = {
2    name:"Regina George", 
3    email:"regina@massive-deal.com"
4}
5
6const success = await soFetch<Success>("/api/users", newUser)

Less Code.
More Fetch.

soFetch is a lightweight wrapper around the FetchAPI that reduces boilerplate, handles errors fluently and simplifies authentication.

Built for JSON

Defaults to JSON for both the request and the response

Fluent Error Handling

Makes it easy to handle multiple error codes, for a single request or globally

Easy Authentication

Includes helpers for most modern authentication methods

Build Multiple Clients

Configure several instances simultaneously to connect with multiple services

Handle Timeouts

Configurable timeouts with sensible defaults out of the box

🌱Install.

NPM:

1npm i @antoinette-agency/sofetch

PNPM:

1pnpm add @antoinette-agency/sofetch

Yarn:

1yarn add @antoinette-agency/sofetch

Bun:

1bun install @antoinette-agency/sofetch

⏩Quickstart.

A GET request looks like:

1const products = await soFetch<Product[]>("/api/products")

A POST request is just:

1const newUser = {
2    name:"Regina George", 
3    email:"regina@massive-deal.com"
4}
5const newUserResponse = await soFetch<NewUserResponse>("/api/users", newUser)
6

What about PUT, PATCH and DELETE?

1//A PUT request:
2const upsertUser = {
3    name:"Regina George",
4    email:"regina@massive-deal.com"
5}
6const successResponse = await soFetch.put<Success>("/api/users/1234", upsertUser)

1//A PATCH request:
2const updateUserEmail = {
3    email:"regina@massive-deal.com"
4}
5const successResponse = await soFetch.patch<Success>("/api/users/1234", updateUserEmail)
6

1//A DELETE request:
2await soFetch.delete("/api/users/1234")
3

⚠️Handling Errors.

SoFetch has lots of options to help you handle errors flexibly. A soFetch request returns an await-able promise, so if you want to handle any kind of error it's just:

1const result = await soFetch("/api/unicorns/1234").catch((e:any) => {
2    console.error(e)
3    alert("An unexpected error occurred")
4})

But what if you wanted to handle a specific error like a 404 - Not Found? In that case you can use .catchHttp() like this:

1const result = await soFetch("/api/unicorns/1234").catchHttp(404, (r:Response) => {
2    alert("This unicorn could not be found.")
3})

You can even chain .catchHttp() statements together:

1const result = await soFetch("/api/unicorns/1234")
2.catchHttp(404, (r:Response) => {
3    alert("This unicorn could not be found.")
4})
5.catchHttp(419, (r:Response) => {
6    alert("This unicorn has expired.")
7})
8.catch((e:any) => {
9    //This code will execute if the HTTP response code is not 404 or 419:
10    alert("An unexpected error occurred")
11})
12

Global Error Handlers.

You might find that you want to use the same error handler for all statuses of a certain type. For example, you might want all 401 - Unauthorized responses to redirect the user to a login page. To do that you can add an error handler to thesoFetch.config like this:

1soFetch.config.catchHttp(401, (res:Response) => {
2    window.location.href = "/login";
3})