Repository files navigation

Tiny 500b fetch "barely-polyfill"

• Tiny: about500 bytes ofES3 gzipped
• Minimal: justfetch() with headers and text/json responses
• Familiar: a subset of the full API
• Supported: supports IE8+(assumingPromise is polyfilled of course!)
• Standalone: one function, no dependencies
• Modern: written in ES2015, transpiled to 500b of old-school JS

🤔What's Missing?

• Uses simple Arrays instead of Iterables, since Arraysare iterables
• No streaming, just Promisifies existing XMLHttpRequest response bodies
• Use in Node.JS is handled byisomorphic-unfetch

• Unfetch
• Installation
• Usage: As a Polyfill
• Usage: As a Ponyfill
• Examples & Demos
• API
• Caveats
• Contribute
• License

For use withnode andnpm:

npm i unfetch

Otherwise, grab it fromunpkg.com/unfetch.

This automatically "installs" unfetch aswindow.fetch() if it detects Fetch isn't supported:

import'unfetch/polyfill'// fetch is now available globally!fetch('/foo.json').then(r=>r.json()).then(data=>console.log(data))

This polyfill version is particularly useful for hotlinking fromunpkg:

<scriptsrc="https://unpkg.com/unfetch/polyfill"></script><script>// now our page can use fetch!fetch('/foo')</script>

With a module bundler likerollup orwebpack,you can import unfetch to use in your code without modifying any globals:

// using JS Modules:importfetchfrom'unfetch'// or using CommonJS:constfetch=require('unfetch')// usage:fetch('/foo.json').then(r=>r.json()).then(data=>console.log(data))

The above will always returnunfetch().(even ifwindow.fetch exists!)

There's also a UMD bundle available asunfetch/dist/unfetch.umd.js, which doesn't automatically install itself aswindow.fetch.

Real Example on JSFiddle ➡️

// simple GET request:fetch('/foo').then(r=>r.text()).then(txt=>console.log(txt))// complex POST request with JSON, headers:fetch('/bear',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({hungry:true})}).then(r=>{open(r.headers.get('location'));returnr.json();})

While one of Unfetch's goals is to provide a familiar interface, its API may differ from otherfetch polyfills/ponyfills.One of the key differences is that Unfetch focuses on implementing thefetch() API, while offering minimal (yet functional) support to the other sections of theFetch spec, like theHeaders class or theResponse class.Unfetch's API is organized as follows:

This function is the heart of Unfetch. It will fetch resources fromurl according to the givenoptions, returning a Promise that will eventually resolve to the response.

Unfetch will account for the following properties inoptions:

• method: Indicates the request method to be performed on thetarget resource (The most common ones beingGET,POST,PUT,PATCH,HEAD,OPTIONS orDELETE).
• headers: AnObject containing additional information to be sent with the request, e.g.{ 'Content-Type': 'application/json' } to indicate a JSON-typed request body.
• credentials: ⚠ Accepts a"include" string, which will allow both CORS and same origin requests to work with cookies. As pointed in the'Caveats' section, Unfetch won't send or receive cookies otherwise. The"same-origin" value is not supported. ⚠
• body: The content to be transmitted in request's body. Common content types includeFormData,JSON,Blob,ArrayBuffer or plain text.

These methods are used to handle the response accordingly in your Promise chain. Instead of implementing full spec-compliantResponse Class functionality, Unfetch provides the following methods and attributes:

Returnstrue if the request received a status in theOK range (200-299).

Contains the status code of the response, e.g.404 for a not found resource,200 for a success.

A message related to thestatus attribute, e.g.OK for a status200.

Will return anotherObject with the same shape and content asresponse.

Will return the response content as plain text, JSON andBlob, respectively.

Again, Unfetch doesn't implement a full spec-compliantHeaders Class, emulating some of the Map-like functionality through its own functions:

• headers.keys: Returns anArray containing thekey for every header in the response.
• headers.entries: Returns anArray containing the[key, value] pairs for everyHeader in the response.
• headers.get(key): Returns thevalue associated with the givenkey.
• headers.has(key): Returns aboolean asserting the existence of avalue for the givenkey among the response headers.

Adapted from the GitHub fetch polyfillreadme.

Thefetch specification differs fromjQuery.ajax() in mainly two ways thatbear keeping in mind:

• By default,fetchwon't send or receive any cookies from the server,resulting in unauthenticated requests if the site relies on maintaining a usersession.

fetch('/users',{credentials:'include'});

• The Promise returned fromfetch()won't reject on HTTP error statuseven if the response is an HTTP 404 or 500. Instead, it will resolve normally,and it will only reject on network failure or if anything prevented therequest from completing.

  To havefetch Promise reject on HTTP error statuses, i.e. on any non-2xxstatus, define a custom response handler:

fetch('/users').then(response=>{if(response.ok){returnresponse;}// convert non-2xx HTTP responses into errors:consterror=newError(response.statusText);error.response=response;returnPromise.reject(error);}).then(response=>response.json()).then(data=>{console.log(data);});

First off, thanks for taking the time to contribute!Now, take a moment to be sure your contributions make sense to everyone else.

Found a problem? Want a new feature? First of all see if your issue or idea hasalready been reported.If it hasn't, just open anew clear and descriptive issue.

Pull requests are the greatest contributions, so be sure they are focused in scope, and do avoid unrelated commits.

💁Remember: size is the #1 priority.

Every byte counts! PR's can't be merged if they increase the output size much.

• Fork it!
• Clone your fork:git clone https://github.com/<your-username>/unfetch
• Navigate to the newly cloned directory:cd unfetch
• Create a new branch for the new feature:git checkout -b my-new-feature
• Install the tools necessary for development:npm install
• Make your changes.
• npm run build to verify your change doesn't increase output size.
• npm test to make sure your change doesn't break anything.
• Commit your changes:git commit -am 'Add some feature'
• Push to the branch:git push origin my-new-feature
• Submit a pull request with full remarks documenting your changes.

MIT License ©Jason Miller