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