source: trip-planner-front/node_modules/npm-registry-fetch/README.md@ 1ad8e64

Last change on this file since 1ad8e64 was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 18.7 KB
Line 
1# npm-registry-fetch
2
3[`npm-registry-fetch`](https://github.com/npm/npm-registry-fetch) is a Node.js
4library that implements a `fetch`-like API for accessing npm registry APIs
5consistently. It's able to consume npm-style configuration values and has all
6the necessary logic for picking registries, handling scopes, and dealing with
7authentication details built-in.
8
9This package is meant to replace the older
10[`npm-registry-client`](https://npm.im/npm-registry-client).
11
12## Example
13
14```javascript
15const npmFetch = require('npm-registry-fetch')
16
17console.log(
18 await npmFetch.json('/-/ping')
19)
20```
21
22## Table of Contents
23
24* [Installing](#install)
25* [Example](#example)
26* [Contributing](#contributing)
27* [API](#api)
28 * [`fetch`](#fetch)
29 * [`fetch.json`](#fetch-json)
30 * [`fetch` options](#fetch-opts)
31
32### Install
33
34`$ npm install npm-registry-fetch`
35
36### Contributing
37
38The npm team enthusiastically welcomes contributions and project participation!
39There's a bunch of things you can do if you want to contribute! The [Contributor
40Guide](CONTRIBUTING.md) has all the information you need for everything from
41reporting bugs to contributing entire new features. Please don't hesitate to
42jump in if you'd like to, or even ask us questions if something isn't clear.
43
44All participants and maintainers in this project are expected to follow [Code of
45Conduct](CODE_OF_CONDUCT.md), and just generally be excellent to each other.
46
47Please refer to the [Changelog](CHANGELOG.md) for project history details, too.
48
49Happy hacking!
50
51### API
52
53#### Caching and `write=true` query strings
54
55Before performing any PUT or DELETE operation, npm clients first make a
56GET request to the registry resource being updated, which includes
57the query string `?write=true`.
58
59The semantics of this are, effectively, "I intend to write to this thing,
60and need to know the latest current value, so that my write can land
61cleanly".
62
63The public npm registry handles these `?write=true` requests by ensuring
64that the cache is re-validated before sending a response. In order to
65maintain the same behavior on the client, and not get tripped up by an
66overeager local cache when we intend to write data to the registry, any
67request that comes through `npm-registry-fetch` that contains `write=true`
68in the query string will forcibly set the `prefer-online` option to `true`,
69and set both `prefer-offline` and `offline` to false, so that any local
70cached value will be revalidated.
71
72#### <a name="fetch"></a> `> fetch(url, [opts]) -> Promise<Response>`
73
74Performs a request to a given URL.
75
76The URL can be either a full URL, or a path to one. The appropriate registry
77will be automatically picked if only a URL path is given.
78
79For available options, please see the section on [`fetch` options](#fetch-opts).
80
81##### Example
82
83```javascript
84const res = await fetch('/-/ping')
85console.log(res.headers)
86res.on('data', d => console.log(d.toString('utf8')))
87```
88
89#### <a name="fetch-json"></a> `> fetch.json(url, [opts]) -> Promise<ResponseJSON>`
90
91Performs a request to a given registry URL, parses the body of the response as
92JSON, and returns it as its final value. This is a utility shorthand for
93`fetch(url).then(res => res.json())`.
94
95For available options, please see the section on [`fetch` options](#fetch-opts).
96
97##### Example
98
99```javascript
100const res = await fetch.json('/-/ping')
101console.log(res) // Body parsed as JSON
102```
103
104#### <a name="fetch-json-stream"></a> `> fetch.json.stream(url, jsonPath, [opts]) -> Stream`
105
106Performs a request to a given registry URL and parses the body of the response
107as JSON, with each entry being emitted through the stream.
108
109The `jsonPath` argument is a [`JSONStream.parse()`
110path](https://github.com/dominictarr/JSONStream#jsonstreamparsepath), and the
111returned stream (unlike default `JSONStream`s), has a valid
112`Symbol.asyncIterator` implementation.
113
114For available options, please see the section on [`fetch` options](#fetch-opts).
115
116##### Example
117
118```javascript
119console.log('https://npm.im/~zkat has access to the following packages:')
120for await (let {key, value} of fetch.json.stream('/-/user/zkat/package', '$*')) {
121 console.log(`https://npm.im/${key} (perms: ${value})`)
122}
123```
124
125#### <a name="fetch-opts"></a> `fetch` Options
126
127Fetch options are optional, and can be passed in as either a Map-like object
128(one with a `.get()` method), a plain javascript object, or a
129[`figgy-pudding`](https://npm.im/figgy-pudding) instance.
130
131##### <a name="opts-agent"></a> `opts.agent`
132
133* Type: http.Agent
134* Default: an appropriate agent based on URL protocol and proxy settings
135
136An [`Agent`](https://nodejs.org/api/http.html#http_class_http_agent) instance to
137be shared across requests. This allows multiple concurrent `fetch` requests to
138happen on the same socket.
139
140You do _not_ need to provide this option unless you want something particularly
141specialized, since proxy configurations and http/https agents are already
142automatically managed internally when this option is not passed through.
143
144##### <a name="opts-body"></a> `opts.body`
145
146* Type: Buffer | Stream | Object
147* Default: null
148
149Request body to send through the outgoing request. Buffers and Streams will be
150passed through as-is, with a default `content-type` of
151`application/octet-stream`. Plain JavaScript objects will be `JSON.stringify`ed
152and the `content-type` will default to `application/json`.
153
154Use [`opts.headers`](#opts-headers) to set the content-type to something else.
155
156##### <a name="opts-ca"></a> `opts.ca`
157
158* Type: String, Array, or null
159* Default: null
160
161The Certificate Authority signing certificate that is trusted for SSL
162connections to the registry. Values should be in PEM format (Windows calls it
163"Base-64 encoded X.509 (.CER)") with newlines replaced by the string `'\n'`. For
164example:
165
166```
167{
168 ca: '-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----'
169}
170```
171
172Set to `null` to only allow "known" registrars, or to a specific CA cert
173to trust only that specific signing authority.
174
175Multiple CAs can be trusted by specifying an array of certificates instead of a
176single string.
177
178See also [`opts.strictSSL`](#opts-strictSSL), [`opts.ca`](#opts-ca) and
179[`opts.key`](#opts-key)
180
181##### <a name="opts-cache"></a> `opts.cache`
182
183* Type: path
184* Default: null
185
186The location of the http cache directory. If provided, certain cachable requests
187will be cached according to [IETF RFC 7234](https://tools.ietf.org/html/rfc7234)
188rules. This will speed up future requests, as well as make the cached data
189available offline if necessary/requested.
190
191See also [`offline`](#opts-offline), [`preferOffline`](#opts-preferOffline),
192and [`preferOnline`](#opts-preferOnline).
193
194##### <a name="opts-cert"></a> `opts.cert`
195
196* Type: String
197* Default: null
198
199A client certificate to pass when accessing the registry. Values should be in
200PEM format (Windows calls it "Base-64 encoded X.509 (.CER)") with newlines
201replaced by the string `'\n'`. For example:
202
203```
204{
205 cert: '-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----'
206}
207```
208
209It is _not_ the path to a certificate file (and there is no "certfile" option).
210
211See also: [`opts.ca`](#opts-ca) and [`opts.key`](#opts-key)
212
213##### <a name="opts-fetchRetries"></a> `opts.fetchRetries`
214
215* Type: Number
216* Default: 2
217
218The "retries" config for [`retry`](https://npm.im/retry) to use when fetching
219packages from the registry.
220
221See also [`opts.retry`](#opts-retry) to provide all retry options as a single
222object.
223
224##### <a name="opts-fetchRetryFactor"></a> `opts.fetchRetryFactor`
225
226* Type: Number
227* Default: 10
228
229The "factor" config for [`retry`](https://npm.im/retry) to use when fetching
230packages.
231
232See also [`opts.retry`](#opts-retry) to provide all retry options as a single
233object.
234
235##### <a name="opts-fetchRetryMintimeout"></a> `opts.fetchRetryMintimeout`
236
237* Type: Number
238* Default: 10000 (10 seconds)
239
240The "minTimeout" config for [`retry`](https://npm.im/retry) to use when fetching
241packages.
242
243See also [`opts.retry`](#opts-retry) to provide all retry options as a single
244object.
245
246##### <a name="opts-fetchRetryMaxtimeout"></a> `opts.fetchRetryMaxtimeout`
247
248* Type: Number
249* Default: 60000 (1 minute)
250
251The "maxTimeout" config for [`retry`](https://npm.im/retry) to use when fetching
252packages.
253
254See also [`opts.retry`](#opts-retry) to provide all retry options as a single
255object.
256
257##### <a name="opts-forceAuth"></a> `opts.forceAuth`
258
259* Type: Object
260* Default: null
261
262If present, other auth-related values in `opts` will be completely ignored,
263including `alwaysAuth`, `email`, and `otp`, when calculating auth for a request,
264and the auth details in `opts.forceAuth` will be used instead.
265
266##### <a name="opts-gzip"></a> `opts.gzip`
267
268* Type: Boolean
269* Default: false
270
271If true, `npm-registry-fetch` will set the `Content-Encoding` header to `gzip`
272and use `zlib.gzip()` or `zlib.createGzip()` to gzip-encode
273[`opts.body`](#opts-body).
274
275##### <a name="opts-headers"></a> `opts.headers`
276
277* Type: Object
278* Default: null
279
280Additional headers for the outgoing request. This option can also be used to
281override headers automatically generated by `npm-registry-fetch`, such as
282`Content-Type`.
283
284##### <a name="opts-ignoreBody"></a> `opts.ignoreBody`
285
286* Type: Boolean
287* Default: false
288
289If true, the **response body** will be thrown away and `res.body` set to `null`.
290This will prevent dangling response sockets for requests where you don't usually
291care what the response body is.
292
293##### <a name="opts-integrity"></a> `opts.integrity`
294
295* Type: String | [SRI object](https://npm.im/ssri)
296* Default: null
297
298If provided, the response body's will be verified against this integrity string,
299using [`ssri`](https://npm.im/ssri). If verification succeeds, the response will
300complete as normal. If verification fails, the response body will error with an
301`EINTEGRITY` error.
302
303Body integrity is only verified if the body is actually consumed to completion --
304that is, if you use `res.json()`/`res.buffer()`, or if you consume the default
305`res` stream data to its end.
306
307Cached data will have its integrity automatically verified using the
308previously-generated integrity hash for the saved request information, so
309`EINTEGRITY` errors can happen if [`opts.cache`](#opts-cache) is used, even if
310`opts.integrity` is not passed in.
311
312##### <a name="opts-key"></a> `opts.key`
313
314* Type: String
315* Default: null
316
317A client key to pass when accessing the registry. Values should be in PEM
318format with newlines replaced by the string `'\n'`. For example:
319
320```
321{
322 key: '-----BEGIN PRIVATE KEY-----\nXXXX\nXXXX\n-----END PRIVATE KEY-----'
323}
324```
325
326It is _not_ the path to a key file (and there is no "keyfile" option).
327
328See also: [`opts.ca`](#opts-ca) and [`opts.cert`](#opts-cert)
329
330##### <a name="opts-localAddress"></a> `opts.localAddress`
331
332* Type: IP Address String
333* Default: null
334
335The IP address of the local interface to use when making connections
336to the registry.
337
338See also [`opts.proxy`](#opts-proxy)
339
340##### <a name="opts-log"></a> `opts.log`
341
342* Type: [`npmlog`](https://npm.im/npmlog)-like
343* Default: null
344
345Logger object to use for logging operation details. Must have the same methods
346as `npmlog`.
347
348##### <a name="opts-mapJSON"></a> `opts.mapJSON`
349
350* Type: Function
351* Default: undefined
352
353When using `fetch.json.stream()` (NOT `fetch.json()`), this will be passed down
354to [`JSONStream`](https://npm.im/JSONStream) as the second argument to
355`JSONStream.parse`, and can be used to transform stream data before output.
356
357##### <a name="opts-maxSockets"></a> `opts.maxSockets`
358
359* Type: Integer
360* Default: 12
361
362Maximum number of sockets to keep open during requests. Has no effect if
363[`opts.agent`](#opts-agent) is used.
364
365##### <a name="opts-method"></a> `opts.method`
366
367* Type: String
368* Default: 'GET'
369
370HTTP method to use for the outgoing request. Case-insensitive.
371
372##### <a name="opts-noproxy"></a> `opts.noproxy`
373
374* Type: Boolean
375* Default: process.env.NOPROXY
376
377If true, proxying will be disabled even if [`opts.proxy`](#opts-proxy) is used.
378
379##### <a name="opts-npmSession"></a> `opts.npmSession`
380
381* Type: String
382* Default: null
383
384If provided, will be sent in the `npm-session` header. This header is used by
385the npm registry to identify individual user sessions (usually individual
386invocations of the CLI).
387
388##### <a name="opts-npmCommand"></a> `opts.npmCommand`
389
390* Type: String
391* Default: null
392
393If provided, it will be sent in the `npm-command` header. This header is
394used by the npm registry to identify the npm command that caused this
395request to be made.
396
397##### <a name="opts-offline"></a> `opts.offline`
398
399* Type: Boolean
400* Default: false
401
402Force offline mode: no network requests will be done during install. To allow
403`npm-registry-fetch` to fill in missing cache data, see
404[`opts.preferOffline`](#opts-preferOffline).
405
406This option is only really useful if you're also using
407[`opts.cache`](#opts-cache).
408
409This option is set to `true` when the request includes `write=true` in the
410query string.
411
412##### <a name="opts-otp"></a> `opts.otp`
413
414* Type: Number | String
415* Default: null
416
417This is a one-time password from a two-factor authenticator. It is required for
418certain registry interactions when two-factor auth is enabled for a user
419account.
420
421##### <a name="opts-otpPrompt"></a> `opts.otpPrompt`
422
423* Type: Function
424* Default: null
425
426This is a method which will be called to provide an OTP if the server
427responds with a 401 response indicating that a one-time-password is
428required.
429
430It may return a promise, which must resolve to the OTP value to be used.
431If the method fails to provide an OTP value, then the fetch will fail with
432the auth error that indicated an OTP was needed.
433
434##### <a name="opts-password"></a> `opts.password`
435
436* Alias: `_password`
437* Type: String
438* Default: null
439
440Password used for basic authentication. For the more modern authentication
441method, please use the (more secure) [`opts.token`](#opts-token)
442
443Can optionally be scoped to a registry by using a "nerf dart" for that registry.
444That is:
445
446```
447{
448 '//registry.npmjs.org/:password': 't0k3nH34r'
449}
450```
451
452See also [`opts.username`](#opts-username)
453
454##### <a name="opts-preferOffline"></a> `opts.preferOffline`
455
456* Type: Boolean
457* Default: false
458
459If true, staleness checks for cached data will be bypassed, but missing data
460will be requested from the server. To force full offline mode, use
461[`opts.offline`](#opts-offline).
462
463This option is generally only useful if you're also using
464[`opts.cache`](#opts-cache).
465
466This option is set to `false` when the request includes `write=true` in the
467query string.
468
469##### <a name="opts-preferOnline"></a> `opts.preferOnline`
470
471* Type: Boolean
472* Default: false
473
474If true, staleness checks for cached data will be forced, making the CLI look
475for updates immediately even for fresh package data.
476
477This option is generally only useful if you're also using
478[`opts.cache`](#opts-cache).
479
480This option is set to `true` when the request includes `write=true` in the
481query string.
482
483##### <a name="opts-projectScope"></a> `opts.projectScope`
484
485* Type: String
486* Default: null
487
488If provided, will be sent in the `npm-scope` header. This header is used by the
489npm registry to identify the toplevel package scope that a particular project
490installation is using.
491
492##### <a name="opts-proxy"></a> `opts.proxy`
493
494* Type: url
495* Default: null
496
497A proxy to use for outgoing http requests. If not passed in, the `HTTP(S)_PROXY`
498environment variable will be used.
499
500##### <a name="opts-query"></a> `opts.query`
501
502* Type: String | Object
503* Default: null
504
505If provided, the request URI will have a query string appended to it using this
506query. If `opts.query` is an object, it will be converted to a query string
507using
508[`querystring.stringify()`](https://nodejs.org/api/querystring.html#querystring_querystring_stringify_obj_sep_eq_options).
509
510If the request URI already has a query string, it will be merged with
511`opts.query`, preferring `opts.query` values.
512
513##### <a name="opts-registry"></a> `opts.registry`
514
515* Type: URL
516* Default: `'https://registry.npmjs.org'`
517
518Registry configuration for a request. If a request URL only includes the URL
519path, this registry setting will be prepended.
520
521See also [`opts.scope`](#opts-scope), [`opts.spec`](#opts-spec), and
522[`opts.<scope>:registry`](#opts-scope-registry) which can all affect the actual
523registry URL used by the outgoing request.
524
525##### <a name="opts-retry"></a> `opts.retry`
526
527* Type: Object
528* Default: null
529
530Single-object configuration for request retry settings. If passed in, will
531override individually-passed `fetch-retry-*` settings.
532
533##### <a name="opts-scope"></a> `opts.scope`
534
535* Type: String
536* Default: null
537
538Associate an operation with a scope for a scoped registry. This option can force
539lookup of scope-specific registries and authentication.
540
541See also [`opts.<scope>:registry`](#opts-scope-registry) and
542[`opts.spec`](#opts-spec) for interactions with this option.
543
544##### <a name="opts-scope-registry"></a> `opts.<scope>:registry`
545
546* Type: String
547* Default: null
548
549This option type can be used to configure the registry used for requests
550involving a particular scope. For example, `opts['@myscope:registry'] =
551'https://scope-specific.registry/'` will make it so requests go out to this
552registry instead of [`opts.registry`](#opts-registry) when
553[`opts.scope`](#opts-scope) is used, or when [`opts.spec`](#opts-spec) is a
554scoped package spec.
555
556The `@` before the scope name is optional, but recommended.
557
558##### <a name="opts-spec"></a> `opts.spec`
559
560* Type: String | [`npm-registry-arg`](https://npm.im/npm-registry-arg) object.
561* Default: null
562
563If provided, can be used to automatically configure [`opts.scope`](#opts-scope)
564based on a specific package name. Non-registry package specs will throw an
565error.
566
567##### <a name="opts-strictSSL"></a> `opts.strictSSL`
568
569* Type: Boolean
570* Default: true
571
572Whether or not to do SSL key validation when making requests to the
573registry via https.
574
575See also [`opts.ca`](#opts-ca).
576
577##### <a name="opts-timeout"></a> `opts.timeout`
578
579* Type: Milliseconds
580* Default: 300000 (5 minutes)
581
582Time before a hanging request times out.
583
584##### <a name="opts-token"></a> `opts.token`
585
586* Alias: `opts._authToken`
587* Type: String
588* Default: null
589
590Authentication token string.
591
592Can be scoped to a registry by using a "nerf dart" for that registry. That is:
593
594```
595{
596 '//registry.npmjs.org/:token': 't0k3nH34r'
597}
598```
599
600##### <a name="opts-userAgent"></a> `opts.userAgent`
601
602* Type: String
603* Default: `'npm-registry-fetch@<version>/node@<node-version>+<arch> (<platform>)'`
604
605User agent string to send in the `User-Agent` header.
606
607##### <a name="opts-username"></a> `opts.username`
608
609* Type: String
610* Default: null
611
612Username used for basic authentication. For the more modern authentication
613method, please use the (more secure) [`opts.token`](#opts-token)
614
615Can optionally be scoped to a registry by using a "nerf dart" for that registry.
616That is:
617
618```
619{
620 '//registry.npmjs.org/:username': 't0k3nH34r'
621}
622```
623
624See also [`opts.password`](#opts-password)
625
626##### <a name="opts-auth"></a> `opts._auth`
627
628* Type: String
629* Default: null
630
631** DEPRECATED ** This is a legacy authentication token supported only for
632compatibility. Please use [`opts.token`](#opts-token) instead.
Note: See TracBrowser for help on using the repository browser.