FetchThrow.js

FetchThrow.js is a mixin for the Fetch API for browsers and Node.js that rejects the returned promise with a FetchError.js instance should the network request fail or the response have a status of at least 400 and less than 600 (as defined for error responses in the HTTP specs).

Installing

npm install fetch-throw

FetchThrow.js follows semantic versioning, so feel free to depend on its major version with something like >= 1.0.0 < 2 (a.k.a ^1.0.0).

If you'd like more convenient access to the thrown FetchError instance (e.g. for instanceof checks), also install fetch-error and ensure there's only one installed:

npm install fetch-error
npm dedupe fetch-error

Using

Wrap the native fetch function with the one from FetchThrow.js:

var fetch = require("fetch-throw")(global.fetch)

Then call the returned function as you would with the regular Fetch API:

var res = fetch("/models/42")

Should /models respond with 404, res will be rejected with an instance of FetchError. The FetchError property on FetchThrow is identical to doing require("fetch-error").

var FetchError = require("fetch-throw").FetchError

res.catch(function(err) {
  if (err instanceof FetchError) {
    var req = err.request
    console.error("%s %s failed: %s", req.method, req.url, err.message)
  }

  throw err
})

In case of unexpected errors (such as network name lookup failures) thrown by fetch before a request is made, res will also be rejected with an instance of FetchError. This allows you to identify failed requests for logging, for example, as shown above.

For a description of properties on the error, see below.

Browser

Browsers have the Fetch API available at window.fetch:

var fetch = require("fetch-throw")(window.fetch)
fetch("/models/42")

Node.js

Node.js doesn't have a built-in implementation of the Fetch API, but you can use any library with a compatible interface, such as my Fetch/Off.js or node-fetch:

var fetch = require("fetch-throw")(require("node-fetch"))
fetch("/models/42")

Properties on an instance of FetchError

License

FetchThrow.js is released under a Lesser GNU Affero General Public License, which in summary means:

• You can use this program for no cost.
• You can use this program for both personal and commercial reasons.
• You do not have to share your own program's code which uses this program.
• You have to share modifications (e.g. bug-fixes) you've made to this program.

For more convoluted language, see the LICENSE file.

About

Andri Möll typed this and the code.
Monday Calendar supported the engineering work.

If you find FetchThrow.js needs improving, please don't hesitate to type to me now at andri@dot.ee or create an issue online.

1.0.1 (Nov 17, 2016)

• Handles lack of Request class better.
  This could happen if there's a minimal Fetch API implementation, such as my Fetch/Off.js.

1.0.0 (Jul 31, 2016)

• Go and prosper!

0.3.2 (Dec 11, 2015)

• Sets response on FetchError if fetch rejects with an error that has it set.
  That's useful if middleware before FetchThrow.js tried to parse the JSON response, but threw a SyntaxError.

0.3.1 (Dec 10, 2015)

• Fixes throwing a FetchError if creating a Request itself throws.

0.3.0 (Dec 10, 2015)

• Renames to FetchThrow.
• Rejects all errors with FetchError.

0.2.0 (Dec 9, 2015)

• Rejects with FetchError instead of HttpError.
• Adds the request property (an instance of Request) with details of the request to the error.
• Rejects with FetchError also for network errors.
• Returns a new fetch function with all enumerable properties carried over.
  Handy if the given fetch function contains the otherwise global Headers, Request and Response objects.
• Exports the throwing fetch function.

0.1.337 (Aug 14, 2015)

• Scoped release for personal use and profit.