Chained and declarative HTTP client based on the browser Fetch API

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

The latest version of Chrome, Firefox, and Safari.

npm i @http-util/request

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

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

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

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

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

⬆ Back to top

Alias for path().

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

⬆ Back to top

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

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

Accept object as params.

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

⬆ Back to top

Add header to request.

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

.header('X-TenantId', companyId)

⬆ Back to top

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

.header('Authorization', value)

.auth('Bearer eyJhbGciOiJIUzI1NiIs')

⬆ Back to top

Set the content type of the body.

.content('multipart/form-data')

⬆ Back to top

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

.content('text/plain')

⬆ Back to top

Convenience method for sending data as json, same with:

.content('application/json')

⬆ Back to top

Set the Accept header.

.accept('text/csv')

⬆ Back to top

Convenience method for getting plain text response, same with:

.accept('text/plain')

⬆ Back to top

Convenience method for getting XML response, same with:

.accept('text/plain')

⬆ Back to top

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

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

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 request.

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

⬆ Back to top

Send GET request, same with:

.send('GET', null)

⬆ Back to top

Send POST request, same with:

.send('POST', body)

⬆ Back to top

Send PUT request, same with:

.send('PUT', body)

⬆ Back to top

Send PATCH request, same with:

.send('PATCH', body)

⬆ Back to top

Send HEAD request, same with:

.send('HEAD', null)

⬆ Back to top

Send DELETE request, same with:

.send('DELETE', null)

⬆ Back to top

Makes this request cache for ttl milliseconds.

⬆ Back to top

Clear the request cache map.

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

⬆ Back to top

Callback that gets invoked with string url before sending.

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

⬆ Back to top

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

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

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

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

⬆ Back to top

CHANGELOG

MIT © Kimi Gao