Security News
ESLint is Now Language-Agnostic: Linting JSON, Markdown, and Beyond
ESLint has added JSON and Markdown linting support with new officially-supported plugins, expanding its versatility beyond JavaScript.
npm-registry-fetch
Advanced tools
The npm-registry-fetch package is a utility that provides a simple interface to fetch resources from the npm registry. It is designed to handle various aspects of communication with the npm registry, such as handling authentication, customizing requests, and processing responses. This package is particularly useful for developers who need to interact programmatically with the npm registry to fetch package data, publish updates, or perform other registry-related tasks.
Fetching package metadata
This feature allows developers to fetch metadata about a package from the npm registry. The code sample demonstrates how to retrieve JSON data for the npm-registry-fetch package itself.
const fetch = require('npm-registry-fetch');
fetch.json('https://registry.npmjs.org/npm-registry-fetch').then(data => {
console.log(data);
}).catch(err => {
console.error('Error fetching package:', err);
});
Custom request options
This feature allows users to customize requests when interacting with the npm registry. The code sample shows how to set custom headers and request methods.
const fetch = require('npm-registry-fetch');
const opts = {
method: 'GET',
headers: {
'Content-Type': 'application/json'
}
};
fetch('https://registry.npmjs.org/npm-registry-fetch', opts).then(response => {
return response.json();
}).then(data => {
console.log(data);
}).catch(err => {
console.error('Error with custom request:', err);
});
The 'request' package is a simplified HTTP request client that supports numerous features for making HTTP calls. It is similar to npm-registry-fetch but is not specifically tailored for interacting with the npm registry. It offers broader HTTP request capabilities but lacks the specialized npm registry integration and convenience features that npm-registry-fetch provides.
Axios is a promise-based HTTP client for the browser and node.js. Like npm-registry-fetch, it can be used to make HTTP requests to any URL, including the npm registry. However, axios is more general-purpose and does not include built-in configurations or optimizations specifically for the npm registry, unlike npm-registry-fetch which is optimized for such interactions.
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
.
const npmFetch = require('npm-registry-fetch')
console.log(
await npmFetch.json('/-/ping')
)
$ npm install npm-registry-fetch
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!
write=true
query stringsBefore performing any PUT or DELETE operation, npm clients first make a
GET request to the registry resource being updated, which includes
the query string ?write=true
.
The semantics of this are, effectively, "I intend to write to this thing, and need to know the latest current value, so that my write can land cleanly".
The public npm registry handles these ?write=true
requests by ensuring
that the cache is re-validated before sending a response. In order to
maintain the same behavior on the client, and not get tripped up by an
overeager local cache when we intend to write data to the registry, any
request that comes through npm-registry-fetch
that contains write=true
in the query string will forcibly set the prefer-online
option to true
,
and set both prefer-offline
and offline
to false, so that any local
cached value will be revalidated.
> 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.
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.
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 JSONStream
s), has a valid
Symbol.asyncIterator
implementation.
For available options, please see the section on fetch
options.
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
OptionsFetch 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
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
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
to set the content-type to something else.
opts.ca
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.strictSSL
, opts.ca
and
opts.key
opts.cache
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
, preferOffline
,
and preferOnline
.
opts.cert
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
and opts.key
opts.fetchRetries
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.fetchRetryFactor
The "factor" config for retry
to use when fetching
packages.
See also opts.retry
to provide all retry options as a single
object.
opts.fetchRetryMintimeout
The "minTimeout" config for retry
to use when fetching
packages.
See also opts.retry
to provide all retry options as a single
object.
opts.fetchRetryMaxtimeout
The "maxTimeout" config for retry
to use when fetching
packages.
See also opts.retry
to provide all retry options as a single
object.
opts.forceAuth
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
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
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.ignoreBody
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
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.key
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
and opts.cert
opts.localAddress
The IP address of the local interface to use when making connections to the registry.
See also opts.proxy
opts.mapJSON
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
Maximum number of sockets to keep open during requests. Has no effect if
opts.agent
is used.
opts.method
HTTP method to use for the outgoing request. Case-insensitive.
opts.noProxy
If present, should be a comma-separated string or an array of domain extensions that a proxy should not be used for.
opts.npmSession
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.npmCommand
If provided, it will be sent in the npm-command
header. This header is
used by the npm registry to identify the npm command that caused this
request to be made.
opts.offline
Force offline mode: no network requests will be done during install. To allow
npm-registry-fetch
to fill in missing cache data, see
opts.preferOffline
.
This option is only really useful if you're also using
opts.cache
.
This option is set to true
when the request includes write=true
in the
query string.
opts.otp
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.otpPrompt
This is a method which will be called to provide an OTP if the server responds with a 401 response indicating that a one-time-password is required.
It may return a promise, which must resolve to the OTP value to be used. If the method fails to provide an OTP value, then the fetch will fail with the auth error that indicated an OTP was needed.
opts.password
_password
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'
}
See also opts.username
opts.preferOffline
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
.
This option is set to false
when the request includes write=true
in the
query string.
opts.preferOnline
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
.
This option is set to true
when the request includes write=true
in the
query string.
opts.scope
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
A proxy to use for outgoing http requests. If not passed in, the HTTP(S)_PROXY
environment variable will be used.
opts.query
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.registry
'https://registry.npmjs.org'
Registry configuration for a request. If a request URL only includes the URL path, this registry setting will be prepended.
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
Single-object configuration for request retry settings. If passed in, will
override individually-passed fetch-retry-*
settings.
opts.scope
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
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
npm-registry-arg
object.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.strictSSL
Whether or not to do SSL key validation when making requests to the registry via https.
See also opts.ca
.
opts.timeout
Time before a hanging request times out.
opts._authToken
Authentication token string.
Can be scoped to a registry by using a "nerf dart" for that registry. That is:
{
'//registry.npmjs.org/:_authToken': 't0k3nH34r'
}
opts.userAgent
'npm-registry-fetch@<version>/node@<node-version>+<arch> (<platform>)'
User agent string to send in the User-Agent
header.
opts.username
Username used for basic authentication. For the more modern authentication
method, please use the (more secure) opts.authtoken
Can optionally be scoped to a registry by using a "nerf dart" for that registry. That is:
{
'//registry.npmjs.org/:username': 't0k3nH34r'
}
See also opts.password
FAQs
Fetch-based http client for use with npm registry APIs
The npm package npm-registry-fetch receives a total of 5,900,432 weekly downloads. As such, npm-registry-fetch popularity was classified as popular.
We found that npm-registry-fetch demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 6 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
ESLint has added JSON and Markdown linting support with new officially-supported plugins, expanding its versatility beyond JavaScript.
Security News
Members Hub is conducting large-scale campaigns to artificially boost Discord server metrics, undermining community trust and platform integrity.
Security News
NIST has failed to meet its self-imposed deadline of clearing the NVD's backlog by the end of the fiscal year. Meanwhile, CVE's awaiting analysis have increased by 33% since June.