What is npm-registry-client?
The npm-registry-client package is a client for interacting with the npm registry. It allows you to perform various operations such as fetching package metadata, publishing packages, and managing package versions.
What are npm-registry-client's main functionalities?
Fetching Package Metadata
This feature allows you to fetch metadata for a specific package from the npm registry. The code sample demonstrates how to fetch metadata for the 'npm' package.
const NpmRegistryClient = require('npm-registry-client');
const client = new NpmRegistryClient();
const uri = 'https://registry.npmjs.org/npm';
client.get(uri, {}, (error, data, raw, res) => {
if (error) {
console.error(error);
} else {
console.log(data);
}
});
Publishing a Package
This feature allows you to publish a package to the npm registry. The code sample demonstrates how to publish a package named 'my-package' with version '1.0.0'.
const NpmRegistryClient = require('npm-registry-client');
const client = new NpmRegistryClient();
const uri = 'https://registry.npmjs.org/npm';
const params = { metadata: { name: 'my-package', version: '1.0.0' }, access: 'public' };
client.publish(uri, params, (error, data) => {
if (error) {
console.error(error);
} else {
console.log('Package published successfully');
}
});
Managing Package Versions
This feature allows you to manage and list the available versions of a package. The code sample demonstrates how to list all available versions of the 'npm' package.
const NpmRegistryClient = require('npm-registry-client');
const client = new NpmRegistryClient();
const uri = 'https://registry.npmjs.org/npm';
client.get(uri, {}, (error, data) => {
if (error) {
console.error(error);
} else {
console.log('Available versions:', Object.keys(data.versions));
}
});
Other packages similar to npm-registry-client
npm
The 'npm' package itself provides a command-line interface for interacting with the npm registry. It offers a wide range of functionalities including installing packages, publishing packages, and managing dependencies. Compared to npm-registry-client, it is more comprehensive and user-friendly for general use.
yarn
Yarn is a package manager that also interacts with the npm registry. It offers similar functionalities such as installing, publishing, and managing packages. Yarn is known for its speed and reliability, and it provides a different workflow compared to npm-registry-client.
pnpm
pnpm is another package manager that interacts with the npm registry. It is designed to be fast and efficient, with a unique approach to managing node_modules. Compared to npm-registry-client, pnpm focuses on performance and disk space optimization.
npm-registry-client
The code that npm uses to talk to the registry.
It handles all the caching and HTTP calls.
Usage
var RegClient = require('npm-registry-client')
var client = new RegClient(config)
var uri = "https://registry.npmjs.org/npm"
var params = {timeout: 1000}
client.get(uri, params, function (error, data, raw, res) {
})
Registry URLs
The registry calls take either a full URL pointing to a resource in the
registry, or a base URL for the registry as a whole (including the registry
path – but be sure to terminate the path with /
). http
and https
URLs are
the only ones supported.
Using the client
Every call to the client follows the same pattern:
uri
{String} The fully-qualified URI of the registry API method being
invoked.params
{Object} Per-request parameters.callback
{Function} Callback to be invoked when the call is complete.
Credentials
Many requests to the registry can be authenticated, and require credentials
for authorization. These credentials always look the same:
username
{String}password
{String}email
{String}alwaysAuth
{Boolean} Whether calls to the target registry are always
authed.
or
token
{String}alwaysAuth
{Boolean} Whether calls to the target registry are always
authed.
Requests
As of npm-registry-client@8
, all requests are made with an Accept
header
of application/vnd.npm.install-v1+json; q=1.0, application/json; q=0.8, */*
.
This enables filtered document responses to requests for package metadata.
You know that you got a filtered response if the mime type is set to
application/vnd.npm.install-v1+json
and not application/json
.
This filtering substantially reduces the over all data size. For example
for https://registry.npmjs.org/npm
, the compressed metadata goes from
410kB to 21kB.
API
client.access(uri, params, cb)
uri
{String} Registry URL for the package's access API endpoint.
Looks like /-/package/<package name>/access
.params
{Object} Object containing per-request properties.
access
{String} New access level for the package. Can be either
public
or restricted
. Registry will raise an error if trying
to change the access level of an unscoped package.auth
{Credentials}
Set the access level for scoped packages. For now, there are only two
access levels: "public" and "restricted".
client.adduser(uri, params, cb)
uri
{String} Base registry URL.params
{Object} Object containing per-request properties.
cb
{Function}
error
{Error | null}data
{Object} the parsed data objectraw
{String} the jsonres
{Response Object} response from couch
Add a user account to the registry, or verify the credentials.
client.deprecate(uri, params, cb)
uri
{String} Full registry URI for the deprecated package.params
{Object} Object containing per-request properties.
version
{String} Semver version range.message
{String} The message to use as a deprecation warning.auth
{Credentials}
cb
{Function}
Deprecate a version of a package in the registry.
client.distTags.fetch(uri, params, cb)
uri
{String} Base URL for the registry.params
{Object} Object containing per-request properties.
package
{String} Name of the package.auth
{Credentials}
cb
{Function}
Fetch all of the dist-tags
for the named package.
client.distTags.add(uri, params, cb)
uri
{String} Base URL for the registry.params
{Object} Object containing per-request properties.
package
{String} Name of the package.distTag
{String} Name of the new dist-tag
.version
{String} Exact version to be mapped to the dist-tag
.auth
{Credentials}
cb
{Function}
Add (or replace) a single dist-tag onto the named package.
client.distTags.set(uri, params, cb)
uri
{String} Base URL for the registry.params
{Object} Object containing per-request properties.
package
{String} Name of the package.distTags
{Object} Object containing a map from tag names to package
versions.auth
{Credentials}
cb
{Function}
Set all of the dist-tags
for the named package at once, creating any
dist-tags
that do not already exist. Any dist-tags
not included in the
distTags
map will be removed.
client.distTags.update(uri, params, cb)
uri
{String} Base URL for the registry.params
{Object} Object containing per-request properties.
package
{String} Name of the package.distTags
{Object} Object containing a map from tag names to package
versions.auth
{Credentials}
cb
{Function}
Update the values of multiple dist-tags
, creating any dist-tags
that do
not already exist. Any pre-existing dist-tags
not included in the distTags
map will be left alone.
client.distTags.rm(uri, params, cb)
uri
{String} Base URL for the registry.params
{Object} Object containing per-request properties.
package
{String} Name of the package.distTag
{String} Name of the new dist-tag
.auth
{Credentials}
cb
{Function}
Remove a single dist-tag
from the named package.
client.get(uri, params, cb)
uri
{String} The complete registry URI to fetchparams
{Object} Object containing per-request properties.
timeout
{Number} Duration before the request times out. Optional
(default: never).follow
{Boolean} Follow 302/301 responses. Optional (default: true).staleOk
{Boolean} If there's cached data available, then return that to
the callback quickly, and update the cache the background. Optional
(default: false).auth
{Credentials} Optional.
cb
{Function}
Fetches data from the registry via a GET request, saving it in the cache folder
with the ETag or the "Last Modified" timestamp.
client.publish(uri, params, cb)
uri
{String} The registry URI for the package to publish.params
{Object} Object containing per-request properties.
metadata
{Object} Package metadata.access
{String} Access for the package. Can be public
or restricted
(no default).body
{Stream} Stream of the package body / tarball.auth
{Credentials}
cb
{Function}
Publish a package to the registry.
Note that this does not create the tarball from a folder.
client.sendAnonymousCLIMetrics(uri, params, cb)
uri
{String} Base URL for the registry.params
{Object} Object containing per-request properties.
metricId
{String} A uuid unique to this dataset.metrics
{Object} The metrics to share with the registry, with the following properties:
from
{Date} When the first data in this report was collected.to
{Date} When the last data in this report was collected. Usually right now.successfulInstalls
{Number} The number of successful installs in this period.failedInstalls
{Number} The number of installs that ended in error in this period.
cb
{Function}
PUT a metrics object to the /-/npm/anon-metrics/v1/
endpoint on the registry.
client.star(uri, params, cb)
uri
{String} The complete registry URI for the package to star.params
{Object} Object containing per-request properties.
starred
{Boolean} True to star the package, false to unstar it. Optional
(default: false).auth
{Credentials}
cb
{Function}
Star or unstar a package.
Note that the user does not have to be the package owner to star or unstar a
package, though other writes do require that the user be the package owner.
client.stars(uri, params, cb)
uri
{String} The base URL for the registry.params
{Object} Object containing per-request properties.
username
{String} Name of user to fetch starred packages for. Optional
(default: user in auth
).auth
{Credentials} Optional (required if username
is omitted).
cb
{Function}
View your own or another user's starred packages.
client.tag(uri, params, cb)
uri
{String} The complete registry URI to tagparams
{Object} Object containing per-request properties.
version
{String} Version to tag.tag
{String} Tag name to apply.auth
{Credentials}
cb
{Function}
Mark a version in the dist-tags
hash, so that pkg@tag
will fetch the
specified version.
client.unpublish(uri, params, cb)
uri
{String} The complete registry URI of the package to unpublish.params
{Object} Object containing per-request properties.
version
{String} version to unpublish. Optional – omit to unpublish all
versions.auth
{Credentials}
cb
{Function}
Remove a version of a package (or all versions) from the registry. When the
last version us unpublished, the entire document is removed from the database.
client.whoami(uri, params, cb)
uri
{String} The base registry for the URI.params
{Object} Object containing per-request properties.
cb
{Function}
Simple call to see who the registry thinks you are. Especially useful with
token-based auth.
PLUMBING
The below are primarily intended for use by the rest of the API, or by the npm
caching logic directly.
client.request(uri, params, cb)
uri
{String} URI pointing to the resource to request.params
{Object} Object containing per-request properties.
method
{String} HTTP method. Optional (default: "GET").body
{Stream | Buffer | String | Object} The request body. Objects
that are not Buffers or Streams are encoded as JSON. Optional – body
only used for write operations.etag
{String} The cached ETag. Optional.lastModified
{String} The cached Last-Modified timestamp. Optional.follow
{Boolean} Follow 302/301 responses. Optional (default: true).streaming
{Boolean} Stream the request body as it comes, handling error
responses in a non-streaming way.auth
{Credentials} Optional.
cb
{Function}
error
{Error | null}data
{Object} the parsed data objectraw
{String} the jsonres
{Response Object} response from couch
Make a generic request to the registry. All the other methods are wrappers
around client.request
.
client.fetch(uri, params, cb)
uri
{String} The complete registry URI to upload toparams
{Object} Object containing per-request properties.
headers
{Stream} HTTP headers to be included with the request. Optional.auth
{Credentials} Optional.
cb
{Function}
Fetch a package from a URL, with auth set appropriately if included. Used to
cache remote tarballs as well as request package tarballs from the registry.
Configuration
The client uses its own configuration, which is just passed in as a simple
nested object. The following are the supported values (with their defaults, if
any):
proxy.http
{URL} The URL to proxy HTTP requests through.proxy.https
{URL} The URL to proxy HTTPS requests through. Defaults to be
the same as proxy.http
if unset.proxy.localAddress
{IP} The local address to use on multi-homed systems.ssl.ca
{String} Certificate signing authority certificates to trust.ssl.certificate
{String} Client certificate (PEM encoded). Enable access
to servers that require client certificates.ssl.key
{String} Private key (PEM encoded) for client certificate.ssl.strict
{Boolean} Whether or not to be strict with SSL certificates.
Default = true
retry.count
{Number} Number of times to retry on GET failures. Default = 2.retry.factor
{Number} factor
setting for node-retry
. Default = 10.retry.minTimeout
{Number} minTimeout
setting for node-retry
.
Default = 10000 (10 seconds)retry.maxTimeout
{Number} maxTimeout
setting for node-retry
.
Default = 60000 (60 seconds)userAgent
{String} User agent header to send. Default =
"node/{process.version}"
log
{Object} The logger to use. Defaults to require("npmlog")
if
that works, otherwise logs are disabled.defaultTag
{String} The default tag to use when publishing new packages.
Default = "latest"
couchToken
{Object} A token for use with
couch-login.sessionToken
{String} A random identifier for this set of client requests.
Default = 8 random hexadecimal bytes.maxSockets
{Number} The maximum number of connections that will be open per
origin (unique combination of protocol:host:port). Passed to the
httpAgent.
Default = 50isFromCI
{Boolean} Identify to severs if this request is coming from CI (for statistics purposes).
Default = detected from environment– primarily this is done by looking for
the CI environment variable to be set to true
. Also accepted are the
existence of the JENKINS_URL
, bamboo.buildKey
and TDDIUM
environment
variables.scope
{String} The scope of the project this command is being run for. This is the
top level npm module in which a command was run.
Default = none