Learn soFetch by example.

Basic Requests

A call to soFetch with a single string argument is a GET, so to get an array of type Product from the endpoint "/products" is just:

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

POST requests

A call to soFetch with a second argument is a POST request. If you wanted to upload a User to the endpoint "/users" and expect aNewUserResponse back, you could do:

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

What about PUT, PATCH and DELETE requests?

These are all supported:

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

Explicit GET and POST

If you prefer to explicitly label your GET and POST requests they follow the same pattern as PUT, PATCH and DELETE above:

1// soFetch<Product[]>("/products") is equivalent to:
2const products = await soFetch.get<Product[]>("/products")

1// soFetch<Success>("/api/users", someObject) is equivalent to:
2const success = await soFetch.post<Success>("/api/users", someObject)

Error Handling

soFetch is await-able so you can catch all asynchronous just like you would with a regular promise:

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

Catching specific HTTP errors

However, you'll likely come across situations where you want to handle a specific error. A common scenario would be to handle a 404 - NOT FOUND response from the server:

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

Handling multiple error types (handler-chaining)

If you want to handle specific errors in different ways you can chain your error handlers together, like this:

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

Note that if you want to catch all errors that weren't explicitly caught by a catchHttp() block you'll need to place the catch() method after the catchHttp()s

Global error handling

To use the same handler every time soFetch receives a specific error response code you can add a handler to the soFetch.config

1soFetch.config
2.catchHttp(401, (res:Response) => {
3    window.location.href = "/login";
4})
5.catchHttp(500, (res:Response) => {
6    alert("An unexpected error has occurred")
7})

Reading the server response.

Sometimes a server returns more information than just an error response code and there might be situations where you want to inspect the response body. How can you do this with soFetch? Helpfully, the response argument returned to a catchHttp() error handler is a regular Fetch API Response object, so you to get the response body you could do something like:

