⚡ Z-Fetch

The mighty native fetch api wrapper made to enhance fetching in JavaScript Applications.

Originally made for Z Js Framework but can work in any framework or javascript environment with no additional setup needed.

🚀 Features

• Framework Agnostic, use in any javaScript project.
• Zero dependencies, wraps native fetch api.
• Intiutive modern api with configuration and flexibility per request.
• Can cancel requests on demand or on timeout.
• Has global configuration for global request options.
• Supports all native fetch api options.
• Bultin caching and cache auto cache revalidation
• Builtin request retries, max retries and polling.
• Builtin bearer token handler, you don't need interceptors!
• Auto json parsing and graceful error handling
• Request refetching on demand

▶️ Installation

1. Using npm, yarn or pnpm

npm install @z-js-framework/z-fetch

2. Using a CDN

<script src="https://cdn.jsdelivr.net/npm/@z-js-framework/z-fetch@latest/dist/z-fetch.js"></script>

or if your using Z Js Framework you don't have to install anything, this comes with the framework.

😇 How To Use With Examples

GET Request

import { GET } from '@z-js-framework/z-fetch';

const getPosts = async () => {
   const { data, error, loading } = await GET('https://jsonplaceholder.typicode.com/posts');
  if (data) {
    console.log('Data:', data);
  } else {
    console.error('Error:', error.message);
  }
}

POST Request

import { POST } from '@z-js-framework/z-fetch';

const createPost = async () => {
   const { data, error, loading } = await POST('https://jsonplaceholder.typicode.com/posts', {
    body: {
      title: 'dune',
      body: 'a story about the dune verse!',
      userId: 1,
    }
   });
  if (data) {
    console.log('Data:', data);
  } else {
    console.error('Error:', error.message);
  }
}

PUT Request

import { PUT } from '@z-js-framework/z-fetch';

const updatePost = async () => {
   const { data, error, loading } = await PUT('https://jsonplaceholder.typicode.com/posts/1', {
    body: {
      title: 'dune latest',
      body: 'a story about the dune verse has changed now the spices rule!',
      userId: 1,
    }
   });
  if (data) {
    console.log('Data:', data);
  } else {
    console.error('Error:', error.message);
  }
}

PATCH Request

import { PATCH } from '@z-js-framework/z-fetch';

const modifyPost = async () => {
   const { data, error, loading } = await PATCH('https://jsonplaceholder.typicode.com/posts/1', {
    body: {
      title: 'dune movie'
    }
   });
  if (data) {
    console.log('Data:', data);
  } else {
    console.error('Error:', error.message);
  }
}

DELETE Request

import { DELETE } from '@z-js-framework/z-fetch';

const deletePost = async () => {
   const { error } = await DELETE('https://jsonplaceholder.typicode.com/posts/1');
  if (!error) {
    console.log('item deleted successfully!');
  } else {
    console.error('Error Deleting Item:', error.message);
  }
}

Advanced Usage 😳

Set Global Configuration

import { setConfig, GET } from '@z-js-framework/z-fetch';

setConfig({
  baseUrl: 'https://jsonplaceholder.typicode.com',
  timeout: 5000,
  withCredentials: false,
  parseJson: true,
});

const getPosts = async () => {
   const { data, error, loading } = await GET('/posts');
  if (data) {
    console.log('Data:', data);
  } else {
    console.error('Error:', error.message);
  }
}

or set per request

import { GET } from '@z-js-framework/z-fetch';

const getPosts = async () => {
   const { data, error, loading } = await GET('https://jsonplaceholder.typicode.com/posts', {
    parseJson: false,
     headers: {
    'Content-Type': 'application/text',
     },
     retry: true,
     maxRetries: 3,
   });

  if (data) {
    console.log('Data:', data);
  } else {
    console.error('Error:', error.message);
  }
}

List of All Available Config Options

Here is the list of all the available options in addtion to native fetch's options. Note that all fetch api's options are valid and supported, these below are just enhancements z-fetch adds on top.

