Elep

# npm-registry-fetch [![npm version](https://img.shields.io/npm/v/npm-registry-fetch.svg)](https://npm.im/npm-registry-fetch) [![license](https://img.shields.io/npm/l/npm-registry-fetch.svg)](https://npm.im/npm-registry-fetch) [![Travis](https://img.shields.io/travis/npm/npm-registry-fetch/latest.svg)](https://travis-ci.org/npm/npm-registry-fetch) [![AppVeyor](https://img.shields.io/appveyor/ci/zkat/npm-registry-fetch/latest.svg)](https://ci.appveyor.com/project/npm/npm-registry-fetch) [![Coverage Status](https://coveralls.io/repos/github/npm/npm-registry-fetch/badge.svg?branch=latest)](https://coveralls.io/github/npm/npm-registry-fetch?branch=latest)

[`npm-registry-fetch`](https://github.com/npm/npm-registry-fetch) is a Node.js
library that implements a `fetch`-like API for accessing npm registry APIs
consistently. It's able to consume npm-style configuration values and has all
the necessary logic for picking registries, handling scopes, and dealing with
authentication details built-in.

This package is meant to replace the older
[`npm-registry-client`](https://npm.im/npm-registry-client).

## Example

```javascript
const npmFetch = require('npm-registry-fetch')

console.log(
  await npmFetch.json('/-/ping')
)
```

## Table of Contents

* [Installing](#install)
* [Example](#example)
* [Contributing](#contributing)
* [API](#api)
  * [`fetch`](#fetch)
  * [`fetch.json`](#fetch-json)
  * [`fetch` options](#fetch-opts)

### Install

`$ npm install npm-registry-fetch`

### Contributing

The npm 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.

All participants and maintainers in this project are expected to follow [Code of
Conduct](CODE_OF_CONDUCT.md), and just generally be excellent to each other.

Please refer to the [Changelog](CHANGELOG.md) for project history details, too.

Happy hacking!

### API

#### <a name="fetch"></a> `> fetch(url, [opts]) -> Promise<Response>`

Performs a request to a given URL.

The URL can be either a full URL, or a path to one. The appropriate registry
will be automatically picked if only a URL path is given.

For available options, please see the section on [`fetch` options](#fetch-opts).

##### Example

```javascript
const res = await fetch('/-/ping')
console.log(res.headers)
res.on('data', d => console.log(d.toString('utf8')))
```

#### <a name="fetch-json"></a> `> fetch.json(url, [opts]) -> Promise<ResponseJSON>`

Performs a request to a given registry URL, parses the body of the response as
JSON, and returns it as its final value. This is a utility shorthand for
`fetch(url).then(res => res.json())`.

For available options, please see the section on [`fetch` options](#fetch-opts).

##### Example

```javascript
const res = await fetch.json('/-/ping')
console.log(res) // Body parsed as JSON
```

#### <a name="fetch-json-stream"></a> `> fetch.json.stream(url, jsonPath, [opts]) -> Stream`

Performs a request to a given registry URL and parses the body of the response
as JSON, with each entry being emitted through the stream.

The `jsonPath` argument is a [`JSONStream.parse()`
path](https://github.com/dominictarr/JSONStream#jsonstreamparsepath), and the
returned stream (unlike default `JSONStream`s), has a valid
`Symbol.asyncIterator` implementation.

For available options, please see the section on [`fetch` options](#fetch-opts).

##### Example

```javascript
console.log('https://npm.im/~zkat has access to the following packages:')
for await (let {key, value} of fetch.json.stream('/-/user/zkat/package', '$*')) {
  console.log(`https://npm.im/${key} (perms: ${value})`)
}
```

#### <a name="fetch-opts"></a> `fetch` Options

Fetch options are optional, and can be passed in as either a Map-like object
(one with a `.get()` method), a plain javascript object, or a
[`figgy-pudding`](https://npm.im/figgy-pudding) instance.

##### <a name="opts-agent"></a> `opts.agent`

* Type: http.Agent
* Default: an appropriate agent based on URL protocol and proxy settings

An [`Agent`](https://nodejs.org/api/http.html#http_class_http_agent) instance to
be shared across requests. This allows multiple concurrent `fetch` requests to
happen on the same socket.

You do _not_ need to provide this option unless you want something particularly
specialized, since proxy configurations and http/https agents are already
automatically managed internally when this option is not passed through.

##### <a name="opts-body"></a> `opts.body`

* Type: Buffer | Stream | Object
* Default: null

Request body to send through the outgoing request. Buffers and Streams will be
passed through as-is, with a default `content-type` of
`application/octet-stream`. Plain JavaScript objects will be `JSON.stringify`ed
and the `content-type` will default to `application/json`.

Use [`opts.headers`](#opts-headers) to set the content-type to something else.

##### <a name="opts-ca"></a> `opts.ca`

* Type: String, Array, or null
* Default: null

The Certificate Authority signing certificate that is trusted for SSL
connections to the registry. Values should be in PEM format (Windows calls it
"Base-64 encoded X.509 (.CER)") with newlines replaced by the string `'\n'`. For
example:

```
{
  ca: '-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----'
}
```

Set to `null` to only allow "known" registrars, or to a specific CA cert
to trust only that specific signing authority.

Multiple CAs can be trusted by specifying an array of certificates instead of a
single string.

See also [`opts.strict-ssl`](#opts-strict-ssl), [`opts.ca`](#opts-ca) and
[`opts.key`](#opts-key)

##### <a name="opts-cache"></a> `opts.cache`

* Type: path
* Default: null

The location of the http cache directory. If provided, certain cachable requests
will be cached according to [IETF RFC 7234](https://tools.ietf.org/html/rfc7234)
rules. This will speed up future requests, as well as make the cached data
available offline if necessary/requested.

See also [`offline`](#opts-offline), [`prefer-offline`](#opts-prefer-offline),
and [`prefer-online`](#opts-prefer-online).

##### <a name="opts-cert"></a> `opts.cert`

* Type: String
* Default: null

A client certificate to pass when accessing the registry.  Values should be in
PEM format (Windows calls it "Base-64 encoded X.509 (.CER)") with newlines
replaced by the string `'\n'`. For example:

```
{
  cert: '-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----'
}
```

It is _not_ the path to a certificate file (and there is no "certfile" option).

See also: [`opts.ca`](#opts-ca) and [`opts.key`](#opts-key)

##### <a name="opts-fetch-retries"></a> `opts.fetch-retries`

* Type: Number
* Default: 2

The "retries" config for [`retry`](https://npm.im/retry) to use when fetching
packages from the registry.

See also [`opts.retry`](#opts-retry) to provide all retry options as a single
object.

##### <a name="opts-fetch-retry-factor"></a> `opts.fetch-retry-factor`

* Type: Number
* Default: 10

The "factor" config for [`retry`](https://npm.im/retry) to use when fetching
packages.

See also [`opts.retry`](#opts-retry) to provide all retry options as a single
object.

##### <a name="opts-fetch-retry-mintimeout"></a> `opts.fetch-retry-mintimeout`

* Type: Number
* Default: 10000 (10 seconds)

The "minTimeout" config for [`retry`](https://npm.im/retry) to use when fetching
packages.

See also [`opts.retry`](#opts-retry) to provide all retry options as a single
object.

##### <a name="opts-fetch-retry-maxtimeout"></a> `opts.fetch-retry-maxtimeout`

* Type: Number
* Default: 60000 (1 minute)

The "maxTimeout" config for [`retry`](https://npm.im/retry) to use when fetching
packages.

See also [`opts.retry`](#opts-retry) to provide all retry options as a single
object.

##### <a name="opts-force-auth"></a> `opts.force-auth`

* Alias: `opts.forceAuth`
* Type: Object
* Default: null

If present, other auth-related values in `opts` will be completely ignored,
including `alwaysAuth`, `email`, and `otp`, when calculating auth for a request,
and the auth details in `opts.forceAuth` will be used instead.

##### <a name="opts-gzip"></a> `opts.gzip`

* Type: Boolean
* Default: false

If true, `npm-registry-fetch` will set the `Content-Encoding` header to `gzip`
and use `zlib.gzip()` or `zlib.createGzip()` to gzip-encode
[`opts.body`](#opts-body).

##### <a name="opts-headers"></a> `opts.headers`

* Type: Object
* Default: null

Additional headers for the outgoing request. This option can also be used to
override headers automatically generated by `npm-registry-fetch`, such as
`Content-Type`.

##### <a name="opts-ignore-body"></a> `opts.ignore-body`

* Alias: `opts.ignoreBody`
* Type: Boolean
* Default: false

If true, the **response body** will be thrown away and `res.body` set to `null`.
This will prevent dangling response sockets for requests where you don't usually
care what the response body is.

##### <a name="opts-integrity"></a> `opts.integrity`

* Type: String | [SRI object](https://npm.im/ssri)
* Default: null

If provided, the response body's will be verified against this integrity string,
using [`ssri`](https://npm.im/ssri). If verification succeeds, the response will
complete as normal. If verification fails, the response body will error with an
`EINTEGRITY` error.

Body integrity is only verified if the body is actually consumed to completion --
that is, if you use `res.json()`/`res.buffer()`, or if you consume the default
`res` stream data to its end.

Cached data will have its integrity automatically verified using the
previously-generated integrity hash for the saved request information, so
`EINTEGRITY` errors can happen if [`opts.cache`](#opts-cache) is used, even if
`opts.integrity` is not passed in.

##### <a name='opts-is-from-ci'></a> `opts.is-from-ci`

* Alias: `opts.isFromCI`
* Type: Boolean
* Default: Based on environment variables

This is used to populate the `npm-in-ci` request header sent to the registry.

##### <a name="opts-key"></a> `opts.key`

* Type: String
* Default: null

A client key to pass when accessing the registry.  Values should be in PEM
format with newlines replaced by the string `'\n'`. For example:

```
{
  key: '-----BEGIN PRIVATE KEY-----\nXXXX\nXXXX\n-----END PRIVATE KEY-----'
}
```

It is _not_ the path to a key file (and there is no "keyfile" option).

See also: [`opts.ca`](#opts-ca) and [`opts.cert`](#opts-cert)

##### <a name="opts-local-address"></a> `opts.local-address`

* Type: IP Address String
* Default: null

The IP address of the local interface to use when making connections
to the registry.