284 lines
12 KiB
Markdown
284 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 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.)
|
||
|
|
|
||
|
|
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. Default `false`.
|
||
|
|
* `before` When picking a manifest from a packument, only consider
|
||
|
|
packages published before the specified date. Default `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.
|
||
|
|
* `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.
|
||
|
|
|
||
|
|
### 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.
|