npm-registry-fetch

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.

Example

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

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

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 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, and just generally be excellent to each other.

Please refer to the Changelog for project history details, too.

Happy hacking!

API

`> 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.

Example

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

`> 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.

Example

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

`> 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, and the returned stream (unlike default JSONStreams), has a valid Symbol.asyncIterator implementation.

For available options, please see the section on fetch options.

Example

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})`)
}

`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 instance.

`opts.agent`

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

An 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.

`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.stringifyed and the content-type will default to application/json.

Use opts.headers to set the content-type to something else.

`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.ca and opts.key

`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 rules. This will speed up future requests, as well as make the cached data available offline if necessary/requested.

See also offline, prefer-offline, and prefer-online.

`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).

`opts.fetch-retries`

Type: Number
Default: 2

The "retries" config for retry to use when fetching packages from the registry.

See also opts.retry to provide all retry options as a single object.

`opts.fetch-retry-factor`

Type: Number
Default: 10

The "factor" config for retry to use when fetching packages.

See also opts.retry to provide all retry options as a single object.

`opts.fetch-retry-mintimeout`

Type: Number
Default: 10000 (10 seconds)

The "minTimeout" config for retry to use when fetching packages.

See also opts.retry to provide all retry options as a single object.

`opts.fetch-retry-maxtimeout`

Type: Number
Default: 60000 (1 minute)

The "maxTimeout" config for retry to use when fetching packages.

See also opts.retry to provide all retry options as a single object.

`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.

`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.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.

`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.

`opts.integrity`

Type: String | SRI object
Default: null

If provided, the response body's will be verified against this integrity string, using 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 is used, even if opts.integrity is not passed in.

`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.

`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).

`opts.local-address`

Type: IP Address String
Default: null

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

`opts.log`

Type: npmlog-like
Default: null

Logger object to use for logging operation details. Must have the same methods as npmlog.

`opts.map-json`

Alias: mapJson, mapJSON
Type: Function
Default: undefined

When using fetch.json.stream() (NOT fetch.json()), this will be passed down to JSONStream as the second argument to JSONStream.parse, and can be used to transform stream data before output.

`opts.maxsockets`

Alias: opts.max-sockets
Type: Integer
Default: 12

Maximum number of sockets to keep open during requests. Has no effect if opts.agent is used.

`opts.method`

Type: String
Default: 'GET'

HTTP method to use for the outgoing request. Case-insensitive.

`opts.noproxy`

Type: Boolean
Default: process.env.NOPROXY

If true, proxying will be disabled even if opts.proxy is used.

`opts.npm-session`

Alias: opts.npmSession
Type: String
Default: null

If provided, will be sent in the npm-session header. This header is used by the npm registry to identify individual user sessions (usually individual invocations of the CLI).

`opts.offline`

Type: Boolean
Default: false

Force offline mode: no network requests will be done during install. To allow npm-registry-fetch to fill in missing cache data, see opts.prefer-offline.

This option is only really useful if you're also using opts.cache.

`opts.otp`

Type: Number | String
Default: null

This is a one-time password from a two-factor authenticator. It is required for certain registry interactions when two-factor auth is enabled for a user account.

`opts.password`

Alias: _password
Type: String
Default: null

Password used for basic authentication. For the more modern authentication method, please use the (more secure) opts.token

Can optionally be scoped to a registry by using a "nerf dart" for that registry. That is:

{
  '//registry.npmjs.org/:password': 't0k3nH34r'
}

`opts.prefer-offline`

Type: Boolean
Default: false

If true, staleness checks for cached data will be bypassed, but missing data will be requested from the server. To force full offline mode, use opts.offline.

This option is generally only useful if you're also using opts.cache.

`opts.prefer-online`

Type: Boolean
Default: false

If true, staleness checks for cached data will be forced, making the CLI look for updates immediately even for fresh package data.

This option is generally only useful if you're also using opts.cache.

`opts.project-scope`

Alias: opts.projectScope
Type: String
Default: null

If provided, will be sent in the npm-scope header. This header is used by the npm registry to identify the toplevel package scope that a particular project installation is using.

`opts.proxy`

Type: url
Default: null

A proxy to use for outgoing http requests. If not passed in, the HTTP(S)_PROXY environment variable will be used.

`opts.query`

Type: String | Object
Default: null

If provided, the request URI will have a query string appended to it using this query. If opts.query is an object, it will be converted to a query string using querystring.stringify().

If the request URI already has a query string, it will be merged with opts.query, preferring opts.query values.

`opts.refer`

Alias: opts.referer
Type: String
Default: null

Value to use for the Referer header. The npm CLI itself uses this to serialize the npm command line using the given request.

`opts.registry`

Type: URL
Default: 'https://registry.npmjs.org'

Registry configuration for a request. If a request URL only includes the URL path, this registry setting will be prepended. This configuration is also used to determine authentication details, so even if the request URL references a completely different host, opts.registry will be used to find the auth details for that request.

See also opts.scope, opts.spec, and opts.<scope>:registry which can all affect the actual registry URL used by the outgoing request.

`opts.retry`

Type: Object
Default: null

