codekingpro/portable-devtools

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