| Option | Description | Use Case | Default Value | | ------------------ | ---------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------- | | baseUrl | Base URL for all requests | Set a common base URL for all API requests | '' | | bearerToken | Bearer token for authentication | Authenticate requests with a bearer token | null | | timeout | Request timeout in milliseconds | Set a timeout for requests | 90000 | | retry | Whether to retry failed requests | Automatically retry failed requests | false | | maxRetries | Maximum number of retries | Set a limit on the number of retries | 3 | | startPolling | Whether to start polling automatically | Enable automatic polling | false | | stopPolling | Whether to stop polling automatically | Disable polling after certain conditions | false | | pollingInterval | Interval between polls in milliseconds | Set polling interval | 5000 | | revalidateCache | Time in milliseconds before revalidating cached data | Refresh cached data after a specific time | 10000 | | withCredentials | Whether to include credentials in requests | Include credentials like cookies | false | | withCache | Whether to use caching for GET requests | Cache GET request responses | true | | parseJson | Whether to parse response as JSON | Automatically parse JSON responses | true | | stringifyPayload | Whether to stringify request body | Automatically stringify request body | true | | mode | CORS mode for requests | Set CORS mode (e.g., 'cors', 'no-cors') | 'cors' | | headers | Default headers for all requests | Set default headers | {'Content-Type': 'application/json', 'Accept': '*/*'} |

Alternatively you can set the bearer token globally for all requests using setBearerToken method as below:

import { setBearerToken } from '@z-js-framework/z-fetch';

setBearerToken('your-bearer-token');

otherwise there more interesting things you can do even with each request, here are examples for polling, caching, request cancelling and refetching.

Polling

import { setConfig, GET } from '@z-js-framework/z-fetch';

setConfig({
  baseUrl: 'https://jsonplaceholder.typicode.com',
  timeout: 5000,
  withCredentials: true,
  parseJson: true,
});

let pageCount = 1;
let pagesData = [];

const getPosts = async () => {
   const { data, error, loading, startPolling, stopPolling, onPollDataReceived } = await GET(`/posts?page=${pageCount}`);
  if (data) {
    pagesData.push({
      page: 1,
      data: data,
    })
    pageCount++;
  } else {
    console.error('Error:', error.message);
  }

  if(pageCount < 100) {
    startPolling(10000); // explicitly poll after every 10 seconds
    onPollDataReceived((data) => {
      pagesData.push({
        page: pageCount,
        data: data,
      });
      pageCount++;
    })
  } else {
    stopPolling();
  }
}

The code above will poll the API every 10 seconds until it reaches 100 pages, it uses extra polling methods exposed in the request's response. onPollDataReceived takes a callback function that will be called every time the API returns new data and avail that new data to it.

Caching

import { GET } from '@z-js-framework/z-fetch';

const getCachedPosts = async () => {
  const { data, error, loading } = await GET('https://jsonplaceholder.typicode.com/posts', {
    withCache: true,
    revalidateCache: 60000, // Revalidate cache every 60 seconds
  });
  if (data) {
    console.log('Cached Data:', data);
  } else {
    console.error('Caching Error:', error.message);
  }
};

Request Cancelling

import { GET } from '@z-js-framework/z-fetch';

let cancelButton = document.getElementById('cancelButton');

const getPosts = async () => {
   const { data, error, loading, cancelRequest } = await GET('https://jsonplaceholder.typicode.com/posts');
  if (data) {
    console.log('Data:', data);
  } else {
    console.error('Error:', error.message);
  }
}

cancelButton.addEventListener('click', () => cancelRequest());

Refetching

import { GET } from '@z-js-framework/z-fetch';

let reloadButton = document.getElementById('reloadButton');

let itemsList = [];

const getPosts = async () => {
   const { data, error, loading, refetch } = await GET('https://jsonplaceholder.typicode.com/posts');
  if (data) {
    itemsList = data;
  } else {
    console.error('Error:', error.message);
  }
}

reloadButton.addEventListener('click', () => refetch((newData) => {
  itemsList = newData;
}));

Refetch takes in a callback, it makes the same exact request with the same everything set and then calls the callback with the new data.

Lastly but not least

you can just use z-fetch as normal fetch, it's just a wrapper around fetch and adds some extra features but in case you want to tap in and do some stuff sure, here is a quick example:

import { POST } from '@z-js-framework/z-fetch';

const createPost = async () => {
  const { response } = await POST('https://jsonplaceholder.typicode.com/posts', {
    body: JSON.stringify({
      title: 'dune',
      body: 'A family gets attacked and great houses do nothing about it!',
      userId: 1,
    })
    parseJson: false,
    stringifyPayload: false,
  });
  let data = await response.json();
  if (data) {
    console.log('Data:', data);
  } else {
    console.error('Error:', response.error.message);
  }
};

As you can see, not exactly but it doesn't get in your way in case you want to do something with the underlying fetch api, its very flexible. Enjoy!!!

🌟 Contributing

Well that's it for now, more stuff surely will come, but so far that's all you need to elevate fetching in your applications, tell me what you think or contribute or suggest a feature, I'll be happy to hear from you.

Humble regards, I am Hussein Kizz