Single-object configuration for request retry settings. If passed in, will override individually-passed fetch-retry-* settings.

`opts.scope`

Type: String
Default: null

Associate an operation with a scope for a scoped registry. This option can force lookup of scope-specific registries and authentication.

See also opts.<scope>:registry and opts.spec for interactions with this option.

`opts.<scope>:registry`

Type: String
Default: null

This option type can be used to configure the registry used for requests involving a particular scope. For example, opts['@myscope:registry'] = 'https://scope-specific.registry/' will make it so requests go out to this registry instead of opts.registry when opts.scope is used, or when opts.spec is a scoped package spec.

The @ before the scope name is optional, but recommended.

`opts.spec`

Type: String | npm-registry-arg object.
Default: null

If provided, can be used to automatically configure opts.scope based on a specific package name. Non-registry package specs will throw an error.

`opts.strict-ssl`

Type: Boolean
Default: true

Whether or not to do SSL key validation when making requests to the registry via https.

`opts.timeout`

Type: Milliseconds
Default: 30000 (30 seconds)

Time before a hanging request times out.

`opts.token`

Alias: opts._authToken
Type: String
Default: null

Authentication token string.

Can be scoped to a registry by using a "nerf dart" for that registry. That is:

{
  '//registry.npmjs.org/:token': 't0k3nH34r'
}

`opts.user-agent`

Type: String
Default: 'npm-registry-fetch@<version>/node@<node-version>+<arch> (<platform>)'

User agent string to send in the User-Agent header.

`opts.username`

Type: String
Default: null

Username used for basic authentication. For the more modern authentication method, please use the (more secure) opts.token

Can optionally be scoped to a registry by using a "nerf dart" for that registry. That is:

{
  '//registry.npmjs.org/:username': 't0k3nH34r'
}

`opts._auth`

Type: String
Default: null

** DEPRECATED ** This is a legacy authentication token supported only for *compatibility. Please use opts.token instead.

Name		Name	Last commit message	Last commit date
Latest commit History 85 Commits
test		test
.gitignore		.gitignore
.travis.yml		.travis.yml
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
ISSUE_TEMPLATE		ISSUE_TEMPLATE
LICENSE.md		LICENSE.md
PULL_REQUEST_TEMPLATE		PULL_REQUEST_TEMPLATE
README.md		README.md
appveyor.yml		appveyor.yml
auth.js		auth.js
check-response.js		check-response.js
config.js		config.js
errors.js		errors.js
index.js		index.js
package-lock.json		package-lock.json
package.json		package.json
silentlog.js		silentlog.js

License

evocateur/npm-registry-fetch

Folders and files

Latest commit

History

Repository files navigation

npm-registry-fetch

Example

Table of Contents

Install

Contributing

API

> fetch(url, [opts]) -> Promise<Response>

Example

> fetch.json(url, [opts]) -> Promise<ResponseJSON>

Example

> fetch.json.stream(url, jsonPath, [opts]) -> Stream

Example

fetch Options

opts.agent

opts.body

opts.ca

opts.cache

opts.cert

opts.fetch-retries

opts.fetch-retry-factor

opts.fetch-retry-mintimeout

opts.fetch-retry-maxtimeout

opts.force-auth

opts.gzip

opts.headers

opts.ignore-body

opts.integrity

opts.is-from-ci

opts.key

opts.local-address

opts.log

opts.map-json

opts.maxsockets

opts.method

opts.noproxy

opts.npm-session

opts.offline

opts.otp

opts.password

opts.prefer-offline

opts.prefer-online

opts.project-scope

opts.proxy

opts.query

opts.refer

opts.registry

opts.retry

opts.scope

opts.<scope>:registry

opts.spec

opts.strict-ssl

opts.timeout

opts.token

opts.user-agent

opts.username

opts._auth

About

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases

Packages 0

Languages

`> fetch(url, [opts]) -> Promise<Response>`

`> fetch.json(url, [opts]) -> Promise<ResponseJSON>`

`> fetch.json.stream(url, jsonPath, [opts]) -> Stream`

`fetch` Options

`opts.agent`

`opts.body`

`opts.ca`

`opts.cache`

`opts.cert`

`opts.fetch-retries`

`opts.fetch-retry-factor`

`opts.fetch-retry-mintimeout`

`opts.fetch-retry-maxtimeout`

`opts.force-auth`

`opts.gzip`

`opts.headers`

`opts.ignore-body`

`opts.integrity`

`opts.is-from-ci`

`opts.key`

`opts.local-address`

`opts.log`

`opts.map-json`

`opts.maxsockets`

`opts.method`

`opts.noproxy`

`opts.npm-session`

`opts.offline`

`opts.otp`

`opts.password`

`opts.prefer-offline`

`opts.prefer-online`

`opts.project-scope`

`opts.proxy`

`opts.query`

`opts.refer`

`opts.registry`

`opts.retry`

`opts.scope`

`opts.<scope>:registry`

`opts.spec`

`opts.strict-ssl`

`opts.timeout`

`opts.token`

`opts.user-agent`

`opts.username`

`opts._auth`

Packages