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

fetchiest

v1.0.1

Published

Fetch wrapper with retry and diagnosis capabilities.

Downloads

5

Readme

Features

  • Optionally retry failed queries a number of times before giving up.

  • Optionally diagnoses failed queries: network failure, server down, something else?

  • Times out queries.

Platforms Supported

This library is formally tested on:

  • the latest version of Chrome and Firefox

  • Edge 18

  • Safari 11, 10

If you need formal support for other platforms, or old browser versions, PRs are welcome.

Loading

Fetchiest is built with a stub that allows loading it as an AMD module or a CommonJS module.

Using Fetchiest

The module exports these items:

  • fetch(...) is a function that passes all its arguments to WHATWG's fetch. However, the 2nd argument may take options specific to fetchiest.

  • GeneralFetchiestError is a class that derives from JavaScript's stock Error. The following errors are derived from it.

  • TimeoutError is raised if the rejection was caused by a timeout.

  • ConnectivityError indicates a network problem. This class of error is never raised directly but is raised through its children:

    • BrowserOfflineError is raised if the browser is offline.

    • ServerDownError is raised if the server is down.

    • NetworkDownError is raised if the network is down.

Options

To set fetchiest's options, you can just add them to the RequestInit object passed to fetch, in a field named fetchiestOptions. (The 2nd argument.) For instance,

const rep = fetch("http://example.com", {
  fetchiestOptions: {
    tries: 3,
    diagnose: {
      serverURL: "...",
    },
  },
});

Fetchiest currently supports these options:

  • tries: the number of times to attempt the query. If unspecified, the default value is 1. Values less than 1 yield undefined behavior.

  • timeout: a timeout for each attempt, in milliseconds. If unspecified or set to 0, this means that there is no timeout. Negative values yield undefined behavior.

  • delay: a delay, in milliseconds, between each tries. If unspecified, the delay is 0. Negative delays yield undefined behavior.

  • diagnose is an object with the following keys:

    • inhibit: if set to a truthy value, this inhibits the diagnosis algorithm, and is equivalent to setting no options at all. This may be useful for debugging code without having to comment out code.

    • timeout: this is a timeout used when doing server checks. This is independent from the top level timeout parameter. The default is a half-second.

    • serverURL: a URL that used to test whether your server is running or not. We recommend making it a path that is inexpensive to serve. For instance, your internet-facing nginx instance could have a rule that serves 200 and no contents for GETs to /ping. Fetchiest uses this URL to double check whether your server is up.

    • knownServers: an array of URLs to known internet servers. Fetchiest uses these URLs to determine whether the Internet is accessible or not.

Diagnosis Rules

Diagnosis happens only if the final try for the request failed with a timeout or if fetch produced a rejected promise. Otherwise, no diagnosis occurs and the error is reported immediately.

Fetchiest uses the following rules when diagnosis is requested:

  1. If navigator.onLine is false, Fetchiest reports that the browser is offline.

  2. If a serverURL is specified, then it checks whether the server is responds to a GET at this URL:

A. If the server responds, Fetchiest reports the error that was reported by the last try.

B. If the server does not respond, Fetchiest reports the result of a connectivity check.

  1. If a serverURL was not specified, Fetchiest reports the result of a connectivity check.

Connectivity Check

  1. If knownServers does not exist or is an empty list, then it reports that the server appears to be down.

  2. Otherwise, Fetchiest contacts all the servers. If none of them respond, then it reports that the network appears to be down. Otherwise, it reports that the server appears to be down.

URL Checking Rules

For all URLs used in diagnosis, the URL is transformed prior to being used:

  1. If it has no query, then it is transformed by adding a query that is a single number corresponding to the current time.

  2. If it has a query, then it is transformed by adding a parameter named _ and having for value a number corresponding to the current time.

We do this to bust caches.

Developing Fetchiest

If you produce a pull request run npm test first to make sure they run clean. If you add features, do add tests.

Coverage

We need a Mocha run to test loading Fetchiest as a CommonJS module with script elements. The Karma run, which exercises over 95% of the code, uses RequireJS to load Fetchiest.

Ideally, we combine the results of the Karma runs with the result of the Mocha run. The problem though is that as we speak, karma-coverage uses Istanbul 0.4.x but to get coverage with Mocha with code that has run through Babel, we need Istanbul 1.0.0-alpha2 or higher. We've not been able to combine the formats produced by the various versions.

Testing

Browser Stack

Fetchiest is tested using BrowserStack. BrowserStack provides this service for free under their program for supporting open-source software.