zlFetch is a wrapper around fetch that provides you with a convenient way to make requests.

It's features are as follows:

• You can use the response right away without calling an extra .then, or response.json(), or response.text()
• It returns everything you need to know about a response in one object — headers, body, status... everything!
• You can debug your request — and see what url, headers, and body you send — without looking into the Network panel... this saves so much time debugging requests!
• There are shorthand methods GET, POST, PUT, PATCH, and DELETE methods, meaning faster access to the most common HTTP methods.
• This package generates query strings for you automatically so you don't have to worry about URLSearchParam stuff. Just pass in an object!
• The Content-Type is set to application/json for you automatically if you use a POST, PUT, PATCH, request — no need to write application/json yourself which saves lots of time (and wrist power)!
• You always override the Content-Type header if you need to!
• Your body data is gets formatted a JSON or form data for you automatically when Content Type is application/json or application/x-www-form-urlencoded.
• No need to write Authorization Headers yourself — zlFetch takes care of both Basic and Bearer Authorization Headres as long as you pass in an auth property.
• Easier error handling when you use promises — all 400 and 500 errors are automatically directed to the catch block which is aligned with how promises work!
• You can also choose to return errors as an error object in the then block — this is super useful in a Node context when you want to check for errors before doing something else!

Note: From v4.0.0 onwards, zlFetch is a ESM library. It cannot be used with CommonJS anymore.

You can install zlFetch through npm:

# Installing through npm
npm install zl-fetch --save

Then you can use it by importing it in your JavaScript file. It works for both browsers and Node.

import zlFetch from 'zl-fetch'

Using zlFetch without npm:

You can use zlFetch without npm by importing it directly to your HTML file. To do this, you first need to set your script's type to module, then import zlFetch from a CDN jsdelivr.

<script type="module">
  import zlFetch from 'https://cdn.jsdelivr.net/npm/[email protected]/src/index.js'
</script>

You can use zlFetch just like a normal fetch function. The only difference is you don't have to write a response.json or response.text method anymore!

zlFetch handles it for you automatically so you can go straight to using your response.

zlFetch('url')
  .then(response => console.log(response))
  .catch(error => console.log(error))

zlFetch sends you all the data you need in the response object. This includes the following:

• headers: response headers
• body: response body
• status: response status
• statusText: response status text
• response: original response from Fetch

New in v4.0.0: You can debug the request object by adding a debug option. This will reveal a debug object that contains the request being constructed.

• url
• method
• headers
• body

zlFetch('url', { debug: true })
  .then({ debug } => console.log(debug))

Note: The logRequestOptions option is replaced by the debug object in v4.0.0. The logRequestOptions option is no longer available.

zlFetch contains shorthand methods for these common REST methods so you can use them quickly.

zlFetch.get(/* some-url */)
zlFetch.post(/* some-url */)
zlFetch.put(/* some-url */)
zlFetch.patch(/* some-url */)
zlFetch.delete(/* some-url */)

You can add query or queries as an option and zlFetch will create a query string for you automatically.:

zlFetch('some-url', {
  queries: {
    param1: 'value1',
    param2: 'to encode'
  }
})

// The above request can be written in Fetch like this:
fetch('url?param1=value1&param2=to%20encode')

zlFetch sets Content-Type to application/json for you automatically if your method is POST, PUT, or PATCH.

It will also help you JSON.stringify your body so you don't have to do it yourself.

zlFetch.post('some-url', {
  body: { message: 'Good game' }
})

// The request above can be written in Fetch like this:
fetch('some-url', {
  method: 'post',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ message: 'Good game' })
})

You can manually set your Content-Type to other values and zlFetch will honour the value you set.

If you set Content-Type to application/x-www-form-urlencoded, zlFetch will automatically format your body to x-www-form-urlencoded for you.

zlFetch.post('some-url', {
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: { message: 'Good game' }
})

// The request above can be written in Fetch like this:
fetch('some-url', {
  method: 'post',
  body: 'message=Good+game'
})

If you provide zlFetch with an auth property, it will generate an Authorization Header for you.

If you pass in a string (commonly for tokens) , it will generate a Bearer Auth.

zlFetch('some-url', { auth: 'token12345' })

// The above request can be written in Fetch like this:
fetch('some-url', {
  headers: { Authorization: `Bearer token12345` }
})

If you pass in an object, zlFetch will generate a Basic Auth for you.

zlFetch('some-url', {
  auth: {
    username: 'username'
    password: '12345678'
  }
})

// The above request can be written in Fetch like this:
fetch('some-url', {
  headers: { Authorization: `Basic ${btoa('username:12345678')}` }
});

zlFetch directs all 400 and 500 errors to the catch method. Errors contain the same information as a response.

• headers: response headers
• body: response body
• status: response status
• statusText: response status text
• response: original response from fetch

This makes is zlFetch super easy to use with promises.

zlFetch('some-url')
  .catch(error => { /* Handle error */})

// The above request can be written in Fetch like this:
fetch('some-url')
  .then(response => {
    if (!response.ok) {
      Promise.reject(response.json)
    }
  })
  .catch(error => { /* Handle error */})

zlFetch also gives you the option to pass all errors into an errors object instead of handling them in catch. This option is very much preferred when you don't your errors to be passed into a catch method. (Very useful when used in servers).

const {response, error} = await zlFetch('some-url')

zlFetch changes the response and error objects. In zlFetch, response and error objects both include these five properties:

1. headers: response headers
2. body: response body
3. status: response status
4. statusText: response status text
5. response: original response from fetch

zlFetch('url')
  .then(response => {
    const headers = response.headers
    const body = response.body
  })
  .catch(error => {
    const headers = error.headers
    const body = error.body
    const status = error.status
  })

zlFetch only supports json,blob, and text response types at this point. (PRs welcome if you want to help zlFetch handle more response types!).

If you want to handle a response not supported by zlFetch, you can pass customResponseParser: true into the options. This returns the response from a normal Fetch request without any additional treatments from zlFetch. You can then use response.json() or other methods as you deem fit.

const response = await zlFetch('url', {
  customResponseParser: true
})
const data = await response.arrayBuffer()