diff options
Diffstat (limited to 'deps/npm/node_modules/pacote/README.md')
| -rw-r--r-- | deps/npm/node_modules/pacote/README.md | 462 |
1 files changed, 209 insertions, 253 deletions
diff --git a/deps/npm/node_modules/pacote/README.md b/deps/npm/node_modules/pacote/README.md index f29d330d8c..49dbde6a92 100644 --- a/deps/npm/node_modules/pacote/README.md +++ b/deps/npm/node_modules/pacote/README.md @@ -1,288 +1,244 @@ -# pacote [](https://npm.im/pacote) [](https://npm.im/pacote) [](https://travis-ci.org/npm/pacote) [](https://ci.appveyor.com/project/npm/pacote) [](https://coveralls.io/github/npm/pacote?branch=latest) +# pacote -[`pacote`](https://github.com/npm/pacote) is a Node.js library for downloading -[npm](https://npmjs.org)-compatible packages. It supports all package specifier -syntax that `npm install` and its ilk support. It transparently caches anything -needed to reduce excess operations, using [`cacache`](https://npm.im/cacache). +JavaScript Package Handler -## Install +## USAGE -`$ npm install --save pacote` - -## Table of Contents - -* [Example](#example) -* [Features](#features) -* [Contributing](#contributing) -* [API](#api) - * [`manifest`](#manifest) - * [`packument`](#packument) - * [`extract`](#extract) - * [`tarball`](#tarball) - * [`tarball.stream`](#tarball-stream) - * [`tarball.toFile`](#tarball-to-file) - * ~~[`prefetch`](#prefetch)~~ (deprecated) - * [`clearMemoized`](#clearMemoized) - * [`options`](#options) - -### Example - -```javascript +```js const pacote = require('pacote') -pacote.manifest('pacote@^1').then(pkg => { - console.log('package manifest for registry pkg:', pkg) - // { "name": "pacote", "version": "1.0.0", ... } -}) +// get a package manifest +pacote.manifest('foo@1.x').then(manifest => console.log('got it', manifest)) -pacote.extract('http://hi.com/pkg.tgz', './here').then(() => { - console.log('remote tarball contents extracted to ./here') -}) -``` +// extract a package into a folder +pacote.extract('github:npm/cli', 'some/path', options) + .then(({from, resolved, integrity}) => { + console.log('extracted!', from, resolved, integrity) + }) -### Features - -* Handles all package types [npm](https://npm.im/npm) does -* [high-performance, reliable, verified local cache](https://npm.im/cacache) -* offline mode -* authentication support (private git, private npm registries, etc) -* github, gitlab, and bitbucket-aware -* semver range support for git dependencies - -### Contributing - -The pacote team enthusiastically welcomes contributions and project participation! There's a bunch of things you can do if you want to contribute! The [Contributor Guide](CONTRIBUTING.md) has all the information you need for everything from reporting bugs to contributing entire new features. Please don't hesitate to jump in if you'd like to, or even ask us questions if something isn't clear. - -### API - -#### <a name="manifest"></a> `> pacote.manifest(spec, [opts])` - -Fetches the *manifest* for a package. Manifest objects are similar and based -on the `package.json` for that package, but with pre-processed and limited -fields. The object has the following shape: - -```javascript -{ - "name": PkgName, - "version": SemverString, - "dependencies": { PkgName: SemverString }, - "optionalDependencies": { PkgName: SemverString }, - "devDependencies": { PkgName: SemverString }, - "peerDependencies": { PkgName: SemverString }, - "bundleDependencies": false || [PkgName], - "bin": { BinName: Path }, - "_resolved": TarballSource, // different for each package type - "_integrity": SubresourceIntegrityHash, - "_shrinkwrap": null || ShrinkwrapJsonObj -} -``` - -Note that depending on the spec type, some additional fields might be present. -For example, packages from `registry.npmjs.org` have additional metadata -appended by the registry. - -##### Example - -```javascript -pacote.manifest('pacote@1.0.0').then(pkgJson => { - // fetched `package.json` data from the registry +pacote.tarball('https://server.com/package.tgz').then(data => { + console.log('got ' + data.length + ' bytes of tarball data') }) ``` -#### <a name="packument"></a> `> pacote.packument(spec, [opts])` - -Fetches the *packument* for a package. Packument objects are general metadata -about a project corresponding to registry metadata, and include version and -`dist-tag` information about a package's available versions, rather than a -specific version. It may include additional metadata not usually available -through the individual package metadata objects. - -It generally looks something like this: - -```javascript -{ - "name": PkgName, - "dist-tags": { - 'latest': VersionString, - [TagName]: VersionString, - ... - }, - "versions": { - [VersionString]: Manifest, - ... - } -} -``` +Anything that you can do to with kind of package, you can do to any kind of +package. Data that isn't relevant (like a packument for a tarball) will be +simulated. -Note that depending on the spec type, some additional fields might be present. -For example, packages from `registry.npmjs.org` have additional metadata -appended by the registry. +## CLI -##### Example +This module exports a command line interface that can do most of what is +described below. Run `pacote -h` to learn more. -```javascript -pacote.packument('pacote').then(pkgJson => { - // fetched package versions metadata from the registry -}) ``` +Pacote - The JavaScript Package Handler, v10.1.1 -#### <a name="extract"></a> `> pacote.extract(spec, destination, [opts])` +Usage: -Extracts package data identified by `<spec>` into a directory named -`<destination>`, which will be created if it does not already exist. + pacote resolve <spec> + Resolve a specifier and output the fully resolved target + Returns integrity and from if '--long' flag is set. -If `opts.digest` is provided and the data it identifies is present in the cache, -`extract` will bypass most of its operations and go straight to extracting the -tarball. + pacote manifest <spec> + Fetch a manifest and print to stdout -##### Example + pacote packument <spec> + Fetch a full packument and print to stdout -```javascript -pacote.extract('pacote@1.0.0', './woot', { - digest: 'deadbeef' -}).then(() => { - // Succeeds as long as `pacote@1.0.0` still exists somewhere. Network and - // other operations are bypassed entirely if `digest` is present in the cache. -}) -``` - -#### <a name="tarball"></a> `> pacote.tarball(spec, [opts])` - -Fetches package data identified by `<spec>` and returns the data as a buffer. + pacote tarball <spec> [<filename>] + Fetch a package tarball and save to <filename> + If <filename> is missing or '-', the tarball will be streamed to stdout. -This API has two variants: + pacote extract <spec> <folder> + Extract a package to the destination folder. -* `pacote.tarball.stream(spec, [opts])` - Same as `pacote.tarball`, except it returns a stream instead of a Promise. -* `pacote.tarball.toFile(spec, dest, [opts])` - Instead of returning data directly, data will be written directly to `dest`, and create any required directories along the way. +Configuration values all match the names of configs passed to npm, or +options passed to Pacote. Additional flags for this executable: -##### Example + --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. -```javascript -pacote.tarball('pacote@1.0.0', { cache: './my-cache' }).then(data => { - // data is the tarball data for pacote@1.0.0 -}) +For example '--cache=/path/to/folder' will use that folder as the cache. ``` -#### <a name="tarball-stream"></a> `> pacote.tarball.stream(spec, [opts])` - -Same as `pacote.tarball`, except it returns a stream instead of a Promise. - -##### Example +## 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. +* `log` A logger object with methods for various log levels. Typically, + this will be [`npmlog`](http://npm.im/npmlog) in the npm CLI use case, + but if not specified, the default is a logger that emits `'log'` events + on the `process` object. +* `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. + +## Extracted File Modes + +Files are extracted with a mode matching the following formula: -```javascript -pacote.tarball.stream('pacote@1.0.0') -.pipe(fs.createWriteStream('./pacote-1.0.0.tgz')) ``` - -#### <a name="tarball-to-file"></a> `> pacote.tarball.toFile(spec, dest, [opts])` - -Like `pacote.tarball`, but instead of returning data directly, data will be -written directly to `dest`, and create any required directories along the way. - -##### Example - -```javascript -pacote.tarball.toFile('pacote@1.0.0', './pacote-1.0.0.tgz') -.then(() => /* pacote tarball written directly to ./pacote-1.0.0.tgz */) +( (tarball entry mode value) | (minimum mode option) ) ~ (umask) ``` -#### <a name="prefetch"></a> `> pacote.prefetch(spec, [opts])` - -##### THIS API IS DEPRECATED. USE `pacote.tarball()` INSTEAD +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. -Fetches package data identified by `<spec>`, usually for the purpose of warming -up the local package cache (with `opts.cache`). It does not return anything. +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. -##### Example +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`: -```javascript -pacote.prefetch('pacote@1.0.0', { cache: './my-cache' }).then(() => { - // ./my-cache now has both the manifest and tarball for `pacote@1.0.0`. -}) ``` - -#### <a name="clearMemoized"></a> `> pacote.clearMemoized()` - -This utility function can be used to force pacote to release its references -to any memoized data in its various internal caches. It might help free -some memory. - -```javascript -pacote.manifest(...).then(() => pacote.clearMemoized) - +(0o771 | 0o666) => 0o777 +(0o777 ~ 0o22) => 0o755 ``` -#### <a name="options"></a> `> options` - -`pacote` accepts [the options for -`npm-registry-fetch`](https://npm.im/npm-registry-fetch#fetch-options) as-is, -with a couple of additional `pacote-specific` ones: - -##### <a name="dirPacker"></a> `opts.dirPacker` - -* Type: Function -* Default: Uses [`npm-packlist`](https://npm.im/npm-packlist) and [`tar`](https://npm.im/tar) to make a tarball. - -Expects a function that takes a single argument, `dir`, and returns a -`ReadableStream` that outputs packaged tarball data. Used when creating tarballs -for package specs that are not already packaged, such as git and directory -dependencies. The default `opts.dirPacker` does not execute `prepare` scripts, -even though npm itself does. - -##### <a name="opts-enjoy-by"></a> `opts.enjoy-by` - -* Alias: `opts.enjoyBy`, `opts.before` -* Type: Date-able -* Default: undefined - -If passed in, will be used while resolving to filter the versions for **registry -dependencies** such that versions published **after** `opts.enjoy-by` are not -considered -- as if they'd never been published. - -##### <a name="opts-include-deprecated"></a> `opts.include-deprecated` - -* Alias: `opts.includeDeprecated` -* Type: Boolean -* Default: false - -If false, deprecated versions will be skipped when selecting from registry range -specifiers. If true, deprecations do not affect version selection. - -##### <a name="opts-full-metadata"></a> `opts.full-metadata` - -* Type: Boolean -* Default: false - -If `true`, the full packument will be fetched when doing metadata requests. By -defaul, `pacote` only fetches the summarized packuments, also called "corgis". - -##### <a name="opts-tag"></a> `opts.tag` - -* Alias: `opts.defaultTag` -* Type: String -* Default: `'latest'` - -Package version resolution tag. When processing registry spec ranges, this -option is used to determine what dist-tag to treat as "latest". For more details -about how `pacote` selects versions and how `tag` is involved, see [the -documentation for `npm-pick-manifest`](https://npm.im/npm-pick-manifest). - -##### <a name="opts-resolved"></a> `opts.resolved` - -* Type: String -* Default: null - -When fetching tarballs, this option can be passed in to skip registry metadata -lookups when downloading tarballs. If the string is a `file:` URL, pacote will -try to read the referenced local file before attempting to do any further -lookups. This option does not bypass integrity checks when `opts.integrity` is -passed in. - -##### <a name="opts-where"></a> `opts.where` - -* Type: String -* Default: null - -Passed as an argument to [`npm-package-arg`](https://npm.im/npm-package-arg) -when resolving `spec` arguments. Used to determine what path to resolve local -path specs relatively from. +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.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. + * `npm-signature` A signature of the package by the + [`npmregistry`](https://keybase.io/npmregistry) Keybase account. + (Obviously only present for packages published to + `https://registry.npmjs.org`.) + +## 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. |