README.md
1# pacote
2
3Fetches package manifests and tarballs from the npm registry.
4
5## USAGE
6
7```js
8const pacote = require('pacote')
9
10// get a package manifest
11pacote.manifest('foo@1.x').then(manifest => console.log('got it', manifest))
12
13// extract a package into a folder
14pacote.extract('github:npm/cli', 'some/path', options)
15 .then(({from, resolved, integrity}) => {
16 console.log('extracted!', from, resolved, integrity)
17 })
18
19pacote.tarball('https://server.com/package.tgz').then(data => {
20 console.log('got ' + data.length + ' bytes of tarball data')
21})
22```
23
24`pacote` works with any kind of package specifier that npm can install. If
25you can pass it to the npm CLI, you can pass it to pacote. (In fact, that's
26exactly what the npm CLI does.)
27
28Anything that you can do with one kind of package, you can do with another.
29
30Data that isn't relevant (like a packument for a tarball) will be
31simulated.
32
33`prepare` scripts will be run when generating tarballs from `git` and
34`directory` locations, to simulate what _would_ be published to the
35registry, so that you get a working package instead of just raw source
36code that might need to be transpiled.
37
38## CLI
39
40This module exports a command line interface that can do most of what is
41described below. Run `pacote -h` to learn more.
42
43```
44Pacote - The JavaScript Package Handler, v10.1.1
45
46Usage:
47
48 pacote resolve <spec>
49 Resolve a specifier and output the fully resolved target
50 Returns integrity and from if '--long' flag is set.
51
52 pacote manifest <spec>
53 Fetch a manifest and print to stdout
54
55 pacote packument <spec>
56 Fetch a full packument and print to stdout
57
58 pacote tarball <spec> [<filename>]
59 Fetch a package tarball and save to <filename>
60 If <filename> is missing or '-', the tarball will be streamed to stdout.
61
62 pacote extract <spec> <folder>
63 Extract a package to the destination folder.
64
65Configuration values all match the names of configs passed to npm, or
66options passed to Pacote. Additional flags for this executable:
67
68 --long Print an object from 'resolve', including integrity and spec.
69 --json Print result objects as JSON rather than node's default.
70 (This is the default if stdout is not a TTY.)
71 --help -h Print this helpful text.
72
73For example '--cache=/path/to/folder' will use that folder as the cache.
74```
75
76## API
77
78The `spec` refers to any kind of package specifier that npm can install.
79If you can pass it to the npm CLI, you can pass it to pacote. (In fact,
80that's exactly what the npm CLI does.)
81
82See below for valid `opts` values.
83
84* `pacote.resolve(spec, opts)` Resolve a specifier like `foo@latest` or
85 `github:user/project` all the way to a tarball url, tarball file, or git
86 repo with commit hash.
87
88* `pacote.extract(spec, dest, opts)` Extract a package's tarball into a
89 destination folder. Returns a promise that resolves to the
90 `{from,resolved,integrity}` of the extracted package.
91
92* `pacote.manifest(spec, opts)` Fetch (or simulate) a package's manifest
93 (basically, the `package.json` file, plus a bit of metadata).
94 See below for more on manifests and packuments. Returns a Promise that
95 resolves to the manifest object.
96
97* `pacote.packument(spec, opts)` Fetch (or simulate) a package's packument
98 (basically, the top-level package document listing all the manifests that
99 the registry returns). See below for more on manifests and packuments.
100 Returns a Promise that resolves to the packument object.
101
102* `pacote.tarball(spec, opts)` Get a package tarball data as a buffer in
103 memory. Returns a Promise that resolves to the tarball data Buffer, with
104 `from`, `resolved`, and `integrity` fields attached.
105
106* `pacote.tarball.file(spec, dest, opts)` Save a package tarball data to
107 a file on disk. Returns a Promise that resolves to
108 `{from,integrity,resolved}` of the fetched tarball.
109
110* `pacote.tarball.stream(spec, streamHandler, opts)` Fetch a tarball and
111 make the stream available to the `streamHandler` function.
112
113 This is mostly an internal function, but it is exposed because it does
114 provide some functionality that may be difficult to achieve otherwise.
115
116 The `streamHandler` function MUST return a Promise that resolves when
117 the stream (and all associated work) is ended, or rejects if the stream
118 has an error.
119
120 The `streamHandler` function MAY be called multiple times, as Pacote
121 retries requests in some scenarios, such as cache corruption or
122 retriable network failures.
123
124### Options
125
126Options are passed to
127[`npm-registry-fetch`](http://npm.im/npm-registry-fetch) and
128[`cacache`](http://npm.im/cacache), so in addition to these, anything for
129those modules can be given to pacote as well.
130
131Options object is cloned, and mutated along the way to add integrity,
132resolved, and other properties, as they are determined.
133
134* `cache` Where to store cache entries and temp files. Passed to
135 [`cacache`](http://npm.im/cacache). Defaults to the same cache directory
136 that npm will use by default, based on platform and environment.
137* `where` Base folder for resolving relative `file:` dependencies.
138* `resolved` Shortcut for looking up resolved values. Should be specified
139 if known.
140* `integrity` Expected integrity of fetched package tarball. If specified,
141 tarballs with mismatched integrity values will raise an `EINTEGRITY`
142 error.
143* `umask` Permission mode mask for extracted files and directories.
144 Defaults to `0o22`. See "Extracted File Modes" below.
145* `fmode` Minimum permission mode for extracted files. Defaults to
146 `0o666`. See "Extracted File Modes" below.
147* `dmode` Minimum permission mode for extracted directories. Defaults to
148 `0o777`. See "Extracted File Modes" below.
149* `preferOnline` Prefer to revalidate cache entries, even when it would not
150 be strictly necessary. Default `false`.
151* `before` When picking a manifest from a packument, only consider
152 packages published before the specified date. Default `null`.
153* `defaultTag` The default `dist-tag` to use when choosing a manifest from a
154 packument. Defaults to `latest`.
155* `registry` The npm registry to use by default. Defaults to
156 `https://registry.npmjs.org/`.
157* `fullMetadata` Fetch the full metadata from the registry for packuments,
158 including information not strictly required for installation (author,
159 description, etc.) Defaults to `true` when `before` is set, since the
160 version publish time is part of the extended packument metadata.
161* `fullReadJson` Use the slower `read-package-json` package insted of
162 `read-package-json-fast` in order to include extra fields like "readme" in
163 the manifest. Defaults to `false`.
164* `packumentCache` For registry packuments only, you may provide a `Map`
165 object which will be used to cache packument requests between pacote
166 calls. This allows you to easily avoid hitting the registry multiple
167 times (even just to validate the cache) for a given packument, since it
168 is unlikely to change in the span of a single command.
169* `silent` A boolean that determines whether the banner is displayed
170 when calling `@npmcli/run-script`.
171* `verifySignatures` A boolean that will make pacote verify the
172 integrity signature of a manifest, if present. There must be a
173 configured `_keys` entry in the config that is scoped to the
174 registry the manifest is being fetched from.
175* `verifyAttestations` A boolean that will make pacote verify Sigstore
176 attestations, if present. There must be a configured `_keys` entry in the
177 config that is scoped to the registry the manifest is being fetched from.
178* `tufCache` Where to store metadata/target files when retrieving the package
179 attestation key material via TUF. Defaults to the same cache directory that
180 npm will use by default, based on platform and environment.
181
182### Advanced API
183
184Each different type of fetcher is exposed for more advanced usage such as
185using helper methods from this classes:
186
187* `DirFetcher`
188* `FileFetcher`
189* `GitFetcher`
190* `RegistryFetcher`
191* `RemoteFetcher`
192
193## Extracted File Modes
194
195Files are extracted with a mode matching the following formula:
196
197```
198( (tarball entry mode value) | (minimum mode option) ) ~ (umask)
199```
200
201This is in order to prevent unreadable files or unlistable directories from
202cluttering a project's `node_modules` folder, even if the package tarball
203specifies that the file should be inaccessible.
204
205It also prevents files from being group- or world-writable without explicit
206opt-in by the user, because all file and directory modes are masked against
207the `umask` value.
208
209So, a file which is `0o771` in the tarball, using the default `fmode` of
210`0o666` and `umask` of `0o22`, will result in a file mode of `0o755`:
211
212```
213(0o771 | 0o666) => 0o777
214(0o777 ~ 0o22) => 0o755
215```
216
217In almost every case, the defaults are appropriate. To respect exactly
218what is in the package tarball (even if this makes an unusable system), set
219both `dmode` and `fmode` options to `0`. Otherwise, the `umask` config
220should be used in most cases where file mode modifications are required,
221and this functions more or less the same as the `umask` value in most Unix
222systems.
223
224## Extracted File Ownership
225
226When running as `root` on Unix systems, all extracted files and folders
227will have their owning `uid` and `gid` values set to match the ownership
228of the containing folder.
229
230This prevents `root`-owned files showing up in a project's `node_modules`
231folder when a user runs `sudo npm install`.
232
233## Manifests
234
235A `manifest` is similar to a `package.json` file. However, it has a few
236pieces of extra metadata, and sometimes lacks metadata that is inessential
237to package installation.
238
239In addition to the common `package.json` fields, manifests include:
240
241* `manifest._resolved` The tarball url or file path where the package
242 artifact can be found.
243* `manifest._from` A normalized form of the spec passed in as an argument.
244* `manifest._integrity` The integrity value for the package artifact.
245* `manifest._id` The canonical spec of this package version: name@version.
246* `manifest.dist` Registry manifests (those included in a packument) have a
247 `dist` object. Only `tarball` is required, though at least one of
248 `shasum` or `integrity` is almost always present.
249
250 * `tarball` The url to the associated package artifact. (Copied by
251 Pacote to `manifest._resolved`.)
252 * `integrity` The integrity SRI string for the artifact. This may not
253 be present for older packages on the npm registry. (Copied by Pacote
254 to `manifest._integrity`.)
255 * `shasum` Legacy integrity value. Hexadecimal-encoded sha1 hash.
256 (Converted to an SRI string and copied by Pacote to
257 `manifest._integrity` when `dist.integrity` is not present.)
258 * `fileCount` Number of files in the tarball.
259 * `unpackedSize` Size on disk of the package when unpacked.
260 * `signatures` Signatures of the shasum. Includes the keyid that
261 correlates to a [`key from the npm
262 registry`](https://registry.npmjs.org/-/npm/v1/keys)
263
264## Packuments
265
266A packument is the top-level package document that lists the set of
267manifests for available versions for a package.
268
269When a packument is fetched with `accept:
270application/vnd.npm.install-v1+json` in the HTTP headers, only the most
271minimum necessary metadata is returned. Additional metadata is returned
272when fetched with only `accept: application/json`.
273
274For Pacote's purposes, the following fields are relevant:
275
276* `versions` An object where each key is a version, and each value is the
277 manifest for that version.
278* `dist-tags` An object mapping dist-tags to version numbers. This is how
279 `foo@latest` gets turned into `foo@1.2.3`.
280* `time` In the full packument, an object mapping version numbers to
281 publication times, for the `opts.before` functionality.
282
283Pacote adds the following field, regardless of the accept header:
284
285* `_contentLength` The size of the packument.
286