scratch-fetch
TypeScript icon, indicating that this package has built-in type declarations

1.1.1 • Public • Published

What is this?

This is a JavaScript FetchAPI library.

How to use

1. Install package

npm install scratch-fetch --save

2. Import module

1. ES5 or earlier

require("scratch-fetch");

2. ES6

import { httpGet, httpPost, httpPut, httpDelete } from "scratch-fetch";

3. Set up your request

You can use either constructor or methods to set up your request.

By constructor:

const response = await httpPost({
                        url: "https://localhost:8080/api/hello",
                        headers: {
                            "KEY_0": "VALUE",
                            "KEY_1": "VALUE"
                        },
                        body: {
                            "key": "value"
                        }
                    }).execute();

By methods

const response = await httpPost()
                        .withUrl("https://localhost:8080/api/hello")
                        .withHeaders({
                            "KEY_0": "VALUE",
                            "KEY_1": "VALUE"
                        }).
                        withBody({
                            "key": "value"
                        }).execute();
  • By default, the request contains "Accept": "application/json" and "Content-Type": "application/json" headers. If you wish to remove default headers, you can set the useDefaultHeaders property in configuration to false when initializing the request. (in constructor)
  • The body of a request will be stringified automatically. If you wish to keep your request body raw, you can set the stringifyBody property in configuration to false when initializing the request. (in constructor)

For example,

const response = await httpGet({
                        url: "https://localhost:8080/api/hello",
                        configuration: {
                            useDefaultHeaders: false, // <- Remove default headers.
                            stringifyBody: false // <- Keep request body raw.
                        }
                    }).execute();

You can reuse a request object multiple times. If you want to change the url of the request (for most cases, we want to change route parameters or query parameters), then you can call the withUrl method at any time to achieve this aim.

For example,

const requests = {
  fetchData: httpGet()
};

async function fetchMyData() {
  const queryString = ""; // queryString may be different every time you call this function.
  const response = requests.fetchData
                          .withUrl(`https://localhost:8080/api/hello?${queryString}`)
                          .execute();
}

scratch-fetch also offers you a function to build query string. To use this function, we have to import it from the module.

1. ES5 or earlier

var buildQueryString = require("scratch-fetch").buildQueryString;

2. ES6

import { buildQueryString } from "scratch-fetch";

Then you can use this function to build your query string.

For example,

const params = {
  page: 5,
  size: 20
};
const queryString = buildQueryString(params); // queryString will be "page=5&size=20", WITHOUT the leading question mark.

4. Get response and handle errors

const response = await httpGet({ url: "https://localhost:8080/api/hello" }).execute();
if (response.ok) {
    console.log(response.value); // "value" is already converted to json object.
}
else if (!response.isAborted) {
    // Handle error here
    console.error(response.error);
}

What do I do if I want to abort a request?

You can call the abort method to abort a request.

For example,

const requests = {
    fetchData: httpGet(),
    updateData: httpPut()
};

// Set up requests
const response = requests.updateData
                        .withUrl("https://localhost:8080/api/hello")
                        .withBody({ "key": "value" })
                        .execute();

// Then somewhere in your code
requests.updateData.abort();
  • If a request is already done (that means you have received the value of response), then the abort method will not do anything.
  • You can handle abort error by checking the isAborted property in the response.

5. API References

1. Constructor

Name Type Default value
url string undefined
headers {}
  • "Accept": "application/json"
  • "Content-Type": "application/json"
body any undefined
configuration IHttpRequestInitConfiguration undefined
IHttpRequestInitConfiguration
Name Type Default value
useDefaultHeaders boolean true
stringifyBody boolean true
allowMultiple boolean false
credentials RequestCredentials "include"
  • The allowMultiple property is used to prevent a request from getting sent multiple times before the previous one is done. By default, this attribute is set to false. If you wish to remove this constraint, you can set it to true.
  • For more info about credentials property, please visit MDN Web Docs

2. Methods

Name Arguments Returned value type
url none (getter) string
headers none (getter) {}
body none (getter) any
withUrl value: string IHttpRequest
withHeaders value: {} IHttpRequest
withBody value: any IHttpRequest
addHeaders value: {} undefined (void)
patchHeaders value: {} undefined (void)
removeHeader key: string boolean
execute - Promise<HttpResponse>
abort - undefined (void)
HttpResponse
Name Type
ok boolean
status number?
isAborted boolean
value any
error {}

Readme

Keywords

Package Sidebar

Install

npm i scratch-fetch

Weekly Downloads

22

Version

1.1.1

License

MIT

Unpacked Size

33.2 kB

Total Files

10

Last publish

Collaborators

  • abe.msc.ac