1const cat = {
2    whiskers:44
3    attitude:"Aloof"
4}
5await soFetch.post("/api/dogs", cat).catch(422, (r:Response) => {
6    const responseBody = await r.json()
7    if (responseBody == "Not a dog") {
8        alert("Please post dogs only")
9    } else {
10        throw new Error("Payload could not be processed")
11    }
12}

Authentication

soFetch has methods to help you authenticate using modern standards. Use the use...Authentication() config methods to configure authentication before you first call soFetch(). Optionally, you can use config.setAuthToken() to set an authentication token later, typically after a user login or token refresh.

1 Basic Authentication

Uses a Base64-encoded username:password string in the Authorization header.

1soFetch.config.useBasicAuthentication({
2    username:"Chris Hodges", 
3    password:"Antoinette"
4})

The example above will add the following header to all subsequent requests:

1Authorization:Basic Q2hyaXMgSG9kZ2VzOkFudG9pbmV0dGU

Where Q2hyaXMgSG9kZ2VzOkFudG9pbmV0dGU is a base-64 encoded concatenation of the username and password, separated by a colon.

Form more info on the Basic Authorization scheme check out the Mozilla Docs

2 Bearer Authentication

Bearer Authentication is the most common authentication scheme for websites where uses have to log in. It's the method used by OAuth 2.0 protected resources. Most modern APIs use bearer tokens.

1//First tell soFetch to use Bearer Authentication:
2soFetch.config.useBearerAuthentication()
3
4//Then, once the user has logged in and received a token you can pass the token to soFetch like this:
5soFetch.config.setAuthToken("SOME_ACCESS_TOKEN")
6

The above example will add the following header to each request but only after the setAuthToken() method has been called.

1Authorization:Bearer SOME_ACCESS_TOKEN

By default the bearer token will be persisted in Local Storage on the browser under the key SOFETCH_AUTHENTICATION. In Node the default behaviour is to hold the key in memory for subsequent requests but not persist the token beyond the lifetime of the soFetch instance.

See below for persistence options and how to change the name of the key

3 Setting an Authentication Token in a Custom Header

Some APIs require an API key in a custom header.

1soFetch.config.useHeaderAuthentication({
2    authToken:"HEADER_ACCESS_TOKEN",
3    headerKey:"custom-header-key"
4})

The above example will add the header custom-header-key:HEADER_ACCESS_TOKEN to all subsequent requests. By default the token will be persisted to local storage.

4 Adding an Authentication Token to the Query String

This method is not as secure, but still common.

1soFetch.config.useQueryStringAuthentication({
2    authToken:"ACCESS_TOKEN",
3    queryStringKey:"API-KEY",
4})

The above example will append a query string parameter with key API-KEY and value ACCESS_TOKEN to each subsequent request, e.g:

1https://api.example.com/data?API-KEY=ACCESS_TOKEN

5 Cookie-Based Authentication

Use this method if the server returns authentication cookies after you login.

1soFetch.config.useCookieAuthentication()

You can also set a cookie programmatically, but this will only be sent to the server if the currently loaded page and the API are served from the same domain.

1//Sets a cookie with key COOKIES_AUTH_KEY and value COOKIES_AUTH_TOKEN:
2soFetch.config.useCookieAuthentication({
3    authenticationKey:"COOKIES_AUTH_KEY"
4})
5soFetch.config.setAuthToken("COOKIES_AUTH_TOKEN")

These 5 methods cover the vast majority of real-world cases, but if your case doesn't quite fit, you could also use soFetch hooks.

Hooks

Hooks (a.k.a. event handlers or interceptors) allow you to read and modify requests and responses as they are sent to and received from a server.

beforeSend()

Lets you read and optionally modify a SoFetchRequest before it's sent to the server. If you return a SoFetchRequest from the handler, this modified request will be passed to the next handler and subsequently to the server.

You can add beforeSend() handlers per request...

1const resource = await soFetch("/some-resource").beforeSend((req:SoFetchRequest) => {
2    req.headers["test-header"] = "Some Value"
3    return req //Remember to return the request if you want to modify it
4})

or on every request via the config:

1soFetch.config.beforeSend((req:SoFetchRequest) => {
2    req.headers["test-header"] = "Some Value"
3    return req
4})
5const resource = await soFetch("/some-resource")

Both the examples above will add a custom header to the request with key test-header and value Some Value

beforeFetchSend()

If you're modifying a request before it's sent you'll normally just want to modify the URL, body or headers. But there might be occasions where you want access to the Fetch API RequestInit object itself. For that you can use the beforeFetchSend() hook, which fires after the beforeSend() hook.

You can add beforeFetchSend() handlers per request...

1const resource = await soFetch("/some-resource").beforeFetchSend((req:RequestInit) => {
2    req.cache = 'reload'
3    return req //Remember to return the request if you want to modify it
4})

or on every request via the config:

1soFetch.config.beforeFetchSend((req:RequestInit) => {
2    req.cache = 'reload'
3    return req
4})
5const resource = await soFetch("/some-resource")

onRequestComplete()

A call to soFetch() will make a request and serialise the response all in one go, so how would you access the full Fetch Response if you wanted to read a response header for example? You'd use the onRequestComplete() hook, like this:

1let pagesTotal = 0
2const posts = await soFetch("/wp-json/wp/v2/posts").onRequestComplete((response:Response) => {
3    postsTotal = parseInt(response.headers.get('X-WP-Total'))
4})

File Upload

Most modern APIs separate sending files from form data so if you just want to send a file to an endpoint, soFetch makes it really easy. Just send a File instead of a serialisable object:

1const file = new File(["File contents"], "test.txt", {type: "text/plain"})
2const result = await soFetch("/api/files", file)

Sending an array of files

This example attaches a change event listener to an HTMLInputElement (assumed to be of type "file")

1const input = document.querySelector<HTMLInputElement>("#fileInput");
2
3input?.addEventListener("change", async () => {
4    if (input.files) {
5        await soFetch("/api/files", input.files)
6    }
7});

Files with Field Names

Sometimes the server endpoint expects the files to have field names. In this case you can post a FileWithFieldName, like this:

1const file = new File(["File contents"], "test.txt", {type: "text/plain"})
2const result = await soFetch("/api/files", {file:file, fieldName:"NAME_EXPECTED_BY_SERVER"})

Sending Files and Data Simultaneously

Sometimes an API endpoint will request files and data at the same time. Implementations of this type of endpoint vary considerably (so read your docs!) but typically you might use FormData instead of JSON to send data and files simultaneously. An example could look something like this:

1const file = new File(["File contents"], "test.txt", {type: "text/plain"})
2            
3const result = await soFetch.put("/api/files-and-data").beforeFetchSend((init:RequestInit) => {
4    const formData = new FormData()
5    formData.append("username", "chris")
6    formData.append("company", "Antoinette")
7    
8    //This bit removes the JSON content-type header, causing Fetch to default to 'multipart/form-data':
9    const headers = {...init.headers} as Record<string,string>
10    if (headers["content-type"]) {
11        delete headers["content-type"]
12    }
13    
14    init.body = formData
15    init.headers = headers
16    return init
17})
18

Instances

Sometimes you might be communicating with 2 APIs at the same time, each with it's own configuration. soFetch lets you handle this scenario easily with it's instance() function.

1//Create the first independent instance:
2apiClient1 = soFetch.instance("CLIENT_1_KEY")
3apiClient1.config.baseUrl = "https://api.example.com"
4apiClient2.config.useCookieAuthentication()
5const result1 = await apiClient1("/some-resource")
6
7//And now the second:
8const apiClient2 = soFetch.instance("CLIENT_2_KEY")
9apiClient2.config.baseUrl = "https://some-other-service.com"
10apiClient2.config.useBearerAuthentication()
11const result2 = await apiClient2("/something-completely-different")
12

In the example above apiClient1 and apiClient2 are completely independent instances of soFetch: