npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

fetch-er

v0.0.10

Published

WHATWG fetch helper

Downloads

15

Readme

fetch-er

Build Status

A WHATWG fetch helper. WHATWG's fetch is very modern. Simple name, uses Promise, options object. But it designed as a low level API. Developers have to deal with some detail. ex: Post parameter serialize, transform response JSON to JavaScript object. So here is the fetch-er to help you deal with these stuff. Inspired by jQuery.ajax.

Example

fetcher.get('/api/users', null, {dataType: 'json'}).then( ([value, res]) => {
  //...
} )

fetcher.getJSON('/api/users').then( ... )

fetcher.post('/api/users', {name: 'John'}).then( ... )

fetcher.put('/api/users',  {name: 'Wick'}).then( ... )

fetcher.delete('/api/users/23').then( ... )

fetch-er is Not

fetch-er is not designed for every case. If you belongs to one of following situation. You should not use fetch-er:

  • Feeling good to use fetch API. Since it's not hard to use fetch without helper.
  • Every byte count, you need to keep your script as small as possible. Every byte matters.

Doc

fetch-er provide a new global object for browser environment, called fetcher. fetcher is an instance of private Fetcher class. In other module systems like: CommonJS, AMD, NodeJS. You will get the same instance of Fetcher when you include this module.

var fetcher = require('fetch-er')

To install, you can use npm or bower or just download dist/fetcher.js.

npm i fetch-er
bower i fetch-er

The Fetcher class have the following basic methods: delete, get, getJSON, head, options, post and put. Mapping the method name to HTTP method for the method will use. All methods receives three arguments:

  • url: The url location of the request
  • data: Optional data for the request
  • options: Optional options object send to fetch

The options object will send to fetch and fetcher provides several new options:

  • contentType: The data type of request body you are going to send. Will overwrite the one in headers.
  • dataType: The data type you expect to receive from server. Supports mime type and following shorcut json, text and xml.
  • mimeType: Will overwrite response mimeType before parse to data.
  • timeout: Will reject returned promise when time limit reach, but no actual abort now(current fetch don't have abort).

What fetcher will do when you do a request through it:

  1. If method is GET or HEAD, parse data to form-urlencoded form. Append to request url.
  2. Auto generate request body if necessary. (json, form-urlencoded)
  • JSON, if a request contains headers have Content-Type: application/json or options.contentType with the same value. The data will parsed by JSON.stringify and write to body.
  • FormData or ArrayBuffer will send to fetch directly.
  • Default request body is form-urlencoded, use jquery-param.
  1. Set mode to cors if request to a different hostname.
  2. Auto parse response data. Fetcher will try to figure out what to do based on response content type and options.dataType.
  • JSON string will parsed by JSON.parse.
  • HTML will be plain text. If you want DOM node as response. You can set options.dataType to xml.
  • XML will be parse by DOMParser.
  • ArrayBuffer or FormData will only available if user set options.dataType.
  • Otherwise, response will be plain text.

Fetcher methods will return a Promise just like fetch. But it will be fulfilled with different value, an array([value, status, response]). First element is the response value. Second element is text response status. Possible status:

  • nocontent for 200 or HEAD request.
  • notmodified for 304 not modified.
  • success for other success request.

Third element is consumed response object. The reason to use array is easier to use ES6 destructuring assign. Ex:

fetcher.get('/api').then( ([value, status, response]) => {
  // blah...
})

PS. Plan to return not consumed response. But current polyfill don't support clone.

request(method, url, data, options)

There is one more method called request. Is the base of all other methods. Receive four arguments: method, url, data and options. The method is in string format. All uppercase characters. Which will pass to fetch directly. And fetch will check is method valid.

If an error happened on fetcher reqeust. The returned promise will reject just like a normal fetch request. This only happens when response status is not normal (100 to 599) or network error. By design fetch will fulfill returned Promise when server have response. And developers can use response.ok to check is this request success. Only when status code between 200 to 299 will set ok to true. But jQuery also accept 304 not modified. And jQuery will reject all other status code. The behavior is very different. And fetcher still not decide which to follow.

The rejected promise will use an array to reject([error, response]). Some error will not get response. Ex: timeout or network error.

setup(options)

There is a method called setup used for setup default option. The default option will be used on every request. But possible to overwrite when make the request. Current supported options are method, contentType, dataType, mimeType, timeout and converters. Default global options are:

{
  method: 'get',
  converters: {
    'text json': JSON.parse,
    'text xml':  parseXML
  }
}

Compare to jQuery.ajax

Stat: y: support, p: partial, n: not support, n/a: not possible, todo: in plan.

| Feature | Stat | |-----------------|-------------------| | accepts | y | | ajaxPrefilter() | n | | ajaxSetup() | p, use setup() | | ajaxTransport() | n/a | | async | n/a | | beforeSend | n | | cache | n | | complete | use promise chain | | contents | n/a | | contentType | y | | context | n/a | | converters | y, 2 level only | | crossDomain | auto | | data | y | | dataFilter | n | | dataType | y | | error | use promise chain | | global | n/a | | headers | y | | ifModified | n | | isLocal | n | | jsonp | n | | jsonpCallback | n | | method | y | | mimeType | y | | password | n/a | | processData | todo | | scriptCharset | n | | statusCode | n | | success | use promise chain | | timeout | y | | traditional | n/a, based on dep | | type | y | | url | y | | username | n/a | | xhr | n/a | | xhrFields | n/a |