org.simantics.maps.server/node/node-v4.8.0-win-x64/node_modules/npm/node_modules/npm-registry-client/README.md

   1 # npm-registry-client
   2
   3 The code that npm uses to talk to the registry.
   4
   5 It handles all the caching and HTTP calls.
   6
   7 ## Usage
   8
   9 ```javascript
  10 var RegClient = require('npm-registry-client')
  11 var client = new RegClient(config)
  12 var uri = "https://registry.npmjs.org/npm"
  13 var params = {timeout: 1000}
  14
  15 client.get(uri, params, function (error, data, raw, res) {
  16   // error is an error if there was a problem.
  17   // data is the parsed data object
  18   // raw is the json string
  19   // res is the response from couch
  20 })
  21 ```
  22
  23 # Registry URLs
  24
  25 The registry calls take either a full URL pointing to a resource in the
  26 registry, or a base URL for the registry as a whole (including the registry
  27 path – but be sure to terminate the path with `/`). `http` and `https` URLs are
  28 the only ones supported.
  29
  30 ## Using the client
  31
  32 Every call to the client follows the same pattern:
  33
  34 * `uri` {String} The *fully-qualified* URI of the registry API method being
  35   invoked.
  36 * `params` {Object} Per-request parameters.
  37 * `callback` {Function} Callback to be invoked when the call is complete.
  38
  39 ### Credentials
  40
  41 Many requests to the registry can by authenticated, and require credentials
  42 for authorization. These credentials always look the same:
  43
  44 * `username` {String}
  45 * `password` {String}
  46 * `email` {String}
  47 * `alwaysAuth` {Boolean} Whether calls to the target registry are always
  48   authed.
  49
  50 **or**
  51
  52 * `token` {String}
  53 * `alwaysAuth` {Boolean} Whether calls to the target registry are always
  54   authed.
  55
  56 ## API
  57
  58 ### client.access(uri, params, cb)
  59
  60 * `uri` {String} Registry URL for the package's access API endpoint.
  61   Looks like `/-/package/<package name>/access`.
  62 * `params` {Object} Object containing per-request properties.
  63   * `access` {String} New access level for the package. Can be either
  64     `public` or `restricted`. Registry will raise an error if trying
  65     to change the access level of an unscoped package.
  66   * `auth` {Credentials}
  67
  68 Set the access level for scoped packages. For now, there are only two
  69 access levels: "public" and "restricted".
  70
  71 ### client.adduser(uri, params, cb)
  72
  73 * `uri` {String} Base registry URL.
  74 * `params` {Object} Object containing per-request properties.
  75   * `auth` {Credentials}
  76 * `cb` {Function}
  77   * `error` {Error | null}
  78   * `data` {Object} the parsed data object
  79   * `raw` {String} the json
  80   * `res` {Response Object} response from couch
  81
  82 Add a user account to the registry, or verify the credentials.
  83
  84 ### client.deprecate(uri, params, cb)
  85
  86 * `uri` {String} Full registry URI for the deprecated package.
  87 * `params` {Object} Object containing per-request properties.
  88   * `version` {String} Semver version range.
  89   * `message` {String} The message to use as a deprecation warning.
  90   * `auth` {Credentials}
  91 * `cb` {Function}
  92
  93 Deprecate a version of a package in the registry.
  94
  95 ### client.distTags.fetch(uri, params, cb)
  96
  97 * `uri` {String} Base URL for the registry.
  98 * `params` {Object} Object containing per-request properties.
  99   * `package` {String} Name of the package.
 100   * `auth` {Credentials}
 101 * `cb` {Function}
 102
 103 Fetch all of the `dist-tags` for the named package.
 104
 105 ### client.distTags.add(uri, params, cb)
 106
 107 * `uri` {String} Base URL for the registry.
 108 * `params` {Object} Object containing per-request properties.
 109   * `package` {String} Name of the package.
 110   * `distTag` {String} Name of the new `dist-tag`.
 111   * `version` {String} Exact version to be mapped to the `dist-tag`.
 112   * `auth` {Credentials}
 113 * `cb` {Function}
 114
 115 Add (or replace) a single dist-tag onto the named package.
 116
 117 ### client.distTags.set(uri, params, cb)
 118
 119 * `uri` {String} Base URL for the registry.
 120 * `params` {Object} Object containing per-request properties.
 121   * `package` {String} Name of the package.
 122   * `distTags` {Object} Object containing a map from tag names to package
 123      versions.
 124   * `auth` {Credentials}
 125 * `cb` {Function}
 126
 127 Set all of the `dist-tags` for the named package at once, creating any
 128 `dist-tags` that do not already exit. Any `dist-tags` not included in the
 129 `distTags` map will be removed.
 130
 131 ### client.distTags.update(uri, params, cb)
 132
 133 * `uri` {String} Base URL for the registry.
 134 * `params` {Object} Object containing per-request properties.
 135   * `package` {String} Name of the package.
 136   * `distTags` {Object} Object containing a map from tag names to package
 137      versions.
 138   * `auth` {Credentials}
 139 * `cb` {Function}
 140
 141 Update the values of multiple `dist-tags`, creating any `dist-tags` that do
 142 not already exist. Any pre-existing `dist-tags` not included in the `distTags`
 143 map will be left alone.
 144
 145 ### client.distTags.rm(uri, params, cb)
 146
 147 * `uri` {String} Base URL for the registry.
 148 * `params` {Object} Object containing per-request properties.
 149   * `package` {String} Name of the package.
 150   * `distTag` {String} Name of the new `dist-tag`.
 151   * `auth` {Credentials}
 152 * `cb` {Function}
 153
 154 Remove a single `dist-tag` from the named package.
 155
 156 ### client.get(uri, params, cb)
 157
 158 * `uri` {String} The complete registry URI to fetch
 159 * `params` {Object} Object containing per-request properties.
 160   * `timeout` {Number} Duration before the request times out. Optional
 161     (default: never).
 162   * `follow` {Boolean} Follow 302/301 responses. Optional (default: true).
 163   * `staleOk` {Boolean} If there's cached data available, then return that to
 164     the callback quickly, and update the cache the background. Optional
 165     (default: false).
 166   * `auth` {Credentials} Optional.
 167 * `cb` {Function}
 168
 169 Fetches data from the registry via a GET request, saving it in the cache folder
 170 with the ETag or the "Last Modified" timestamp.
 171
 172 ### client.publish(uri, params, cb)
 173
 174 * `uri` {String} The registry URI for the package to publish.
 175 * `params` {Object} Object containing per-request properties.
 176   * `metadata` {Object} Package metadata.
 177   * `access` {String} Access for the package. Can be `public` or `restricted` (no default).
 178   * `body` {Stream} Stream of the package body / tarball.
 179   * `auth` {Credentials}
 180 * `cb` {Function}
 181
 182 Publish a package to the registry.
 183
 184 Note that this does not create the tarball from a folder.
 185
 186 ### client.star(uri, params, cb)
 187
 188 * `uri` {String} The complete registry URI for the package to star.
 189 * `params` {Object} Object containing per-request properties.
 190   * `starred` {Boolean} True to star the package, false to unstar it. Optional
 191     (default: false).
 192   * `auth` {Credentials}
 193 * `cb` {Function}
 194
 195 Star or unstar a package.
 196
 197 Note that the user does not have to be the package owner to star or unstar a
 198 package, though other writes do require that the user be the package owner.
 199
 200 ### client.stars(uri, params, cb)
 201
 202 * `uri` {String} The base URL for the registry.
 203 * `params` {Object} Object containing per-request properties.
 204   * `username` {String} Name of user to fetch starred packages for. Optional
 205     (default: user in `auth`).
 206   * `auth` {Credentials} Optional (required if `username` is omitted).
 207 * `cb` {Function}
 208
 209 View your own or another user's starred packages.
 210
 211 ### client.tag(uri, params, cb)
 212
 213 * `uri` {String} The complete registry URI to tag
 214 * `params` {Object} Object containing per-request properties.
 215   * `version` {String} Version to tag.
 216   * `tag` {String} Tag name to apply.
 217   * `auth` {Credentials}
 218 * `cb` {Function}
 219
 220 Mark a version in the `dist-tags` hash, so that `pkg@tag` will fetch the
 221 specified version.
 222
 223 ### client.unpublish(uri, params, cb)
 224
 225 * `uri` {String} The complete registry URI of the package to unpublish.
 226 * `params` {Object} Object containing per-request properties.
 227   * `version` {String} version to unpublish. Optional – omit to unpublish all
 228     versions.
 229   * `auth` {Credentials}
 230 * `cb` {Function}
 231
 232 Remove a version of a package (or all versions) from the registry.  When the
 233 last version us unpublished, the entire document is removed from the database.
 234
 235 ### client.whoami(uri, params, cb)
 236
 237 * `uri` {String} The base registry for the URI.
 238 * `params` {Object} Object containing per-request properties.
 239   * `auth` {Credentials}
 240 * `cb` {Function}
 241
 242 Simple call to see who the registry thinks you are. Especially useful with
 243 token-based auth.
 244
 245
 246 ## PLUMBING
 247
 248 The below are primarily intended for use by the rest of the API, or by the npm
 249 caching logic directly.
 250
 251 ### client.request(uri, params, cb)
 252
 253 * `uri` {String} URI pointing to the resource to request.
 254 * `params` {Object} Object containing per-request properties.
 255   * `method` {String} HTTP method. Optional (default: "GET").
 256   * `body` {Stream | Buffer | String | Object} The request body.  Objects
 257     that are not Buffers or Streams are encoded as JSON. Optional – body
 258     only used for write operations.
 259   * `etag` {String} The cached ETag. Optional.
 260   * `lastModified` {String} The cached Last-Modified timestamp. Optional.
 261   * `follow` {Boolean} Follow 302/301 responses. Optional (default: true).
 262   * `streaming` {Boolean} Stream the request body as it comes, handling error
 263     responses in a non-streaming way.
 264   * `auth` {Credentials} Optional.
 265 * `cb` {Function}
 266   * `error` {Error | null}
 267   * `data` {Object} the parsed data object
 268   * `raw` {String} the json
 269   * `res` {Response Object} response from couch
 270
 271 Make a generic request to the registry. All the other methods are wrappers
 272 around `client.request`.
 273
 274 ### client.fetch(uri, params, cb)
 275
 276 * `uri` {String} The complete registry URI to upload to
 277 * `params` {Object} Object containing per-request properties.
 278   * `headers` {Stream} HTTP headers to be included with the request. Optional.
 279   * `auth` {Credentials} Optional.
 280 * `cb` {Function}
 281
 282 Fetch a package from a URL, with auth set appropriately if included. Used to
 283 cache remote tarballs as well as request package tarballs from the registry.
 284
 285 # Configuration
 286
 287 The client uses its own configuration, which is just passed in as a simple
 288 nested object. The following are the supported values (with their defaults, if
 289 any):
 290
 291 * `proxy.http` {URL} The URL to proxy HTTP requests through.
 292 * `proxy.https` {URL} The URL to proxy HTTPS requests through. Defaults to be
 293   the same as `proxy.http` if unset.
 294 * `proxy.localAddress` {IP} The local address to use on multi-homed systems.
 295 * `ssl.ca` {String} Certificate signing authority certificates to trust.
 296 * `ssl.certificate` {String} Client certificate (PEM encoded). Enable access
 297   to servers that require client certificates.
 298 * `ssl.key` {String} Private key (PEM encoded) for client certificate.
 299 * `ssl.strict` {Boolean} Whether or not to be strict with SSL certificates.
 300   Default = `true`
 301 * `retry.count` {Number} Number of times to retry on GET failures. Default = 2.
 302 * `retry.factor` {Number} `factor` setting for `node-retry`. Default = 10.
 303 * `retry.minTimeout` {Number} `minTimeout` setting for `node-retry`.
 304   Default = 10000 (10 seconds)
 305 * `retry.maxTimeout` {Number} `maxTimeout` setting for `node-retry`.
 306   Default = 60000 (60 seconds)
 307 * `userAgent` {String} User agent header to send. Default =
 308   `"node/{process.version}"`
 309 * `log` {Object} The logger to use.  Defaults to `require("npmlog")` if
 310   that works, otherwise logs are disabled.
 311 * `defaultTag` {String} The default tag to use when publishing new packages.
 312   Default = `"latest"`
 313 * `couchToken` {Object} A token for use with
 314   [couch-login](https://npmjs.org/package/couch-login).
 315 * `sessionToken` {String} A random identifier for this set of client requests.
 316   Default = 8 random hexadecimal bytes.
 317 * `maxSockets` {Number} The maximum number of connections that will be open per
 318   origin (unique combination of protocol:host:port). Passed to the
 319   [httpAgent](https://nodejs.org/api/http.html#http_agent_maxsockets).
 320   Default = 50