• Home
Name Date Size #Lines LOC

..--

lib/12-May-2024-1,7761,302

LICENSED12-May-2024791 1612

README.mdD12-May-202411.6 KiB286220

package.jsonD12-May-20241.9 KiB8079

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