251 lines
12 KiB
Markdown
251 lines
12 KiB
Markdown
|
# pacote
|
||
|
|
|
||
|
|
Fetches package manifests and tarballs from the npm registry.
|
||
|
|
|
||
|
|
## USAGE
|
||
|
|
|
||
|
|
```js
|
||
|
|
const pacote = require('pacote')
|
||
|
|
|
||
|
|
// get a package manifest
|
||
|
|
pacote.manifest('foo@1.x').then(manifest => console.log('got it', manifest))
|
||
|
|
|
||
|
|
// extract a package into a folder
|
||
|
|
pacote.extract('github:npm/cli', 'some/path', options)
|
||
|
|
.then(({from, resolved, integrity}) => {
|
||
|
|
console.log('extracted!', from, resolved, integrity)
|
||
|
|
})
|
||
|
|
|
||
|
|
pacote.tarball('https://server.com/package.tgz').then(data => {
|
||
|
|
console.log('got ' + data.length + ' bytes of tarball data')
|
||
|
|
})
|
||
|
|
```
|
||
|
|
|
||
|
|
`pacote` works with any kind of package specifier that npm can install.
|
||
|
|
If you can pass it to the npm CLI, you can pass it to pacote.
|
||
|
|
(In fact, that's exactly what the npm CLI does.)
|
||
|
|
|
||
|
|
Anything that you can do with one kind of package, you can do with another.
|
||
|
|
|
||
|
|
Data that isn't relevant (like a packument for a tarball) will be simulated.
|
||
|
|
|
||
|
|
`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.
|
||
|
|
|
||
|
|
## CLI
|
||
|
|
|
||
|
|
This module exports a command line interface that can do most of what is described below. Run `pacote -h` to learn more.
|
||
|
|
|
||
|
|
```
|
||
|
|
Pacote - The JavaScript Package Handler, v10.1.1
|
||
|
|
|
||
|
|
Usage:
|
||
|
|
|
||
|
|
pacote resolve <spec>
|
||
|
|
Resolve a specifier and output the fully resolved target
|
||
|
|
Returns integrity and from if '--long' flag is set.
|
||
|
|
|
||
|
|
pacote manifest <spec>
|
||
|
|
Fetch a manifest and print to stdout
|
||
|
|
|
||
|
|
pacote packument <spec>
|
||
|
|
Fetch a full packument and print to stdout
|
||
|
|
|
||
|
|
pacote tarball <spec> [<filename>]
|
||
|
|
Fetch a package tarball and save to <filename>
|
||
|
|
If <filename> is missing or '-', the tarball will be streamed to stdout.
|
||
|
|
|
||
|
|
pacote extract <spec> <folder>
|
||
|
|
Extract a package to the destination folder.
|
||
|
|
|
||
|
|
Configuration values all match the names of configs passed to npm, or
|
||
|
|
options passed to Pacote. Additional flags for this executable:
|
||
|
|
|
||
|
|
--long Print an object from 'resolve', including integrity and spec.
|
||
|
|
--json Print result objects as JSON rather than node's default.
|
||
|
|
(This is the default if stdout is not a TTY.)
|
||
|
|
--help -h Print this helpful text.
|
||
|
|
|
||
|
|
For example '--cache=/path/to/folder' will use that folder as the cache.
|
||
|
|
```
|
||
|
|
|
||
|
|
## API
|
||
|
|
|
||
|
|
The `spec` refers to any kind of [package specifier](npm.im/npm-package-arg) that npm can install.
|
||
|
|
|
||
|
|
See below for valid `opts` values.
|
||
|
|
|
||
|
|
* `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.
|
||
|
|
|
||
|
|
* `pacote.extract(spec, dest, opts)` Extract a package's tarball into a destination folder.
|
||
|
|
Returns a promise that resolves to the `{from,resolved,integrity}` of the extracted package.
|
||
|
|
|
||
|
|
* `pacote.manifest(spec, opts)` Fetch (or simulate) a package's manifest (basically, the `package.json` file, plus a bit of metadata).
|
||
|
|
See below for more on manifests and packuments.
|
||
|
|
Returns a Promise that resolves to the manifest object.
|
||
|
|
|
||
|
|
* `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).
|
||
|
|
See below for more on manifests and packuments.
|
||
|
|
Returns a Promise that resolves to the packument object.
|
||
|
|
|
||
|
|
* `pacote.tarball(spec, opts)` Get a package tarball data as a buffer in
|
||
|
|
memory.
|
||
|
|
Returns a Promise that resolves to the tarball data Buffer, with `from`, `resolved`, and `integrity` fields attached.
|
||
|
|
|
||
|
|
* `pacote.tarball.file(spec, dest, opts)` Save a package tarball data to a file on disk.
|
||
|
|
Returns a Promise that resolves to `{from,integrity,resolved}` of the fetched tarball.
|
||
|
|
|
||
|
|
* `pacote.tarball.stream(spec, streamHandler, opts)` Fetch a tarball and make the stream available to the `streamHandler` function.
|
||
|
|
|
||
|
|
This is mostly an internal function, but it is exposed because it does provide some functionality that may be difficult to achieve otherwise.
|
||
|
|
|
||
|
|
The `streamHandler` function MUST return a Promise that resolves when the stream (and all associated work) is ended, or rejects if the stream
|
||
|
|
has an error.
|
||
|
|
|
||
|
|
The `streamHandler` function MAY be called multiple times, as Pacote retries requests in some scenarios, such as cache corruption or retriable network failures.
|
||
|
|
|
||
|
|
### Options
|
||
|
|
|
||
|
|
Options are passed to
|
||
|
|
[`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.
|
||
|
|
|
||
|
|
Options object is cloned, and mutated along the way to add integrity, resolved, and other properties, as they are determined.
|
||
|
|
|
||
|
|
* `cache` Where to store cache entries and temp files.
|
||
|
|
Passed to [`cacache`](http://npm.im/cacache).
|
||
|
|
Defaults to the same cache directory that npm will use by default, based on platform and environment.
|
||
|
|
* `where` Base folder for resolving relative `file:` dependencies.
|
||
|
|
* `resolved` Shortcut for looking up resolved values. Should be specified if known.
|
||
|
|
* `integrity` Expected integrity of fetched package tarball.
|
||
|
|
If specified, tarballs with mismatched integrity values will raise an `EINTEGRITY` error.
|
||
|
|
* `umask` Permission mode mask for extracted files and directories.
|
||
|
|
Defaults to `0o22`.
|
||
|
|
See "Extracted File Modes" below.
|
||
|
|
* `fmode` Minimum permission mode for extracted files.
|
||
|
|
Defaults to `0o666`.
|
||
|
|
See "Extracted File Modes" below.
|
||
|
|
* `dmode` Minimum permission mode for extracted directories.
|
||
|
|
Defaults to `0o777`.
|
||
|
|
See "Extracted File Modes" below.
|
||
|
|
* `preferOnline` Prefer to revalidate cache entries, even when it would not be strictly necessary.
|
||
|
|
Defaults to `false`.
|
||
|
|
* `before` When picking a manifest from a packument, only consider packages published before the specified date.
|
||
|
|
Defaults to `null`.
|
||
|
|
* `defaultTag` The default `dist-tag` to use when choosing a manifest from a packument.
|
||
|
|
Defaults to `latest`.
|
||
|
|
* `registry` The npm registry to use by default.
|
||
|
|
Defaults to `https://registry.npmjs.org/`.
|
||
|
|
* `fullMetadata` Fetch the full metadata from the registry for packuments, including information not strictly required for installation (author, description, etc.).
|
||
|
|
Defaults to `true` when `before` is set, since the version publish time is part of the extended packument metadata.
|
||
|
|
Otherwise defaults to `false`.
|
||
|
|
* `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.
|
||
|
|
Defaults to `false`.
|
||
|
|
* `packumentCache` For registry packuments only, you may provide a `Map` object which will be used to cache packument requests between pacote calls.
|
||
|
|
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.
|
||
|
|
* `verifySignatures` A boolean that will make pacote verify the integrity signature of a manifest, if present.
|
||
|
|
There must be a configured `_keys` entry in the config that is scoped to the registry the manifest is being fetched from.
|
||
|
|
* `verifyAttestations` A boolean that will make pacote verify Sigstore attestations, if present.
|
||
|
|
There must be a configured `_keys` entry in the config that is scoped to the registry the manifest is being fetched from.
|
||
|
|
* `tufCache` Where to store metadata/target files when retrieving the package attestation key material via TUF.
|
||
|
|
Defaults to the same cache directory that npm will use by default, based on platform and environment.
|
||
|
|
* `allowGit` Whether or not to allow data to be fetched from a git spec.
|
||
|
|
Possible values are `all`, `none`, or `root`.
|
||
|
|
Defaults to `all`.
|
||
|
|
`all` means git is allowed
|
||
|
|
`none` means git is not allowed
|
||
|
|
`root` means that git is only allowed if fetching from a root context.
|
||
|
|
Context for whether or not the package being fetched is `root` is set via the `_isRoot` option.
|
||
|
|
* `allowRemote` Whether or not to allow data to be fetched from remote specs.
|
||
|
|
Possible values and defaults are the same as `allowGit`
|
||
|
|
* `allowFile` Whether or not to allow data to be fetched from file specs.
|
||
|
|
Possible values and defaults are the same as `allowGit`
|
||
|
|
* `allowDirectory` Whether or not to allow data to be fetched from directory specs.
|
||
|
|
Possible values and defaults are the same as `allowGit`
|
||
|
|
* `_isRoot` Whether or not the package being fetched is in a root context.
|
||
|
|
Defaults to `false`,
|
||
|
|
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.
|
||
|
|
|
||
|
|
For more info on spec types (i.e. git, remote) see [npm-package-arg](npm.im/npm-package-arg)
|
||
|
|
|
||
|
|
### Advanced API
|
||
|
|
|
||
|
|
Each different type of fetcher is exposed for more advanced usage such as using helper methods from this classes:
|
||
|
|
|
||
|
|
* `DirFetcher`
|
||
|
|
* `FileFetcher`
|
||
|
|
* `GitFetcher`
|
||
|
|
* `RegistryFetcher`
|
||
|
|
* `RemoteFetcher`
|
||
|
|
|
||
|
|
## Extracted File Modes
|
||
|
|
|
||
|
|
Files are extracted with a mode matching the following formula:
|
||
|
|
|
||
|
|
```
|
||
|
|
( (tarball entry mode value) | (minimum mode option) ) ~ (umask)
|
||
|
|
```
|
||
|
|
|
||
|
|
This 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.
|
||
|
|
|
||
|
|
It 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.
|
||
|
|
|
||
|
|
So, 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`:
|
||
|
|
|
||
|
|
```
|
||
|
|
(0o771 | 0o666) => 0o777
|
||
|
|
(0o777 ~ 0o22) => 0o755
|
||
|
|
```
|
||
|
|
|
||
|
|
In almost every case, the defaults are appropriate.
|
||
|
|
To respect exactly what is in the package tarball (even if this makes an unusable system), set both `dmode` and `fmode` options to `0`.
|
||
|
|
Otherwise, 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.
|
||
|
|
|
||
|
|
## Extracted File Ownership
|
||
|
|
|
||
|
|
When 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.
|
||
|
|
|
||
|
|
This prevents `root`-owned files showing up in a project's `node_modules` folder when a user runs `sudo npm install`.
|
||
|
|
|
||
|
|
## Manifests
|
||
|
|
|
||
|
|
A `manifest` is similar to a `package.json` file.
|
||
|
|
However, it has a few pieces of extra metadata, and sometimes lacks metadata that is inessential to package installation.
|
||
|
|
|
||
|
|
In addition to the common `package.json` fields, manifests include:
|
||
|
|
|
||
|
|
* `manifest._resolved` The tarball url or file path where the package artifact can be found.
|
||
|
|
* `manifest._from` A normalized form of the spec passed in as an argument.
|
||
|
|
* `manifest._integrity` The integrity value for the package artifact.
|
||
|
|
* `manifest._id` The canonical spec of this package version: name@version.
|
||
|
|
* `manifest.dist` Registry manifests (those included in a packument) have a `dist` object.
|
||
|
|
Only `tarball` is required, though at least one of `shasum` or `integrity` is almost always present.
|
||
|
|
|
||
|
|
* `tarball` The url to the associated package artifact.
|
||
|
|
(Copied by Pacote to `manifest._resolved`.)
|
||
|
|
* `integrity` The integrity SRI string for the artifact.
|
||
|
|
This may not be present for older packages on the npm registry.
|
||
|
|
(Copied by Pacote to `manifest._integrity`.)
|
||
|
|
* `shasum` Legacy integrity value. Hexadecimal-encoded sha1 hash.
|
||
|
|
(Converted to an SRI string and copied by Pacote to `manifest._integrity` when `dist.integrity` is not present.)
|
||
|
|
* `fileCount` Number of files in the tarball.
|
||
|
|
* `unpackedSize` Size on disk of the package when unpacked.
|
||
|
|
* `signatures` Signatures of the shasum.
|
||
|
|
Includes the keyid that correlates to a [`key from the npm registry`](https://registry.npmjs.org/-/npm/v1/keys)
|
||
|
|
|
||
|
|
## Packuments
|
||
|
|
|
||
|
|
A packument is the top-level package document that lists the set of manifests for available versions for a package.
|
||
|
|
|
||
|
|
When a packument is fetched with `accept: application/vnd.npm.install-v1+json` in the HTTP headers, only the most minimum necessary metadata is returned.
|
||
|
|
Additional metadata is returned when fetched with only `accept: application/json`.
|
||
|
|
|
||
|
|
For Pacote's purposes, the following fields are relevant:
|
||
|
|
|
||
|
|
* `versions` An object where each key is a version, and each value is the manifest for that version.
|
||
|
|
* `dist-tags` An object mapping dist-tags to version numbers.
|
||
|
|
This is how `foo@latest` gets turned into `foo@1.2.3`.
|
||
|
|
* `time` In the full packument, an object mapping version numbers to publication times, for the `opts.before` functionality.
|
||
|
|
|
||
|
|
Pacote adds the following field, regardless of the accept header:
|
||
|
|
|
||
|
|
* `_contentLength` The size of the packument.
|