• This repository has been archived on 11/Aug/2021
  • Stars
    star
    264
  • Rank 155,103 (Top 4 %)
  • Language
    JavaScript
  • License
    ISC License
  • Created over 12 years ago
  • Updated over 3 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

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) {
  // error is an error if there was a problem.
  // data is the parsed data object
  // raw is the json string
  // res is the response from couch
})

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.
    • auth {Credentials}
  • cb {Function}
    • error {Error | null}
    • data {Object} the parsed data object
    • raw {String} the json
    • res {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 fetch
  • params {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.
    • fullMetadata {Boolean} If true, don't attempt to fetch filtered ("corgi") registry metadata. (default: false)
  • 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 tag
  • params {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.
    • auth {Credentials}
  • 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 object
    • raw {String} the json
    • res {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 to
  • params {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.retries {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 = 50
  • isFromCI {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

More Repositories

1

npm

This repository is moving to: https://github.com/npm/cli
17,473
star
2

cli

the package manager for JavaScript
JavaScript
8,303
star
3

node-semver

The semver parser for node (the one npm uses)
JavaScript
4,772
star
4

npm-expansions

Send us a pull request by editing expansions.txt
JavaScript
2,209
star
5

tink

a dependency unwinder for javascript
JavaScript
2,153
star
6

ini

An ini parser/serializer in JavaScript
JavaScript
733
star
7

npx

npm package executor
JavaScript
731
star
8

rfcs

Public change requests/proposals & ideation
JavaScript
726
star
9

npm-registry-couchapp

couchapp bits of registry.npmjs.org
JavaScript
615
star
10

nopt

Node/npm Option Parsing
JavaScript
527
star
11

registry

npm registry documentation
449
star
12

npmlog

The logger that npm uses
JavaScript
423
star
13

marky-markdown

npm's markdown parser
JavaScript
405
star
14

arborist

npm's tree doctor
JavaScript
369
star
15

documentation

Documentation for the npm registry, website, and command-line interface.
MDX
369
star
16

pacote

npm fetcher
JavaScript
349
star
17

download-counts

Background jobs and a minimal service for collecting and delivering download counts
JavaScript
328
star
18

gauge

A terminal based horizontal guage aka, a progress bar
JavaScript
319
star
19

node-which

Like which(1) unix command. Find the first instance of an executable in the PATH.
JavaScript
305
star
20

init-package-json

A node module to get your node module started
JavaScript
284
star
21

validate-npm-package-name

Is the given string an acceptable npm package name?
JavaScript
282
star
22

cacache

npm's content-addressable cache
JavaScript
274
star
23

npm-merge-driver

git merge driver for resolving conflicts in npm-related files
JavaScript
271
star
24

lockfile

A very polite lock file utility, which endeavors to not litter, and to wait patiently for others.
JavaScript
259
star
25

registry-issue-archive

An archive of the old npm registry issue tracker
250
star
26

write-file-atomic

Write files in an atomic fashion w/configurable ownership
JavaScript
217
star
27

read-package-json

The thing npm uses to read package.json files with semantics and defaults and validation and stuff
JavaScript
214
star
28

roadmap

Public roadmap for npm
213
star
29

hosted-git-info

Provides metadata and conversions from repository urls for Github, Bitbucket and Gitlab
JavaScript
206
star
30

fstream

Advanced FS Streaming for Node
JavaScript
205
star
31

make-fetch-happen

making fetch happen for npm
JavaScript
190
star
32

read

read(1) for node.
JavaScript
187
star
33

normalize-package-data

normalizes package metadata, typically found in package.json file.
JavaScript
184
star
34

ndm

ndm allows you to deploy OS-specific service-wrappers directly from npm-packages.
JavaScript
181
star
35

are-we-there-yet

Track complex hiearchies of asynchronous task completion statuses.
JavaScript
173
star
36

abbrev-js

Like ruby's Abbrev module
JavaScript
158
star
37

statusboard

Public monitor/status/health board for @npm/cli-team's maintained projects
JavaScript
152
star
38

security-holder

An npm package that holds a spot.
145
star
39

osenv

Look up environment settings specific to different operating systems.
JavaScript
137
star
40

feedback

Public feedback discussions for npm
133
star
41

npm-registry-fetch

like fetch() but for the npm registry
JavaScript
130
star
42

npm-package-arg

Parse the things that can be arguments to `npm install`
JavaScript
116
star
43

libnpm

programmatic npm API
JavaScript
113
star
44

npm-collection-staff-picks

JavaScript
112
star
45

npm-packlist

Walk through a folder and figure out what goes in an npm package
JavaScript
110
star
46

promzard

A prompting json thingie
JavaScript
101
star
47

npm-remote-ls

Examine a package's dependency graph before you install it
JavaScript
89
star
48

npmconf

npm config thing
JavaScript
75
star
49

cmd-shim

The cmd-shim used in npm
JavaScript
75
star
50

npm-tips

A collection of short (5 words or so) tips and tricks that can be sprinkled about the npm site.
JavaScript
73
star
51

www

community space for the npm website
68
star
52

policies

Privacy policy, code of conduct, license, and other npm legal stuff
Shell
67
star
53

package-json

Programmatic API to update package.json
JavaScript
65
star
54

git

a util for spawning git from npm CLI contexts
JavaScript
62
star
55

npm_conf

A conference about npm, maybe. Not to be confused with npmconf.
59
star
56

ignore-walk

Nested/recursive `.gitignore`/`.npmignore` parsing and filtering.
JavaScript
57
star
57

registry-follower-tutorial

write you a registry follower for great good
JavaScript
56
star
58

ssri

subresource integrity for npm
JavaScript
55
star
59

minipass-fetch

An implementation of window.fetch in Node.js using Minipass streams
JavaScript
54
star
60

ci-detect

Detect what kind of CI environment the program is in
JavaScript
53
star
61

run-script

Run a lifecycle script for a package (descendant of npm-lifecycle)
JavaScript
53
star
62

read-installed

Read all the installed packages in a folder, and return a tree structure with all the data.
JavaScript
52
star
63

mute-stream

Bytes go in, but they don't come out (when muted).
JavaScript
49
star
64

fs-write-stream-atomic

Like `fs.createWriteStream(...)`, but atomic.
JavaScript
48
star
65

read-package-json-fast

Like read-package-json, but faster
JavaScript
48
star
66

libnpmpublish

programmatically publish and unpublish npm packages
JavaScript
46
star
67

logical-tree

Calculates a nested logical tree using a package.json and a package lock.
JavaScript
44
star
68

read-package-tree

Read the contents of node_modules
JavaScript
42
star
69

jobs

41
star
70

unique-filename

Generate a unique filename for use in temporary directories or caches.
JavaScript
40
star
71

lock-verify

Report if your package.json is out of sync with your package-lock.json
JavaScript
38
star
72

fstream-ignore

JavaScript
37
star
73

benchmarks

The npm CLI's benchmark suite
JavaScript
36
star
74

npm-lifecycle

npm lifecycle script runner
JavaScript
36
star
75

wombat-cli

The wombat cli tool.
JavaScript
35
star
76

npme-installer

npm Enterprise installer
JavaScript
35
star
77

couch-login

A module for doing logged-in requests against a couchdb server
JavaScript
33
star
78

libnpmexec

npm exec (npx) Programmatic API
JavaScript
33
star
79

npm-audit-report

npm audit security report
JavaScript
33
star
80

ansible-nagios

Ansible role for building Nagios 4.
Perl
32
star
81

config

Configuration management for https://github.com/npm/cli
JavaScript
32
star
82

parse-conflict-json

Parse a JSON string that has git merge conflicts, resolving if possible
JavaScript
32
star
83

npm-profile

Make changes to your npmjs.com profile via cli or library
JavaScript
31
star
84

unique-slug

Generate a unique character string suitible for use in files and URLs.
JavaScript
31
star
85

fstream-npm

fstream class for creating npm packages
JavaScript
30
star
86

redsess

Yet another redis session thing for node.
JavaScript
30
star
87

concurrent-couch-follower

a couch follower wrapper that you can use to be sure you don't miss any documents even if you process them asynchronously.
JavaScript
28
star
88

npm-registry-mock

mock the npm registry
JavaScript
27
star
89

lint

lint the npmcli way
JavaScript
26
star
90

fs

filesystem helper functions, wrappers, and promisification for the npm cli
JavaScript
25
star
91

template-oss

a template package for npm CLI team development
JavaScript
25
star
92

libnpmsearch

programmatic API for the shiny new npm search endpoint
JavaScript
25
star
93

bin-links

.bin/ script linker
JavaScript
24
star
94

libnpmaccess

programmatic api for `npm access`
JavaScript
24
star
95

logos

official logos for npm, Inc
22
star
96

types

Typescript definitions for npm registry content
JavaScript
22
star
97

public-api

21
star
98

deprecate-holder

An npm package that holds a spot.
21
star
99

map-workspaces

Retrieves a name:pathname Map for a given workspaces config
JavaScript
20
star
100

libnpmversion

library to do the things that 'npm version' does
JavaScript
20
star