Chained and declarative HTTP client based on the browser Fetch API

Features

• ✔︎ Chained and declarative api methods
• ✔︎ Based on the browser Fetch API
• ✔︎ Form support
• ✔︎ Download support

Browser Support

The latest version of Chrome, Firefox, and Safari.

Install

npm i @http-util/request

Example

import request from '@http-util/request'

(async () => {
    const res = await request
      .p('https://cnodejs.org/api/v1')
      .p('topics')
      .q('page', 2)
      .q('tab', 'good')
      .q('limit', 5)
      .get()
    console.log('res', res)
})()

API Preview

• PATH
  • path(path: string | number)
  • p(path: string | number)
• QUERY
  • query(key: string, value: string | number | boolean | array)
  • q(key: string, value: string | number | boolean | array)
  • queryAll(params: object)
• HEADER
  • header(name: string, value: string | number | boolean)
  • auth(value: string)
  • content(contentType: string)
    • withText()
    • withJson()
  • accept(acceptType: string)
    • asText()
    • asXML()
• FORM
  • append(name: string, value: string | Blob, fileName?: string)
  • formData(data: object)
  • formUrl(url: object | string)
• HTTP METHODS
  • send(method: string, body?: any)
  • get()
  • post(body?: any)
  • put(body?: any)
  • patch(body?: any)
  • head()
  • delete()
• CACHE
  • cache(ttl: number)
  • clearCache()
• OTHER
  • beforeSend(callback: func)
  • asRaw()
  • download(fileName?: string)
  • options(options: object)

API Docs

path(path: string | number)

Add path segment to request url including non-encoded path segment.

request
  .path('https://cnodejs.org')
  .path('api')
  .path('v1')
  .path('topics')
  .get()

you can also make one path with the slash:

request
  .path('https://cnodejs.org/api/v1/topics')
  .get()

⬆ Back to top

p(path: string | number)

Alias for path().

request
  .p('https://cnodejs.org')
  .p('api')
  .p('v1')
  .p('topics')
  .get()

⬆ Back to top

query(key: string, value: string | number | boolean | array)

Add query parameter to request url.

request
  .path('https://cnodejs.org/api/v1')
  .path('topics')
  .query('page', 2)
  .query('tab', 'good')
  .query('limit', 5)
  .get()

⬆ Back to top

q(key: string, value: string | number | boolean | array)

Alias for query().

request
  .p('https://cnodejs.org/api/v1')
  .p('topics')
  .q('page', 2)
  .q('tab', 'good')
  .q('limit', 5)
  .get()

⬆ Back to top

queryAll(params: object)

Accept object as params.

request
  .p('https://cnodejs.org/api/v1')
  .p('topics')
  .queryAll({
    'page': 2,
    'tab': 'good',
    'limit': 5
  })
  .get()

⬆ Back to top

header(name: string, value: string | number | boolean)

Add header to request.

request
  .p('account')
  .p('users')
  .p(userId)
  .p('state')
  .header('Content-Type', 'text/plain')
  .put('LOCKED');

You can also define custom header by this method:

.header('X-TenantId', companyId)

⬆ Back to top

auth(value: string)

Convenience method for setting the "Authorization" header, same with:

.header('Authorization', value)

.auth('Bearer eyJhbGciOiJIUzI1NiIs')

⬆ Back to top

content(contentType: string)

Set the content type of the body.

.content('multipart/form-data')

⬆ Back to top

withText()

Convenience method for sending data as plain text, same with:

.content('text/plain')

⬆ Back to top

withJson()

Convenience method for sending data as json, same with:

.content('application/json')

⬆ Back to top

accept(acceptType: string)

Set the Accept header.

.accept('text/csv')

⬆ Back to top

asText()

Convenience method for getting plain text response, same with:

.accept('text/plain')

⬆ Back to top

asXML()

Convenience method for getting XML response, same with:

.accept('text/plain')

⬆ Back to top

append(name: string, value: string | Blob, fileName?: string)

Append formData params and set the content-type header to multipart/form-data automatically.

request
  .path('flipper/v0/flip')
  .path('order')
  .append('quotation', file)
  .accept('application/vnd.oasis.ubl+json')
  .post();

⬆ Back to top

formData(data: object)

Convert the javascript object to a FormData and set the content-type header to multipart/form-data automatically.

const data = {
  pony: true,
  text: 'abc'
}
​
request
  .path('...')
  .formData(data)
  .post()

⬆ Back to top

formUrl(input: object | string)

Convert the input to an url encoded string and set the content-type header to application/x-www-form-urlencoded automatically.

const input = {
  pony: true,
  tim: { isFat: false }
}
const alreadyEncodedForm = 'pony=true&tim=%7B%22isFat%22%3Afalse%7D'
​
request.path('...').formUrl(form).post()
request.path('...').formUrl(alreadyEncodedForm).post()

⬆ Back to top

send(method: string, body?: any)

Send request.

supported methods: POST, GET, POST, PUT, DELETE, PATCH, etc.

⬆ Back to top

get()

Send GET request, same with:

.send('GET', null)

⬆ Back to top

post(body?: any)

Send POST request, same with:

.send('POST', body)

⬆ Back to top

put(body?: any)

Send PUT request, same with:

.send('PUT', body)

⬆ Back to top

patch(body?: any)

Send PATCH request, same with:

.send('PATCH', body)

⬆ Back to top

head()

Send HEAD request, same with:

.send('HEAD', null)

⬆ Back to top

delete()

Send DELETE request, same with:

.send('DELETE', null)

⬆ Back to top

cache(ttl: number)

Makes this request cache for ttl milliseconds.

⬆ Back to top

clearCache()

Clear the request cache map.

import { clearCache } from '@http-util/request'
​
clearCache()

⬆ Back to top

beforeSend(callback: func)

Callback that gets invoked with string url before sending.

Note: It can only change headers and body of the request.

⬆ Back to top

asRaw()

Return a promise for the response (including status code and headers), rather than for just the response data.

request
  .path(url)
  .asRaw()
  .get()

⬆ Back to top

download(fileName?: string)

File will be named by following priority:

• High: download(fileName).
• Medium: response headers 'Content-Disposition' filename.
• Low: string after the last slash of path url.

// file will be downloaded and named 'prop-types.js'
request
  .p('https://cdn.bootcss.com/prop-types/15.6.1/prop-types.js')
  .download()
​
// file will be downloaded and named 'types.js'
request
  .p('https://cdn.bootcss.com/prop-types/15.6.1/prop-types.js')
  .download('types.js')
​
// you can also download file by chained path style
request
  .p('https://cdn.bootcss.com')
  .p('prop-types')
  .p('15.6.1')
  .p('prop-types.js')
  .download()

⬆ Back to top

options(options: object)

Set Fetch API options, this options method will replace other options you defined.

request
  .p('...')
  .options({credentials: 'include'})
  .post(body)

⬆ Back to top

Changelog

CHANGELOG

License

MIT © Kimi Gao