make-fetch-happen - npm Package Compare versions

Comparing version 0.0.0 to 1.0.0

package.json

 {
   "name": "make-fetch-happen",
-  "version": "0.0.0",
+  "version": "1.0.0",
   "description": "Opinionated, caching, retrying fetch client",
@@ -37,12 +37,10 @@ "main": "index.js",
     "bluebird": "^3.5.0",
-    "cacache": "^6.2.0",
+    "cacache": "^6.3.0",
     "checksum-stream": "^1.0.2",
     "lru-cache": "^4.0.2",
     "mississippi": "^1.2.0",
-    "npm-registry-client": "^7.4.6",
-    "osenv": "^0.1.4",
-    "promise-inflight": "^1.0.1",
+    "node-fetch": "^2.0.0-alpha.3",
+    "promise-retry": "^1.1.1",
     "proxy-agent": "^2.0.0",
-    "realize-package-specifier": "^3.0.3",
-    "request": "^2.81.0"
+    "safe-buffer": "^5.0.1"
   },
@@ -49,0 +47,0 @@ "devDependencies": {

README.md

 # make-fetch-happen [![npm version](https://img.shields.io/npm/v/make-fetch-happen.svg)](https://npm.im/make-fetch-happen) [![license](https://img.shields.io/npm/l/make-fetch-happen.svg)](https://npm.im/make-fetch-happen) [![Travis](https://img.shields.io/travis/zkat/make-fetch-happen.svg)](https://travis-ci.org/zkat/make-fetch-happen) [![AppVeyor](https://ci.appveyor.com/api/projects/status/github/zkat/make-fetch-happen?svg=true)](https://ci.appveyor.com/project/zkat/make-fetch-happen) [![Coverage Status](https://coveralls.io/repos/github/zkat/make-fetch-happen/badge.svg?branch=latest)](https://coveralls.io/github/zkat/make-fetch-happen?branch=latest)
 
 
-**NOTE: this package is still under heavy development. Please don't use it yet**
+[`make-fetch-happen`](https://github.com/zkat/make-fetch-happen) is a Node.js library that implements the [`fetch` API](https://fetch.spec.whatwg.org/), including cache support, request pooling, proxies, retries, and more!
 
-[`make-fetch-happen`](https://github.com/zkat/make-fetch-happen) is a Node.js library that implements the [`fetch` API](https://fetch.spec.whatwg.org/) in a Node.js-specific way while still providing a lot of the bells and whistles of the standard.
-
 ## Install
@@ -17,2 +15,12 @@
 * [Contributing](#contributing)
+* [API](#api)
+  * [`fetch`](#fetch)
+  * [`node-fetch` options](#node-fetch-options)
+  * [`make-fetch-happen` options](#extra-options)
+    * [`opts.cacheManager`](#opts-cache-manager)
+    * [`opts.cache`](#opts-cache)
+    * [`opts.proxy`](#opts-proxy)
+    * [`opts.retry`](#opts-retry)
+    * [`opts.integrity`](#opts-integrity)
+* [Message From Our Sponsors](#wow)
 
@@ -22,2 +30,18 @@ ### Example
 ```javascript
+const fetch = require('make-fetch-happen')
+
+fetch('https://registry.npmjs.org/make-fetch-happen', {
+  cacheManager: './my-cache' // cache will be written here
+}).then(res => res.json()).then(body => {
+  console.log(`got ${body.name} from web`)
+  return fetch('https://registry.npmjs.org/make-fetch-happen', {
+    cacheManager: './my-cache',
+    cache: 'no-cache' // forces a conditional request
+  })
+}).then(res => {
+  console.log(res.status) // 304! cache validated!
+  return res.json().then(body => {
+    console.log(`got ${body.name} from cache`)
+  })
+})
 ```
@@ -27,10 +51,13 @@
 
-* Mostly spec-compliant
-* Pretty darn fast
+* Follows `fetch` spec, using [`node-fetch`](https://npm.im/node-fetch) under the hood.
 * Request pooling out of the box
-* Proxy support
-* Built-in optional disk-based caching, using standard HTTP caching rules
-* [Subresource Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) support
-* Streaming support based on Node.js streams
+* Quite fast, really
+* Automatic HTTP-semantics-aware request retries
+* Proxy support (http, https, socks, socks4, socks5, pac)
+* Built-in request caching following full HTTP caching rules (`Cache-Control`, `ETag`, `304`s, cache fallback on error, etc).
+* Customize cache storage with any [Cache API](https://developer.mozilla.org/en-US/docs/Web/API/Cache)-compliant `Cache` instance. Cache to Redis!
+* Node.js Stream support
 * Transparent gzip and deflate support
+* (PENDING) Range request caching and resuming
+* (PENDING) [Subresource Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) support
 
@@ -40,1 +67,221 @@ ### Contributing
 The make-fetch-happen team enthusiastically welcomes contributions and project participation! There's a bunch of things you can do if you want to contribute! The [Contributor Guide](CONTRIBUTING.md) has all the information you need for everything from reporting bugs to contributing entire new features. Please don't hesitate to jump in if you'd like to, or even ask us questions if something isn't clear.
+
+### API
+
+#### <a name="fetch"></a> `> fetch(uriOrRequest, [opts]) -> Promise<Response>`
+
+This function implements most of the [`fetch` API](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch): given a `uri` string or a `Request` instance, it will fire off an http request and return a Promise containing the relevant response.
+
+If `opts` is provided, the [`node-fetch`-specific options](#node-fetch-options) will be passed to that library. There are also [additional options](#extra-options) specific to make-fetch-happen that add various features, such as HTTP caching, integrity verification, proxy support, and more.
+
+##### Example
+
+```javascript
+fetch('https://google.com').then(res => res.buffer())
+```
+
+#### <a name="node-fetch-options"></a> `> node-fetch options`
+
+The following options for `node-fetch` are used as-is:
+
+* method
+* body
+* redirect
+* follow
+* timeout
+* compress
+* size
+
+These other options are modified or augmented by make-fetch-happen:
+
+* headers - Default `User-Agent` set to make-fetch happen. `Connection` is set to `keep-alive` or `close` automatically depending on `opts.agent`.
+* agent
+  * If agent is null, an http or https Agent will be automatically used. By default, these will be `http.globalAgent` and `https.globalAgent`.
+  * If [`opts.proxy`](#opts-proxy) is provided and `opts.agent` is null, the agent will be set to a [`proxy-agent`](https://npm.im/proxy-agent) instance.
+  * If `opts.agent` is `false` or an object is provided, it will be used as the request-pooling agent for this request.
+
+For more details, see [the documentation for `node-fetch` itself](https://github.com/bitinn/node-fetch#options).
+
+#### <a name="extra-options"></a> `> make-fetch-happen options`
+
+make-fetch-happen augments the `node-fetch` API with additional features available through extra options. The following extra options are available:
+
+* [`opts.cacheManager`](#opts-cache-manager) - Cache target to read/write
+* [`opts.cache`](#opts-cache) - `fetch` cache mode. Controls cache *behavior*.
+* [`opts.proxy`](#opts-proxy) - Proxy agent
+* [`opts.retry`](#opts-retry) - Request retry settings
+* [`opts.integrity`](#opts-integrity) - [Subresource Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) metadata.
+
+#### <a name="opts-cache-manager"></a> `> opts.cacheManager`
+
+Either a `String` or a `Cache`. If the former, it will be assumed to be a `Path` to be used as the cache root for [`cacache`](https://npm.im/cacache).
+
+If an object is provided, it will be assumed to be a compliant [`Cache` instance](https://developer.mozilla.org/en-US/docs/Web/API/Cache). Only `Cache.match()`, `Cache.put()`, and `Cache.delete()` are required. Options objects will not be passed in to `match()` or `delete()`.
+
+By implementing this API, you can customize the storage backend for make-fetch-happen itself -- for example, you could implement a cache that uses `redis` for caching, or simply keeps everything in memory. Most of the caching logic exists entirely on the make-fetch-happen side, so the only thing you need to worry about is reading, writing, and deleting, as well as making sure `fetch.Response` objects are what gets returned.
+
+You can refer to `cache.js` in the make-fetch-happen source code for a reference implementation.
+
+##### Example
+
+```javascript
+fetch('https://registry.npmjs.org/make-fetch-happen', {
+  cacheManager: './my-local-cache'
+}) // -> 200-level response will be written to disk
+
+fetch('https://npm.im/cacache', {
+  cacheManager: new MyCustomRedisCache(process.env.PORT)
+}) // -> 200-level response will be written to redis
+```
+
+A possible (minimal) implementation for `MyCustomRedisCache`:
+
+```javascript
+const bluebird = require('bluebird')
+const redis = require("redis")
+bluebird.promisifyAll(redis.RedisClient.prototype)
+class MyCustomRedisCache {
+  constructor (opts) {
+    this.redis = redis.createClient(opts)
+  }
+  match (req) {
+    return this.redis.getAsync(req.url).then(res => {
+      if (res) {
+        const parsed = JSON.parse(res)
+        return new fetch.Response(parsed.body, {
+          url: req.url,
+          headers: parsed.headers,
+          status: 200
+        })
+      }
+    })
+  }
+  put (req, res) {
+    return res.buffer().then(body => {
+      return this.redis.setAsync(req.url, JSON.stringify({
+        body: body,
+        headers: res.headers.raw()
+      }))
+    }).then(() => {
+      // return the response itself
+      return res
+    })
+  }
+  'delete' (req) {
+    return this.redis.unlinkAsync(req.url)
+  }
+}
+```
+
+#### <a name="opts-cache"></a> `> opts.cache`
+
+This option follows the standard `fetch` API cache option. This option will do nothing if [`opts.cacheManager`](#opts-cache-manager) is null. The following values are accepted (as strings):
+
+* `default` - Fetch will inspect the HTTP cache on the way to the network. If there is a fresh response it will be used. If there is a stale response a conditional request will be created, and a normal request otherwise. It then updates the HTTP cache with the response.
+* `no-store` - Fetch behaves as if there is no HTTP cache at all.
+* `reload` - Fetch behaves as if there is no HTTP cache on the way to the network. Ergo, it creates a normal request and updates the HTTP cache with the response.
+* `no-cache` - Fetch creates a conditional request if there is a response in the HTTP cache and a normal request otherwise. It then updates the HTTP cache with the response.
+* `force-cache` - Fetch uses any response in the HTTP cache matching the request, not paying attention to staleness. If there was no response, it creates a normal request and updates the HTTP cache with the response.
+* `only-if-cached` - Fetch uses any response in the HTTP cache matching the request, not paying attention to staleness. If there was no response, it returns a network error. (Can only be used when request’s mode is "same-origin". Any cached redirects will be followed assuming request’s redirect mode is "follow" and the redirects do not violate request’s mode.)
+
+(Note: option descriptions are taken from https://fetch.spec.whatwg.org/#http-network-or-cache-fetch)
+
+##### Example
+
+```javascript
+// Will error with ENOTCACHED if we haven't already cached this url
+fetch('https://registry.npmjs.org/make-fetch-happen', {
+  cacheManager: './my-cache',
+  cache: 'only-if-cached'
+})
+
+// Will refresh any local content and cache the new response
+fetch('https://registry.npmjs.org/make-fetch-happen', {
+  cacheManager: './my-cache',
+  cache: 'reload'
+})
+
+// Will use any local data, even if stale. Otherwise, will hit network.
+fetch('https://registry.npmjs.org/make-fetch-happen', {
+  cacheManager: './my-cache',
+  cache: 'force-cache'
+})
+```
+
+#### <a name="opts-proxy"></a> `> opts.proxy`
+
+A string URI or an object with options to be passed directly to [`proxy-agent`](https://npm.im/proxy-agent). Options available may vary depending on the proxy type. Refer the `proxy-agent`'s documentation for more details.
+
+##### Example
+
+```javascript
+fetch('https://registry.npmjs.org/make-fetch-happen', {
+  proxy: 'https://corporate.yourcompany.proxy:4445'
+})
+
+fetch('https://registry.npmjs.org/make-fetch-happen', {
+  proxy: {
+    protocol: 'https:',
+    hostname: 'corporate.yourcompany.proxy',
+    port: 4445,
+    ca: process.env.CERTIFICATE_AUTHORITY
+  }
+})
+```
+
+#### <a name="opts-retry"></a> `> opts.retry`
+
+An object that can be used to tune request retry settings. Requests are retried if they result in a `500`-level http status, or if the request fails entirely with an error. make-fetch-happen will never retry `POST` requests - it will only retry idempotent requests (GET, HEAD, PUT, DELETE, PATCH, etc), and those only if `opts.body` is NOT a stream.
+
+If `opts.retry` is `false`, requests will never be retried.
+
+The following retry options are available:
+
+* retries
+* factor
+* minTimeout
+* maxTimeout
+* randomize
+
+For details on what each of these do, refer to the [`retry`](https://npm.im/retry) documentation.
+
+##### Example
+
+```javascript
+fetch('https://flaky.site.com', {
+  retry: {
+    retries: 10,
+    randomize: true
+  }
+})
+
+fetch('http://reliable.site.com', {
+  retry: false
+})
+```
+
+#### <a name="opts-integrity"></a> `> opts.integrity`
+
+**(NOT IMPLEMENTED YET)**
+
+Matches the response body against the given [Subresource Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) metadata. If verification fails, the request will fail with an `EBADCHECKSUM` error.
+
+`integrity` may either be a string or an [`ssri`](https://npm.im/ssri) Integrity-like.
+
+##### Example
+
+```javascript
+fetch('https://registry.npmjs.org/make-fetch-happen/-/make-fetch-happen-1.0.0.tgz', {
+  integrity: 'sha1-o47j7zAYnedYFn1dF/fR9OV3z8Q='
+}) // -> ok
+
+fetch('https://malicious-registry.org/make-fetch-happen/-/make-fetch-happen-1.0.0.tgz'. {
+  integrity: 'sha1-o47j7zAYnedYFn1dF/fR9OV3z8Q='
+}) // Error: EBADCHECKSUM
+```
+
+### <a name="wow"></a> Message From Our Sponsors
+
+![](stop.gif)
+
+![](happening.gif)

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Network access

Supply chain risk

This module accesses the network.

Found 3 instances in 1 package

Filesystem access

Supply chain risk

Accesses the file system, and could potentially read sensitive data.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Empty package

Supply chain risk

Package does not contain any code. It may be removed, is name squatting, or the result of a faulty package publish.

Found 1 instance in 1 package

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

33336

increased by758.07%

Dependency count

9

decreased by-18.18%

Number of package files

6

increased by100%

Lines of code

496

increased byInfinity%

Number of low quality alerts

1

decreased by-50%

Number of lines in readme file

284

increased by667.57%

Worsened metrics

Number of low supply chain risk alerts

2

increased by100%

Number of medium supply chain risk alerts

10

increased by900%

Dependency changes

• + Addednode-fetch@^2.0.0-alpha.3

• + Addedpromise-retry@^1.1.1

• + Addedsafe-buffer@^5.0.1

• + Addederr-code@1.1.2(transitive)

• + Addednode-fetch@2.7.0(transitive)

• + Addedpromise-retry@1.1.1(transitive)

• + Addedsafe-buffer@5.2.1(transitive)

• + Addedtr46@0.0.3(transitive)

• + Addedwebidl-conversions@3.0.1(transitive)

• + Addedwhatwg-url@5.0.0(transitive)

• - Removednpm-registry-client@^7.4.6

• - Removedosenv@^0.1.4

• - Removedpromise-inflight@^1.0.1

• - Removedrealize-package-specifier@^3.0.3

• - Removedrequest@^2.81.0

• - Removedajv@6.12.6(transitive)

• - Removedansi-regex@2.1.1(transitive)

• - Removedare-we-there-yet@1.1.7(transitive)

• - Removedasap@2.0.6(transitive)

• - Removedasn1@0.2.6(transitive)

• - Removedassert-plus@1.0.0(transitive)

• - Removedasynckit@0.4.0(transitive)

• - Removedaws-sign2@0.7.0(transitive)

• - Removedaws4@1.13.2(transitive)

• - Removedbcrypt-pbkdf@1.0.2(transitive)

• - Removedcaseless@0.12.0(transitive)

• - Removedcode-point-at@1.1.0(transitive)

• - Removedcombined-stream@1.0.8(transitive)

• - Removedconsole-control-strings@1.1.0(transitive)

• - Removedcore-util-is@1.0.2(transitive)

• - Removeddashdash@1.14.1(transitive)

• - Removeddelayed-stream@1.0.0(transitive)

• - Removeddelegates@1.0.0(transitive)

• - Removeddezalgo@1.0.4(transitive)

• - Removedecc-jsbn@0.1.2(transitive)

• - Removedextsprintf@1.3.0(transitive)

• - Removedfast-deep-equal@3.1.3(transitive)

• - Removedfast-json-stable-stringify@2.1.0(transitive)

• - Removedforever-agent@0.6.1(transitive)

• - Removedform-data@2.3.3(transitive)

• - Removedfunction-bind@1.1.2(transitive)

• - Removedgauge@2.7.4(transitive)

• - Removedgetpass@0.1.7(transitive)

• - Removedhar-schema@2.0.0(transitive)

• - Removedhar-validator@5.1.5(transitive)

• - Removedhas-unicode@2.0.1(transitive)

• - Removedhasown@2.0.2(transitive)

• - Removedhosted-git-info@2.8.9(transitive)

• - Removedhttp-signature@1.2.0(transitive)

• - Removedis-core-module@2.15.1(transitive)

• - Removedis-fullwidth-code-point@1.0.0(transitive)

• - Removedis-typedarray@1.0.0(transitive)

• - Removedisstream@0.1.2(transitive)

• - Removedjsbn@0.1.1(transitive)

• - Removedjson-schema@0.4.0(transitive)

• - Removedjson-schema-traverse@0.4.1(transitive)

• - Removedjson-stringify-safe@5.0.1(transitive)

• - Removedjsprim@1.4.2(transitive)

• - Removedmime-db@1.52.0(transitive)

• - Removedmime-types@2.1.35(transitive)

• - Removednormalize-package-data@2.5.0(transitive)

• - Removednpm-package-arg@4.2.1(transitive)

• - Removednpm-registry-client@7.5.0(transitive)

• - Removednpmlog@4.1.2(transitive)

• - Removednumber-is-nan@1.0.1(transitive)

• - Removedoauth-sign@0.9.0(transitive)

• - Removedobject-assign@4.1.1(transitive)

• - Removedos-homedir@1.0.2(transitive)

• - Removedos-tmpdir@1.0.2(transitive)

• - Removedosenv@0.1.5(transitive)

• - Removedpath-parse@1.0.7(transitive)

• - Removedperformance-now@2.1.0(transitive)

• - Removedpsl@1.9.0(transitive)

• - Removedpunycode@2.3.1(transitive)

• - Removedqs@6.5.3(transitive)

• - Removedrealize-package-specifier@3.0.3(transitive)

• - Removedrequest@2.88.2(transitive)

• - Removedresolve@1.22.8(transitive)

• - Removedsemver@5.7.2(transitive)

• - Removedset-blocking@2.0.0(transitive)

• - Removedsignal-exit@3.0.7(transitive)

• - Removedslide@1.1.6(transitive)

• - Removedspdx-correct@3.2.0(transitive)

• - Removedspdx-exceptions@2.5.0(transitive)

• - Removedspdx-expression-parse@3.0.1(transitive)

• - Removedspdx-license-ids@3.0.20(transitive)

• - Removedsshpk@1.18.0(transitive)

• - Removedstring-width@1.0.2(transitive)

• - Removedstrip-ansi@3.0.1(transitive)

• - Removedsupports-preserve-symlinks-flag@1.0.0(transitive)

• - Removedtough-cookie@2.5.0(transitive)

• - Removedtunnel-agent@0.6.0(transitive)

• - Removedtweetnacl@0.14.5(transitive)

• - Removeduri-js@4.4.1(transitive)

• - Removeduuid@3.4.0(transitive)

• - Removedvalidate-npm-package-license@3.0.4(transitive)

• - Removedverror@1.10.0(transitive)

• - Removedwide-align@1.1.5(transitive)

• Updatedcacache@^6.3.0