zf

zl-fetch

A library that makes the Fetch API a breeze

Showing:

Popularity

Downloads/wk

54

GitHub Stars

195

Maintenance

Last Commit

2mos ago

Contributors

2

Package

Dependencies

3

License

MIT

Type Definitions

Tree-Shakeable

Yes?

Categories

Readme

zlFetch

Features

  1. zlFetch helps you create your request. It helps you:
    1. Create query parameters for GET requests
    2. Do Basic and Bearer-type authorization
    3. Formats body for JSON or x-www-form-urlencoded
  2. zlFetch transforms the response:
    1. It lets you use your responses in the first then method.
    2. It directs 400 and 500 errors into catch.

Download/install

You can install zlFetch through npm.

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

If you want to use zlFetch in your browser, download dist/index.min.js or use the CDN link below:

<script src="https://cdn.jsdelivr.net/npm/zl-fetch"></script>

Quick Start

Basic usage (in Browser)

// Basic usage
zlFetch("http://your-website.com")
  .then(response => console.log(response))
  .catch(error => console.log(error));

You can use import zlFetch the ES6 way if you wish to:

// ES6 imports
import zlFetch from "zl-fetch";
zlFetch("http://your-website.com")
  .then(response => console.log(response))
  .catch(error => console.log(error));

Basic usage (in Node)

You use it the same way you expect to with browsers!

const zlFetch = require("zl-fetch");
zlFetch("http://your-website.com")
  .then(response => console.log(response))
  .catch(error => console.log(error));

Response and Error objects

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("http://your-website.com")
  .then(response => {
    const headers = response.headers;
    const body = response.body;
  })
  .catch(error => {
    const headers = error.headers;
    const body = error.body;
    const status = error.status;
  });

GET requests

To send a GET request, enter the endpoint as the first argument.

// With zlFetch
zlFetch("http://your-website.com");

// With fetch api
fetch("http://your-website.com");

zlFetch formats and encodes query parameters for you if you provide a queries option.

zlFetch('http://your-website.com', {
  queries: {
    param1: 'value1',
    param2: 'to encode'
  }
})

// With fetch API
fetch('http://your-website.com?param1=value1&param2=to%20encode')

POST requests

Set method to post to send a post request. zlFetch will set Content-Type will be set to application/json for you. It will also convert your body to a JSON string automatically.

// with zlFetch
zlFetch("http://your-website.com", {
  method: "post",
  body: {
    key: "value"
  }
});

// Resultant fetch api
fetch("http://your-website.com", {
  method: "post",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    key: "value"
  })
});

// Setting other content type
zlFetch("http://your-website.com", {
  method: "post",
  headers: { "Content-Type": "application/x-www-form-urlencoded" }
});

Other Content-Types

You may choose to overwrite Content-Type yourself. To do so, pass headers and Content-Type property.

fetch("http://your-website.com", {
  method: "post",
  headers: { "Content-Type": "Another Content Type" },
  body: {
    key: "value"
  )
});

If Content-Type is set to application/x-www-form-urlencoded, zlFetch will format body to be valid for x-www-form-urlencoded.

zlFetch("http://your-website.com", {
  method: "post",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: {
    key: "value",
    web: "https://google.com"
  }
});

// Resultant fetch api
fetch("http://your-website.com", {
  method: "post",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: "key=value&web=https%3A%2F%2Fgoogle.com"
});

Authentication/Authorization

zlFetch adds Authorization headers for you if you include an auth property.

zlFetch("http://your-website.com", {
  auth: /* Your credentials */
})

Basic Authentication

To perform basic authentication, pass username and password into auth.

zlFetch("http://your-website.com", {
  auth: {
    username: 'your-username'
    password: 'your-password'
  }
})

// Resultant fetch api
fetch("http://your-website.com", {
  headers: { Authorization: `Basic ${btoa("yourusername:12345678")}` }
});

Token/Bearer Authentication

To perform token-based authentication, pass your token into auth.

zlFetch("http://your-website.com", {
  auth: "token12345"
});

// Resultant fetch api
fetch("http://your-website.com", {
  headers: { Authorization: `Bearer token12345` }
});

Shorhand methods

From v3.0 onwards, zlFetch supports method shorthands.

Supported shorthand methods include:

  1. get
  2. post
  3. put
  4. patch
  5. delete
// These two are the same
zlFetch.post('http://your-website.com')
zlFetch('http://your-website.com', { method: 'post' })

Response Types

zlFetch supports only json and text response types for now. If you run into an error with a response type, file an issue and I'll support it asap. (This might take time though!)

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100