npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

zl-fetch

v6.0.6

Published

A library that makes the Fetch API easy to use

Downloads

195

Readme

zlFetch

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

It's features are as follows:

Note: zlFetch is a ESM library since v4.0.0.

Installing zlFetch

Through npm (recommended)

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

Then you can use it by importing it in your JavaScript file.

import zlFetch from 'zl-fetch'

Using zlFetch without npm:

You can import zlFetch directly into JavaScript through a CDN.

To do this, you first need to set your script's type to module, then import zlFetch.

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

Quick Start

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))

Shorthand methods for GET, POST, PUT, PATCH, and DELETE

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 */)

Supported response types

zlFetch supports json, text, and blob response types so you don't have to write response.json(), response.text() or response.blob().

Other response types are not supported right now. If you need to support other response types, consider using your own response handler

The response contains all the data you may need

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

We do this so you don't have to fish out the headers, status, statusText or even the rest of the response object by yourself.

Debugging the request

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))

Error Handling

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 */
  })

Easy error handling when using async/await

zlFetch lets you pass all errors into an errors object. You can do this by adding a returnError option. This is useful when you work a lot with async/await.

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

Helpful Features

Query string helpers

You can add query or queries as an option and zlFetch will create a query string for you automatically. Use this with GET requests.

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')

Content-Type generation based on body content

zlFetch sets Content-Type appropriately depending on your body data. It supports three kinds of data:

  • Object
  • Query Strings
  • Form Data

If you pass in an object, zlFetch will set Content-Type to application/json. It will also JSON.stringify your body so you don't have to do it yourself.

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

// The above request is equivalent to this
fetch('some-url', {
  method: 'post',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ message: 'Good game' }),
})

zlFetch contains a toObject helper that lets you convert Form Data into an object. This makes it super easy to zlFetch with forms.

import { toObject } from 'zl-fetch'
const data = new FormData(form.elements)

zlFetch('some-url', {
  body: toObject(data),
})

If you pass in a string, zlFetch will set Content-Type to application/x-www-form-urlencoded.

zlFetch also contains a toQueryString method that can help you convert objects to query strings so you can use this option easily.

import { toQueryString } from 'zl-fetch'

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

// The above request is equivalent to this
fetch('some-url', {
  method: 'post',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: 'message=Good%20game',
})

If you pass in a Form Data, zlFetch will let the native fetch function handle the Content-Type. Generally, this will use multipart/form-data with the default options. If you use this, make sure your server can receive multipart/form-data!

import { toObject } from 'zl-fetch'
const data = new FormData(form.elements)

zlFetch('some-url', { body: data })

// The above request is equivalent to this
fetch('some-url', { body: data })

// Your server should be able to receive multipart/form-data if you do this. If you're using Express, you can a middleware like multer to make this possible:
import multer from 'multer'
const upload = multer()
app.use(upload.array())

Breaking Change in v5.0.0: If you pass in a Content-Type header, zlFetch will not set format your body content anymore. We expect you to be able to pass in the correct data type. (We had to do this to support the new API mentioned above).

Authorization header helpers

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')}` }
});

Creating a zlFetch Instance

You can create an instance of zlFetch with predefined options. This is super helpful if you need to send requests with similar options or url.

  • url is required
  • options is optional
import { createZLFetch } from 'zl-fetch'

// Creating the instance
const api = zlFetch(baseUrl, options)

All instances have shorthand methods as well.

// Shorthand methods
const response = api.get(/* ... */)
const response = api.post(/* ... */)
const response = api.put(/* ... */)
const response = api.patch(/* ... */)
const response = api.delete(/* ... */)

New in v5.0.0

You can now use a zlFetch instance without passing a URL. This is useful if you have created an instance with the right endpoints.

import { createZLFetch } from 'zl-fetch'

// Creating the instance
const api = zlFetch(baseUrl, options)

All instances have shorthand methods as well.

// Shorthand methods
const response = api.get() // Without URL, without options
const response = api.get('some-url') // With URL, without options
const response = api.post('some-url', { body: 'message=good+game' }) // With URL, with options
const response = api.post({ body: 'message=good+game' }) // Without URL, with options

Custom response handler

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()