(url)` format, where email and url are
+ optional. Lines which start with a `#` or are blank, will be ignored.
### SEE ALSO
diff --git a/deps/npm/docs/content/configuring-npm/package-lock-json.md b/deps/npm/docs/content/configuring-npm/package-lock-json.md
index a3083410f7e2a2..4d994bbc8c0a28 100644
--- a/deps/npm/docs/content/configuring-npm/package-lock-json.md
+++ b/deps/npm/docs/content/configuring-npm/package-lock-json.md
@@ -14,132 +14,223 @@ generate identical trees, regardless of intermediate dependency updates.
This file is intended to be committed into source repositories, and serves
various purposes:
-* Describe a single representation of a dependency tree such that teammates, deployments, and continuous integration are guaranteed to install exactly the same dependencies.
+* Describe a single representation of a dependency tree such that
+ teammates, deployments, and continuous integration are guaranteed to
+ install exactly the same dependencies.
-* Provide a facility for users to "time-travel" to previous states of `node_modules` without having to commit the directory itself.
+* Provide a facility for users to "time-travel" to previous states of
+ `node_modules` without having to commit the directory itself.
-* To facilitate greater visibility of tree changes through readable source control diffs.
+* Facilitate greater visibility of tree changes through readable source
+ control diffs.
-* And optimize the installation process by allowing npm to skip repeated metadata resolutions for previously-installed packages.
+* Optimize the installation process by allowing npm to skip repeated
+ metadata resolutions for previously-installed packages.
-One key detail about `package-lock.json` is that it cannot be published, and it
-will be ignored if found in any place other than the toplevel package. It shares
-a format with [npm-shrinkwrap.json](/configuring-npm/shrinkwrap-json), which is essentially the same file, but
-allows publication. This is not recommended unless deploying a CLI tool or
-otherwise using the publication process for producing production packages.
+* As of npm v7, lockfiles include enough information to gain a complete
+ picture of the package tree, reducing the need to read `package.json`
+ files, and allowing for significant performance improvements.
-If both `package-lock.json` and `npm-shrinkwrap.json` are present in the root of
-a package, `package-lock.json` will be completely ignored.
+### `package-lock.json` vs `npm-shrinkwrap.json`
+Both of these files have the same format, and perform similar functions in
+the root of a project.
-### File Format
+The difference is that `package-lock.json` is that it cannot be published,
+and it will be ignored if found in any place other than the root project.
-#### name
+In contrast, [npm-shrinkwrap.json](/configuring-npm/npm-shrinkwrap-json) allows
+publication, and defines the dependency tree from the point encountered.
+This is not recommended unless deploying a CLI tool or otherwise using the
+publication process for producing production packages.
-The name of the package this is a package-lock for. This must match what's in
-`package.json`.
+If both `package-lock.json` and `npm-shrinkwrap.json` are present in the
+root of a project, `npm-shrinkwrap.json` will take precedence and
+`package-lock.json` will be ignored.
-#### version
+### Hidden Lockfiles
-The version of the package this is a package-lock for. This must match what's in
-`package.json`.
+In order to avoid processing the `node_modules` folder repeatedly, npm as
+of v7 uses a "hidden" lockfile present in
+`node_modules/.package-lock.json`. This contains information about the
+tree, and is used in lieu of reading the entire `node_modules` hierarchy
+provided that the following conditions are met:
-#### lockfileVersion
+- All package folders it references exist in the `node_modules` hierarchy.
+- No package folders exist in the `node_modules` hierarchy that are not
+ listed in the lockfile.
+- The modified time of the file is at least as recent as all of the package
+ folders it references.
-An integer version, starting at `1` with the version number of this document
-whose semantics were used when generating this `package-lock.json`.
+That is, the hidden lockfile will only be relevant if it was created as
+part of the most recent update to the package tree. If another CLI mutates
+the tree in any way, this will be detected, and the hidden lockfile will be
+ignored.
-#### packageIntegrity
+Note that it _is_ possible to manually change the _contents_ of a package
+in such a way that the modified time of the package folder is unaffected.
+For example, if you add a file to `node_modules/foo/lib/bar.js`, then the
+modified time on `node_modules/foo` will not reflect this change. If you
+are manually editing files in `node_modules`, it is generally best to
+delete the file at `node_modules/.package-lock.json`.
-This is a [subresource
-integrity](https://w3c.github.io/webappsec/specs/subresourceintegrity/) value
-created from the `package.json`. No preprocessing of the `package.json` should
-be done. Subresource integrity strings can be produced by modules like
-[`ssri`](https://www.npmjs.com/package/ssri).
+As the hidden lockfile is ignored by older npm versions, it does not
+contain the backwards compatibility affordances present in "normal"
+lockfiles. That is, it is `lockfileVersion: 3`, rather than
+`lockfileVersion: 2`.
-#### preserveSymlinks
+### Handling Old Lockfiles
-Indicates that the install was done with the environment variable
-`NODE_PRESERVE_SYMLINKS` enabled. The installer should insist that the value of
-this property match that environment variable.
+When npm detects a lockfile from npm v6 or before during the package
+installation process, it is automatically updated to fetch missing
+information from either the `node_modules` tree or (in the case of empty
+`node_modules` trees or very old lockfile formats) the npm registry.
-#### dependencies
+### File Format
-A mapping of package name to dependency object. Dependency objects have the
-following properties:
+#### `name`
-##### version
+The name of the package this is a package-lock for. This will match what's
+in `package.json`.
-This is a specifier that uniquely identifies this package and should be
-usable in fetching a new copy of it.
+#### `version`
-* bundled dependencies: Regardless of source, this is a version number that is purely for informational purposes.
-* registry sources: This is a version number. (eg, `1.2.3`)
-* git sources: This is a git specifier with resolved committish. (eg, `git+https://example.com/foo/bar#115311855adb0789a0466714ed48a1499ffea97e`)
-* http tarball sources: This is the URL of the tarball. (eg, `https://example.com/example-1.3.0.tgz`)
-* local tarball sources: This is the file URL of the tarball. (eg `file:///opt/storage/example-1.3.0.tgz`)
-* local link sources: This is the file URL of the link. (eg `file:libs/our-module`)
+The version of the package this is a package-lock for. This will match
+what's in `package.json`.
-##### integrity
+#### `lockfileVersion`
-This is a [Standard Subresource
-Integrity](https://w3c.github.io/webappsec/specs/subresourceintegrity/) for this
-resource.
+An integer version, starting at `1` with the version number of this
+document whose semantics were used when generating this
+`package-lock.json`.
-* For bundled dependencies this is not included, regardless of source.
-* For registry sources, this is the `integrity` that the registry provided, or if one wasn't provided the SHA1 in `shasum`.
-* For git sources this is the specific commit hash we cloned from.
-* For remote tarball sources this is an integrity based on a SHA512 of
- the file.
-* For local tarball sources: This is an integrity field based on the SHA512 of the file.
+Note that the file format changed significantly in npm v7 to track
+information that would have otherwise required looking in `node_modules` or
+the npm registry. Lockfiles generated by npm v7 will contain
+`lockfileVersion: 2`.
-##### resolved
+* No version provided: an "ancient" shrinkwrap file from a version of npm
+ prior to npm v5.
+* `1`: The lockfile version used by npm v5 and v6.
+* `2`: The lockfile version used by npm v7, which is backwards compatible
+ to v1 lockfiles.
+* `3`: The lockfile version used by npm v7, _without_ backwards
+ compatibility affordances. This is used for the hidden lockfile at
+ `node_modules/.package-lock.json`, and will likely be used in a future
+ version of npm, once support for npm v6 is no longer relevant.
-* For bundled dependencies this is not included, regardless of source.
-* For registry sources this is path of the tarball relative to the registry
- URL. If the tarball URL isn't on the same server as the registry URL then
- this is a complete URL.
+npm will always attempt to get whatever data it can out of a lockfile, even
+if it is not a version that it was designed to support.
-##### bundled
+#### `packages`
-If true, this is the bundled dependency and will be installed by the parent
-module. When installing, this module will be extracted from the parent
-module during the extract phase, not installed as a separate dependency.
+This is an object that maps package locations to an object containing the
+information about that package.
-##### dev
+The root project is typically listed with a key of `""`, and all other
+packages are listed with their relative paths from the root project folder.
-If true then this dependency is either a development dependency ONLY of the
-top level module or a transitive dependency of one. This is false for
-dependencies that are both a development dependency of the top level and a
-transitive dependency of a non-development dependency of the top level.
+Package descriptors have the following fields:
-##### optional
+* version: The version found in `package.json`
-If true then this dependency is either an optional dependency ONLY of the
-top level module or a transitive dependency of one. This is false for
-dependencies that are both an optional dependency of the top level and a
-transitive dependency of a non-optional dependency of the top level.
+* resolved: The place where the package was actually resolved from. In
+ the case of packages fetched from the registry, this will be a url to a
+ tarball. In the case of git dependencies, this will be the full git url
+ with commit sha. In the case of link dependencies, this will be the
+ location of the link target.
-All optional dependencies should be included even if they're uninstallable
-on the current platform.
+* integrity: A `sha512` or `sha1` [Standard Subresource
+ Integrity](https://w3c.github.io/webappsec/specs/subresourceintegrity/)
+ string for the artifact that was unpacked in this location.
+* link: A flag to indicate that this is a symbolic link. If this is
+ present, no other fields are specified, since the link target will also
+ be included in the lockfile.
-##### requires
+* dev, optional, devOptional: If the package is strictly part of the
+ `devDependencies` tree, then `dev` will be true. If it is strictly part
+ of the `optionalDependencies` tree, then `optional` will be set. If it
+ is both a `dev` dependency _and_ an `optional` dependency of a non-dev
+ dependency, then `devOptional` will be set. (An `optional` dependency of
+ a `dev` dependency will have both `dev` and `optional` set.)
-This is a mapping of module name to version. This is a list of everything
-this module requires, regardless of where it will be installed. The version
-should match via normal matching rules a dependency either in our
-`dependencies` or in a level higher than us.
+* inBundle: A flag to indicate that the package is a bundled dependency.
+* hasInstallScript: A flag to indicate that the package has a `preinstall`,
+ `install`, or `postinstall` script.
-##### dependencies
+* hasShrinkwrap: A flag to indicate that the package has an
+ `npm-shrinkwrap.json` file.
+
+* bin, license, engines, dependencies, optionalDependencies: fields from
+ `package.json`
+
+#### dependencies
-The dependencies of this dependency, exactly as at the top level.
+Legacy data for supporting versions of npm that use `lockfileVersion: 1`.
+This is a mapping of package names to dependency objects. Because the
+object structure is strictly hierarchical, symbolic link dependencies are
+somewhat challenging to represent in some cases.
+
+npm v7 ignores this section entirely if a `packages` section is present,
+but does keep it up to date in order to support switching between npm v6
+and npm v7.
+
+Dependency objects have the following fields:
+
+* version: a specifier that varies depending on the nature of the package,
+ and is usable in fetching a new copy of it.
+
+ * bundled dependencies: Regardless of source, this is a version number
+ that is purely for informational purposes.
+ * registry sources: This is a version number. (eg, `1.2.3`)
+ * git sources: This is a git specifier with resolved committish. (eg,
+ `git+https://example.com/foo/bar#115311855adb0789a0466714ed48a1499ffea97e`)
+ * http tarball sources: This is the URL of the tarball. (eg,
+ `https://example.com/example-1.3.0.tgz`)
+ * local tarball sources: This is the file URL of the tarball. (eg
+ `file:///opt/storage/example-1.3.0.tgz`)
+ * local link sources: This is the file URL of the link. (eg
+ `file:libs/our-module`)
+
+* integrity: A `sha512` or `sha1` [Standard Subresource
+ Integrity](https://w3c.github.io/webappsec/specs/subresourceintegrity/)
+ string for the artifact that was unpacked in this location. For git
+ dependencies, this is the commit sha.
+
+* resolved: For registry sources this is path of the tarball relative to
+ the registry URL. If the tarball URL isn't on the same server as the
+ registry URL then this is a complete URL.
+
+* bundled: If true, this is the bundled dependency and will be installed
+ by the parent module. When installing, this module will be extracted
+ from the parent module during the extract phase, not installed as a
+ separate dependency.
+
+* dev: If true then this dependency is either a development dependency ONLY
+ of the top level module or a transitive dependency of one. This is false
+ for dependencies that are both a development dependency of the top level
+ and a transitive dependency of a non-development dependency of the top
+ level.
+
+* optional: If true then this dependency is either an optional dependency
+ ONLY of the top level module or a transitive dependency of one. This is
+ false for dependencies that are both an optional dependency of the top
+ level and a transitive dependency of a non-optional dependency of the top
+ level.
+
+* requires: This is a mapping of module name to version. This is a list of
+ everything this module requires, regardless of where it will be
+ installed. The version should match via normal matching rules a
+ dependency either in our `dependencies` or in a level higher than us.
+
+* dependencies: The dependencies of this dependency, exactly as at the top
+ level.
### See also
* [npm shrinkwrap](/commands/npm-shrinkwrap)
-* [shrinkwrap.json](/configuring-npm/shrinkwrap-json)
-* [package-locks](/configuring-npm/package-locks)
+* [npm-shrinkwrap.json](/configuring-npm/npm-shrinkwrap-json)
* [package.json](/configuring-npm/package-json)
* [npm install](/commands/npm-install)
diff --git a/deps/npm/docs/content/configuring-npm/package-locks.md b/deps/npm/docs/content/configuring-npm/package-locks.md
deleted file mode 100644
index a456ef8936645d..00000000000000
--- a/deps/npm/docs/content/configuring-npm/package-locks.md
+++ /dev/null
@@ -1,178 +0,0 @@
----
-title: package-locks
-section: 5
-description: An explanation of npm lockfiles
----
-
-### Description
-
-Conceptually, the "input" to [`npm install`](/commands/npm-install) is a [package.json](/configuring-npm/package-json), while its
-"output" is a fully-formed `node_modules` tree: a representation of the
-dependencies you declared. In an ideal world, npm would work like a pure
-function: the same `package.json` should produce the exact same `node_modules`
-tree, any time. In some cases, this is indeed true. But in many others, npm is
-unable to do this. There are multiple reasons for this:
-
-* different versions of npm (or other package managers) may have been used to install a package, each using slightly different installation algorithms.
-
-* a new version of a direct semver-range package may have been published since the last time your packages were installed, and thus a newer version will be used.
-
-* A dependency of one of your dependencies may have published a new version, which will update even if you used pinned dependency specifiers (`1.2.3` instead of `^1.2.3`)
-
-* The registry you installed from is no longer available, or allows mutation of versions (unlike the primary npm registry), and a different version of a package exists under the same version number now.
-
-As an example, consider package A:
-
-```json
-{
- "name": "A",
- "version": "0.1.0",
- "dependencies": {
- "B": "<0.1.0"
- }
-}
-```
-
-package B:
-
-```json
-{
- "name": "B",
- "version": "0.0.1",
- "dependencies": {
- "C": "<0.1.0"
- }
-}
-```
-
-and package C:
-```json
-{
- "name": "C",
- "version": "0.0.1"
-}
-```
-
-If these are the only versions of A, B, and C available in the
-registry, then a normal `npm install A` will install:
-
-```json
-A@0.1.0
-`-- B@0.0.1
- `-- C@0.0.1
-```
-
-However, if B@0.0.2 is published, then a fresh `npm install A` will
-install:
-
-```bash
-A@0.1.0
-`-- B@0.0.2
- `-- C@0.0.1
-```
-
-assuming the new version did not modify B's dependencies. Of course,
-the new version of B could include a new version of C and any number
-of new dependencies. If such changes are undesirable, the author of A
-could specify a dependency on B@0.0.1. However, if A's author and B's
-author are not the same person, there's no way for A's author to say
-that he or she does not want to pull in newly published versions of C
-when B hasn't changed at all.
-
-To prevent this potential issue, npm uses [package-lock.json](/configuring-npm/package-lock-json) or, if present, [npm-shrinkwrap.json](/configuring-npm/shrinkwrap-json). These files are called package locks, or lockfiles.
-
-Whenever you run `npm install`, npm generates or updates your package lock,
-which will look something like this:
-
-```json
-{
- "name": "A",
- "version": "0.1.0",
- ...metadata fields...
- "dependencies": {
- "B": {
- "version": "0.0.1",
- "resolved": "https://registry.npmjs.org/B/-/B-0.0.1.tgz",
- "integrity": "sha512-DeAdb33F+"
- "dependencies": {
- "C": {
- "version": "git://github.com/org/C.git#5c380ae319fc4efe9e7f2d9c78b0faa588fd99b4"
- }
- }
- }
- }
-}
-```
-
-This file describes an *exact*, and more importantly *reproducible*
-`node_modules` tree. Once it's present, any future installation will base its
-work off this file, instead of recalculating dependency versions off
-[package.json](/configuring-npm/package-json).
-
-The presence of a package lock changes the installation behavior such that:
-
-1. The module tree described by the package lock is reproduced. This means
-reproducing the structure described in the file, using the specific files
-referenced in "resolved" if available, falling back to normal package resolution
-using "version" if one isn't.
-
-2. The tree is walked and any missing dependencies are installed in the usual
-fashion.
-
-If `preshrinkwrap`, `shrinkwrap` or `postshrinkwrap` are in the `scripts`
-property of the `package.json`, they will be executed in order. `preshrinkwrap`
-and `shrinkwrap` are executed before the shrinkwrap, `postshrinkwrap` is
-executed afterwards. These scripts run for both `package-lock.json` and
-`npm-shrinkwrap.json`. For example to run some postprocessing on the generated
-file:
-
-```json
- "scripts": {
- "postshrinkwrap": "json -I -e \"this.myMetadata = $MY_APP_METADATA\""
- }
-```
-
-#### Using locked packages
-
-Using a locked package is no different than using any package without a package
-lock: any commands that update `node_modules` and/or `package.json`'s
-dependencies will automatically sync the existing lockfile. This includes `npm
-install`, `npm rm`, `npm update`, etc. To prevent this update from happening,
-you can use the `--no-save` option to prevent saving altogether, or
-`--no-shrinkwrap` to allow `package.json` to be updated while leaving
-`package-lock.json` or `npm-shrinkwrap.json` intact.
-
-It is highly recommended you commit the generated package lock to source
-control: this will allow anyone else on your team, your deployments, your
-CI/continuous integration, and anyone else who runs `npm install` in your
-package source to get the exact same dependency tree that you were developing
-on. Additionally, the diffs from these changes are human-readable and will
-inform you of any changes npm has made to your `node_modules`, so you can notice
-if any transitive dependencies were updated, hoisted, etc.
-
-#### Resolving lockfile conflicts
-
-Occasionally, two separate npm install will create package locks that cause
-merge conflicts in source control systems. As of `npm@5.7.0`, these conflicts
-can be resolved by manually fixing any `package.json` conflicts, and then
-running `npm install [--package-lock-only]` again. npm will automatically
-resolve any conflicts for you and write a merged package lock that includes all
-the dependencies from both branches in a reasonable tree. If
-`--package-lock-only` is provided, it will do this without also modifying your
-local `node_modules/`.
-
-To make this process seamless on git, consider installing
-[`npm-merge-driver`](https://npm.im/npm-merge-driver), which will teach git how
-to do this itself without any user interaction. In short: `$ npx
-npm-merge-driver install -g` will let you do this, and even works with
-pre-`npm@5.7.0` versions of npm 5, albeit a bit more noisily. Note that if
-`package.json` itself conflicts, you will have to resolve that by hand and run
-`npm install` manually, even with the merge driver.
-
-### See Also
-
-* https://medium.com/@sdboyer/so-you-want-to-write-a-package-manager-4ae9c17d9527
-* [package.json](/configuring-npm/package-json)
-* [package-lock.json](/configuring-npm/package-lock-json)
-* [shrinkwrap.json](/configuring-npm/shrinkwrap-json)
-* [npm shrinkwrap](/commands/npm-shrinkwrap)
diff --git a/deps/npm/docs/output/commands/npm-audit.html b/deps/npm/docs/output/commands/npm-audit.html
index 4482f6608999f2..8705b442873c05 100644
--- a/deps/npm/docs/output/commands/npm-audit.html
+++ b/deps/npm/docs/output/commands/npm-audit.html
@@ -271,7 +271,6 @@ Examples
See Also
diff --git a/deps/npm/docs/output/commands/npm-ci.html b/deps/npm/docs/output/commands/npm-ci.html
index 9aa49839f5c095..8361e995b3a161 100644
--- a/deps/npm/docs/output/commands/npm-ci.html
+++ b/deps/npm/docs/output/commands/npm-ci.html
@@ -193,7 +193,7 @@ Example
See Also
diff --git a/deps/npm/docs/output/commands/npm-ls.html b/deps/npm/docs/output/commands/npm-ls.html
index b3991e6400e862..15d1bbc99f4784 100644
--- a/deps/npm/docs/output/commands/npm-ls.html
+++ b/deps/npm/docs/output/commands/npm-ls.html
@@ -159,7 +159,7 @@ Description
the results to only the paths to the packages named. Note that nested
packages will also show the paths to the specified packages. For
example, running npm ls promzard in npm’s source tree will show:
-npm@7.4.0 /path/to/npm
+npm@7.4.3 /path/to/npm
└─┬ init-package-json@0.0.4
└── promzard@0.1.5
npm-prefix
Synopsis
npm prefix [-g]
Description
-
Print the local prefix to standard out. This is the closest parent directory
+
Print the local prefix to standard output. This is the closest parent directory
to contain a package.json file or node_modules directory, unless -g is
also specified.
If -g is specified, this will be the value of the global prefix. See
npm config
+
Example
+
npm prefix
+/usr/local/projects/foo
+
+
npm prefix -g
+/usr/local
+See Also
npm root npm-search
Synopsis
@@ -152,29 +152,36 @@
Table of contents
Description
Search the registry for packages matching the search terms. npm search
performs a linear, incremental, lexically-ordered search through package
-metadata for all files in the registry. If color is enabled, it will further
-highlight the matches in the results.
-
Additionally, using the --searchopts and --searchexclude options paired with
-more search terms will respectively include and exclude further patterns. The
-main difference between --searchopts and the standard search terms is that the
-former does not highlight results in the output and can be used for more
-fine-grained filtering. Additionally, both of these can be added to .npmrc for
-default search filtering behavior.
+metadata for all files in the registry. If your terminal has color
+support, it will further highlight the matches in the results. This can
+be disabled with the config item
color
+
Additionally, using the --searchopts and --searchexclude options
+paired with more search terms will include and exclude further patterns.
+The main difference between --searchopts and the standard search terms
+is that the former does not highlight results in the output and you can
+use them more fine-grained filtering. Additionally, you can add both of
+these to your config to change default search filtering behavior.
Search also allows targeting of maintainers in search results, by prefixing
their npm username with =.
-
If a term starts with /, then it’s interpreted as a regular expression and
-supports standard JavaScript RegExp syntax. A trailing / will be ignored in
-this case. (Note that many regular expression characters must be escaped or
-quoted in most shells.)
-
A Note on caching
+
If a term starts with /, then it’s interpreted as a regular expression
+and supports standard JavaScript RegExp syntax. In this case search will
+ignore a trailing / . (Note you must escape or quote many regular
+expression characters in most shells.)
Configuration
+
All of the following can be defined in a .npmrc file, or passed as
+parameters to the cli prefixed with -- (e.g. --json)
description
Default: true
Type: Boolean
-
Used as --no-description, disables search matching in package descriptions and
-suppresses display of that field in results.
+
color
+
+Default: true
+Type: Boolean
+
+
Used as --no-color, disables color highlighting of matches in the
+results.
json
Default: false
@@ -193,9 +200,9 @@ long
Type: Boolean
Display full package descriptions and other long text across multiple
-lines. When disabled (default) search results are truncated to fit
-neatly on a single line. Modules with extremely long names will
-fall on multiple lines.
+lines. When disabled (which is the default) the output will
+truncate search results to fit neatly on a single line. Modules with
+extremely long names will fall on multiple lines.
searchopts
Default: “”
@@ -208,28 +215,37 @@ searchexclude
Type: String
Space-separated options that limit the results from search.
-
searchstaleness
-
-Default: 900 (15 minutes)
-Type: Number
-
-
The age of the cache, in seconds, before another registry request is made.
registry
-
Search the specified registry for modules. If you have configured npm to point
-to a different default registry, such as your internal private module
-repository, npm search will default to that registry when searching. Pass a
-different registry url such as the default above in order to override this
-setting.
+
Search the specified registry for modules. If you have configured npm to
+point to a different default registry (such as your internal private
+module repository), npm search will also default to that registry when
+searching.
+
A note on caching
+
The npm cli caches search results with the same terms and options
+locally in its cache. You can use the following to change how and when
+the cli uses this cache. See npm cache
+
prefer-online
+
Forced staleness checks for cached searches, making the cli look for
+updates immediately even for fresh search results.
+
prefer-offline
+
Bypasses staleness checks for cached. Missing data will still be
+requested from the server. To force full offline mode, use offline.
+
offline
+
Forces full offline mode. Any searches not locally cached will result in
+an error.
See Also
Table of contents
Description
This command repurposes package-lock.json into a publishable
-npm-shrinkwrap.json or simply creates a new one. The file created and updated
-by this command will then take precedence over any other existing or future
-package-lock.json files. For a detailed explanation of the design and purpose
-of package locks in npm, see package-locks .
+npm-shrinkwrap.json or simply creates a new one. The file created and
+updated by this command will then take precedence over any other existing
+or future package-lock.json files. For a detailed explanation of the
+design and purpose of package locks in npm, see
+package-lock-json .
See Also
npm-start
Synopsis
npm start [-- <args>]
Description
-
This runs an arbitrary command specified in the package’s "start" property of
-its "scripts" object. If no "start" property is specified on the
-"scripts" object, it will run node server.js.
+
This runs a predefined command specified in the "start" property of
+a package’s "scripts" object.
+
If the "scripts" object does not define a "start" property, npm
+will run node server.js.
+
Note that this is different from the default node behavior of running
+the file specified in a package’s "main" attribute when evoking with
+node .
As of npm@2.0.0npm run-script
+
Example
+
{
+ "scripts": {
+ "start": "node foo.js"
+ }
+}
+
+
npm start
+
+> npm@x.x.x start
+> node foo.js
+
+(foo.js output would be here)
+
+See Also
npm run-script npm-stop
Synopsis
npm stop [-- <args>]
Description
-
This runs a package’s “stop” script, if one was provided.
+
This runs a predefined command specified in the “stop” property of a
+package’s “scripts” object.
+
Unlike with npm start , there is no default script
+that will run if the "stop" property is not defined.
+
Example
+
{
+ "scripts": {
+ "stop": "node bar.js"
+ }
+}
+
+
npm stop
+
+> npm@x.x.x stop
+> node bar.js
+
+(bar.js output would be here)
+
+See Also
npm run-script npm-test
Synopsis
@@ -150,7 +150,21 @@
Table of contents
aliases: t, tst
Description
-
This runs a package’s “test” script, if one was provided.
+
This runs a predefined command specified in the "test" property of
+a package’s "scripts" object.
+
Example
+
{
+ "scripts": {
+ "test": "node test.js"
+ }
+}
+
+
npm test
+> npm@x.x.x test
+> node test.js
+
+(test.js output would be here)
+See Also
npm run-script Description
This lets you list, create and revoke authentication tokens.
npm token list:
-Shows a table of all active authentication tokens. You can request this as
-JSON with --json or tab-separated values with --parseable.--json or tab-separated values with --parseable.
+--------+---------+------------+----------+----------------+
| id | token | created | read-only | CIDR whitelist |
@@ -175,11 +175,19 @@ Description
+--------+---------+------------+----------+----------------+
-npm token create [--read-only] [--cidr=<cidr-ranges>]:
-Create a new authentication token. It can be --read-only or accept a list of
-CIDR ranges to
-limit use of this token to. This will prompt you for your password, and, if you have
-two-factor authentication enabled, an otp.
+npm token create [--read-only] [--cidr=<cidr-ranges>]:
+Create a new authentication token. It can be --read-only, or accept
+a list of
+CIDR
+ranges with which to limit use of this token. This will prompt you for
+your password, and, if you have two-factor authentication enabled, an
+otp.
+Currently, the cli can not generate automation tokens. Please refer to
+the docs
+website
+for more information on generating automation tokens.
+
+----------------+--------------------------------------+
| token | a73c9572-f1b9-8983-983d-ba3ac3cc913d |
@@ -193,10 +201,12 @@ Description
npm token revoke <token|id>:
-This removes an authentication token, making it immediately unusable. This can accept
-both complete tokens (as you get back from npm token create and will
-find in your .npmrc) and ids as seen in the npm token list output.
-This will NOT accept the truncated token found in npm token list output.npm token create, and those
+found in your .npmrc), and ids as seen in the parseable or json
+output of npm token list. This will NOT accept the truncated token
+found in the normal npm token list output.
npm-uninstall
Synopsis
-
npm uninstall [<@scope>/]<pkg>[@<version>]... [-S|--save|-D|--save-dev|-O|--save-optional|--no-save]
+npm uninstall [<@scope>/]<pkg>[@<version>]... [-S|--save|--no-save]
aliases: remove, rm, r, un, unlink
Description
This uninstalls a package, completely removing everything npm installed
on its behalf.
-Example:
-npm uninstall sax
-It also removes the package from the dependencies, devDependencies,
+optionalDependencies, and peerDependencies objects in your
+package.json.
+Futher, if you have an npm-shrinkwrap.json or package-lock.json, npm
+will update those files as well.
+--no-save will tell npm not to remove the package from your
+package.json, npm-shrinkwrap.json, or package-lock.json files.
+--save or -S will tell npm to remove the package from your
+package.json, npm-shrinkwrap.json, and package-lock.json files.
+This is the default, but you may need to use this if you have for
+instance save=false in your npmrc file
In global mode (ie, with -g or --global appended to the command),
-it uninstalls the current package context as a global package.
-npm uninstall takes 3 exclusive, optional flags which save or update
-the package version in your main package.json:
-
-
--S, --save: Package will be removed from your dependencies.
-
-
--D, --save-dev: Package will be removed from your devDependencies.
-
-
--O, --save-optional: Package will be removed from your optionalDependencies.
-
-
---no-save: Package will not be removed from your package.json file.
-
-
-Further, if you have an npm-shrinkwrap.json then it will be updated as
-well.
+it uninstalls the current package context as a global package.
+--no-save is ignored in this case.
Scope is optional and follows the usual rules for scope
-Examples:
-npm uninstall sax --save
-npm uninstall @myorg/privatepackage --save
-npm uninstall node-tap --save-dev
-npm uninstall dtrace-provider --save-optional
-npm uninstall lodash --no-save
+Examples
+npm uninstall sax
+sax will no longer be in your package.json, npm-shrinkwrap.json, or
+package-lock.json files.
+npm uninstall lodash --no-save
lodash will not be removed from your package.json,
+npm-shrinkwrap.json, or package-lock.json files.
See Also
npm prune Table of contents
Synopsis
+
To learn more about how the npm registry treats unpublish, see our unpublish policies
Unpublishing a single version of a package
npm unpublish [<@scope>/]<pkg>@<version>
@@ -152,16 +153,21 @@
Unpublishing an entire package
npm unpublish [<@scope>/]<pkg> --force
Warning
-
Consider using the deprecate command instead, if your intent is to encourage users to upgrade, or if you no longer want to maintain a package.
+
Consider using the deprecate
Description
-
This removes a package version from the registry, deleting its
-entry and removing the tarball.
-
If no version is specified, or if all versions are removed then
-the root package entry is removed from the registry entirely.
-
Even if a package version is unpublished, that specific name and
-version combination can never be reused. In order to publish the
-package again, a new version number must be used. If you unpublish the entire package, you may not publish any new versions of that package until 24 hours have passed.
-
To learn more about how unpublish is treated on the npm registry, see our unpublish policies.
+
This removes a package version from the registry, deleting its entry and
+removing the tarball.
+
The npm registry will return an error if you are not logged
+in .
+
If you do not specify a version or if you remove all of a package’s
+versions then the registry will remove the root package entry entirely.
+
Even if you unpublish a package version, that specific name and version
+combination can never be reused. In order to publish the package again,
+you must use a new version number. If you unpublish the entire package,
+you may not publish any new versions of that package until 24 hours have
+passed.
See Also
npm
Synopsis
npm <command> [args]
Version
-
7.4.0
+
7.4.3
Description
npm is the package manager for the Node JavaScript platform. It puts
modules in place so that node can find them, and manages dependency
@@ -246,19 +246,10 @@
Configuration
Contributions
Patches welcome!
If you would like to contribute, but don’t know what to work on, read
-the contributing guidelines and check the issues list.
-
+the
contributing guidelines
+and check the issues list.
Bugs
-
When you find issues, please report them:
-
+
When you find issues, please report them: https://github.com/npm/cli/issues
Be sure to follow the template and bug reporting guidelines.
Feature Requests
Discuss new feature ideas on our discussion forum:
@@ -269,11 +260,6 @@
Feature Requests
-
Author
-
Isaac Z. Schlueter ::
-isaacs ::
-@izs ::
-i@izs.me
See Also
npm help Table of contents
Description
-
To publish and install packages to and from the public npm registry, you must install Node.js and the npm command line interface using either a Node version manager or a Node installer. We strongly recommend using a Node version manager to install Node.js and npm. We do not recommend using a Node installer, since the Node installation process installs npm in a directory with local permissions and can cause permissions errors when you run npm packages globally.
+
To publish and install packages to and from the public npm registry, you
+must install Node.js and the npm command line interface using either a Node
+version manager or a Node installer. We strongly recommend using a Node
+version manager to install Node.js and npm. We do not recommend using a
+Node installer, since the Node installation process installs npm in a
+directory with local permissions and can cause permissions errors when you
+run npm packages globally.
Overview
Checking your version of npm and Node.js
-
To see if you already have Node.js and npm installed and check the installed version, run the following commands:
+
To see if you already have Node.js and npm installed and check the
+installed version, run the following commands:
node -v
npm -v
Using a Node version manager to install Node.js and npm
-
Node version managers allow you to install and switch between multiple versions of Node.js and npm on your system so you can test your applications on multiple versions of npm to ensure they work for users on different versions.
+
Node version managers allow you to install and switch between multiple
+versions of Node.js and npm on your system so you can test your
+applications on multiple versions of npm to ensure they work for users on
+different versions.
OSX or Linux Node version managers
Using a Node installer to install Node.js and npm
-
If you are unable to use a Node version manager, you can use a Node installer to install both Node.js and npm on your system.
+
If you are unable to use a Node version manager, you can use a Node
+installer to install both Node.js and npm on your system.
OS X or Windows Node installers
-
If you’re using OS X or Windows, use one of the installers from the Node.js download page . Be sure to install the version labeled LTS . Other versions have not yet been tested with npm.
+
If you’re using OS X or Windows, use one of the installers from the
+Node.js download page . Be sure to
+install the version labeled LTS . Other versions have not yet been
+tested with npm.
Linux or other operating systems Node installers
-
If you’re using Linux or another operating system, use one of the following installers:
+
If you’re using Linux or another operating system, use one of the following
+installers:
-
Or see this page to install npm for Linux in the way many Linux developers prefer.
+
Or see this page to
+install npm for Linux in the way many Linux developers prefer.
Less-common operating systems
-
For more information on installing Node.js on a variety of operating systems, see this page .
+
For more information on installing Node.js on a variety of operating
+systems, see this page .
diff --git a/deps/npm/docs/output/configuring-npm/shrinkwrap-json.html b/deps/npm/docs/output/configuring-npm/npm-shrinkwrap-json.html
similarity index 89%
rename from deps/npm/docs/output/configuring-npm/shrinkwrap-json.html
rename to deps/npm/docs/output/configuring-npm/npm-shrinkwrap-json.html
index b4425d3df95fe8..d0de6a1470a2c6 100644
--- a/deps/npm/docs/output/configuring-npm/shrinkwrap-json.html
+++ b/deps/npm/docs/output/configuring-npm/npm-shrinkwrap-json.html
@@ -1,5 +1,5 @@
-shrinkwrap.json
+npm-shrinkwrap.json
-
-
-
-
-
-
-
-
-npm command-line interface
-
-
-
-
-package-locks
-An explanation of npm lockfiles
-
-
-
-
-Description
-
Conceptually, the “input” to npm installpackage.json , while its
-“output” is a fully-formed node_modules tree: a representation of the
-dependencies you declared. In an ideal world, npm would work like a pure
-function: the same package.json should produce the exact same node_modules
-tree, any time. In some cases, this is indeed true. But in many others, npm is
-unable to do this. There are multiple reasons for this:
-
-
-different versions of npm (or other package managers) may have been used to install a package, each using slightly different installation algorithms.
-
-
-a new version of a direct semver-range package may have been published since the last time your packages were installed, and thus a newer version will be used.
-
-
-A dependency of one of your dependencies may have published a new version, which will update even if you used pinned dependency specifiers (1.2.3 instead of ^1.2.3)
-
-
-The registry you installed from is no longer available, or allows mutation of versions (unlike the primary npm registry), and a different version of a package exists under the same version number now.
-
-
-
As an example, consider package A:
-
{
- "name": "A",
- "version": "0.1.0",
- "dependencies": {
- "B": "<0.1.0"
- }
-}
-
-
package B:
-
{
- "name": "B",
- "version": "0.0.1",
- "dependencies": {
- "C": "<0.1.0"
- }
-}
-
-
and package C:
-
{
- "name": "C",
- "version": "0.0.1"
-}
-
-
If these are the only versions of A, B, and C available in the
-registry, then a normal npm install A will install:
-
A@0.1.0
-`-- B@0.0.1
- `-- C@0.0.1
-
-
However, if B@0.0.2 is published, then a fresh npm install A will
-install:
-
A@0.1.0
-`-- B@0.0.2
- `-- C@0.0.1
-
-
assuming the new version did not modify B’s dependencies. Of course,
-the new version of B could include a new version of C and any number
-of new dependencies. If such changes are undesirable, the author of A
-could specify a dependency on B@0.0.1. However, if A’s author and B’s
-author are not the same person, there’s no way for A’s author to say
-that he or she does not want to pull in newly published versions of C
-when B hasn’t changed at all.
-
To prevent this potential issue, npm uses package-lock.json or, if present, npm-shrinkwrap.json . These files are called package locks, or lockfiles.
-
Whenever you run npm install, npm generates or updates your package lock,
-which will look something like this:
-
{
- "name": "A",
- "version": "0.1.0",
- ...metadata fields...
- "dependencies": {
- "B": {
- "version": "0.0.1",
- "resolved": "https://registry.npmjs.org/B/-/B-0.0.1.tgz",
- "integrity": "sha512-DeAdb33F+"
- "dependencies": {
- "C": {
- "version": "git://github.com/org/C.git#5c380ae319fc4efe9e7f2d9c78b0faa588fd99b4"
- }
- }
- }
- }
-}
-
-
This file describes an exact , and more importantly reproducible
-node_modules tree. Once it’s present, any future installation will base its
-work off this file, instead of recalculating dependency versions off
-package.json .
-
The presence of a package lock changes the installation behavior such that:
-
-
-The module tree described by the package lock is reproduced. This means
-reproducing the structure described in the file, using the specific files
-referenced in “resolved” if available, falling back to normal package resolution
-using “version” if one isn’t.
-
-
-The tree is walked and any missing dependencies are installed in the usual
-fashion.
-
-
-
If preshrinkwrap, shrinkwrap or postshrinkwrap are in the scripts
-property of the package.json, they will be executed in order. preshrinkwrap
-and shrinkwrap are executed before the shrinkwrap, postshrinkwrap is
-executed afterwards. These scripts run for both package-lock.json and
-npm-shrinkwrap.json. For example to run some postprocessing on the generated
-file:
-
"scripts": {
- "postshrinkwrap": "json -I -e \"this.myMetadata = $MY_APP_METADATA\""
- }
-
-
Using locked packages
-
Using a locked package is no different than using any package without a package
-lock: any commands that update node_modules and/or package.json’s
-dependencies will automatically sync the existing lockfile. This includes npm install, npm rm, npm update, etc. To prevent this update from happening,
-you can use the --no-save option to prevent saving altogether, or
---no-shrinkwrap to allow package.json to be updated while leaving
-package-lock.json or npm-shrinkwrap.json intact.
-
It is highly recommended you commit the generated package lock to source
-control: this will allow anyone else on your team, your deployments, your
-CI/continuous integration, and anyone else who runs npm install in your
-package source to get the exact same dependency tree that you were developing
-on. Additionally, the diffs from these changes are human-readable and will
-inform you of any changes npm has made to your node_modules, so you can notice
-if any transitive dependencies were updated, hoisted, etc.
-
Resolving lockfile conflicts
-
Occasionally, two separate npm install will create package locks that cause
-merge conflicts in source control systems. As of npm@5.7.0, these conflicts
-can be resolved by manually fixing any package.json conflicts, and then
-running npm install [--package-lock-only] again. npm will automatically
-resolve any conflicts for you and write a merged package lock that includes all
-the dependencies from both branches in a reasonable tree. If
---package-lock-only is provided, it will do this without also modifying your
-local node_modules/.
-
To make this process seamless on git, consider installing
-npm-merge-driver$ npx npm-merge-driver install -g will let you do this, and even works with
-pre-npm@5.7.0 versions of npm 5, albeit a bit more noisily. Note that if
-package.json itself conflicts, you will have to resolve that by hand and run
-npm install manually, even with the merge driver.
-
See Also
-
-
-
-
-
-
\ No newline at end of file
diff --git a/deps/npm/lib/link.js b/deps/npm/lib/link.js
index f7e13369c86a25..84f36ada662016 100644
--- a/deps/npm/lib/link.js
+++ b/deps/npm/lib/link.js
@@ -45,6 +45,9 @@ const link = async args => {
// Returns a list of items that can't be fulfilled by
// things found in the current arborist inventory
const missingArgsFromTree = (tree, args) => {
+ if (tree.isLink)
+ return missingArgsFromTree(tree.target, args)
+
const foundNodes = []
const missing = args.filter(a => {
const arg = npa(a)
diff --git a/deps/npm/lib/ls.js b/deps/npm/lib/ls.js
index 362dacad3dc30c..153759d83815e6 100644
--- a/deps/npm/lib/ls.js
+++ b/deps/npm/lib/ls.js
@@ -99,7 +99,7 @@ const getHumanOutputItem = (node, { args, color, global, long }) => {
// special formatting for top-level package name
if (node.isRoot) {
const hasNoPackageJson = !Object.keys(node.package).length
- if (hasNoPackageJson)
+ if (hasNoPackageJson || global)
printable = path
else
printable += `${long ? EOL : ' '}${path}`
diff --git a/deps/npm/lib/search.js b/deps/npm/lib/search.js
index 38f5a1d77b3226..a3d806d2f1507e 100644
--- a/deps/npm/lib/search.js
+++ b/deps/npm/lib/search.js
@@ -12,7 +12,7 @@ const completion = require('./utils/completion/none.js')
const usage = usageUtil(
'search',
- 'npm search [--long] [search terms ...]'
+ 'npm search [-l|--long] [--json] [--parseable] [--no-description] [search terms ...]'
)
const cmd = (args, cb) => search(args).then(() => cb()).catch(cb)
diff --git a/deps/npm/lib/token.js b/deps/npm/lib/token.js
index 98bbd30433cdd6..b737b5ffbca320 100644
--- a/deps/npm/lib/token.js
+++ b/deps/npm/lib/token.js
@@ -17,7 +17,7 @@ token._validateCIDRList = validateCIDRList
const usageUtil = require('./utils/usage.js')
token.usage = usageUtil('token',
'npm token list\n' +
- 'npm token revoke \n' +
+ 'npm token revoke \n' +
'npm token create [--read-only] [--cidr=list]')
const UsageError = (msg) =>
diff --git a/deps/npm/lib/uninstall.js b/deps/npm/lib/uninstall.js
index 83a0b009699eb6..15995c0b3cc946 100644
--- a/deps/npm/lib/uninstall.js
+++ b/deps/npm/lib/uninstall.js
@@ -9,7 +9,7 @@ const completion = require('./utils/completion/installed-shallow.js')
const usage = usageUtil(
'uninstall',
- 'npm uninstall [<@scope>/][@]... [--save-prod|--save-dev|--save-optional] [--no-save]'
+ 'npm uninstall [<@scope>/][@]... [-S|--save|--no-save]'
)
const cmd = (args, cb) => rm(args).then(() => cb()).catch(cb)
diff --git a/deps/npm/lib/unpublish.js b/deps/npm/lib/unpublish.js
index 75993af9437d0d..528208c39693e0 100644
--- a/deps/npm/lib/unpublish.js
+++ b/deps/npm/lib/unpublish.js
@@ -35,7 +35,7 @@ const completionFn = async (args) => {
const access = await libaccess.lsPackages(username, opts)
// do a bit of filtering at this point, so that we don't need
// to fetch versions for more than one thing, but also don't
- // accidentally a whole project
+ // accidentally unpublish a whole project
let pkgs = Object.keys(access || {})
if (!partialWord || !pkgs.length)
return pkgs
diff --git a/deps/npm/man/man1/npm-audit.1 b/deps/npm/man/man1/npm-audit.1
index 03f3c3f2bccb95..1c7268e135bb26 100644
--- a/deps/npm/man/man1/npm-audit.1
+++ b/deps/npm/man/man1/npm-audit.1
@@ -205,8 +205,6 @@ $ npm audit \-\-audit\-level=moderate
.IP \(bu 2
npm help install
.IP \(bu 2
-npm help package\-locks
-.IP \(bu 2
npm help config
.RE
diff --git a/deps/npm/man/man1/npm-ci.1 b/deps/npm/man/man1/npm-ci.1
index e7092af6f34758..b74c14dc7730bf 100644
--- a/deps/npm/man/man1/npm-ci.1
+++ b/deps/npm/man/man1/npm-ci.1
@@ -83,6 +83,6 @@ cache:
.IP \(bu 2
npm help install
.IP \(bu 2
-npm help package\-locks
+npm help package\-lock\.json
.RE
diff --git a/deps/npm/man/man1/npm-ls.1 b/deps/npm/man/man1/npm-ls.1
index 94df47109a032e..0a90b749529343 100644
--- a/deps/npm/man/man1/npm-ls.1
+++ b/deps/npm/man/man1/npm-ls.1
@@ -26,7 +26,7 @@ example, running \fBnpm ls promzard\fP in npm's source tree will show:
.P
.RS 2
.nf
-npm@7\.4\.0 /path/to/npm
+npm@7\.4\.3 /path/to/npm
└─┬ init\-package\-json@0\.0\.4
└── promzard@0\.1\.5
.fi
diff --git a/deps/npm/man/man1/npm-prefix.1 b/deps/npm/man/man1/npm-prefix.1
index cc1e99d664e124..ce1426703aa0e1 100644
--- a/deps/npm/man/man1/npm-prefix.1
+++ b/deps/npm/man/man1/npm-prefix.1
@@ -10,12 +10,27 @@ npm prefix [\-g]
.RE
.SS Description
.P
-Print the local prefix to standard out\. This is the closest parent directory
+Print the local prefix to standard output\. This is the closest parent directory
to contain a \fBpackage\.json\fP file or \fBnode_modules\fP directory, unless \fB\-g\fP is
also specified\.
.P
If \fB\-g\fP is specified, this will be the value of the global prefix\. See
npm help \fBconfig\fP for more detail\.
+.SS Example
+.P
+.RS 2
+.nf
+npm prefix
+/usr/local/projects/foo
+.fi
+.RE
+.P
+.RS 2
+.nf
+npm prefix \-g
+/usr/local
+.fi
+.RE
.SS See Also
.RS 0
.IP \(bu 2
diff --git a/deps/npm/man/man1/npm-search.1 b/deps/npm/man/man1/npm-search.1
index 061bdc5458e20c..ab71c948f48bf8 100644
--- a/deps/npm/man/man1/npm-search.1
+++ b/deps/npm/man/man1/npm-search.1
@@ -14,25 +14,28 @@ aliases: s, se, find
.P
Search the registry for packages matching the search terms\. \fBnpm search\fP
performs a linear, incremental, lexically\-ordered search through package
-metadata for all files in the registry\. If color is enabled, it will further
-highlight the matches in the results\.
+metadata for all files in the registry\. If your terminal has color
+support, it will further highlight the matches in the results\. This can
+be disabled with the config item \fBcolor\fP
.P
-Additionally, using the \fB\-\-searchopts\fP and \fB\-\-searchexclude\fP options paired with
-more search terms will respectively include and exclude further patterns\. The
-main difference between \fB\-\-searchopts\fP and the standard search terms is that the
-former does not highlight results in the output and can be used for more
-fine\-grained filtering\. Additionally, both of these can be added to \fB\|\.npmrc\fP for
-default search filtering behavior\.
+Additionally, using the \fB\-\-searchopts\fP and \fB\-\-searchexclude\fP options
+paired with more search terms will include and exclude further patterns\.
+The main difference between \fB\-\-searchopts\fP and the standard search terms
+is that the former does not highlight results in the output and you can
+use them more fine\-grained filtering\. Additionally, you can add both of
+these to your config to change default search filtering behavior\.
.P
Search also allows targeting of maintainers in search results, by prefixing
their npm username with \fB=\fP\|\.
.P
-If a term starts with \fB/\fP, then it's interpreted as a regular expression and
-supports standard JavaScript RegExp syntax\. A trailing \fB/\fP will be ignored in
-this case\. (Note that many regular expression characters must be escaped or
-quoted in most shells\.)
-.SS A Note on caching
+If a term starts with \fB/\fP, then it's interpreted as a regular expression
+and supports standard JavaScript RegExp syntax\. In this case search will
+ignore a trailing \fB/\fP \. (Note you must escape or quote many regular
+expression characters in most shells\.)
.SS Configuration
+.P
+All of the following can be defined in a \fB\|\.npmrc\fP file, or passed as
+parameters to the cli prefixed with \fB\-\-\fP (e\.g\. \fB\-\-json\fP)
.SS description
.RS 0
.IP \(bu 2
@@ -40,10 +43,18 @@ Default: true
.IP \(bu 2
Type: Boolean
+.RE
+.SS color
+.RS 0
+.IP \(bu 2
+Default: true
+.IP \(bu 2
+Type: Boolean
+
.RE
.P
-Used as \fB\-\-no\-description\fP, disables search matching in package descriptions and
-suppresses display of that field in results\.
+Used as \fB\-\-no\-color\fP, disables color highlighting of matches in the
+results\.
.SS json
.RS 0
.IP \(bu 2
@@ -74,9 +85,9 @@ Type: Boolean
.RE
.P
Display full package descriptions and other long text across multiple
-lines\. When disabled (default) search results are truncated to fit
-neatly on a single line\. Modules with extremely long names will
-fall on multiple lines\.
+lines\. When disabled (which is the default) the output will
+truncate search results to fit neatly on a single line\. Modules with
+extremely long names will fall on multiple lines\.
.SS searchopts
.RS 0
.IP \(bu 2
@@ -97,16 +108,6 @@ Type: String
.RE
.P
Space\-separated options that limit the results from search\.
-.SS searchstaleness
-.RS 0
-.IP \(bu 2
-Default: 900 (15 minutes)
-.IP \(bu 2
-Type: Number
-
-.RE
-.P
-The age of the cache, in seconds, before another registry request is made\.
.SS registry
.RS 0
.IP \(bu 2
@@ -116,11 +117,28 @@ Type: url
.RE
.P
-Search the specified registry for modules\. If you have configured npm to point
-to a different default registry, such as your internal private module
-repository, \fBnpm search\fP will default to that registry when searching\. Pass a
-different registry url such as the default above in order to override this
-setting\.
+Search the specified registry for modules\. If you have configured npm to
+point to a different default registry (such as your internal private
+module repository), \fBnpm search\fP will also default to that registry when
+searching\.
+.SS A note on caching
+.P
+The npm cli caches search results with the same terms and options
+locally in its cache\. You can use the following to change how and when
+the cli uses this cache\. See npm help \fBcache\fP for more
+on how the cache works\.
+.SS prefer\-online
+.P
+Forced staleness checks for cached searches, making the cli look for
+updates immediately even for fresh search results\.
+.SS prefer\-offline
+.P
+Bypasses staleness checks for cached\. Missing data will still be
+requested from the server\. To force full offline mode, use \fBoffline\fP\|\.
+.SS offline
+.P
+Forces full offline mode\. Any searches not locally cached will result in
+an error\.
.SS See Also
.RS 0
.IP \(bu 2
@@ -131,5 +149,9 @@ npm help config
npm help npmrc
.IP \(bu 2
npm help view
+.IP \(bu 2
+npm help cache
+.IP \(bu 2
+https://npm\.im/npm\-registry\-fetch
.RE
diff --git a/deps/npm/man/man1/npm-shrinkwrap.1 b/deps/npm/man/man1/npm-shrinkwrap.1
index 73ef9c3ce307ed..c5151ab9abe2b2 100644
--- a/deps/npm/man/man1/npm-shrinkwrap.1
+++ b/deps/npm/man/man1/npm-shrinkwrap.1
@@ -11,10 +11,11 @@ npm shrinkwrap
.SS Description
.P
This command repurposes \fBpackage\-lock\.json\fP into a publishable
-\fBnpm\-shrinkwrap\.json\fP or simply creates a new one\. The file created and updated
-by this command will then take precedence over any other existing or future
-\fBpackage\-lock\.json\fP files\. For a detailed explanation of the design and purpose
-of package locks in npm, see npm help package\-locks\.
+\fBnpm\-shrinkwrap\.json\fP or simply creates a new one\. The file created and
+updated by this command will then take precedence over any other existing
+or future \fBpackage\-lock\.json\fP files\. For a detailed explanation of the
+design and purpose of package locks in npm, see
+npm help package\-lock\-json\.
.SS See Also
.RS 0
.IP \(bu 2
@@ -24,13 +25,11 @@ npm help run\-script
.IP \(bu 2
npm help scripts
.IP \(bu 2
-npm help package\.js
-.IP \(bu 2
-npm help package\-locks
+npm help package\.json
.IP \(bu 2
npm help package\-lock\.json
.IP \(bu 2
-npm help shrinkwrap\.json
+npm help npm\-shrinkwrap\.json
.IP \(bu 2
npm help ls
diff --git a/deps/npm/man/man1/npm-start.1 b/deps/npm/man/man1/npm-start.1
index 44bf825b2d6d88..a3d343d84f4bbd 100644
--- a/deps/npm/man/man1/npm-start.1
+++ b/deps/npm/man/man1/npm-start.1
@@ -10,12 +10,41 @@ npm start [\-\- ]
.RE
.SS Description
.P
-This runs an arbitrary command specified in the package's \fB"start"\fP property of
-its \fB"scripts"\fP object\. If no \fB"start"\fP property is specified on the
-\fB"scripts"\fP object, it will run \fBnode server\.js\fP\|\.
+This runs a predefined command specified in the \fB"start"\fP property of
+a package's \fB"scripts"\fP object\.
+.P
+If the \fB"scripts"\fP object does not define a \fB"start"\fP property, npm
+will run \fBnode server\.js\fP\|\.
+.P
+Note that this is different from the default node behavior of running
+the file specified in a package's \fB"main"\fP attribute when evoking with
+\fBnode \.\fP
.P
As of \fBnpm@2\.0\.0\fP \fIhttps://blog\.npmjs\.org/post/98131109725/npm\-2\-0\-0\fR, you can
use custom arguments when executing scripts\. Refer to npm help \fBrun\-script\fP for more details\.
+.SS Example
+.P
+.RS 2
+.nf
+{
+ "scripts": {
+ "start": "node foo\.js"
+ }
+}
+.fi
+.RE
+.P
+.RS 2
+.nf
+npm start
+
+> npm@x\.x\.x start
+> node foo\.js
+
+(foo\.js output would be here)
+
+.fi
+.RE
.SS See Also
.RS 0
.IP \(bu 2
diff --git a/deps/npm/man/man1/npm-stop.1 b/deps/npm/man/man1/npm-stop.1
index 9ca8142296a454..2d811be0b48f92 100644
--- a/deps/npm/man/man1/npm-stop.1
+++ b/deps/npm/man/man1/npm-stop.1
@@ -10,7 +10,34 @@ npm stop [\-\- ]
.RE
.SS Description
.P
-This runs a package's "stop" script, if one was provided\.
+This runs a predefined command specified in the "stop" property of a
+package's "scripts" object\.
+.P
+Unlike with npm help start, there is no default script
+that will run if the \fB"stop"\fP property is not defined\.
+.SS Example
+.P
+.RS 2
+.nf
+{
+ "scripts": {
+ "stop": "node bar\.js"
+ }
+}
+.fi
+.RE
+.P
+.RS 2
+.nf
+npm stop
+
+> npm@x\.x\.x stop
+> node bar\.js
+
+(bar\.js output would be here)
+
+.fi
+.RE
.SS See Also
.RS 0
.IP \(bu 2
diff --git a/deps/npm/man/man1/npm-test.1 b/deps/npm/man/man1/npm-test.1
index 5844149a7306f9..877e25c8157f5c 100644
--- a/deps/npm/man/man1/npm-test.1
+++ b/deps/npm/man/man1/npm-test.1
@@ -12,7 +12,29 @@ aliases: t, tst
.RE
.SS Description
.P
-This runs a package's "test" script, if one was provided\.
+This runs a predefined command specified in the \fB"test"\fP property of
+a package's \fB"scripts"\fP object\.
+.SS Example
+.P
+.RS 2
+.nf
+{
+ "scripts": {
+ "test": "node test\.js"
+ }
+}
+.fi
+.RE
+.P
+.RS 2
+.nf
+npm test
+> npm@x\.x\.x test
+> node test\.js
+
+(test\.js output would be here)
+.fi
+.RE
.SS See Also
.RS 0
.IP \(bu 2
diff --git a/deps/npm/man/man1/npm-token.1 b/deps/npm/man/man1/npm-token.1
index 86ba1819106808..5edb1cee42eda1 100644
--- a/deps/npm/man/man1/npm-token.1
+++ b/deps/npm/man/man1/npm-token.1
@@ -16,8 +16,8 @@ This lets you list, create and revoke authentication tokens\.
.RS 0
.IP \(bu 2
\fBnpm token list\fP:
-Shows a table of all active authentication tokens\. You can request this as
-JSON with \fB\-\-json\fP or tab\-separated values with \fB\-\-parseable\fP\|\.
+Shows a table of all active authentication tokens\. You can request
+this as JSON with \fB\-\-json\fP or tab\-separated values with \fB\-\-parseable\fP\|\.
.RE
.P
@@ -45,10 +45,16 @@ JSON with \fB\-\-json\fP or tab\-separated values with \fB\-\-parseable\fP\|\.
.RS 0
.IP \(bu 2
\fBnpm token create [\-\-read\-only] [\-\-cidr=]\fP:
-Create a new authentication token\. It can be \fB\-\-read\-only\fP or accept a list of
-CIDR \fIhttps://en\.wikipedia\.org/wiki/Classless_Inter\-Domain_Routing\fR ranges to
-limit use of this token to\. This will prompt you for your password, and, if you have
-two\-factor authentication enabled, an otp\.
+Create a new authentication token\. It can be \fB\-\-read\-only\fP, or accept
+a list of
+CIDR \fIhttps://en\.wikipedia\.org/wiki/Classless_Inter\-Domain_Routing\fR
+ranges with which to limit use of this token\. This will prompt you for
+your password, and, if you have two\-factor authentication enabled, an
+otp\.
+Currently, the cli can not generate automation tokens\. Please refer to
+the docs
+website \fIhttps://docs\.npmjs\.com/creating\-and\-viewing\-access\-tokens\fR
+for more information on generating automation tokens\.
.RE
.P
@@ -68,9 +74,11 @@ two\-factor authentication enabled, an otp\.
.RS 0
.IP \(bu 2
\fBnpm token revoke \fP:
-This removes an authentication token, making it immediately unusable\. This can accept
-both complete tokens (as you get back from \fBnpm token create\fP and will
-find in your \fB\|\.npmrc\fP) and ids as seen in the \fBnpm token list\fP output\.
-This will NOT accept the truncated token found in \fBnpm token list\fP output\.
+Immediately removes an authentication token from the registry\. You
+will no longer be able to use it\. This can accept both complete
+tokens (such as those you get back from \fBnpm token create\fP, and those
+found in your \fB\|\.npmrc\fP), and ids as seen in the parseable or json
+output of \fBnpm token list\fP\|\. This will NOT accept the truncated token
+found in the normal \fBnpm token list\fP output\.
.RE
diff --git a/deps/npm/man/man1/npm-uninstall.1 b/deps/npm/man/man1/npm-uninstall.1
index f341264506be1c..fb5016b3903935 100644
--- a/deps/npm/man/man1/npm-uninstall.1
+++ b/deps/npm/man/man1/npm-uninstall.1
@@ -5,7 +5,7 @@
.P
.RS 2
.nf
-npm uninstall [<@scope>/][@]\.\.\. [\-S|\-\-save|\-D|\-\-save\-dev|\-O|\-\-save\-optional|\-\-no\-save]
+npm uninstall [<@scope>/][@]\.\.\. [\-S|\-\-save|\-\-no\-save]
aliases: remove, rm, r, un, unlink
.fi
@@ -15,47 +15,45 @@ aliases: remove, rm, r, un, unlink
This uninstalls a package, completely removing everything npm installed
on its behalf\.
.P
-Example:
+It also removes the package from the \fBdependencies\fP, \fBdevDependencies\fP,
+\fBoptionalDependencies\fP, and \fBpeerDependencies\fP objects in your
+\fBpackage\.json\fP\|\.
.P
-.RS 2
-.nf
-npm uninstall sax
-.fi
-.RE
+Futher, if you have an \fBnpm\-shrinkwrap\.json\fP or \fBpackage\-lock\.json\fP, npm
+will update those files as well\.
.P
-In global mode (ie, with \fB\-g\fP or \fB\-\-global\fP appended to the command),
-it uninstalls the current package context as a global package\.
+\fB\-\-no\-save\fP will tell npm not to remove the package from your
+\fBpackage\.json\fP, \fBnpm\-shrinkwrap\.json\fP, or \fBpackage\-lock\.json\fP files\.
.P
-\fBnpm uninstall\fP takes 3 exclusive, optional flags which save or update
-the package version in your main package\.json:
-.RS 0
-.IP \(bu 2
-\fB\-S, \-\-save\fP: Package will be removed from your \fBdependencies\fP\|\.
-.IP \(bu 2
-\fB\-D, \-\-save\-dev\fP: Package will be removed from your \fBdevDependencies\fP\|\.
-.IP \(bu 2
-\fB\-O, \-\-save\-optional\fP: Package will be removed from your \fBoptionalDependencies\fP\|\.
-.IP \(bu 2
-\fB\-\-no\-save\fP: Package will not be removed from your \fBpackage\.json\fP file\.
-
-.RE
+\fB\-\-save\fP or \fB\-S\fP will tell npm to remove the package from your
+\fBpackage\.json\fP, \fBnpm\-shrinkwrap\.json\fP, and \fBpackage\-lock\.json\fP files\.
+This is the default, but you may need to use this if you have for
+instance \fBsave=false\fP in your \fBnpmrc\fP file
.P
-Further, if you have an \fBnpm\-shrinkwrap\.json\fP then it will be updated as
-well\.
+In global mode (ie, with \fB\-g\fP or \fB\-\-global\fP appended to the command),
+it uninstalls the current package context as a global package\.
+\fB\-\-no\-save\fP is ignored in this case\.
.P
Scope is optional and follows the usual rules for npm help \fBscope\fP\|\.
+.SS Examples
.P
-Examples:
+.RS 2
+.nf
+npm uninstall sax
+.fi
+.RE
+.P
+\fBsax\fP will no longer be in your \fBpackage\.json\fP, \fBnpm\-shrinkwrap\.json\fP, or
+\fBpackage\-lock\.json\fP files\.
.P
.RS 2
.nf
-npm uninstall sax \-\-save
-npm uninstall @myorg/privatepackage \-\-save
-npm uninstall node\-tap \-\-save\-dev
-npm uninstall dtrace\-provider \-\-save\-optional
npm uninstall lodash \-\-no\-save
.fi
.RE
+.P
+\fBlodash\fP will not be removed from your \fBpackage\.json\fP,
+\fBnpm\-shrinkwrap\.json\fP, or \fBpackage\-lock\.json\fP files\.
.SS See Also
.RS 0
.IP \(bu 2
diff --git a/deps/npm/man/man1/npm-unpublish.1 b/deps/npm/man/man1/npm-unpublish.1
index 7c965107871bae..6542ec54643f38 100644
--- a/deps/npm/man/man1/npm-unpublish.1
+++ b/deps/npm/man/man1/npm-unpublish.1
@@ -2,6 +2,10 @@
.SH "NAME"
\fBnpm-unpublish\fR \- Remove a package from the registry
.SS Synopsis
+.P
+To learn more about how the npm registry treats unpublish, see our unpublish policies
.SS Unpublishing a single version of a package
.P
.RS 2
@@ -18,20 +22,25 @@ npm unpublish [<@scope>/] \-\-force
.RE
.SS Warning
.P
-Consider using the \fBdeprecate\fP command instead, if your intent is to encourage users to upgrade, or if you no longer want to maintain a package\.
+Consider using the npm help \fBdeprecate\fP command instead,
+if your intent is to encourage users to upgrade, or if you no longer
+want to maintain a package\.
.SS Description
.P
-This removes a package version from the registry, deleting its
-entry and removing the tarball\.
+This removes a package version from the registry, deleting its entry and
+removing the tarball\.
.P
-If no version is specified, or if all versions are removed then
-the root package entry is removed from the registry entirely\.
+The npm registry will return an error if you are not npm help logged
+in\.
.P
-Even if a package version is unpublished, that specific name and
-version combination can never be reused\. In order to publish the
-package again, a new version number must be used\. If you unpublish the entire package, you may not publish any new versions of that package until 24 hours have passed\.
+If you do not specify a version or if you remove all of a package's
+versions then the registry will remove the root package entry entirely\.
.P
-To learn more about how unpublish is treated on the npm registry, see our unpublish policies \|\.
+Even if you unpublish a package version, that specific name and version
+combination can never be reused\. In order to publish the package again,
+you must use a new version number\. If you unpublish the entire package,
+you may not publish any new versions of that package until 24 hours have
+passed\.
.SS See Also
.RS 0
.IP \(bu 2
@@ -44,5 +53,7 @@ npm help registry
npm help adduser
.IP \(bu 2
npm help owner
+.IP \(bu 2
+npm help login
.RE
diff --git a/deps/npm/man/man1/npm.1 b/deps/npm/man/man1/npm.1
index 73b67d8a52cdba..a75dc70db92309 100644
--- a/deps/npm/man/man1/npm.1
+++ b/deps/npm/man/man1/npm.1
@@ -10,7 +10,7 @@ npm [args]
.RE
.SS Version
.P
-7\.4\.0
+7\.4\.3
.SS Description
.P
npm is the package manager for the Node JavaScript platform\. It puts
@@ -141,26 +141,11 @@ See npm help \fBconfig\fP for much much more information\.
Patches welcome!
.P
If you would like to contribute, but don't know what to work on, read
-the contributing guidelines and check the issues list\.
-.RS 0
-.IP \(bu 2
-CONTRIBUTING\.md \fIhttps://github\.com/npm/cli/blob/latest/CONTRIBUTING\.md\fR
-.IP \(bu 2
-Bug tracker \fIhttps://github\.com/npm/cli/issues\fR
-
-.RE
+the contributing guidelines \fIhttps://github\.com/npm/cli/blob/latest/CONTRIBUTING\.md\fR
+and check the issues list\.
.SS Bugs
.P
-When you find issues, please report them:
-.RS 0
-.IP \(bu 2
-web:
-https://github\.com/npm/npm/issues
-.IP \(bu 2
-archived web:
-https://npm\.community/c/bugs
-
-.RE
+When you find issues, please report them: https://github\.com/npm/cli/issues
.P
Be sure to follow the template and bug reporting guidelines\.
.SS Feature Requests
@@ -178,12 +163,6 @@ Or suggest formal RFC proposals:
https://github\.com/npm/rfcs
.RE
-.SS Author
-.P
-Isaac Z\. Schlueter \fIhttp://blog\.izs\.me/\fR ::
-isaacs \fIhttps://github\.com/isaacs/\fR ::
-@izs \fIhttps://twitter\.com/izs\fR ::
-i@izs\.me
.SS See Also
.RS 0
.IP \(bu 2
diff --git a/deps/npm/man/man5/install.5 b/deps/npm/man/man5/install.5
index 4aa76d059bf8f4..d01600aa8d769a 100644
--- a/deps/npm/man/man5/install.5
+++ b/deps/npm/man/man5/install.5
@@ -3,20 +3,30 @@
\fBinstall\fR \- Download and install node and npm
.SS Description
.P
-To publish and install packages to and from the public npm registry, you must install Node\.js and the npm command line interface using either a Node version manager or a Node installer\. \fBWe strongly recommend using a Node version manager to install Node\.js and npm\.\fR We do not recommend using a Node installer, since the Node installation process installs npm in a directory with local permissions and can cause permissions errors when you run npm packages globally\.
+To publish and install packages to and from the public npm registry, you
+must install Node\.js and the npm command line interface using either a Node
+version manager or a Node installer\. \fBWe strongly recommend using a Node
+version manager to install Node\.js and npm\.\fR We do not recommend using a
+Node installer, since the Node installation process installs npm in a
+directory with local permissions and can cause permissions errors when you
+run npm packages globally\.
.SS Overview
.RS 0
.IP \(bu 2
-Checking your version of npm and Node\.js \fI#checking\-your\-version\-of\-npm\-and\-node\-js\fR
+Checking your version of npm and
+Node\.js \fI#checking\-your\-version\-of\-npm\-and\-node\-js\fR
.IP \(bu 2
-Using a Node version manager to install Node\.js and npm \fI#using\-a\-node\-version\-manager\-to\-install\-node\-js\-and\-npm\fR
+Using a Node version manager to install Node\.js and
+npm \fI#using\-a\-node\-version\-manager\-to\-install\-node\-js\-and\-npm\fR
.IP \(bu 2
-Using a Node installer to install Node\.js and npm \fI#using\-a\-node\-installer\-to\-install\-node\-js\-and\-npm\fR
+Using a Node installer to install Node\.js and
+npm \fI#using\-a\-node\-installer\-to\-install\-node\-js\-and\-npm\fR
.RE
.SS Checking your version of npm and Node\.js
.P
-To see if you already have Node\.js and npm installed and check the installed version, run the following commands:
+To see if you already have Node\.js and npm installed and check the
+installed version, run the following commands:
.P
.RS 2
.nf
@@ -26,7 +36,10 @@ npm \-v
.RE
.SS Using a Node version manager to install Node\.js and npm
.P
-Node version managers allow you to install and switch between multiple versions of Node\.js and npm on your system so you can test your applications on multiple versions of npm to ensure they work for users on different versions\.
+Node version managers allow you to install and switch between multiple
+versions of Node\.js and npm on your system so you can test your
+applications on multiple versions of npm to ensure they work for users on
+different versions\.
.SS OSX or Linux Node version managers
.RS 0
.IP \(bu 2
@@ -45,29 +58,39 @@ nvm\-windows \fIhttps://github\.com/coreybutler/nvm\-windows\fR
.RE
.SS Using a Node installer to install Node\.js and npm
.P
-If you are unable to use a Node version manager, you can use a Node installer to install both Node\.js and npm on your system\.
+If you are unable to use a Node version manager, you can use a Node
+installer to install both Node\.js and npm on your system\.
.RS 0
.IP \(bu 2
Node\.js installer \fIhttps://nodejs\.org/en/download/\fR
.IP \(bu 2
-NodeSource installer \fIhttps://github\.com/nodesource/distributions\fR\|\. If you use Linux, we recommend that you use a NodeSource installer\.
+NodeSource installer \fIhttps://github\.com/nodesource/distributions\fR\|\. If
+you use Linux, we recommend that you use a NodeSource installer\.
.RE
.SS OS X or Windows Node installers
.P
-If you're using OS X or Windows, use one of the installers from the Node\.js download page \fIhttps://nodejs\.org/en/download/\fR\|\. Be sure to install the version labeled \fBLTS\fR\|\. Other versions have not yet been tested with npm\.
+If you're using OS X or Windows, use one of the installers from the
+Node\.js download page \fIhttps://nodejs\.org/en/download/\fR\|\. Be sure to
+install the version labeled \fBLTS\fR\|\. Other versions have not yet been
+tested with npm\.
.SS Linux or other operating systems Node installers
.P
-If you're using Linux or another operating system, use one of the following installers:
+If you're using Linux or another operating system, use one of the following
+installers:
.RS 0
.IP \(bu 2
-NodeSource installer \fIhttps://github\.com/nodesource/distributions\fR (recommended)
+NodeSource installer \fIhttps://github\.com/nodesource/distributions\fR
+(recommended)
.IP \(bu 2
-One of the installers on the Node\.js download page \fIhttps://nodejs\.org/en/download/\fR
+One of the installers on the Node\.js download
+page \fIhttps://nodejs\.org/en/download/\fR
.RE
.P
-Or see this page \fIhttps://nodejs\.org/en/download/package\-manager/\fR to install npm for Linux in the way many Linux developers prefer\.
+Or see this page \fIhttps://nodejs\.org/en/download/package\-manager/\fR to
+install npm for Linux in the way many Linux developers prefer\.
.SS Less\-common operating systems
.P
-For more information on installing Node\.js on a variety of operating systems, see this page \fIhttps://nodejs\.org/en/download/package\-manager/\fR\|\.
+For more information on installing Node\.js on a variety of operating
+systems, see this page \fIhttps://nodejs\.org/en/download/package\-manager/\fR\|\.
diff --git a/deps/npm/man/man5/shrinkwrap-json.5 b/deps/npm/man/man5/npm-shrinkwrap-json.5
similarity index 56%
rename from deps/npm/man/man5/shrinkwrap-json.5
rename to deps/npm/man/man5/npm-shrinkwrap-json.5
index 606b2179a10a40..7f8012e847099f 100644
--- a/deps/npm/man/man5/shrinkwrap-json.5
+++ b/deps/npm/man/man5/npm-shrinkwrap-json.5
@@ -1,23 +1,27 @@
-.TH "SHRINKWRAP\.JSON" "5" "January 2021" "" ""
+.TH "NPM\-SHRINKWRAP\.JSON" "5" "January 2021" "" ""
.SH "NAME"
-\fBshrinkwrap.json\fR \- A publishable lockfile
+\fBnpm-shrinkwrap.json\fR \- A publishable lockfile
.SS Description
.P
-\fBnpm\-shrinkwrap\.json\fP is a file created by npm help \fBshrinkwrap\fP\|\. It is identical to
+\fBnpm\-shrinkwrap\.json\fP is a file created by npm help \fBnpm
+shrinkwrap\fP\|\. It is identical to
\fBpackage\-lock\.json\fP, with one major caveat: Unlike \fBpackage\-lock\.json\fP,
\fBnpm\-shrinkwrap\.json\fP may be included when publishing a package\.
.P
The recommended use\-case for \fBnpm\-shrinkwrap\.json\fP is applications deployed
through the publishing process on the registry: for example, daemons and
command\-line tools intended as global installs or \fBdevDependencies\fP\|\. It's
-strongly discouraged for library authors to publish this file, since that would
-prevent end users from having control over transitive dependency updates\.
+strongly discouraged for library authors to publish this file, since that
+would prevent end users from having control over transitive dependency
+updates\.
.P
-Additionally, if both \fBpackage\-lock\.json\fP and \fBnpm\-shrinkwrap\.json\fP are present
-in a package root, \fBpackage\-lock\.json\fP will be ignored in favor of this file\.
+If both \fBpackage\-lock\.json\fP and \fBnpm\-shrinkwrap\.json\fP are present in a
+package root, \fBnpm\-shrinkwrap\.json\fP will be preferred over the
+\fBpackage\-lock\.json\fP file\.
.P
-For full details and description of the \fBnpm\-shrinkwrap\.json\fP file format, refer
-to the manual page for npm help package\-lock\.json\.
+For full details and description of the \fBnpm\-shrinkwrap\.json\fP file format,
+refer to the manual page for
+npm help package\-lock\.json\.
.SS See also
.RS 0
.IP \(bu 2
diff --git a/deps/npm/man/man5/npmrc.5 b/deps/npm/man/man5/npmrc.5
index 877c2175a486a8..baf2fe3e5d9078 100644
--- a/deps/npm/man/man5/npmrc.5
+++ b/deps/npm/man/man5/npmrc.5
@@ -3,13 +3,14 @@
\fBnpmrc\fR \- The npm config files
.SS Description
.P
-npm gets its config settings from the command line, environment
-variables, and \fBnpmrc\fP files\.
+npm gets its config settings from the command line, environment variables,
+and \fBnpmrc\fP files\.
.P
-The \fBnpm config\fP command can be used to update and edit the contents
-of the user and global npmrc files\.
+The \fBnpm config\fP command can be used to update and edit the contents of the
+user and global npmrc files\.
.P
-For a list of available configuration options, see npm help config\.
+For a list of available configuration options, see
+npm help config\.
.SS Files
.P
The four relevant files are:
@@ -25,9 +26,9 @@ npm builtin config file (/path/to/npm/npmrc)
.RE
.P
-All npm config files are an ini\-formatted list of \fBkey = value\fP
-parameters\. Environment variables can be replaced using
-\fB${VARIABLE_NAME}\fP\|\. For example:
+All npm config files are an ini\-formatted list of \fBkey = value\fP parameters\.
+Environment variables can be replaced using \fB${VARIABLE_NAME}\fP\|\. For
+example:
.P
.RS 2
.nf
@@ -35,12 +36,11 @@ prefix = ${HOME}/\.npm\-packages
.fi
.RE
.P
-Each of these files is loaded, and config options are resolved in
-priority order\. For example, a setting in the userconfig file would
-override the setting in the globalconfig file\.
+Each of these files is loaded, and config options are resolved in priority
+order\. For example, a setting in the userconfig file would override the
+setting in the globalconfig file\.
.P
-Array values are specified by adding "[]" after the key name\. For
-example:
+Array values are specified by adding "[]" after the key name\. For example:
.P
.RS 2
.nf
@@ -50,7 +50,9 @@ key[] = "second value"
.RE
.SS Comments
.P
-Lines in \fB\|\.npmrc\fP files are interpreted as comments when they begin with a \fB;\fP or \fB#\fP character\. \fB\|\.npmrc\fP files are parsed by npm/ini \fIhttps://github\.com/npm/ini\fR, which specifies this comment syntax\.
+Lines in \fB\|\.npmrc\fP files are interpreted as comments when they begin with a
+\fB;\fP or \fB#\fP character\. \fB\|\.npmrc\fP files are parsed by
+npm/ini \fIhttps://github\.com/npm/ini\fR, which specifies this comment syntax\.
.P
For example:
.P
@@ -67,31 +69,30 @@ When working locally in a project, a \fB\|\.npmrc\fP file in the root of the
project (ie, a sibling of \fBnode_modules\fP and \fBpackage\.json\fP) will set
config values specific to this project\.
.P
-Note that this only applies to the root of the project that you're
-running npm in\. It has no effect when your module is published\. For
-example, you can't publish a module that forces itself to install
-globally, or in a different location\.
+Note that this only applies to the root of the project that you're running
+npm in\. It has no effect when your module is published\. For example, you
+can't publish a module that forces itself to install globally, or in a
+different location\.
.P
Additionally, this file is not read in global mode, such as when running
\fBnpm install \-g\fP\|\.
.SS Per\-user config file
.P
-\fB$HOME/\.npmrc\fP (or the \fBuserconfig\fP param, if set in the environment
-or on the command line)
+\fB$HOME/\.npmrc\fP (or the \fBuserconfig\fP param, if set in the environment or on
+the command line)
.SS Global config file
.P
-\fB$PREFIX/etc/npmrc\fP (or the \fBglobalconfig\fP param, if set above):
-This file is an ini\-file formatted list of \fBkey = value\fP parameters\.
-Environment variables can be replaced as above\.
+\fB$PREFIX/etc/npmrc\fP (or the \fBglobalconfig\fP param, if set above): This file
+is an ini\-file formatted list of \fBkey = value\fP parameters\. Environment
+variables can be replaced as above\.
.SS Built\-in config file
.P
\fBpath/to/npm/itself/npmrc\fP
.P
This is an unchangeable "builtin" configuration file that npm keeps
consistent across updates\. Set fields in here using the \fB\|\./configure\fP
-script that comes with npm\. This is primarily for distribution
-maintainers to override default configs in a standard and consistent
-manner\.
+script that comes with npm\. This is primarily for distribution maintainers
+to override default configs in a standard and consistent manner\.
.SS See also
.RS 0
.IP \(bu 2
diff --git a/deps/npm/man/man5/package-json.5 b/deps/npm/man/man5/package-json.5
index 17946fd18fb559..79ebabc5eec228 100644
--- a/deps/npm/man/man5/package-json.5
+++ b/deps/npm/man/man5/package-json.5
@@ -3,33 +3,37 @@
\fBpackage.json\fR \- Specifics of npm's package\.json handling
.SS Description
.P
-This document is all you need to know about what's required in your package\.json
-file\. It must be actual JSON, not just a JavaScript object literal\.
+This document is all you need to know about what's required in your
+package\.json file\. It must be actual JSON, not just a JavaScript object
+literal\.
.P
A lot of the behavior described in this document is affected by the config
settings described in npm help \fBconfig\fP\|\.
.SS name
.P
If you plan to publish your package, the \fImost\fR important things in your
-package\.json are the name and version fields as they will be required\. The name
-and version together form an identifier that is assumed to be completely unique\.
-Changes to the package should come along with changes to the version\. If you don't
-plan to publish your package, the name and version fields are optional\.
+package\.json are the name and version fields as they will be required\. The
+name and version together form an identifier that is assumed to be
+completely unique\. Changes to the package should come along with changes
+to the version\. If you don't plan to publish your package, the name and
+version fields are optional\.
.P
The name is what your thing is called\.
.P
Some rules:
.RS 0
.IP \(bu 2
-The name must be less than or equal to 214 characters\. This includes the scope for
-scoped packages\.
+The name must be less than or equal to 214 characters\. This includes the
+scope for scoped packages\.
.IP \(bu 2
-The names of scoped packages can begin with a dot or an underscore\. This is not permitted without a scope\.
+The names of scoped packages can begin with a dot or an underscore\. This
+is not permitted without a scope\.
.IP \(bu 2
New packages must not have uppercase letters in the name\.
.IP \(bu 2
-The name ends up being part of a URL, an argument on the command line, and a
-folder name\. Therefore, the name can't contain any non\-URL\-safe characters\.
+The name ends up being part of a URL, an argument on the command line,
+and a folder name\. Therefore, the name can't contain any non\-URL\-safe
+characters\.
.RE
.P
@@ -38,15 +42,16 @@ Some tips:
.IP \(bu 2
Don't use the same name as a core Node module\.
.IP \(bu 2
-Don't put "js" or "node" in the name\. It's assumed that it's js, since you're
-writing a package\.json file, and you can specify the engine using the "engines"
-field\. (See below\.)
+Don't put "js" or "node" in the name\. It's assumed that it's js, since
+you're writing a package\.json file, and you can specify the engine using
+the "engines" field\. (See below\.)
.IP \(bu 2
-The name will probably be passed as an argument to require(), so it should
-be something short, but also reasonably descriptive\.
+The name will probably be passed as an argument to require(), so it
+should be something short, but also reasonably descriptive\.
.IP \(bu 2
-You may want to check the npm registry to see if there's something by that name
-already, before you get too attached to it\. https://www\.npmjs\.com/
+You may want to check the npm registry to see if there's something by
+that name already, before you get too attached to it\.
+https://www\.npmjs\.com/
.RE
.P
@@ -55,14 +60,15 @@ npm help \fBscope\fP for more detail\.
.SS version
.P
If you plan to publish your package, the \fImost\fR important things in your
-package\.json are the name and version fields as they will be required\. The name
-and version together form an identifier that is assumed to be completely unique\.
-Changes to the package should come along with changes to the version\. If you don't
-plan to publish your package, the name and version fields are optional\.
+package\.json are the name and version fields as they will be required\. The
+name and version together form an identifier that is assumed to be
+completely unique\. Changes to the package should come along with changes
+to the version\. If you don't plan to publish your package, the name and
+version fields are optional\.
.P
Version must be parseable by
-node\-semver \fIhttps://github\.com/npm/node\-semver\fR, which is bundled
-with npm as a dependency\. (\fBnpm install semver\fP to use it yourself\.)
+node\-semver \fIhttps://github\.com/npm/node\-semver\fR, which is bundled with
+npm as a dependency\. (\fBnpm install semver\fP to use it yourself\.)
.P
More on version numbers and ranges at npm help semver\.
.SS description
@@ -71,8 +77,8 @@ Put a description in it\. It's a string\. This helps people discover your
package, as it's listed in \fBnpm search\fP\|\.
.SS keywords
.P
-Put keywords in it\. It's an array of strings\. This helps people
-discover your package as it's listed in \fBnpm search\fP\|\.
+Put keywords in it\. It's an array of strings\. This helps people discover
+your package as it's listed in \fBnpm search\fP\|\.
.SS homepage
.P
The url to the project homepage\.
@@ -87,47 +93,54 @@ Example:
.SS bugs
.P
The url to your project's issue tracker and / or the email address to which
-issues should be reported\. These are helpful for people who encounter issues
-with your package\.
+issues should be reported\. These are helpful for people who encounter
+issues with your package\.
.P
It should look like this:
.P
.RS 2
.nf
-{ "url" : "https://github\.com/owner/project/issues"
-, "email" : "project@hostname\.com"
+{
+ "url" : "https://github\.com/owner/project/issues",
+ "email" : "project@hostname\.com"
}
.fi
.RE
.P
-You can specify either one or both values\. If you want to provide only a url,
-you can specify the value for "bugs" as a simple string instead of an object\.
+You can specify either one or both values\. If you want to provide only a
+url, you can specify the value for "bugs" as a simple string instead of an
+object\.
.P
If a url is provided, it will be used by the \fBnpm bugs\fP command\.
.SS license
.P
-You should specify a license for your package so that people know how they are
-permitted to use it, and any restrictions you're placing on it\.
+You should specify a license for your package so that people know how they
+are permitted to use it, and any restrictions you're placing on it\.
.P
-If you're using a common license such as BSD\-2\-Clause or MIT, add a
-current SPDX license identifier for the license you're using, like this:
+If you're using a common license such as BSD\-2\-Clause or MIT, add a current
+SPDX license identifier for the license you're using, like this:
.P
.RS 2
.nf
-{ "license" : "BSD\-3\-Clause" }
+{
+ "license" : "BSD\-3\-Clause"
+}
.fi
.RE
.P
-You can check the full list of SPDX license IDs \fIhttps://spdx\.org/licenses/\fR\|\.
-Ideally you should pick one that is
+You can check the full list of SPDX license
+IDs \fIhttps://spdx\.org/licenses/\fR\|\. Ideally you should pick one that is
OSI \fIhttps://opensource\.org/licenses/alphabetical\fR approved\.
.P
-If your package is licensed under multiple common licenses, use an SPDX license
-expression syntax version 2\.0 string \fIhttps://www\.npmjs\.com/package/spdx\fR, like this:
+If your package is licensed under multiple common licenses, use an SPDX
+license expression syntax version 2\.0
+string \fIhttps://www\.npmjs\.com/package/spdx\fR, like this:
.P
.RS 2
.nf
-{ "license" : "(ISC OR GPL\-3\.0)" }
+{
+ "license" : "(ISC OR GPL\-3\.0)"
+}
.fi
.RE
.P
@@ -136,32 +149,37 @@ you are using a custom license, use a string value like this one:
.P
.RS 2
.nf
-{ "license" : "SEE LICENSE IN " }
+{
+ "license" : "SEE LICENSE IN "
+}
.fi
.RE
.P
Then include a file named \fB\fP at the top level of the package\.
.P
-Some old packages used license objects or a "licenses" property containing an
-array of license objects:
+Some old packages used license objects or a "licenses" property containing
+an array of license objects:
.P
.RS 2
.nf
// Not valid metadata
-{ "license" :
- { "type" : "ISC"
- , "url" : "https://opensource\.org/licenses/ISC"
+{
+ "license" : {
+ "type" : "ISC",
+ "url" : "https://opensource\.org/licenses/ISC"
}
}
// Not valid metadata
-{ "licenses" :
- [
- { "type": "MIT"
- , "url": "https://www\.opensource\.org/licenses/mit\-license\.php"
- }
- , { "type": "Apache\-2\.0"
- , "url": "https://opensource\.org/licenses/apache2\.0\.php"
+{
+ "licenses" : [
+ {
+ "type": "MIT",
+ "url": "https://www\.opensource\.org/licenses/mit\-license\.php"
+ },
+ {
+ "type": "Apache\-2\.0",
+ "url": "https://opensource\.org/licenses/apache2\.0\.php"
}
]
}
@@ -172,9 +190,17 @@ Those styles are now deprecated\. Instead, use SPDX expressions, like this:
.P
.RS 2
.nf
-{ "license": "ISC" }
-
-{ "license": "(MIT OR Apache\-2\.0)" }
+{
+ "license": "ISC"
+}
+.fi
+.RE
+.P
+.RS 2
+.nf
+{
+ "license": "(MIT OR Apache\-2\.0)"
+}
.fi
.RE
.P
@@ -183,30 +209,37 @@ unpublished package under any terms:
.P
.RS 2
.nf
-{ "license": "UNLICENSED" }
+{
+ "license": "UNLICENSED"
+}
.fi
.RE
.P
Consider also setting \fB"private": true\fP to prevent accidental publication\.
.SS people fields: author, contributors
.P
-The "author" is one person\. "contributors" is an array of people\. A "person"
-is an object with a "name" field and optionally "url" and "email", like this:
+The "author" is one person\. "contributors" is an array of people\. A
+"person" is an object with a "name" field and optionally "url" and "email",
+like this:
.P
.RS 2
.nf
-{ "name" : "Barney Rubble"
-, "email" : "b@rubble\.com"
-, "url" : "http://barnyrubble\.tumblr\.com/"
+{
+ "name" : "Barney Rubble",
+ "email" : "b@rubble\.com",
+ "url" : "http://barnyrubble\.tumblr\.com/"
}
.fi
.RE
.P
-Or you can shorten that all into a single string, and npm will parse it for you:
+Or you can shorten that all into a single string, and npm will parse it for
+you:
.P
.RS 2
.nf
-"Barney Rubble (http://barnyrubble\.tumblr\.com/)"
+{
+ "author": "Barney Rubble (http://barnyrubble\.tumblr\.com/)"
+}
.fi
.RE
.P
@@ -216,60 +249,62 @@ npm also sets a top\-level "maintainers" field with your npm user info\.
.SS funding
.P
You can specify an object containing an URL that provides up\-to\-date
-information about ways to help fund development of your package, or
-a string URL, or an array of these:
+information about ways to help fund development of your package, or a
+string URL, or an array of these:
.P
.RS 2
.nf
-"funding": {
- "type" : "individual",
- "url" : "http://example\.com/donate"
-}
-
-"funding": {
- "type" : "patreon",
- "url" : "https://www\.patreon\.com/my\-account"
-}
-
-"funding": "http://example\.com/donate"
-
-"funding": [
- {
+{
+ "funding": {
"type" : "individual",
"url" : "http://example\.com/donate"
},
- "http://example\.com/donateAlso",
- {
+
+ "funding": {
"type" : "patreon",
"url" : "https://www\.patreon\.com/my\-account"
- }
-]
+ },
+
+ "funding": "http://example\.com/donate",
+
+ "funding": [
+ {
+ "type" : "individual",
+ "url" : "http://example\.com/donate"
+ },
+ "http://example\.com/donateAlso",
+ {
+ "type" : "patreon",
+ "url" : "https://www\.patreon\.com/my\-account"
+ }
+ ]
+}
.fi
.RE
.P
Users can use the \fBnpm fund\fP subcommand to list the \fBfunding\fP URLs of all
-dependencies of their project, direct and indirect\. A shortcut to visit each
-funding url is also available when providing the project name such as:
-\fBnpm fund \fP (when there are multiple URLs, the first one will be
-visited)
+dependencies of their project, direct and indirect\. A shortcut to visit
+each funding url is also available when providing the project name such as:
+\fBnpm fund \fP (when there are multiple URLs, the first one will
+be visited)
.SS files
.P
-The optional \fBfiles\fP field is an array of file patterns that describes
-the entries to be included when your package is installed as a
-dependency\. File patterns follow a similar syntax to \fB\|\.gitignore\fP, but
-reversed: including a file, directory, or glob pattern (\fB*\fP, \fB**/*\fP, and such)
-will make it so that file is included in the tarball when it's packed\. Omitting
-the field will make it default to \fB["*"]\fP, which means it will include all files\.
+The optional \fBfiles\fP field is an array of file patterns that describes the
+entries to be included when your package is installed as a dependency\. File
+patterns follow a similar syntax to \fB\|\.gitignore\fP, but reversed: including a
+file, directory, or glob pattern (\fB*\fP, \fB**/*\fP, and such) will make it so
+that file is included in the tarball when it's packed\. Omitting the field
+will make it default to \fB["*"]\fP, which means it will include all files\.
.P
-Some special files and directories are also included or excluded regardless of
-whether they exist in the \fBfiles\fP array (see below)\.
+Some special files and directories are also included or excluded regardless
+of whether they exist in the \fBfiles\fP array (see below)\.
.P
-You can also provide a \fB\|\.npmignore\fP file in the root of your package or
-in subdirectories, which will keep files from being included\. At the
-root of your package it will not override the "files" field, but in
-subdirectories it will\. The \fB\|\.npmignore\fP file works just like a
-\fB\|\.gitignore\fP\|\. If there is a \fB\|\.gitignore\fP file, and \fB\|\.npmignore\fP is
-missing, \fB\|\.gitignore\fP\|'s contents will be used instead\.
+You can also provide a \fB\|\.npmignore\fP file in the root of your package or in
+subdirectories, which will keep files from being included\. At the root of
+your package it will not override the "files" field, but in subdirectories
+it will\. The \fB\|\.npmignore\fP file works just like a \fB\|\.gitignore\fP\|\. If there is
+a \fB\|\.gitignore\fP file, and \fB\|\.npmignore\fP is missing, \fB\|\.gitignore\fP\|'s contents
+will be used instead\.
.P
Files included with the "package\.json#files" field \fIcannot\fR be excluded
through \fB\|\.npmignore\fP or \fB\|\.gitignore\fP\|\.
@@ -324,24 +359,28 @@ Conversely, some files are always ignored:
.IP \(bu 2
\fB*\.orig\fP
.IP \(bu 2
-\fBpackage\-lock\.json\fP (use shrinkwrap instead)
+\fBpackage\-lock\.json\fP (use
+npm help \fBnpm\-shrinkwrap\.json\fP if you wish
+it to be published)
.RE
.SS main
.P
-The main field is a module ID that is the primary entry point to your program\.
-That is, if your package is named \fBfoo\fP, and a user installs it, and then does
-\fBrequire("foo")\fP, then your main module's exports object will be returned\.
+The main field is a module ID that is the primary entry point to your
+program\. That is, if your package is named \fBfoo\fP, and a user installs it,
+and then does \fBrequire("foo")\fP, then your main module's exports object will
+be returned\.
.P
-This should be a module ID relative to the root of your package folder\.
+This should be a module relative to the root of your package folder\.
.P
-For most modules, it makes the most sense to have a main script and often not
-much else\.
+For most modules, it makes the most sense to have a main script and often
+not much else\.
.SS browser
.P
If your module is meant to be used client\-side the browser field should be
used instead of the main field\. This is helpful to hint users that it might
-rely on primitives that aren't available in Node\.js modules\. (e\.g\. \fBwindow\fP)
+rely on primitives that aren't available in Node\.js modules\. (e\.g\.
+\fBwindow\fP)
.SS bin
.P
A lot of packages have one or more executable files that they'd like to
@@ -349,29 +388,35 @@ install into the PATH\. npm makes this pretty easy (in fact, it uses this
feature to install the "npm" executable\.)
.P
To use this, supply a \fBbin\fP field in your package\.json which is a map of
-command name to local file name\. On install, npm will symlink that file into
-\fBprefix/bin\fP for global installs, or \fB\|\./node_modules/\.bin/\fP for local
+command name to local file name\. On install, npm will symlink that file
+into \fBprefix/bin\fP for global installs, or \fB\|\./node_modules/\.bin/\fP for local
installs\.
.P
For example, myapp could have this:
.P
.RS 2
.nf
-{ "bin" : { "myapp" : "\./cli\.js" } }
+{
+ "bin": {
+ "myapp": "\./cli\.js"
+ }
+}
.fi
.RE
.P
-So, when you install myapp, it'll create a symlink from the \fBcli\.js\fP script to
-\fB/usr/local/bin/myapp\fP\|\.
+So, when you install myapp, it'll create a symlink from the \fBcli\.js\fP script
+to \fB/usr/local/bin/myapp\fP\|\.
.P
-If you have a single executable, and its name should be the name
-of the package, then you can just supply it as a string\. For example:
+If you have a single executable, and its name should be the name of the
+package, then you can just supply it as a string\. For example:
.P
.RS 2
.nf
-{ "name": "my\-program"
-, "version": "1\.2\.5"
-, "bin": "\./path/to/program" }
+{
+ "name": "my\-program",
+ "version": "1\.2\.5",
+ "bin": "\./path/to/program"
+}
.fi
.RE
.P
@@ -379,9 +424,13 @@ would be the same as this:
.P
.RS 2
.nf
-{ "name": "my\-program"
-, "version": "1\.2\.5"
-, "bin" : { "my\-program" : "\./path/to/program" } }
+{
+ "name": "my\-program",
+ "version": "1\.2\.5",
+ "bin": {
+ "my\-program": "\./path/to/program"
+ }
+}
.fi
.RE
.P
@@ -390,35 +439,42 @@ Please make sure that your file(s) referenced in \fBbin\fP starts with
executable!
.SS man
.P
-Specify either a single file or an array of filenames to put in place for the
-\fBman\fP program to find\.
+Specify either a single file or an array of filenames to put in place for
+the \fBman\fP program to find\.
.P
If only a single file is provided, then it's installed such that it is the
-result from \fBman \fP, regardless of its actual filename\. For example:
+result from \fBman \fP, regardless of its actual filename\. For
+example:
.P
.RS 2
.nf
-{ "name" : "foo"
-, "version" : "1\.2\.3"
-, "description" : "A packaged foo fooer for fooing foos"
-, "main" : "foo\.js"
-, "man" : "\./man/doc\.1"
+{
+ "name": "foo",
+ "version": "1\.2\.3",
+ "description": "A packaged foo fooer for fooing foos",
+ "main": "foo\.js",
+ "man": "\./man/doc\.1"
}
.fi
.RE
.P
-would link the \fB\|\./man/doc\.1\fP file in such that it is the target for \fBman foo\fP
+would link the \fB\|\./man/doc\.1\fP file in such that it is the target for \fBman
+foo\fP
.P
If the filename doesn't start with the package name, then it's prefixed\.
So, this:
.P
.RS 2
.nf
-{ "name" : "foo"
-, "version" : "1\.2\.3"
-, "description" : "A packaged foo fooer for fooing foos"
-, "main" : "foo\.js"
-, "man" : [ "\./man/foo\.1", "\./man/bar\.1" ]
+{
+ "name": "foo",
+ "version": "1\.2\.3",
+ "description": "A packaged foo fooer for fooing foos",
+ "main": "foo\.js",
+ "man": [
+ "\./man/foo\.1",
+ "\./man/bar\.1"
+ ]
}
.fi
.RE
@@ -426,15 +482,20 @@ So, this:
will create files to do \fBman foo\fP and \fBman foo\-bar\fP\|\.
.P
Man files must end with a number, and optionally a \fB\|\.gz\fP suffix if they are
-compressed\. The number dictates which man section the file is installed into\.
+compressed\. The number dictates which man section the file is installed
+into\.
.P
.RS 2
.nf
-{ "name" : "foo"
-, "version" : "1\.2\.3"
-, "description" : "A packaged foo fooer for fooing foos"
-, "main" : "foo\.js"
-, "man" : [ "\./man/foo\.1", "\./man/foo\.2" ]
+{
+ "name": "foo",
+ "version": "1\.2\.3",
+ "description": "A packaged foo fooer for fooing foos",
+ "main": "foo\.js",
+ "man": [
+ "\./man/foo\.1",
+ "\./man/foo\.2"
+ ]
}
.fi
.RE
@@ -442,40 +503,26 @@ compressed\. The number dictates which man section the file is installed into\.
will create entries for \fBman foo\fP and \fBman 2 foo\fP
.SS directories
.P
-The CommonJS Packages \fIhttp://wiki\.commonjs\.org/wiki/Packages/1\.0\fR spec details a
-few ways that you can indicate the structure of your package using a \fBdirectories\fP
-object\. If you look at npm's package\.json \fIhttps://registry\.npmjs\.org/npm/latest\fR,
-you'll see that it has directories for doc, lib, and man\.
+The CommonJS Packages \fIhttp://wiki\.commonjs\.org/wiki/Packages/1\.0\fR spec
+details a few ways that you can indicate the structure of your package
+using a \fBdirectories\fP object\. If you look at npm's
+package\.json \fIhttps://registry\.npmjs\.org/npm/latest\fR, you'll see that it
+has directories for doc, lib, and man\.
.P
In the future, this information may be used in other creative ways\.
-.SS directories\.lib
-.P
-Tell people where the bulk of your library is\. Nothing special is done
-with the lib folder in any way, but it's useful meta info\.
.SS directories\.bin
.P
If you specify a \fBbin\fP directory in \fBdirectories\.bin\fP, all the files in
that folder will be added\.
.P
-Because of the way the \fBbin\fP directive works, specifying both a
-\fBbin\fP path and setting \fBdirectories\.bin\fP is an error\. If you want to
-specify individual files, use \fBbin\fP, and for all the files in an
-existing \fBbin\fP directory, use \fBdirectories\.bin\fP\|\.
+Because of the way the \fBbin\fP directive works, specifying both a \fBbin\fP path
+and setting \fBdirectories\.bin\fP is an error\. If you want to specify
+individual files, use \fBbin\fP, and for all the files in an existing \fBbin\fP
+directory, use \fBdirectories\.bin\fP\|\.
.SS directories\.man
.P
A folder that is full of man pages\. Sugar to generate a "man" array by
walking the folder\.
-.SS directories\.doc
-.P
-Put markdown files in here\. Eventually, these will be displayed nicely,
-maybe, someday\.
-.SS directories\.example
-.P
-Put example scripts in here\. Someday, it might be exposed in some clever way\.
-.SS directories\.test
-.P
-Put your tests in here\. It is currently not exposed, but it might be in the
-future\.
.SS repository
.P
Specify the place where your code lives\. This is helpful for people who
@@ -486,68 +533,76 @@ Do it like this:
.P
.RS 2
.nf
-"repository": {
- "type" : "git",
- "url" : "https://github\.com/npm/cli\.git"
-}
-
-"repository": {
- "type" : "svn",
- "url" : "https://v8\.googlecode\.com/svn/trunk/"
+{
+ "repository": {
+ "type": "git",
+ "url": "https://github\.com/npm/cli\.git"
+ }
}
.fi
.RE
.P
-The URL should be a publicly available (perhaps read\-only) url that can be handed
-directly to a VCS program without any modification\. It should not be a url to an
-html project page that you put in your browser\. It's for computers\.
+The URL should be a publicly available (perhaps read\-only) url that can be
+handed directly to a VCS program without any modification\. It should not
+be a url to an html project page that you put in your browser\. It's for
+computers\.
.P
-For GitHub, GitHub gist, Bitbucket, or GitLab repositories you can use the same
-shortcut syntax you use for \fBnpm install\fP:
+For GitHub, GitHub gist, Bitbucket, or GitLab repositories you can use the
+same shortcut syntax you use for \fBnpm install\fP:
.P
.RS 2
.nf
-"repository": "npm/npm"
+{
+ "repository": "npm/npm",
-"repository": "github:user/repo"
+ "repository": "github:user/repo",
-"repository": "gist:11081aaa281"
+ "repository": "gist:11081aaa281",
-"repository": "bitbucket:user/repo"
+ "repository": "bitbucket:user/repo",
-"repository": "gitlab:user/repo"
+ "repository": "gitlab:user/repo"
+}
.fi
.RE
.P
-If the \fBpackage\.json\fP for your package is not in the root directory (for example
-if it is part of a monorepo), you can specify the directory in which it lives:
+If the \fBpackage\.json\fP for your package is not in the root directory (for
+example if it is part of a monorepo), you can specify the directory in
+which it lives:
.P
.RS 2
.nf
-"repository": {
- "type" : "git",
- "url" : "https://github\.com/facebook/react\.git",
- "directory": "packages/react\-dom"
+{
+ "repository": {
+ "type": "git",
+ "url": "https://github\.com/facebook/react\.git",
+ "directory": "packages/react\-dom"
+ }
}
.fi
.RE
.SS scripts
.P
-The "scripts" property is a dictionary containing script commands that are run
-at various times in the lifecycle of your package\. The key is the lifecycle
-event, and the value is the command to run at that point\.
+The "scripts" property is a dictionary containing script commands that are
+run at various times in the lifecycle of your package\. The key is the
+lifecycle event, and the value is the command to run at that point\.
.P
-See npm help \fBscripts\fP to find out more about writing package scripts\.
+See npm help \fBscripts\fP to find out more about writing package
+scripts\.
.SS config
.P
-A "config" object can be used to set configuration parameters used in package
-scripts that persist across upgrades\. For instance, if a package had the
-following:
+A "config" object can be used to set configuration parameters used in
+package scripts that persist across upgrades\. For instance, if a package
+had the following:
.P
.RS 2
.nf
-{ "name" : "foo"
-, "config" : { "port" : "8080" } }
+{
+ "name": "foo",
+ "config": {
+ "port": "8080"
+ }
+}
.fi
.RE
.P
@@ -555,8 +610,8 @@ and then had a "start" command that then referenced the
\fBnpm_package_config_port\fP environment variable, then the user could
override that by doing \fBnpm config set foo:port 8001\fP\|\.
.P
-See npm help \fBconfig\fP and npm help \fBscripts\fP for more on package
-configs\.
+See npm help \fBconfig\fP and npm help \fBscripts\fP for
+more on package configs\.
.SS dependencies
.P
Dependencies are specified in a simple object that maps a package name to a
@@ -564,10 +619,11 @@ version range\. The version range is a string which has one or more
space\-separated descriptors\. Dependencies can also be identified with a
tarball or git URL\.
.P
-\fBPlease do not put test harnesses or transpilers in your
-\fBdependencies\fP object\.\fR See \fBdevDependencies\fP, below\.
+\fBPlease do not put test harnesses or transpilers or other "development"
+time tools in your \fBdependencies\fP object\.\fR See \fBdevDependencies\fP, below\.
.P
-See npm help semver for more details about specifying version ranges\.
+See npm help semver for more details about specifying version
+ranges\.
.RS 0
.IP \(bu 2
\fBversion\fP Must match \fBversion\fP exactly
@@ -580,7 +636,8 @@ See npm help semver for more details about specifying version ranges\.
.IP \(bu 2
\fB<=version\fP
.IP \(bu 2
-\fB~version\fP "Approximately equivalent to version" See npm help semver
+\fB~version\fP "Approximately equivalent to version" See
+npm help semver
.IP \(bu 2
\fB^version\fP "Compatible with version" See npm help semver
.IP \(bu 2
@@ -600,7 +657,8 @@ See npm help semver for more details about specifying version ranges\.
.IP \(bu 2
\fBuser/repo\fP See 'GitHub URLs' below
.IP \(bu 2
-\fBtag\fP A specific version tagged and published as \fBtag\fP See npm help \fBdist\-tag\fP
+\fBtag\fP A specific version tagged and published as \fBtag\fP See npm help \fBnpm
+dist\-tag\fP
.IP \(bu 2
\fBpath/path/path\fP See Local Paths \fI#local\-paths\fR below
@@ -610,19 +668,20 @@ For example, these are all valid:
.P
.RS 2
.nf
-{ "dependencies" :
- { "foo" : "1\.0\.0 \- 2\.9999\.9999"
- , "bar" : ">=1\.0\.2 <2\.1\.2"
- , "baz" : ">1\.0\.2 <=2\.3\.4"
- , "boo" : "2\.0\.1"
- , "qux" : "<1\.0\.0 || >=2\.3\.1 <2\.4\.5 || >=2\.5\.2 <3\.0\.0"
- , "asd" : "http://asdf\.com/asdf\.tar\.gz"
- , "til" : "~1\.2"
- , "elf" : "~1\.2\.3"
- , "two" : "2\.x"
- , "thr" : "3\.3\.x"
- , "lat" : "latest"
- , "dyl" : "file:\.\./dyl"
+{
+ "dependencies": {
+ "foo": "1\.0\.0 \- 2\.9999\.9999",
+ "bar": ">=1\.0\.2 <2\.1\.2",
+ "baz": ">1\.0\.2 <=2\.3\.4",
+ "boo": "2\.0\.1",
+ "qux": "<1\.0\.0 || >=2\.3\.1 <2\.4\.5 || >=2\.5\.2 <3\.0\.0",
+ "asd": "http://asdf\.com/asdf\.tar\.gz",
+ "til": "~1\.2",
+ "elf": "~1\.2\.3",
+ "two": "2\.x",
+ "thr": "3\.3\.x",
+ "lat": "latest",
+ "dyl": "file:\.\./dyl"
}
}
.fi
@@ -649,8 +708,8 @@ Git urls are of the form:
If \fB#\fP is provided, it will be used to clone exactly that
commit\. If the commit\-ish has the format \fB#semver:\fP, \fB\fP can
be any valid semver range or exact version, and npm will look for any tags
-or refs matching that range in the remote repository, much as it would for a
-registry dependency\. If neither \fB#\fP or \fB#semver:\fP is
+or refs matching that range in the remote repository, much as it would for
+a registry dependency\. If neither \fB#\fP or \fB#semver:\fP is
specified, then \fBmaster\fP is used\.
.P
Examples:
@@ -684,9 +743,9 @@ included\. For example:
.RE
.SS Local Paths
.P
-As of version 2\.0\.0 you can provide a path to a local directory that contains a
-package\. Local paths can be saved using \fBnpm install \-S\fP or
-\fBnpm install \-\-save\fP, using any of these forms:
+As of version 2\.0\.0 you can provide a path to a local directory that
+contains a package\. Local paths can be saved using \fBnpm install \-S\fP or \fBnpm
+install \-\-save\fP, using any of these forms:
.P
.RS 2
.nf
@@ -711,32 +770,32 @@ in which case they will be normalized to a relative path and added to your
.fi
.RE
.P
-This feature is helpful for local offline development and creating
-tests that require npm installing where you don't want to hit an
-external server, but should not be used when publishing packages
-to the public registry\.
+This feature is helpful for local offline development and creating tests
+that require npm installing where you don't want to hit an external server,
+but should not be used when publishing packages to the public registry\.
.SS devDependencies
.P
If someone is planning on downloading and using your module in their
-program, then they probably don't want or need to download and build
-the external test or documentation framework that you use\.
+program, then they probably don't want or need to download and build the
+external test or documentation framework that you use\.
.P
-In this case, it's best to map these additional items in a \fBdevDependencies\fP
-object\.
+In this case, it's best to map these additional items in a
+\fBdevDependencies\fP object\.
.P
-These things will be installed when doing \fBnpm link\fP or \fBnpm install\fP
-from the root of a package, and can be managed like any other npm
-configuration param\. See npm help \fBconfig\fP for more on the topic\.
+These things will be installed when doing \fBnpm link\fP or \fBnpm install\fP from
+the root of a package, and can be managed like any other npm configuration
+param\. See npm help \fBconfig\fP for more on the topic\.
.P
For build steps that are not platform\-specific, such as compiling
-CoffeeScript or other languages to JavaScript, use the \fBprepare\fP
-script to do this, and make the required package a devDependency\.
+CoffeeScript or other languages to JavaScript, use the \fBprepare\fP script to
+do this, and make the required package a devDependency\.
.P
For example:
.P
.RS 2
.nf
-{ "name": "ethopia\-waza",
+{
+ "name": "ethopia\-waza",
"description": "a delightfully fruity coffee varietal",
"version": "1\.2\.3",
"devDependencies": {
@@ -750,16 +809,17 @@ For example:
.fi
.RE
.P
-The \fBprepare\fP script will be run before publishing, so that users
-can consume the functionality without requiring them to compile it
-themselves\. In dev mode (ie, locally running \fBnpm install\fP), it'll
-run this script as well, so that you can test it easily\.
+The \fBprepare\fP script will be run before publishing, so that users can
+consume the functionality without requiring them to compile it themselves\.
+In dev mode (ie, locally running \fBnpm install\fP), it'll run this script as
+well, so that you can test it easily\.
.SS peerDependencies
.P
In some cases, you want to express the compatibility of your package with a
host tool or library, while not necessarily doing a \fBrequire\fP of this host\.
-This is usually referred to as a \fIplugin\fR\|\. Notably, your module may be exposing
-a specific interface, expected and specified by the host documentation\.
+This is usually referred to as a \fIplugin\fR\|\. Notably, your module may be
+exposing a specific interface, expected and specified by the host
+documentation\.
.P
For example:
.P
@@ -775,9 +835,9 @@ For example:
.fi
.RE
.P
-This ensures your package \fBtea\-latte\fP can be installed \fIalong\fR with the second
-major version of the host package \fBtea\fP only\. \fBnpm install tea\-latte\fP could
-possibly yield the following dependency graph:
+This ensures your package \fBtea\-latte\fP can be installed \fIalong\fR with the
+second major version of the host package \fBtea\fP only\. \fBnpm install
+tea\-latte\fP could possibly yield the following dependency graph:
.P
.RS 2
.nf
@@ -786,24 +846,28 @@ possibly yield the following dependency graph:
.fi
.RE
.P
-\fBNOTE: npm versions 1 and 2 will automatically install \fBpeerDependencies\fP if
-they are not explicitly depended upon higher in the dependency tree\. In the
-next major version of npm (npm@3), this will no longer be the case\. You will
-receive a warning that the peerDependency is not installed instead\.\fR The
-behavior in npms 1 & 2 was frequently confusing and could easily put you into
-dependency hell, a situation that npm is designed to avoid as much as possible\.
-.P
-Trying to install another plugin with a conflicting requirement will cause an
-error\. For this reason, make sure your plugin requirement is as broad as
-possible, and not to lock it down to specific patch versions\.
-.P
-Assuming the host complies with semver \fIhttps://semver\.org/\fR, only changes in
-the host package's major version will break your plugin\. Thus, if you've worked
-with every 1\.x version of the host package, use \fB"^1\.0"\fP or \fB"1\.x"\fP to express
-this\. If you depend on features introduced in 1\.5\.2, use \fB">= 1\.5\.2 < 2"\fP\|\.
+In npm versions 3 through 6, \fBpeerDependencies\fP were not automatically
+installed, and would raise a warning if an invalid version of the peer
+dependency was found in the tree\. As of npm v7, peerDependencies \fIare\fR
+installed by default\.
+.P
+Trying to install another plugin with a conflicting requirement may cause
+an error if the tree cannot be resolved correctly\. For this reason, make
+sure your plugin requirement is as broad as possible, and not to lock it
+down to specific patch versions\.
+.P
+Assuming the host complies with semver \fIhttps://semver\.org/\fR, only changes
+in the host package's major version will break your plugin\. Thus, if you've
+worked with every 1\.x version of the host package, use \fB"^1\.0"\fP or \fB"1\.x"\fP
+to express this\. If you depend on features introduced in 1\.5\.2, use
+\fB"^1\.5\.2"\fP\|\.
.SS peerDependenciesMeta
.P
-When a user installs your package, npm will emit warnings if packages specified in \fBpeerDependencies\fP are not already installed\. The \fBpeerDependenciesMeta\fP field serves to provide npm more information on how your peer dependencies are to be used\. Specifically, it allows peer dependencies to be marked as optional\.
+When a user installs your package, npm will emit warnings if packages
+specified in \fBpeerDependencies\fP are not already installed\. The
+\fBpeerDependenciesMeta\fP field serves to provide npm more information on how
+your peer dependencies are to be used\. Specifically, it allows peer
+dependencies to be marked as optional\.
.P
For example:
.P
@@ -825,7 +889,10 @@ For example:
.fi
.RE
.P
-Marking a peer dependency as optional ensures npm will not emit a warning if the \fBsoy\-milk\fP package is not installed on the host\. This allows you to integrate and interact with a variety of host packages without requiring all of them to be installed\.
+Marking a peer dependency as optional ensures npm will not emit a warning
+if the \fBsoy\-milk\fP package is not installed on the host\. This allows you to
+integrate and interact with a variety of host packages without requiring
+all of them to be installed\.
.SS bundledDependencies
.P
This defines an array of package names that will be bundled when publishing
@@ -846,7 +913,8 @@ If we define a package\.json like this:
"name": "awesome\-web\-framework",
"version": "1\.0\.0",
"bundledDependencies": [
- "renderized", "super\-streams"
+ "renderized",
+ "super\-streams"
]
}
.fi
@@ -855,18 +923,18 @@ If we define a package\.json like this:
we can obtain \fBawesome\-web\-framework\-1\.0\.0\.tgz\fP file by running \fBnpm pack\fP\|\.
This file contains the dependencies \fBrenderized\fP and \fBsuper\-streams\fP which
can be installed in a new project by executing \fBnpm install
-awesome\-web\-framework\-1\.0\.0\.tgz\fP\|\. Note that the package names do not include
-any versions, as that information is specified in \fBdependencies\fP\|\.
+awesome\-web\-framework\-1\.0\.0\.tgz\fP\|\. Note that the package names do not
+include any versions, as that information is specified in \fBdependencies\fP\|\.
.P
If this is spelled \fB"bundleDependencies"\fP, then that is also honored\.
.SS optionalDependencies
.P
-If a dependency can be used, but you would like npm to proceed if it cannot be
-found or fails to install, then you may put it in the \fBoptionalDependencies\fP
-object\. This is a map of package name to version or url, just like the
-\fBdependencies\fP object\. The difference is that build failures do not cause
-installation to fail\. Running \fBnpm install \-\-no\-optional\fP will prevent these
-dependencies from being installed\.
+If a dependency can be used, but you would like npm to proceed if it cannot
+be found or fails to install, then you may put it in the
+\fBoptionalDependencies\fP object\. This is a map of package name to version or
+url, just like the \fBdependencies\fP object\. The difference is that build
+failures do not cause installation to fail\. Running \fBnpm install
+\-\-no\-optional\fP will prevent these dependencies from being installed\.
.P
It is still your program's responsibility to handle the lack of the
dependency\. For example, something like this:
@@ -899,34 +967,33 @@ You can specify the version of node that your stuff works on:
.P
.RS 2
.nf
-{ "engines" : { "node" : ">=0\.10\.3 <0\.12" } }
+{
+ "engines": {
+ "node": ">=0\.10\.3 <15"
+ }
+}
.fi
.RE
.P
And, like with dependencies, if you don't specify the version (or if you
specify "*" as the version), then any version of node will do\.
.P
-If you specify an "engines" field, then npm will require that "node" be
-somewhere on that list\. If "engines" is omitted, then npm will just assume
-that it works on node\.
-.P
-You can also use the "engines" field to specify which versions of npm
-are capable of properly installing your program\. For example:
+You can also use the "engines" field to specify which versions of npm are
+capable of properly installing your program\. For example:
.P
.RS 2
.nf
-{ "engines" : { "npm" : "~1\.0\.20" } }
+{
+ "engines": {
+ "npm": "~1\.0\.20"
+ }
+}
.fi
.RE
.P
-Unless the user has set the \fBengine\-strict\fP config flag, this
-field is advisory only and will only produce warnings when your package is installed as a dependency\.
-.SS engineStrict
-.P
-\fBThis feature was removed in npm 3\.0\.0\fR
-.P
-Prior to npm 3\.0\.0, this feature was used to treat this package as if the
-user had set \fBengine\-strict\fP\|\. It is no longer used\.
+Unless the user has set the \fBengine\-strict\fP config flag, this field is
+advisory only and will only produce warnings when your package is installed
+as a dependency\.
.SS os
.P
You can specify which operating systems your
@@ -934,16 +1001,25 @@ module will run on:
.P
.RS 2
.nf
-"os" : [ "darwin", "linux" ]
+{
+ "os": [
+ "darwin",
+ "linux"
+ ]
+}
.fi
.RE
.P
-You can also block instead of allowing operating systems,
-just prepend the blocked os with a '!':
+You can also block instead of allowing operating systems, just prepend the
+blocked os with a '!':
.P
.RS 2
.nf
-"os" : [ "!win32" ]
+{
+ "os": [
+ "!win32"
+ ]
+}
.fi
.RE
.P
@@ -958,7 +1034,12 @@ you can specify which ones\.
.P
.RS 2
.nf
-"cpu" : [ "x64", "ia32" ]
+{
+ "cpu": [
+ "x64",
+ "ia32"
+ ]
+}
.fi
.RE
.P
@@ -966,53 +1047,49 @@ Like the \fBos\fP option, you can also block architectures:
.P
.RS 2
.nf
-"cpu" : [ "!arm", "!mips" ]
+{
+ "cpu": [
+ "!arm",
+ "!mips"
+ ]
+}
.fi
.RE
.P
The host architecture is determined by \fBprocess\.arch\fP
-.SS preferGlobal
-.P
-\fBDEPRECATED\fR
-.P
-This option used to trigger an npm warning, but it will no longer warn\. It is
-purely there for informational purposes\. It is now recommended that you install
-any binaries as local devDependencies wherever possible\.
.SS private
.P
-If you set \fB"private": true\fP in your package\.json, then npm will refuse
-to publish it\.
+If you set \fB"private": true\fP in your package\.json, then npm will refuse to
+publish it\.
.P
-This is a way to prevent accidental publication of private repositories\. If
-you would like to ensure that a given package is only ever published to a
-specific registry (for example, an internal registry), then use the
-\fBpublishConfig\fP dictionary described below to override the \fBregistry\fP config
-param at publish\-time\.
+This is a way to prevent accidental publication of private repositories\.
+If you would like to ensure that a given package is only ever published to
+a specific registry (for example, an internal registry), then use the
+\fBpublishConfig\fP dictionary described below to override the \fBregistry\fP
+config param at publish\-time\.
.SS publishConfig
.P
This is a set of config values that will be used at publish\-time\. It's
especially handy if you want to set the tag, registry or access, so that
you can ensure that a given package is not tagged with "latest", published
-to the global public registry or that a scoped module is private by default\.
-.P
-Any config values can be overridden, but only "tag", "registry" and "access"
-probably matter for the purposes of publishing\.
+to the global public registry or that a scoped module is private by
+default\.
.P
-See npm help \fBconfig\fP to see the list of config options that can be
-overridden\.
+See npm help \fBconfig\fP to see the list of config options that
+can be overridden\.
.SS workspaces
.P
The optional \fBworkspaces\fP field is an array of file patterns that describes
-locations within the local file system that the install client should look up
-to find each npm help workspace that needs to be symlinked to
-the top level \fBnode_modules\fP folder\.
+locations within the local file system that the install client should look
+up to find each npm help workspace that needs to be
+symlinked to the top level \fBnode_modules\fP folder\.
.P
It can describe either the direct paths of the folders to be used as
workspaces or it can define globs that will resolve to these same folders\.
.P
-In the following example, all folders located inside the folder \fB\|\./packages\fP
-will be treated as workspaces as long as they have valid \fBpackage\.json\fP files
-inside them:
+In the following example, all folders located inside the folder
+\fB\|\./packages\fP will be treated as workspaces as long as they have valid
+\fBpackage\.json\fP files inside them:
.P
.RS 2
.nf
@@ -1032,18 +1109,18 @@ npm will default some values based on package contents\.
.RS 0
.IP \(bu 2
\fB"scripts": {"start": "node server\.js"}\fP
-If there is a \fBserver\.js\fP file in the root of your package, then npm
-will default the \fBstart\fP command to \fBnode server\.js\fP\|\.
+If there is a \fBserver\.js\fP file in the root of your package, then npm will
+default the \fBstart\fP command to \fBnode server\.js\fP\|\.
.IP \(bu 2
\fB"scripts":{"install": "node\-gyp rebuild"}\fP
-If there is a \fBbinding\.gyp\fP file in the root of your package and you have not defined an \fBinstall\fP or \fBpreinstall\fP script, npm will
-default the \fBinstall\fP command to compile using node\-gyp\.
+If there is a \fBbinding\.gyp\fP file in the root of your package and you have
+not defined an \fBinstall\fP or \fBpreinstall\fP script, npm will default the
+\fBinstall\fP command to compile using node\-gyp\.
.IP \(bu 2
\fB"contributors": [\.\.\.]\fP
-If there is an \fBAUTHORS\fP file in the root of your package, npm will
-treat each line as a \fBName (url)\fP format, where email and url
-are optional\. Lines which start with a \fB#\fP or are blank, will be
-ignored\.
+If there is an \fBAUTHORS\fP file in the root of your package, npm will treat
+each line as a \fBName (url)\fP format, where email and url are
+optional\. Lines which start with a \fB#\fP or are blank, will be ignored\.
.RE
.SS SEE ALSO
diff --git a/deps/npm/man/man5/package-lock-json.5 b/deps/npm/man/man5/package-lock-json.5
index 4c69eefe99ef0a..453c0105cb0bad 100644
--- a/deps/npm/man/man5/package-lock-json.5
+++ b/deps/npm/man/man5/package-lock-json.5
@@ -12,138 +12,243 @@ This file is intended to be committed into source repositories, and serves
various purposes:
.RS 0
.IP \(bu 2
-Describe a single representation of a dependency tree such that teammates, deployments, and continuous integration are guaranteed to install exactly the same dependencies\.
+Describe a single representation of a dependency tree such that
+teammates, deployments, and continuous integration are guaranteed to
+install exactly the same dependencies\.
.IP \(bu 2
-Provide a facility for users to "time\-travel" to previous states of \fBnode_modules\fP without having to commit the directory itself\.
+Provide a facility for users to "time\-travel" to previous states of
+\fBnode_modules\fP without having to commit the directory itself\.
.IP \(bu 2
-To facilitate greater visibility of tree changes through readable source control diffs\.
+Facilitate greater visibility of tree changes through readable source
+control diffs\.
.IP \(bu 2
-And optimize the installation process by allowing npm to skip repeated metadata resolutions for previously\-installed packages\.
+Optimize the installation process by allowing npm to skip repeated
+metadata resolutions for previously\-installed packages\.
+.IP \(bu 2
+As of npm v7, lockfiles include enough information to gain a complete
+picture of the package tree, reducing the need to read \fBpackage\.json\fP
+files, and allowing for significant performance improvements\.
.RE
+.SS \fBpackage\-lock\.json\fP vs \fBnpm\-shrinkwrap\.json\fP
.P
-One key detail about \fBpackage\-lock\.json\fP is that it cannot be published, and it
-will be ignored if found in any place other than the toplevel package\. It shares
-a format with npm help npm\-shrinkwrap\.json, which is essentially the same file, but
-allows publication\. This is not recommended unless deploying a CLI tool or
-otherwise using the publication process for producing production packages\.
+Both of these files have the same format, and perform similar functions in
+the root of a project\.
.P
-If both \fBpackage\-lock\.json\fP and \fBnpm\-shrinkwrap\.json\fP are present in the root of
-a package, \fBpackage\-lock\.json\fP will be completely ignored\.
-.SS File Format
-.SS name
-.P
-The name of the package this is a package\-lock for\. This must match what's in
-\fBpackage\.json\fP\|\.
-.SS version
-.P
-The version of the package this is a package\-lock for\. This must match what's in
-\fBpackage\.json\fP\|\.
-.SS lockfileVersion
-.P
-An integer version, starting at \fB1\fP with the version number of this document
-whose semantics were used when generating this \fBpackage\-lock\.json\fP\|\.
-.SS packageIntegrity
-.P
-This is a subresource
-integrity \fIhttps://w3c\.github\.io/webappsec/specs/subresourceintegrity/\fR value
-created from the \fBpackage\.json\fP\|\. No preprocessing of the \fBpackage\.json\fP should
-be done\. Subresource integrity strings can be produced by modules like
-\fBssri\fP \fIhttps://www\.npmjs\.com/package/ssri\fR\|\.
-.SS preserveSymlinks
-.P
-Indicates that the install was done with the environment variable
-\fBNODE_PRESERVE_SYMLINKS\fP enabled\. The installer should insist that the value of
-this property match that environment variable\.
-.SS dependencies
+The difference is that \fBpackage\-lock\.json\fP is that it cannot be published,
+and it will be ignored if found in any place other than the root project\.
.P
-A mapping of package name to dependency object\. Dependency objects have the
-following properties:
-.SS version
+In contrast, npm help npm\-shrinkwrap\.json allows
+publication, and defines the dependency tree from the point encountered\.
+This is not recommended unless deploying a CLI tool or otherwise using the
+publication process for producing production packages\.
.P
-This is a specifier that uniquely identifies this package and should be
-usable in fetching a new copy of it\.
+If both \fBpackage\-lock\.json\fP and \fBnpm\-shrinkwrap\.json\fP are present in the
+root of a project, \fBnpm\-shrinkwrap\.json\fP will take precedence and
+\fBpackage\-lock\.json\fP will be ignored\.
+.SS Hidden Lockfiles
+.P
+In order to avoid processing the \fBnode_modules\fP folder repeatedly, npm as
+of v7 uses a "hidden" lockfile present in
+\fBnode_modules/\.package\-lock\.json\fP\|\. This contains information about the
+tree, and is used in lieu of reading the entire \fBnode_modules\fP hierarchy
+provided that the following conditions are met:
.RS 0
.IP \(bu 2
-bundled dependencies: Regardless of source, this is a version number that is purely for informational purposes\.
+All package folders it references exist in the \fBnode_modules\fP hierarchy\.
.IP \(bu 2
-registry sources: This is a version number\. (eg, \fB1\.2\.3\fP)
+No package folders exist in the \fBnode_modules\fP hierarchy that are not
+listed in the lockfile\.
+.IP \(bu 2
+The modified time of the file is at least as recent as all of the package
+folders it references\.
+
+.RE
+.P
+That is, the hidden lockfile will only be relevant if it was created as
+part of the most recent update to the package tree\. If another CLI mutates
+the tree in any way, this will be detected, and the hidden lockfile will be
+ignored\.
+.P
+Note that it \fIis\fR possible to manually change the \fIcontents\fR of a package
+in such a way that the modified time of the package folder is unaffected\.
+For example, if you add a file to \fBnode_modules/foo/lib/bar\.js\fP, then the
+modified time on \fBnode_modules/foo\fP will not reflect this change\. If you
+are manually editing files in \fBnode_modules\fP, it is generally best to
+delete the file at \fBnode_modules/\.package\-lock\.json\fP\|\.
+.P
+As the hidden lockfile is ignored by older npm versions, it does not
+contain the backwards compatibility affordances present in "normal"
+lockfiles\. That is, it is \fBlockfileVersion: 3\fP, rather than
+\fBlockfileVersion: 2\fP\|\.
+.SS Handling Old Lockfiles
+.P
+When npm detects a lockfile from npm v6 or before during the package
+installation process, it is automatically updated to fetch missing
+information from either the \fBnode_modules\fP tree or (in the case of empty
+\fBnode_modules\fP trees or very old lockfile formats) the npm registry\.
+.SS File Format
+.SS \fBname\fP
+.P
+The name of the package this is a package\-lock for\. This will match what's
+in \fBpackage\.json\fP\|\.
+.SS \fBversion\fP
+.P
+The version of the package this is a package\-lock for\. This will match
+what's in \fBpackage\.json\fP\|\.
+.SS \fBlockfileVersion\fP
+.P
+An integer version, starting at \fB1\fP with the version number of this
+document whose semantics were used when generating this
+\fBpackage\-lock\.json\fP\|\.
+.P
+Note that the file format changed significantly in npm v7 to track
+information that would have otherwise required looking in \fBnode_modules\fP or
+the npm registry\. Lockfiles generated by npm v7 will contain
+\fBlockfileVersion: 2\fP\|\.
+.RS 0
.IP \(bu 2
-git sources: This is a git specifier with resolved committish\. (eg, \fBgit+https://example\.com/foo/bar#115311855adb0789a0466714ed48a1499ffea97e\fP)
+No version provided: an "ancient" shrinkwrap file from a version of npm
+prior to npm v5\.
.IP \(bu 2
-http tarball sources: This is the URL of the tarball\. (eg, \fBhttps://example\.com/example\-1\.3\.0\.tgz\fP)
+\fB1\fP: The lockfile version used by npm v5 and v6\.
.IP \(bu 2
-local tarball sources: This is the file URL of the tarball\. (eg \fBfile:///opt/storage/example\-1\.3\.0\.tgz\fP)
+\fB2\fP: The lockfile version used by npm v7, which is backwards compatible
+to v1 lockfiles\.
.IP \(bu 2
-local link sources: This is the file URL of the link\. (eg \fBfile:libs/our\-module\fP)
+\fB3\fP: The lockfile version used by npm v7, \fIwithout\fR backwards
+compatibility affordances\. This is used for the hidden lockfile at
+\fBnode_modules/\.package\-lock\.json\fP, and will likely be used in a future
+version of npm, once support for npm v6 is no longer relevant\.
.RE
-.SS integrity
.P
-This is a Standard Subresource
-Integrity \fIhttps://w3c\.github\.io/webappsec/specs/subresourceintegrity/\fR for this
-resource\.
+npm will always attempt to get whatever data it can out of a lockfile, even
+if it is not a version that it was designed to support\.
+.SS \fBpackages\fP
+.P
+This is an object that maps package locations to an object containing the
+information about that package\.
+.P
+The root project is typically listed with a key of \fB""\fP, and all other
+packages are listed with their relative paths from the root project folder\.
+.P
+Package descriptors have the following fields:
.RS 0
.IP \(bu 2
-For bundled dependencies this is not included, regardless of source\.
+version: The version found in \fBpackage\.json\fP
+.IP \(bu 2
+resolved: The place where the package was actually resolved from\. In
+the case of packages fetched from the registry, this will be a url to a
+tarball\. In the case of git dependencies, this will be the full git url
+with commit sha\. In the case of link dependencies, this will be the
+location of the link target\.
+.IP \(bu 2
+integrity: A \fBsha512\fP or \fBsha1\fP Standard Subresource
+Integrity \fIhttps://w3c\.github\.io/webappsec/specs/subresourceintegrity/\fR
+string for the artifact that was unpacked in this location\.
+.IP \(bu 2
+link: A flag to indicate that this is a symbolic link\. If this is
+present, no other fields are specified, since the link target will also
+be included in the lockfile\.
.IP \(bu 2
-For registry sources, this is the \fBintegrity\fP that the registry provided, or if one wasn't provided the SHA1 in \fBshasum\fP\|\.
+dev, optional, devOptional: If the package is strictly part of the
+\fBdevDependencies\fP tree, then \fBdev\fP will be true\. If it is strictly part
+of the \fBoptionalDependencies\fP tree, then \fBoptional\fP will be set\. If it
+is both a \fBdev\fP dependency \fIand\fR an \fBoptional\fP dependency of a non\-dev
+dependency, then \fBdevOptional\fP will be set\. (An \fBoptional\fP dependency of
+a \fBdev\fP dependency will have both \fBdev\fP and \fBoptional\fP set\.)
.IP \(bu 2
-For git sources this is the specific commit hash we cloned from\.
+inBundle: A flag to indicate that the package is a bundled dependency\.
.IP \(bu 2
-For remote tarball sources this is an integrity based on a SHA512 of
-the file\.
+hasInstallScript: A flag to indicate that the package has a \fBpreinstall\fP,
+\fBinstall\fP, or \fBpostinstall\fP script\.
.IP \(bu 2
-For local tarball sources: This is an integrity field based on the SHA512 of the file\.
+hasShrinkwrap: A flag to indicate that the package has an
+\fBnpm\-shrinkwrap\.json\fP file\.
+.IP \(bu 2
+bin, license, engines, dependencies, optionalDependencies: fields from
+\fBpackage\.json\fP
.RE
-.SS resolved
+.SS dependencies
+.P
+Legacy data for supporting versions of npm that use \fBlockfileVersion: 1\fP\|\.
+This is a mapping of package names to dependency objects\. Because the
+object structure is strictly hierarchical, symbolic link dependencies are
+somewhat challenging to represent in some cases\.
+.P
+npm v7 ignores this section entirely if a \fBpackages\fP section is present,
+but does keep it up to date in order to support switching between npm v6
+and npm v7\.
+.P
+Dependency objects have the following fields:
.RS 0
.IP \(bu 2
-For bundled dependencies this is not included, regardless of source\.
+version: a specifier that varies depending on the nature of the package,
+and is usable in fetching a new copy of it\.
+.RS
+.IP \(bu 2
+bundled dependencies: Regardless of source, this is a version number
+that is purely for informational purposes\.
.IP \(bu 2
-For registry sources this is path of the tarball relative to the registry
-URL\. If the tarball URL isn't on the same server as the registry URL then
-this is a complete URL\.
+registry sources: This is a version number\. (eg, \fB1\.2\.3\fP)
+.IP \(bu 2
+git sources: This is a git specifier with resolved committish\. (eg,
+\fBgit+https://example\.com/foo/bar#115311855adb0789a0466714ed48a1499ffea97e\fP)
+.IP \(bu 2
+http tarball sources: This is the URL of the tarball\. (eg,
+\fBhttps://example\.com/example\-1\.3\.0\.tgz\fP)
+.IP \(bu 2
+local tarball sources: This is the file URL of the tarball\. (eg
+\fBfile:///opt/storage/example\-1\.3\.0\.tgz\fP)
+.IP \(bu 2
+local link sources: This is the file URL of the link\. (eg
+\fBfile:libs/our\-module\fP)
+
+.RE
+.IP \(bu 2
+integrity: A \fBsha512\fP or \fBsha1\fP Standard Subresource
+Integrity \fIhttps://w3c\.github\.io/webappsec/specs/subresourceintegrity/\fR
+string for the artifact that was unpacked in this location\. For git
+dependencies, this is the commit sha\.
+.IP \(bu 2
+resolved: For registry sources this is path of the tarball relative to
+the registry URL\. If the tarball URL isn't on the same server as the
+registry URL then this is a complete URL\.
+.IP \(bu 2
+bundled: If true, this is the bundled dependency and will be installed
+by the parent module\. When installing, this module will be extracted
+from the parent module during the extract phase, not installed as a
+separate dependency\.
+.IP \(bu 2
+dev: If true then this dependency is either a development dependency ONLY
+of the top level module or a transitive dependency of one\. This is false
+for dependencies that are both a development dependency of the top level
+and a transitive dependency of a non\-development dependency of the top
+level\.
+.IP \(bu 2
+optional: If true then this dependency is either an optional dependency
+ONLY of the top level module or a transitive dependency of one\. This is
+false for dependencies that are both an optional dependency of the top
+level and a transitive dependency of a non\-optional dependency of the top
+level\.
+.IP \(bu 2
+requires: This is a mapping of module name to version\. This is a list of
+everything this module requires, regardless of where it will be
+installed\. The version should match via normal matching rules a
+dependency either in our \fBdependencies\fP or in a level higher than us\.
+.IP \(bu 2
+dependencies: The dependencies of this dependency, exactly as at the top
+level\.
.RE
-.SS bundled
-.P
-If true, this is the bundled dependency and will be installed by the parent
-module\. When installing, this module will be extracted from the parent
-module during the extract phase, not installed as a separate dependency\.
-.SS dev
-.P
-If true then this dependency is either a development dependency ONLY of the
-top level module or a transitive dependency of one\. This is false for
-dependencies that are both a development dependency of the top level and a
-transitive dependency of a non\-development dependency of the top level\.
-.SS optional
-.P
-If true then this dependency is either an optional dependency ONLY of the
-top level module or a transitive dependency of one\. This is false for
-dependencies that are both an optional dependency of the top level and a
-transitive dependency of a non\-optional dependency of the top level\.
-.P
-All optional dependencies should be included even if they're uninstallable
-on the current platform\.
-.SS requires
-.P
-This is a mapping of module name to version\. This is a list of everything
-this module requires, regardless of where it will be installed\. The version
-should match via normal matching rules a dependency either in our
-\fBdependencies\fP or in a level higher than us\.
-.SS dependencies
-.P
-The dependencies of this dependency, exactly as at the top level\.
.SS See also
.RS 0
.IP \(bu 2
npm help shrinkwrap
.IP \(bu 2
-npm help shrinkwrap\.json
-.IP \(bu 2
-npm help package\-locks
+npm help npm\-shrinkwrap\.json
.IP \(bu 2
npm help package\.json
.IP \(bu 2
diff --git a/deps/npm/man/man5/package-locks.5 b/deps/npm/man/man5/package-locks.5
deleted file mode 100644
index c71959c743fa77..00000000000000
--- a/deps/npm/man/man5/package-locks.5
+++ /dev/null
@@ -1,200 +0,0 @@
-.TH "PACKAGE\-LOCKS" "5" "January 2021" "" ""
-.SH "NAME"
-\fBpackage-locks\fR \- An explanation of npm lockfiles
-.SS Description
-.P
-Conceptually, the "input" to npm help \fBinstall\fP is a npm help package\.json, while its
-"output" is a fully\-formed \fBnode_modules\fP tree: a representation of the
-dependencies you declared\. In an ideal world, npm would work like a pure
-function: the same \fBpackage\.json\fP should produce the exact same \fBnode_modules\fP
-tree, any time\. In some cases, this is indeed true\. But in many others, npm is
-unable to do this\. There are multiple reasons for this:
-.RS 0
-.IP \(bu 2
-different versions of npm (or other package managers) may have been used to install a package, each using slightly different installation algorithms\.
-.IP \(bu 2
-a new version of a direct semver\-range package may have been published since the last time your packages were installed, and thus a newer version will be used\.
-.IP \(bu 2
-A dependency of one of your dependencies may have published a new version, which will update even if you used pinned dependency specifiers (\fB1\.2\.3\fP instead of \fB^1\.2\.3\fP)
-.IP \(bu 2
-The registry you installed from is no longer available, or allows mutation of versions (unlike the primary npm registry), and a different version of a package exists under the same version number now\.
-
-.RE
-.P
-As an example, consider package A:
-.P
-.RS 2
-.nf
-{
- "name": "A",
- "version": "0\.1\.0",
- "dependencies": {
- "B": "<0\.1\.0"
- }
-}
-.fi
-.RE
-.P
-package B:
-.P
-.RS 2
-.nf
-{
- "name": "B",
- "version": "0\.0\.1",
- "dependencies": {
- "C": "<0\.1\.0"
- }
-}
-.fi
-.RE
-.P
-and package C:
-.P
-.RS 2
-.nf
-{
- "name": "C",
- "version": "0\.0\.1"
-}
-.fi
-.RE
-.P
-If these are the only versions of A, B, and C available in the
-registry, then a normal \fBnpm install A\fP will install:
-.P
-.RS 2
-.nf
-A@0\.1\.0
-`\-\- B@0\.0\.1
- `\-\- C@0\.0\.1
-.fi
-.RE
-.P
-However, if B@0\.0\.2 is published, then a fresh \fBnpm install A\fP will
-install:
-.P
-.RS 2
-.nf
-A@0\.1\.0
-`\-\- B@0\.0\.2
- `\-\- C@0\.0\.1
-.fi
-.RE
-.P
-assuming the new version did not modify B's dependencies\. Of course,
-the new version of B could include a new version of C and any number
-of new dependencies\. If such changes are undesirable, the author of A
-could specify a dependency on B@0\.0\.1\|\. However, if A's author and B's
-author are not the same person, there's no way for A's author to say
-that he or she does not want to pull in newly published versions of C
-when B hasn't changed at all\.
-.P
-To prevent this potential issue, npm uses npm help package\-lock\.json or, if present, npm help npm\-shrinkwrap\.json\. These files are called package locks, or lockfiles\.
-.P
-Whenever you run \fBnpm install\fP, npm generates or updates your package lock,
-which will look something like this:
-.P
-.RS 2
-.nf
-{
- "name": "A",
- "version": "0\.1\.0",
- \.\.\.metadata fields\.\.\.
- "dependencies": {
- "B": {
- "version": "0\.0\.1",
- "resolved": "https://registry\.npmjs\.org/B/\-/B\-0\.0\.1\.tgz",
- "integrity": "sha512\-DeAdb33F+"
- "dependencies": {
- "C": {
- "version": "git://github\.com/org/C\.git#5c380ae319fc4efe9e7f2d9c78b0faa588fd99b4"
- }
- }
- }
- }
-}
-.fi
-.RE
-.P
-This file describes an \fIexact\fR, and more importantly \fIreproducible\fR
-\fBnode_modules\fP tree\. Once it's present, any future installation will base its
-work off this file, instead of recalculating dependency versions off
-npm help package\.json\.
-.P
-The presence of a package lock changes the installation behavior such that:
-.RS 0
-.IP 1. 3
-The module tree described by the package lock is reproduced\. This means
-reproducing the structure described in the file, using the specific files
-referenced in "resolved" if available, falling back to normal package resolution
-using "version" if one isn't\.
-.IP 2. 3
-The tree is walked and any missing dependencies are installed in the usual
-fashion\.
-
-.RE
-.P
-If \fBpreshrinkwrap\fP, \fBshrinkwrap\fP or \fBpostshrinkwrap\fP are in the \fBscripts\fP
-property of the \fBpackage\.json\fP, they will be executed in order\. \fBpreshrinkwrap\fP
-and \fBshrinkwrap\fP are executed before the shrinkwrap, \fBpostshrinkwrap\fP is
-executed afterwards\. These scripts run for both \fBpackage\-lock\.json\fP and
-\fBnpm\-shrinkwrap\.json\fP\|\. For example to run some postprocessing on the generated
-file:
-.P
-.RS 2
-.nf
- "scripts": {
- "postshrinkwrap": "json \-I \-e \\"this\.myMetadata = $MY_APP_METADATA\\""
- }
-.fi
-.RE
-.SS Using locked packages
-.P
-Using a locked package is no different than using any package without a package
-lock: any commands that update \fBnode_modules\fP and/or \fBpackage\.json\fP\|'s
-dependencies will automatically sync the existing lockfile\. This includes \fBnpm
-install\fP, \fBnpm rm\fP, \fBnpm update\fP, etc\. To prevent this update from happening,
-you can use the \fB\-\-no\-save\fP option to prevent saving altogether, or
-\fB\-\-no\-shrinkwrap\fP to allow \fBpackage\.json\fP to be updated while leaving
-\fBpackage\-lock\.json\fP or \fBnpm\-shrinkwrap\.json\fP intact\.
-.P
-It is highly recommended you commit the generated package lock to source
-control: this will allow anyone else on your team, your deployments, your
-CI/continuous integration, and anyone else who runs \fBnpm install\fP in your
-package source to get the exact same dependency tree that you were developing
-on\. Additionally, the diffs from these changes are human\-readable and will
-inform you of any changes npm has made to your \fBnode_modules\fP, so you can notice
-if any transitive dependencies were updated, hoisted, etc\.
-.SS Resolving lockfile conflicts
-.P
-Occasionally, two separate npm install will create package locks that cause
-merge conflicts in source control systems\. As of \fBnpm@5\.7\.0\fP, these conflicts
-can be resolved by manually fixing any \fBpackage\.json\fP conflicts, and then
-running \fBnpm install [\-\-package\-lock\-only]\fP again\. npm will automatically
-resolve any conflicts for you and write a merged package lock that includes all
-the dependencies from both branches in a reasonable tree\. If
-\fB\-\-package\-lock\-only\fP is provided, it will do this without also modifying your
-local \fBnode_modules/\fP\|\.
-.P
-To make this process seamless on git, consider installing
-\fBnpm\-merge\-driver\fP \fIhttps://npm\.im/npm\-merge\-driver\fR, which will teach git how
-to do this itself without any user interaction\. In short: \fB$ npx
-npm\-merge\-driver install \-g\fP will let you do this, and even works with
-pre\-\fBnpm@5\.7\.0\fP versions of npm 5, albeit a bit more noisily\. Note that if
-\fBpackage\.json\fP itself conflicts, you will have to resolve that by hand and run
-\fBnpm install\fP manually, even with the merge driver\.
-.SS See Also
-.RS 0
-.IP \(bu 2
-https://medium\.com/@sdboyer/so\-you\-want\-to\-write\-a\-package\-manager\-4ae9c17d9527
-.IP \(bu 2
-npm help package\.json
-.IP \(bu 2
-npm help package\-lock\.json
-.IP \(bu 2
-npm help shrinkwrap\.json
-.IP \(bu 2
-npm help shrinkwrap
-
-.RE
diff --git a/deps/npm/node_modules/@npmcli/arborist/lib/arborist/index.js b/deps/npm/node_modules/@npmcli/arborist/lib/arborist/index.js
index 4c7e96da4ecf39..6c46656eb92923 100644
--- a/deps/npm/node_modules/@npmcli/arborist/lib/arborist/index.js
+++ b/deps/npm/node_modules/@npmcli/arborist/lib/arborist/index.js
@@ -53,6 +53,7 @@ class Arborist extends Base {
...options,
path: options.path || '.',
cache: options.cache || `${homedir()}/.npm/_cacache`,
+ packumentCache: new Map(),
}
this.cache = resolve(this.options.cache)
this.path = resolve(this.options.path)
diff --git a/deps/npm/node_modules/@npmcli/arborist/lib/arborist/load-actual.js b/deps/npm/node_modules/@npmcli/arborist/lib/arborist/load-actual.js
index abf39e5dc1757e..49e76e265b816e 100644
--- a/deps/npm/node_modules/@npmcli/arborist/lib/arborist/load-actual.js
+++ b/deps/npm/node_modules/@npmcli/arborist/lib/arborist/load-actual.js
@@ -111,7 +111,7 @@ module.exports = cls => class ActualLoader extends cls {
pkg: {},
global,
})
- return this[_loadActualActually]({root, ignoreMissing})
+ return this[_loadActualActually]({root, ignoreMissing, global})
}
// not in global mode, hidden lockfile is allowed, load root pkg too
@@ -154,7 +154,7 @@ module.exports = cls => class ActualLoader extends cls {
return this[_actualTree]
}
- async [_loadActualActually] ({ root, ignoreMissing }) {
+ async [_loadActualActually] ({ root, ignoreMissing, global }) {
await this[_loadFSTree](this[_actualTree])
if (!ignoreMissing)
await this[_findMissingEdges]()
@@ -162,6 +162,17 @@ module.exports = cls => class ActualLoader extends cls {
this[_transplant](root)
await this[_loadWorkspaces](this[_actualTree])
+ if (global) {
+ // need to depend on the children, or else all of them
+ // will end up being flagged as extraneous, since the
+ // global root isn't a "real" project
+ const tree = this[_actualTree]
+ const actualRoot = tree.isLink ? tree.target : tree
+ const { dependencies = {} } = actualRoot.package
+ for (const name of actualRoot.children.keys())
+ dependencies[name] = dependencies[name] || '*'
+ actualRoot.package = { ...actualRoot.package, dependencies }
+ }
// only reset root flags if we're not re-rooting, otherwise leave as-is
calcDepFlags(this[_actualTree], !root)
return this[_actualTree]
diff --git a/deps/npm/node_modules/@npmcli/arborist/lib/arborist/reify.js b/deps/npm/node_modules/@npmcli/arborist/lib/arborist/reify.js
index 661d879eb19e64..d916b49c22c018 100644
--- a/deps/npm/node_modules/@npmcli/arborist/lib/arborist/reify.js
+++ b/deps/npm/node_modules/@npmcli/arborist/lib/arborist/reify.js
@@ -136,7 +136,7 @@ module.exports = cls => class Reifier extends cls {
async [_validatePath] () {
// don't create missing dirs on dry runs
- if (this[_packageLockOnly] || this[_dryRun] || this[_global])
+ if (this[_packageLockOnly] || this[_dryRun])
return
await mkdirp(resolve(this.path))
@@ -830,9 +830,14 @@ module.exports = cls => class Reifier extends cls {
const pname = child.package.name
const alias = name !== pname
updateDepSpec(pkg, name, (alias ? `npm:${pname}@` : '') + range)
- } else if (req.hosted)
- updateDepSpec(pkg, name, req.hosted.shortcut({ noCommittish: false }))
- else
+ } else if (req.hosted) {
+ // save the git+https url if it has auth, otherwise shortcut
+ const h = req.hosted
+ const opt = { noCommittish: false }
+ const save = h.https && h.auth ? `git+${h.https(opt)}`
+ : h.shortcut(opt)
+ updateDepSpec(pkg, name, save)
+ } else
updateDepSpec(pkg, name, req.saveSpec)
}
diff --git a/deps/npm/node_modules/@npmcli/arborist/lib/consistent-resolve.js b/deps/npm/node_modules/@npmcli/arborist/lib/consistent-resolve.js
index 5d648de5bd87b4..32276482419017 100644
--- a/deps/npm/node_modules/@npmcli/arborist/lib/consistent-resolve.js
+++ b/deps/npm/node_modules/@npmcli/arborist/lib/consistent-resolve.js
@@ -9,6 +9,7 @@ const consistentResolve = (resolved, fromPath, toPath, relPaths = false) => {
return null
try {
+ const hostedOpt = { noCommittish: false }
const {
fetchSpec,
saveSpec,
@@ -20,7 +21,9 @@ const consistentResolve = (resolved, fromPath, toPath, relPaths = false) => {
const isPath = type === 'file' || type === 'directory'
return isPath && !relPaths ? `file:${fetchSpec}`
: isPath ? 'file:' + (toPath ? relpath(toPath, fetchSpec) : fetchSpec)
- : hosted ? 'git+' + hosted.sshurl({ noCommittish: false })
+ : hosted ? `git+${
+ hosted.auth ? hosted.https(hostedOpt) : hosted.sshurl(hostedOpt)
+ }`
: type === 'git' ? saveSpec
// always return something. 'foo' is interpreted as 'foo@' otherwise.
: rawSpec === '' && raw.slice(-1) !== '@' ? raw
diff --git a/deps/npm/node_modules/@npmcli/arborist/lib/diff.js b/deps/npm/node_modules/@npmcli/arborist/lib/diff.js
index 1864a3ea10b676..ada67f8161d308 100644
--- a/deps/npm/node_modules/@npmcli/arborist/lib/diff.js
+++ b/deps/npm/node_modules/@npmcli/arborist/lib/diff.js
@@ -72,6 +72,11 @@ const allChildren = node => {
if (!node)
return new Map()
+ // if the node is a global root, and also a link, then what we really
+ // want is to traverse the target's children
+ if (node.global && node.isRoot && node.isLink)
+ return allChildren(node.target)
+
const kids = new Map()
for (const n of [node, ...node.fsChildren]) {
for (const kid of n.children.values())
diff --git a/deps/npm/node_modules/@npmcli/arborist/lib/edge.js b/deps/npm/node_modules/@npmcli/arborist/lib/edge.js
index 0e30f463363700..c5f00faff2999f 100644
--- a/deps/npm/node_modules/@npmcli/arborist/lib/edge.js
+++ b/deps/npm/node_modules/@npmcli/arborist/lib/edge.js
@@ -1,6 +1,7 @@
// An edge in the dependency graph
// Represents a dependency relationship of some kind
+const util = require('util')
const npa = require('npm-package-arg')
const depValid = require('./dep-valid.js')
const _from = Symbol('_from')
@@ -24,6 +25,21 @@ const types = new Set([
'workspace',
])
+class ArboristEdge {}
+const printableEdge = (edge) => {
+ const edgeFrom = edge.from && edge.from.location
+ const edgeTo = edge.to && edge.to.location
+
+ return Object.assign(new ArboristEdge(), {
+ name: edge.name,
+ spec: edge.spec,
+ type: edge.type,
+ ...(edgeFrom != null ? { from: edgeFrom } : {}),
+ ...(edgeTo ? { to: edgeTo } : {}),
+ ...(edge.error ? { error: edge.error } : {}),
+ })
+}
+
class Edge {
constructor (options) {
const { type, name, spec, accept, from } = options
@@ -185,6 +201,14 @@ class Edge {
get to () {
return this[_to]
}
+
+ toJSON () {
+ return printableEdge(this)
+ }
+
+ [util.inspect.custom] () {
+ return this.toJSON()
+ }
}
Edge.types = [...types]
diff --git a/deps/npm/node_modules/@npmcli/arborist/lib/index.js b/deps/npm/node_modules/@npmcli/arborist/lib/index.js
index 830a88a5f953ba..fd7d8817258ed6 100644
--- a/deps/npm/node_modules/@npmcli/arborist/lib/index.js
+++ b/deps/npm/node_modules/@npmcli/arborist/lib/index.js
@@ -2,5 +2,6 @@ module.exports = require('./arborist/index.js')
module.exports.Arborist = module.exports
module.exports.Node = require('./node.js')
module.exports.Link = require('./link.js')
+module.exports.Edge = require('./edge.js')
// XXX export the other classes, too. shrinkwrap, diff, etc.
// they're handy!
diff --git a/deps/npm/node_modules/@npmcli/arborist/lib/node.js b/deps/npm/node_modules/@npmcli/arborist/lib/node.js
index 6e243c049d2730..396bcb58a2de96 100644
--- a/deps/npm/node_modules/@npmcli/arborist/lib/node.js
+++ b/deps/npm/node_modules/@npmcli/arborist/lib/node.js
@@ -40,6 +40,7 @@ const treeCheck = require('./tree-check.js')
const walkUp = require('walk-up-path')
const {resolve, relative, dirname, basename} = require('path')
+const util = require('util')
const _package = Symbol('_package')
const _parent = Symbol('_parent')
const _target = Symbol.for('_target')
@@ -63,6 +64,71 @@ const _meta = Symbol('_meta')
const relpath = require('./relpath.js')
const consistentResolve = require('./consistent-resolve.js')
+// helper function to output a clearer visualization
+// of the current node and its descendents
+class ArboristNode {}
+
+const printableTree = (tree, path = []) =>
+ (path.includes(tree) ? { location: tree.location } : (path.push(tree), Object.assign(new ArboristNode(), {
+ name: tree.name,
+ ...(tree.package && tree.package.version
+ ? { version: tree.package.version }
+ : {}),
+ location: tree.location,
+ path: tree.path,
+ realpath: tree.realpath,
+ ...(tree.isLink ? { target: printableTree(tree.target, path) } : {}),
+ ...(tree.resolved != null ? { resolved: tree.resolved } : {}),
+ ...(tree.extraneous ? { extraneous: true } : {
+ ...(tree.dev ? { dev: true } : {}),
+ ...(tree.optional ? { optional: true } : {}),
+ ...(tree.devOptional && !tree.dev && !tree.optional
+ ? { devOptional: true } : {}),
+ ...(tree.peer ? { peer: true } : {}),
+ }),
+ ...(tree.inBundle ? { bundled: true } : {}),
+ // handle top-level tree error
+ ...(tree.error
+ ? {
+ error: {
+ code: tree.error.code,
+ ...(tree.error.path
+ ? { path: tree.error.path }
+ : {}),
+ },
+ } : {}),
+ // handle errors for each node
+ ...(tree.errors && tree.errors.length
+ ? {
+ errors: tree.errors.map(error => ({
+ code: error.code,
+ ...(error.path
+ ? { path: error.path }
+ : {}),
+ })),
+ } : {}),
+ ...(tree.edgesIn && tree.edgesIn.size ? {
+ edgesIn: new Set([...tree.edgesIn]
+ .sort((a, b) => a.from.location.localeCompare(b.from.location))),
+ } : {}),
+ ...(tree.edgesOut && tree.edgesOut.size ? {
+ edgesOut: new Map([...tree.edgesOut.entries()]
+ .sort((a, b) => a[0].localeCompare(b[0]))),
+ } : {}),
+ ...(tree.fsChildren && tree.fsChildren.size ? {
+ fsChildren: new Set([...tree.fsChildren]
+ .sort((a, b) => a.path.localeCompare(b.path))
+ .map(tree => printableTree(tree, path))),
+ } : {}),
+ ...(tree.target || !tree.children || !tree.children.size
+ ? {}
+ : {
+ children: new Map([...tree.children.entries()]
+ .sort((a, b) => a[0].localeCompare(b[0]))
+ .map(([name, tree]) => [name, printableTree(tree, path)])),
+ }),
+ })))
+
class Node {
constructor (options) {
// NB: path can be null if it's a link target
@@ -1145,6 +1211,14 @@ class Node {
const base = scoped ? `${basename(d)}/${basename(rp)}` : basename(rp)
return base === name && basename(nm) === 'node_modules' ? dir : false
}
+
+ toJSON () {
+ return printableTree(this)
+ }
+
+ [util.inspect.custom] () {
+ return this.toJSON()
+ }
}
module.exports = Node
diff --git a/deps/npm/node_modules/@npmcli/arborist/lib/shrinkwrap.js b/deps/npm/node_modules/@npmcli/arborist/lib/shrinkwrap.js
index a454320a318e68..9254531e49d4aa 100644
--- a/deps/npm/node_modules/@npmcli/arborist/lib/shrinkwrap.js
+++ b/deps/npm/node_modules/@npmcli/arborist/lib/shrinkwrap.js
@@ -200,9 +200,9 @@ class Shrinkwrap {
return s[_maybeStat]().then(([sw, lock]) => {
s.filename = resolve(s.path,
(s.hiddenLockfile ? 'node_modules/.package-lock'
- : s.shrinkwrapOnly || sw && !lock ? 'npm-shrinkwrap'
+ : s.shrinkwrapOnly || sw ? 'npm-shrinkwrap'
: 'package-lock') + '.json')
- s.loadedFromDisk = sw || lock
+ s.loadedFromDisk = !!(sw || lock)
s.type = basename(s.filename)
return s
})
@@ -353,14 +353,14 @@ class Shrinkwrap {
// we don't need to load package-lock.json except for top of tree nodes,
// only npm-shrinkwrap.json.
return this[_maybeRead]().then(([sw, lock, yarn]) => {
- const data = lock || sw || ''
+ const data = sw || lock || ''
// use shrinkwrap only for deps, otherwise prefer package-lock
// and ignore npm-shrinkwrap if both are present.
// TODO: emit a warning here or something if both are present.
this.filename = resolve(this.path,
(this.hiddenLockfile ? 'node_modules/.package-lock'
- : this.shrinkwrapOnly || sw && !lock ? 'npm-shrinkwrap'
+ : this.shrinkwrapOnly || sw ? 'npm-shrinkwrap'
: 'package-lock') + '.json')
this.type = basename(this.filename)
diff --git a/deps/npm/node_modules/@npmcli/arborist/package.json b/deps/npm/node_modules/@npmcli/arborist/package.json
index 6300a5e867d4cd..fafd1fb0f865f2 100644
--- a/deps/npm/node_modules/@npmcli/arborist/package.json
+++ b/deps/npm/node_modules/@npmcli/arborist/package.json
@@ -1,12 +1,12 @@
{
"name": "@npmcli/arborist",
- "version": "2.0.3",
+ "version": "2.0.6",
"description": "Manage node_modules trees",
"dependencies": {
"@npmcli/installed-package-contents": "^1.0.5",
"@npmcli/map-workspaces": "^1.0.1",
- "@npmcli/metavuln-calculator": "^1.0.0",
- "@npmcli/move-file": "^1.0.1",
+ "@npmcli/metavuln-calculator": "^1.0.1",
+ "@npmcli/move-file": "^1.1.0",
"@npmcli/name-from-folder": "^1.0.1",
"@npmcli/node-gyp": "^1.0.1",
"@npmcli/run-script": "^1.8.1",
@@ -19,7 +19,8 @@
"npm-install-checks": "^4.0.0",
"npm-package-arg": "^8.1.0",
"npm-pick-manifest": "^6.1.0",
- "pacote": "^11.1.14",
+ "npm-registry-fetch": "^9.0.0",
+ "pacote": "^11.2.3",
"parse-conflict-json": "^1.1.1",
"promise-all-reject-late": "^1.0.0",
"promise-call-limit": "^1.0.1",
diff --git a/deps/npm/node_modules/@npmcli/metavuln-calculator/lib/advisory.js b/deps/npm/node_modules/@npmcli/metavuln-calculator/lib/advisory.js
index 95bcc67558ed17..15340f5dc70e87 100644
--- a/deps/npm/node_modules/@npmcli/metavuln-calculator/lib/advisory.js
+++ b/deps/npm/node_modules/@npmcli/metavuln-calculator/lib/advisory.js
@@ -65,7 +65,7 @@ class Advisory {
// load up the data from a cache entry and a fetched packument
load (cached, packument) {
- // basic data integrity gutchecks
+ // basic data integrity gutcheck
if (!cached || typeof cached !== 'object') {
throw new TypeError('invalid cached data, expected object')
}
@@ -148,7 +148,42 @@ class Advisory {
}
[_calculateRange] () {
- const metavuln = this.vulnerableVersions.join(' || ').trim()
+ // calling semver.simplifyRange with a massive list of versions, and those
+ // versions all concatenated with `||` is a geometric CPU explosion!
+ // we can try to be a *little* smarter up front by doing x-y for all
+ // contiguous version sets in the list
+ const ranges = []
+ this.versions = semver.sort(this.versions)
+ this.vulnerableVersions = semver.sort(this.vulnerableVersions)
+ for (let v = 0, vulnVer = 0; v < this.versions.length; v++) {
+ // figure out the vulnerable subrange
+ const vr = [this.versions[v]]
+ while (v < this.versions.length) {
+ if (this.versions[v] !== this.vulnerableVersions[vulnVer]) {
+ // we don't test prerelease versions, so just skip past it
+ if (/-/.test(this.versions[v])) {
+ v++
+ continue
+ }
+ break
+ }
+ if (vr.length > 1)
+ vr[1] = this.versions[v]
+ else
+ vr.push(this.versions[v])
+ v++
+ vulnVer++
+ }
+ // it'll either be just the first version, which means no overlap,
+ // or the start and end versions, which might be the same version
+ if (vr.length > 1) {
+ const tail = this.versions[this.versions.length - 1]
+ ranges.push(vr[1] === tail ? `>=${vr[0]}`
+ : vr[0] === vr[1] ? vr[0]
+ : vr.join(' - '))
+ }
+ }
+ const metavuln = ranges.join(' || ').trim()
this.range = !metavuln ? '<0.0.0-0'
: semver.simplifyRange(this.versions, metavuln, semverOpt)
}
@@ -271,25 +306,99 @@ class Advisory {
}
for (const list of versionSets) {
- const headVuln = this.testVersion(list[0])
- const tailVuln = this.testVersion(list[list.length - 1])
+ // it's common to have version lists like:
+ // 1.0.0
+ // 1.0.1-alpha.0
+ // 1.0.1-alpha.1
+ // ...
+ // 1.0.1-alpha.999
+ // 1.0.1
+ // 1.0.2-alpha.0
+ // ...
+ // 1.0.2-alpha.99
+ // 1.0.2
+ // with a huge number of prerelease versions that are not installable
+ // anyway.
+ // If mid has a prerelease tag, and list[0] does not, then walk it
+ // back until we hit a non-prerelease version
+ // If mid has a prerelease tag, and list[list.length-1] does not,
+ // then walk it forward until we hit a version without a prerelease tag
+ // Similarly, if the head/tail is a prerelease, but there is a non-pr
+ // version in the list, then start there instead.
+ let h = 0
+ const origHeadVuln = this.testVersion(list[h])
+ while (h < list.length && /-/.test(String(list[h])))
+ h++
+
+ // don't filter out the whole list! they might all be pr's
+ if (h === list.length)
+ h = 0
+ else if (origHeadVuln) {
+ // if the original was vulnerable, assume so are all of these
+ for (let hh = 0; hh < h; hh++)
+ this[_markVulnerable](list[hh])
+ }
+
+ let t = list.length - 1
+ const origTailVuln = this.testVersion(list[t])
+ while (t > h && /-/.test(String(list[t])))
+ t--
+
+ // don't filter out the whole list! might all be pr's
+ if (t === h)
+ t = list.length - 1
+ else if (origTailVuln) {
+ // if original tail was vulnerable, assume these are as well
+ for (let tt = list.length - 1; tt > t; tt--)
+ this[_markVulnerable](list[tt])
+ }
+
+ const headVuln = h === 0 ? origHeadVuln
+ : this.testVersion(list[h])
+
+ const tailVuln = t === list.length - 1 ? origTailVuln
+ : this.testVersion(list[t])
+
// if head and tail both vulnerable, whole list is thrown out
if (headVuln && tailVuln) {
- for (const v of list.slice(1, -1)) {
- this[_markVulnerable](v)
- }
+ for (let v = h; v < t; v++)
+ this[_markVulnerable](list[v])
continue
}
// if length is 2 or 1, then we marked them all already
- if (list.length <= 2)
+ if (t < h + 2)
continue
const mid = Math.floor(list.length / 2)
- // leave out the ends, since we tested those already
- versionSets.add(list.slice(0, mid))
- versionSets.add(list.slice(mid))
+ const pre = list.slice(0, mid)
+ const post = list.slice(mid)
+
+ // if the parent list wasn't prereleases, then drop pr tags
+ // from end of the pre list, and beginning of the post list,
+ // marking as vulnerable if the midpoint item we picked is.
+ if (!/-/.test(String(pre[0]))) {
+ const midVuln = this.testVersion(pre[pre.length - 1])
+ while (/-/.test(String(pre[pre.length-1]))) {
+ const v = pre.pop()
+ if (midVuln)
+ this[_markVulnerable](v)
+ }
+ }
+
+ if (!/-/.test(String(post[post.length-1]))) {
+ const midVuln = this.testVersion(post[0])
+ while (/-/.test(String(post[0]))) {
+ const v = post.shift()
+ if (midVuln)
+ this[_markVulnerable](v)
+ }
+ }
+
+ versionSets.add(pre)
+ versionSets.add(post)
}
}
}
+
module.exports = Advisory
diff --git a/deps/npm/node_modules/@npmcli/metavuln-calculator/package.json b/deps/npm/node_modules/@npmcli/metavuln-calculator/package.json
index ec5eea5a4ceac3..636382170f177c 100644
--- a/deps/npm/node_modules/@npmcli/metavuln-calculator/package.json
+++ b/deps/npm/node_modules/@npmcli/metavuln-calculator/package.json
@@ -1,6 +1,6 @@
{
"name": "@npmcli/metavuln-calculator",
- "version": "1.0.0",
+ "version": "1.0.2",
"main": "lib/index.js",
"files": [
"lib"
diff --git a/deps/npm/node_modules/@npmcli/move-file/README.md b/deps/npm/node_modules/@npmcli/move-file/README.md
index da682ebd5123a5..8a5a57f0f8d926 100644
--- a/deps/npm/node_modules/@npmcli/move-file/README.md
+++ b/deps/npm/node_modules/@npmcli/move-file/README.md
@@ -3,7 +3,7 @@
A fork of [move-file](https://github.com/sindresorhus/move-file) with
compatibility with all node 10.x versions.
-> Move a file
+> Move a file (or directory)
The built-in
[`fs.rename()`](https://nodejs.org/api/fs.html#fs_fs_rename_oldpath_newpath_callback)
@@ -18,6 +18,7 @@ would have expected `fs.rename()` to be.
- Optionally prevent overwriting an existing file.
- Creates non-existent destination directories for you.
- Support for Node versions that lack built-in recursive `fs.mkdir()`
+- Automatically recurses when source is a directory.
## Install
@@ -48,13 +49,13 @@ Returns a `Promise` that resolves when the file has been moved.
Type: `string`
-File you want to move.
+File, or directory, you want to move.
#### destination
Type: `string`
-Where you want the file moved.
+Where you want the file or directory moved.
#### options
@@ -65,4 +66,4 @@ Type: `object`
Type: `boolean`\
Default: `true`
-Overwrite existing destination file.
+Overwrite existing destination file(s).
diff --git a/deps/npm/node_modules/@npmcli/move-file/index.js b/deps/npm/node_modules/@npmcli/move-file/index.js
index d1567d1f64f730..51f9535d39f4cc 100644
--- a/deps/npm/node_modules/@npmcli/move-file/index.js
+++ b/deps/npm/node_modules/@npmcli/move-file/index.js
@@ -1,4 +1,5 @@
-const { dirname } = require('path')
+const { dirname, join, resolve, relative, isAbsolute } = require('path')
+const rimraf_ = require('rimraf')
const { promisify } = require('util')
const {
access: access_,
@@ -7,14 +8,31 @@ const {
copyFileSync,
unlink: unlink_,
unlinkSync,
+ readdir: readdir_,
+ readdirSync,
rename: rename_,
renameSync,
+ stat: stat_,
+ statSync,
+ lstat: lstat_,
+ lstatSync,
+ symlink: symlink_,
+ symlinkSync,
+ readlink: readlink_,
+ readlinkSync
} = require('fs')
const access = promisify(access_)
const copyFile = promisify(copyFile_)
const unlink = promisify(unlink_)
+const readdir = promisify(readdir_)
const rename = promisify(rename_)
+const stat = promisify(stat_)
+const lstat = promisify(lstat_)
+const symlink = promisify(symlink_)
+const readlink = promisify(readlink_)
+const rimraf = promisify(rimraf_)
+const rimrafSync = rimraf_.sync
const mkdirp = require('mkdirp')
@@ -36,7 +54,7 @@ const pathExistsSync = path => {
}
}
-module.exports = async (source, destination, options = {}) => {
+const moveFile = async (source, destination, options = {}, root = true, symlinks = []) => {
if (!source || !destination) {
throw new TypeError('`source` and `destination` file required')
}
@@ -56,15 +74,38 @@ module.exports = async (source, destination, options = {}) => {
await rename(source, destination)
} catch (error) {
if (error.code === 'EXDEV') {
- await copyFile(source, destination)
- await unlink(source)
+ const sourceStat = await lstat(source)
+ if (sourceStat.isDirectory()) {
+ const files = await readdir(source)
+ await Promise.all(files.map((file) => moveFile(join(source, file), join(destination, file), options, false, symlinks)))
+ } else if (sourceStat.isSymbolicLink()) {
+ symlinks.push({ source, destination })
+ } else {
+ await copyFile(source, destination)
+ }
} else {
throw error
}
}
+
+ if (root) {
+ await Promise.all(symlinks.map(async ({ source, destination }) => {
+ let target = await readlink(source)
+ // junction symlinks in windows will be absolute paths, so we need to make sure they point to the destination
+ if (isAbsolute(target))
+ target = resolve(destination, relative(source, target))
+ // try to determine what the actual file is so we can create the correct type of symlink in windows
+ let targetStat
+ try {
+ targetStat = await stat(resolve(dirname(source), target))
+ } catch (err) {}
+ await symlink(target, destination, targetStat && targetStat.isDirectory() ? 'junction' : 'file')
+ }))
+ await rimraf(source)
+ }
}
-module.exports.sync = (source, destination, options = {}) => {
+const moveFileSync = (source, destination, options = {}, root = true, symlinks = []) => {
if (!source || !destination) {
throw new TypeError('`source` and `destination` file required')
}
@@ -84,10 +125,38 @@ module.exports.sync = (source, destination, options = {}) => {
renameSync(source, destination)
} catch (error) {
if (error.code === 'EXDEV') {
- copyFileSync(source, destination)
- unlinkSync(source)
+ const sourceStat = lstatSync(source)
+ if (sourceStat.isDirectory()) {
+ const files = readdirSync(source)
+ for (const file of files) {
+ moveFileSync(join(source, file), join(destination, file), options, false, symlinks)
+ }
+ } else if (sourceStat.isSymbolicLink()) {
+ symlinks.push({ source, destination })
+ } else {
+ copyFileSync(source, destination)
+ }
} else {
throw error
}
}
+
+ if (root) {
+ for (const { source, destination } of symlinks) {
+ let target = readlinkSync(source)
+ // junction symlinks in windows will be absolute paths, so we need to make sure they point to the destination
+ if (isAbsolute(target))
+ target = resolve(destination, relative(source, target))
+ // try to determine what the actual file is so we can create the correct type of symlink in windows
+ let targetStat
+ try {
+ targetStat = statSync(resolve(dirname(source), target))
+ } catch (err) {}
+ symlinkSync(target, destination, targetStat && targetStat.isDirectory() ? 'junction' : 'file')
+ }
+ rimrafSync(source)
+ }
}
+
+module.exports = moveFile
+module.exports.sync = moveFileSync
diff --git a/deps/npm/node_modules/@npmcli/move-file/node_modules/rimraf/LICENSE b/deps/npm/node_modules/@npmcli/move-file/node_modules/rimraf/LICENSE
new file mode 100644
index 00000000000000..19129e315fe593
--- /dev/null
+++ b/deps/npm/node_modules/@npmcli/move-file/node_modules/rimraf/LICENSE
@@ -0,0 +1,15 @@
+The ISC License
+
+Copyright (c) Isaac Z. Schlueter and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
diff --git a/deps/npm/node_modules/@npmcli/move-file/node_modules/rimraf/README.md b/deps/npm/node_modules/@npmcli/move-file/node_modules/rimraf/README.md
new file mode 100644
index 00000000000000..423b8cf854ad3e
--- /dev/null
+++ b/deps/npm/node_modules/@npmcli/move-file/node_modules/rimraf/README.md
@@ -0,0 +1,101 @@
+[](https://travis-ci.org/isaacs/rimraf) [](https://david-dm.org/isaacs/rimraf) [](https://david-dm.org/isaacs/rimraf#info=devDependencies)
+
+The [UNIX command](http://en.wikipedia.org/wiki/Rm_(Unix)) `rm -rf` for node.
+
+Install with `npm install rimraf`, or just drop rimraf.js somewhere.
+
+## API
+
+`rimraf(f, [opts], callback)`
+
+The first parameter will be interpreted as a globbing pattern for files. If you
+want to disable globbing you can do so with `opts.disableGlob` (defaults to
+`false`). This might be handy, for instance, if you have filenames that contain
+globbing wildcard characters.
+
+The callback will be called with an error if there is one. Certain
+errors are handled for you:
+
+* Windows: `EBUSY` and `ENOTEMPTY` - rimraf will back off a maximum of
+ `opts.maxBusyTries` times before giving up, adding 100ms of wait
+ between each attempt. The default `maxBusyTries` is 3.
+* `ENOENT` - If the file doesn't exist, rimraf will return
+ successfully, since your desired outcome is already the case.
+* `EMFILE` - Since `readdir` requires opening a file descriptor, it's
+ possible to hit `EMFILE` if too many file descriptors are in use.
+ In the sync case, there's nothing to be done for this. But in the
+ async case, rimraf will gradually back off with timeouts up to
+ `opts.emfileWait` ms, which defaults to 1000.
+
+## options
+
+* unlink, chmod, stat, lstat, rmdir, readdir,
+ unlinkSync, chmodSync, statSync, lstatSync, rmdirSync, readdirSync
+
+ In order to use a custom file system library, you can override
+ specific fs functions on the options object.
+
+ If any of these functions are present on the options object, then
+ the supplied function will be used instead of the default fs
+ method.
+
+ Sync methods are only relevant for `rimraf.sync()`, of course.
+
+ For example:
+
+ ```javascript
+ var myCustomFS = require('some-custom-fs')
+
+ rimraf('some-thing', myCustomFS, callback)
+ ```
+
+* maxBusyTries
+
+ If an `EBUSY`, `ENOTEMPTY`, or `EPERM` error code is encountered
+ on Windows systems, then rimraf will retry with a linear backoff
+ wait of 100ms longer on each try. The default maxBusyTries is 3.
+
+ Only relevant for async usage.
+
+* emfileWait
+
+ If an `EMFILE` error is encountered, then rimraf will retry
+ repeatedly with a linear backoff of 1ms longer on each try, until
+ the timeout counter hits this max. The default limit is 1000.
+
+ If you repeatedly encounter `EMFILE` errors, then consider using
+ [graceful-fs](http://npm.im/graceful-fs) in your program.
+
+ Only relevant for async usage.
+
+* glob
+
+ Set to `false` to disable [glob](http://npm.im/glob) pattern
+ matching.
+
+ Set to an object to pass options to the glob module. The default
+ glob options are `{ nosort: true, silent: true }`.
+
+ Glob version 6 is used in this module.
+
+ Relevant for both sync and async usage.
+
+* disableGlob
+
+ Set to any non-falsey value to disable globbing entirely.
+ (Equivalent to setting `glob: false`.)
+
+## rimraf.sync
+
+It can remove stuff synchronously, too. But that's not so good. Use
+the async API. It's better.
+
+## CLI
+
+If installed with `npm install rimraf -g` it can be used as a global
+command `rimraf [ ...]` which is useful for cross platform support.
+
+## mkdirp
+
+If you need to create a directory recursively, check out
+[mkdirp](https://github.com/substack/node-mkdirp).
diff --git a/deps/npm/node_modules/@npmcli/move-file/node_modules/rimraf/bin.js b/deps/npm/node_modules/@npmcli/move-file/node_modules/rimraf/bin.js
new file mode 100755
index 00000000000000..0d1e17be701ec3
--- /dev/null
+++ b/deps/npm/node_modules/@npmcli/move-file/node_modules/rimraf/bin.js
@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+var rimraf = require('./')
+
+var help = false
+var dashdash = false
+var noglob = false
+var args = process.argv.slice(2).filter(function(arg) {
+ if (dashdash)
+ return !!arg
+ else if (arg === '--')
+ dashdash = true
+ else if (arg === '--no-glob' || arg === '-G')
+ noglob = true
+ else if (arg === '--glob' || arg === '-g')
+ noglob = false
+ else if (arg.match(/^(-+|\/)(h(elp)?|\?)$/))
+ help = true
+ else
+ return !!arg
+})
+
+if (help || args.length === 0) {
+ // If they didn't ask for help, then this is not a "success"
+ var log = help ? console.log : console.error
+ log('Usage: rimraf [ ...]')
+ log('')
+ log(' Deletes all files and folders at "path" recursively.')
+ log('')
+ log('Options:')
+ log('')
+ log(' -h, --help Display this usage info')
+ log(' -G, --no-glob Do not expand glob patterns in arguments')
+ log(' -g, --glob Expand glob patterns in arguments (default)')
+ process.exit(help ? 0 : 1)
+} else
+ go(0)
+
+function go (n) {
+ if (n >= args.length)
+ return
+ var options = {}
+ if (noglob)
+ options = { glob: false }
+ rimraf(args[n], options, function (er) {
+ if (er)
+ throw er
+ go(n+1)
+ })
+}
diff --git a/deps/npm/node_modules/@npmcli/move-file/node_modules/rimraf/package.json b/deps/npm/node_modules/@npmcli/move-file/node_modules/rimraf/package.json
new file mode 100644
index 00000000000000..26e05d85ea2fdf
--- /dev/null
+++ b/deps/npm/node_modules/@npmcli/move-file/node_modules/rimraf/package.json
@@ -0,0 +1,29 @@
+{
+ "name": "rimraf",
+ "version": "2.7.1",
+ "main": "rimraf.js",
+ "description": "A deep deletion module for node (like `rm -rf`)",
+ "author": "Isaac Z. Schlueter (http://blog.izs.me/)",
+ "license": "ISC",
+ "repository": "git://github.com/isaacs/rimraf.git",
+ "scripts": {
+ "preversion": "npm test",
+ "postversion": "npm publish",
+ "postpublish": "git push origin --all; git push origin --tags",
+ "test": "tap test/*.js"
+ },
+ "bin": "./bin.js",
+ "dependencies": {
+ "glob": "^7.1.3"
+ },
+ "files": [
+ "LICENSE",
+ "README.md",
+ "bin.js",
+ "rimraf.js"
+ ],
+ "devDependencies": {
+ "mkdirp": "^0.5.1",
+ "tap": "^12.1.1"
+ }
+}
diff --git a/deps/npm/node_modules/@npmcli/move-file/node_modules/rimraf/rimraf.js b/deps/npm/node_modules/@npmcli/move-file/node_modules/rimraf/rimraf.js
new file mode 100644
index 00000000000000..a90ad029f3ece1
--- /dev/null
+++ b/deps/npm/node_modules/@npmcli/move-file/node_modules/rimraf/rimraf.js
@@ -0,0 +1,372 @@
+module.exports = rimraf
+rimraf.sync = rimrafSync
+
+var assert = require("assert")
+var path = require("path")
+var fs = require("fs")
+var glob = undefined
+try {
+ glob = require("glob")
+} catch (_err) {
+ // treat glob as optional.
+}
+var _0666 = parseInt('666', 8)
+
+var defaultGlobOpts = {
+ nosort: true,
+ silent: true
+}
+
+// for EMFILE handling
+var timeout = 0
+
+var isWindows = (process.platform === "win32")
+
+function defaults (options) {
+ var methods = [
+ 'unlink',
+ 'chmod',
+ 'stat',
+ 'lstat',
+ 'rmdir',
+ 'readdir'
+ ]
+ methods.forEach(function(m) {
+ options[m] = options[m] || fs[m]
+ m = m + 'Sync'
+ options[m] = options[m] || fs[m]
+ })
+
+ options.maxBusyTries = options.maxBusyTries || 3
+ options.emfileWait = options.emfileWait || 1000
+ if (options.glob === false) {
+ options.disableGlob = true
+ }
+ if (options.disableGlob !== true && glob === undefined) {
+ throw Error('glob dependency not found, set `options.disableGlob = true` if intentional')
+ }
+ options.disableGlob = options.disableGlob || false
+ options.glob = options.glob || defaultGlobOpts
+}
+
+function rimraf (p, options, cb) {
+ if (typeof options === 'function') {
+ cb = options
+ options = {}
+ }
+
+ assert(p, 'rimraf: missing path')
+ assert.equal(typeof p, 'string', 'rimraf: path should be a string')
+ assert.equal(typeof cb, 'function', 'rimraf: callback function required')
+ assert(options, 'rimraf: invalid options argument provided')
+ assert.equal(typeof options, 'object', 'rimraf: options should be object')
+
+ defaults(options)
+
+ var busyTries = 0
+ var errState = null
+ var n = 0
+
+ if (options.disableGlob || !glob.hasMagic(p))
+ return afterGlob(null, [p])
+
+ options.lstat(p, function (er, stat) {
+ if (!er)
+ return afterGlob(null, [p])
+
+ glob(p, options.glob, afterGlob)
+ })
+
+ function next (er) {
+ errState = errState || er
+ if (--n === 0)
+ cb(errState)
+ }
+
+ function afterGlob (er, results) {
+ if (er)
+ return cb(er)
+
+ n = results.length
+ if (n === 0)
+ return cb()
+
+ results.forEach(function (p) {
+ rimraf_(p, options, function CB (er) {
+ if (er) {
+ if ((er.code === "EBUSY" || er.code === "ENOTEMPTY" || er.code === "EPERM") &&
+ busyTries < options.maxBusyTries) {
+ busyTries ++
+ var time = busyTries * 100
+ // try again, with the same exact callback as this one.
+ return setTimeout(function () {
+ rimraf_(p, options, CB)
+ }, time)
+ }
+
+ // this one won't happen if graceful-fs is used.
+ if (er.code === "EMFILE" && timeout < options.emfileWait) {
+ return setTimeout(function () {
+ rimraf_(p, options, CB)
+ }, timeout ++)
+ }
+
+ // already gone
+ if (er.code === "ENOENT") er = null
+ }
+
+ timeout = 0
+ next(er)
+ })
+ })
+ }
+}
+
+// Two possible strategies.
+// 1. Assume it's a file. unlink it, then do the dir stuff on EPERM or EISDIR
+// 2. Assume it's a directory. readdir, then do the file stuff on ENOTDIR
+//
+// Both result in an extra syscall when you guess wrong. However, there
+// are likely far more normal files in the world than directories. This
+// is based on the assumption that a the average number of files per
+// directory is >= 1.
+//
+// If anyone ever complains about this, then I guess the strategy could
+// be made configurable somehow. But until then, YAGNI.
+function rimraf_ (p, options, cb) {
+ assert(p)
+ assert(options)
+ assert(typeof cb === 'function')
+
+ // sunos lets the root user unlink directories, which is... weird.
+ // so we have to lstat here and make sure it's not a dir.
+ options.lstat(p, function (er, st) {
+ if (er && er.code === "ENOENT")
+ return cb(null)
+
+ // Windows can EPERM on stat. Life is suffering.
+ if (er && er.code === "EPERM" && isWindows)
+ fixWinEPERM(p, options, er, cb)
+
+ if (st && st.isDirectory())
+ return rmdir(p, options, er, cb)
+
+ options.unlink(p, function (er) {
+ if (er) {
+ if (er.code === "ENOENT")
+ return cb(null)
+ if (er.code === "EPERM")
+ return (isWindows)
+ ? fixWinEPERM(p, options, er, cb)
+ : rmdir(p, options, er, cb)
+ if (er.code === "EISDIR")
+ return rmdir(p, options, er, cb)
+ }
+ return cb(er)
+ })
+ })
+}
+
+function fixWinEPERM (p, options, er, cb) {
+ assert(p)
+ assert(options)
+ assert(typeof cb === 'function')
+ if (er)
+ assert(er instanceof Error)
+
+ options.chmod(p, _0666, function (er2) {
+ if (er2)
+ cb(er2.code === "ENOENT" ? null : er)
+ else
+ options.stat(p, function(er3, stats) {
+ if (er3)
+ cb(er3.code === "ENOENT" ? null : er)
+ else if (stats.isDirectory())
+ rmdir(p, options, er, cb)
+ else
+ options.unlink(p, cb)
+ })
+ })
+}
+
+function fixWinEPERMSync (p, options, er) {
+ assert(p)
+ assert(options)
+ if (er)
+ assert(er instanceof Error)
+
+ try {
+ options.chmodSync(p, _0666)
+ } catch (er2) {
+ if (er2.code === "ENOENT")
+ return
+ else
+ throw er
+ }
+
+ try {
+ var stats = options.statSync(p)
+ } catch (er3) {
+ if (er3.code === "ENOENT")
+ return
+ else
+ throw er
+ }
+
+ if (stats.isDirectory())
+ rmdirSync(p, options, er)
+ else
+ options.unlinkSync(p)
+}
+
+function rmdir (p, options, originalEr, cb) {
+ assert(p)
+ assert(options)
+ if (originalEr)
+ assert(originalEr instanceof Error)
+ assert(typeof cb === 'function')
+
+ // try to rmdir first, and only readdir on ENOTEMPTY or EEXIST (SunOS)
+ // if we guessed wrong, and it's not a directory, then
+ // raise the original error.
+ options.rmdir(p, function (er) {
+ if (er && (er.code === "ENOTEMPTY" || er.code === "EEXIST" || er.code === "EPERM"))
+ rmkids(p, options, cb)
+ else if (er && er.code === "ENOTDIR")
+ cb(originalEr)
+ else
+ cb(er)
+ })
+}
+
+function rmkids(p, options, cb) {
+ assert(p)
+ assert(options)
+ assert(typeof cb === 'function')
+
+ options.readdir(p, function (er, files) {
+ if (er)
+ return cb(er)
+ var n = files.length
+ if (n === 0)
+ return options.rmdir(p, cb)
+ var errState
+ files.forEach(function (f) {
+ rimraf(path.join(p, f), options, function (er) {
+ if (errState)
+ return
+ if (er)
+ return cb(errState = er)
+ if (--n === 0)
+ options.rmdir(p, cb)
+ })
+ })
+ })
+}
+
+// this looks simpler, and is strictly *faster*, but will
+// tie up the JavaScript thread and fail on excessively
+// deep directory trees.
+function rimrafSync (p, options) {
+ options = options || {}
+ defaults(options)
+
+ assert(p, 'rimraf: missing path')
+ assert.equal(typeof p, 'string', 'rimraf: path should be a string')
+ assert(options, 'rimraf: missing options')
+ assert.equal(typeof options, 'object', 'rimraf: options should be object')
+
+ var results
+
+ if (options.disableGlob || !glob.hasMagic(p)) {
+ results = [p]
+ } else {
+ try {
+ options.lstatSync(p)
+ results = [p]
+ } catch (er) {
+ results = glob.sync(p, options.glob)
+ }
+ }
+
+ if (!results.length)
+ return
+
+ for (var i = 0; i < results.length; i++) {
+ var p = results[i]
+
+ try {
+ var st = options.lstatSync(p)
+ } catch (er) {
+ if (er.code === "ENOENT")
+ return
+
+ // Windows can EPERM on stat. Life is suffering.
+ if (er.code === "EPERM" && isWindows)
+ fixWinEPERMSync(p, options, er)
+ }
+
+ try {
+ // sunos lets the root user unlink directories, which is... weird.
+ if (st && st.isDirectory())
+ rmdirSync(p, options, null)
+ else
+ options.unlinkSync(p)
+ } catch (er) {
+ if (er.code === "ENOENT")
+ return
+ if (er.code === "EPERM")
+ return isWindows ? fixWinEPERMSync(p, options, er) : rmdirSync(p, options, er)
+ if (er.code !== "EISDIR")
+ throw er
+
+ rmdirSync(p, options, er)
+ }
+ }
+}
+
+function rmdirSync (p, options, originalEr) {
+ assert(p)
+ assert(options)
+ if (originalEr)
+ assert(originalEr instanceof Error)
+
+ try {
+ options.rmdirSync(p)
+ } catch (er) {
+ if (er.code === "ENOENT")
+ return
+ if (er.code === "ENOTDIR")
+ throw originalEr
+ if (er.code === "ENOTEMPTY" || er.code === "EEXIST" || er.code === "EPERM")
+ rmkidsSync(p, options)
+ }
+}
+
+function rmkidsSync (p, options) {
+ assert(p)
+ assert(options)
+ options.readdirSync(p).forEach(function (f) {
+ rimrafSync(path.join(p, f), options)
+ })
+
+ // We only end up here once we got ENOTEMPTY at least once, and
+ // at this point, we are guaranteed to have removed all the kids.
+ // So, we know that it won't be ENOENT or ENOTDIR or anything else.
+ // try really hard to delete stuff on windows, because it has a
+ // PROFOUNDLY annoying habit of not closing handles promptly when
+ // files are deleted, resulting in spurious ENOTEMPTY errors.
+ var retries = isWindows ? 100 : 1
+ var i = 0
+ do {
+ var threw = true
+ try {
+ var ret = options.rmdirSync(p, options)
+ threw = false
+ return ret
+ } finally {
+ if (++i < retries && threw)
+ continue
+ }
+ } while (true)
+}
diff --git a/deps/npm/node_modules/@npmcli/move-file/package.json b/deps/npm/node_modules/@npmcli/move-file/package.json
index 476bc76ba73ff5..46b42c9e9aa2b8 100644
--- a/deps/npm/node_modules/@npmcli/move-file/package.json
+++ b/deps/npm/node_modules/@npmcli/move-file/package.json
@@ -1,12 +1,13 @@
{
"name": "@npmcli/move-file",
- "version": "1.0.1",
+ "version": "1.1.0",
"files": [
"index.js"
],
"description": "move a file (fork of move-file)",
"dependencies": {
- "mkdirp": "^1.0.4"
+ "mkdirp": "^1.0.4",
+ "rimraf": "^2.7.1"
},
"devDependencies": {
"require-inject": "^1.4.4",
diff --git a/deps/npm/node_modules/make-fetch-happen/index.js b/deps/npm/node_modules/make-fetch-happen/index.js
index b8d7bd98da5965..54f72049c1d52b 100644
--- a/deps/npm/node_modules/make-fetch-happen/index.js
+++ b/deps/npm/node_modules/make-fetch-happen/index.js
@@ -285,6 +285,10 @@ function remoteFetch (uri, opts) {
size: opts.size,
counter: opts.counter,
timeout: opts.timeout,
+ ca: opts.ca,
+ cert: opts.cert,
+ key: opts.key,
+ rejectUnauthorized: opts.strictSSL,
}
return retry(
diff --git a/deps/npm/node_modules/make-fetch-happen/package.json b/deps/npm/node_modules/make-fetch-happen/package.json
index 4fc6163d5a0278..2d555bcb86f41e 100644
--- a/deps/npm/node_modules/make-fetch-happen/package.json
+++ b/deps/npm/node_modules/make-fetch-happen/package.json
@@ -1,6 +1,6 @@
{
"name": "make-fetch-happen",
- "version": "8.0.12",
+ "version": "8.0.13",
"description": "Opinionated, caching, retrying fetch client",
"main": "index.js",
"files": [
diff --git a/deps/npm/node_modules/pacote/README.md b/deps/npm/node_modules/pacote/README.md
index 81cd437efcd994..619e0ec44e8f6c 100644
--- a/deps/npm/node_modules/pacote/README.md
+++ b/deps/npm/node_modules/pacote/README.md
@@ -162,6 +162,11 @@ resolved, and other properties, as they are determined.
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.
+* `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.
## Extracted File Modes
diff --git a/deps/npm/node_modules/pacote/lib/fetcher.js b/deps/npm/node_modules/pacote/lib/fetcher.js
index 33fbf79c61b60f..c4e5852daf8a87 100644
--- a/deps/npm/node_modules/pacote/lib/fetcher.js
+++ b/deps/npm/node_modules/pacote/lib/fetcher.js
@@ -47,6 +47,8 @@ class FetcherBase {
throw new TypeError('options object is required')
this.spec = npa(spec, opts.where)
+ this.allowGitIgnore = !!opts.allowGitIgnore
+
// a bit redundant because presumably the caller already knows this,
// but it makes it easier to not have to keep track of the requested
// spec when we're dispatching thousands of these at once, and normalizing
@@ -60,6 +62,7 @@ class FetcherBase {
// clone the opts object so that others aren't upset when we mutate it
// by adding/modifying the integrity value.
this.opts = {...opts}
+
this.cache = opts.cache || cacheDir()
this.resolved = opts.resolved || null
@@ -413,7 +416,7 @@ class FetcherBase {
const base = basename(entry.path)
if (base === '.npmignore')
sawIgnores.add(entry.path)
- else if (base === '.gitignore') {
+ else if (base === '.gitignore' && !this.allowGitIgnore) {
// rename, but only if there's not already a .npmignore
const ni = entry.path.replace(/\.gitignore$/, '.npmignore')
if (sawIgnores.has(ni))
diff --git a/deps/npm/node_modules/pacote/lib/git.js b/deps/npm/node_modules/pacote/lib/git.js
index 81f7ca2567ce36..406ab5c600221b 100644
--- a/deps/npm/node_modules/pacote/lib/git.js
+++ b/deps/npm/node_modules/pacote/lib/git.js
@@ -24,13 +24,16 @@ const _cloneRepo = Symbol('_cloneRepo')
const _setResolvedWithSha = Symbol('_setResolvedWithSha')
const _prepareDir = Symbol('_prepareDir')
-// get the repository url. prefer ssh, fall back to git://
+// get the repository url.
+// prefer https if there's auth, since ssh will drop that.
+// otherwise, prefer ssh if available (more secure).
// We have to add the git+ back because npa suppresses it.
-const repoUrl = (hosted, opts) =>
- hosted.sshurl && addGitPlus(hosted.sshurl(opts)) ||
- hosted.https && addGitPlus(hosted.https(opts))
+const repoUrl = (h, opts) =>
+ h.sshurl && !(h.https && h.auth) && addGitPlus(h.sshurl(opts)) ||
+ h.https && addGitPlus(h.https(opts))
-const addGitPlus = url => url && `git+${url}`
+// add git+ to the url, but only one time.
+const addGitPlus = url => url && `git+${url}`.replace(/^(git\+)+/, 'git+')
class GitFetcher extends Fetcher {
constructor (spec, opts) {
@@ -51,6 +54,11 @@ class GitFetcher extends Fetcher {
this.resolvedSha = ''
}
+ // just exposed to make it easier to test all the combinations
+ static repoUrl (hosted, opts) {
+ return repoUrl(hosted, opts)
+ }
+
get types () {
return ['git']
}
@@ -69,13 +77,16 @@ class GitFetcher extends Fetcher {
}
// first try https, since that's faster and passphrase-less for
- // public repos. Fall back to SSH to support private repos.
- // NB: we always store the SSH url in the 'resolved' field.
+ // public repos, and supports private repos when auth is provided.
+ // Fall back to SSH to support private repos
+ // NB: we always store the https url in resolved field if auth
+ // is present, otherwise ssh if the hosted type provides it
[_resolvedFromHosted] (hosted) {
return this[_resolvedFromRepo](hosted.https && hosted.https())
.catch(er => {
const ssh = hosted.sshurl && hosted.sshurl()
- if (!ssh)
+ // no fallthrough if we can't fall through or have https auth
+ if (!ssh || hosted.auth)
throw er
return this[_resolvedFromRepo](ssh)
})
@@ -121,9 +132,11 @@ class GitFetcher extends Fetcher {
// either a git url with a hash, or a tarball download URL
[_addGitSha] (sha) {
if (this.spec.hosted) {
- this[_setResolvedWithSha](
- this.spec.hosted.shortcut({ noCommittish: true }) + '#' + sha
- )
+ const h = this.spec.hosted
+ const opt = { noCommittish: true }
+ const base = h.https && h.auth ? h.https(opt) : h.shortcut(opt)
+
+ this[_setResolvedWithSha](`${base}#${sha}`)
} else {
const u = url.format(new url.URL(`#${sha}`, this.spec.rawSpec))
this[_setResolvedWithSha](url.format(u))
@@ -207,6 +220,7 @@ class GitFetcher extends Fetcher {
const nameat = this.spec.name ? `${this.spec.name}@` : ''
return new RemoteFetcher(h.tarball({ noCommittish: false }), {
...this.opts,
+ allowGitIgnore: true,
pkgid: `git:${nameat}${this.resolved}`,
resolved: this.resolved,
integrity: null, // it'll always be different, if we have one
@@ -231,14 +245,19 @@ class GitFetcher extends Fetcher {
})
}
+ // first try https, since that's faster and passphrase-less for
+ // public repos, and supports private repos when auth is provided.
+ // Fall back to SSH to support private repos
+ // NB: we always store the https url in resolved field if auth
+ // is present, otherwise ssh if the hosted type provides it
[_cloneHosted] (ref, tmp) {
const hosted = this.spec.hosted
const https = hosted.https()
return this[_cloneRepo](hosted.https({ noCommittish: true }), ref, tmp)
.catch(er => {
const ssh = hosted.sshurl && hosted.sshurl({ noCommittish: true })
- /* istanbul ignore if - should be covered by the resolve() call */
- if (!ssh)
+ // no fallthrough if we can't fall through or have https auth
+ if (!ssh || hosted.auth)
throw er
return this[_cloneRepo](ssh, ref, tmp)
})
diff --git a/deps/npm/node_modules/pacote/lib/registry.js b/deps/npm/node_modules/pacote/lib/registry.js
index b9df036146406d..537610d2990d09 100644
--- a/deps/npm/node_modules/pacote/lib/registry.js
+++ b/deps/npm/node_modules/pacote/lib/registry.js
@@ -20,6 +20,14 @@ class RegistryFetcher extends Fetcher {
constructor (spec, opts) {
super(spec, opts)
+ // you usually don't want to fetch the same packument multiple times in
+ // the span of a given script or command, no matter how many pacote calls
+ // are made, so this lets us avoid doing that. It's only relevant for
+ // registry fetchers, because other types simulate their packument from
+ // the manifest, which they memoize on this.package, so it's very cheap
+ // already.
+ this.packumentCache = this.opts.packumentCache || null
+
// handle case when npm-package-arg guesses wrong.
if (this.spec.type === 'tag' &&
this.spec.rawSpec === '' &&
@@ -64,11 +72,17 @@ class RegistryFetcher extends Fetcher {
}
}
- packument () {
+ async packument () {
+ // note this might be either an in-flight promise for a request,
+ // or the actual packument, but we never want to make more than
+ // one request at a time for the same thing regardless.
+ if (this.packumentCache && this.packumentCache.has(this.packumentUrl))
+ return this.packumentCache.get(this.packumentUrl)
+
// npm-registry-fetch the packument
// set the appropriate header for corgis if fullMetadata isn't set
// return the res.json() promise
- return fetch(this.packumentUrl, {
+ const p = fetch(this.packumentUrl, {
...this.opts,
headers: this[_headers](),
spec: this.spec,
@@ -77,8 +91,12 @@ class RegistryFetcher extends Fetcher {
}).then(res => res.json().then(packument => {
packument._cached = res.headers.has('x-local-cache')
packument._contentLength = +res.headers.get('content-length')
+ if (this.packumentCache)
+ this.packumentCache.set(this.packumentUrl, packument)
return packument
})).catch(er => {
+ if (this.packumentCache)
+ this.packumentCache.delete(this.packumentUrl)
if (er.code === 'E404' && !this.fullMetadata) {
// possible that corgis are not supported by this registry
this.fullMetadata = true
@@ -86,6 +104,9 @@ class RegistryFetcher extends Fetcher {
}
throw er
})
+ if (this.packumentCache)
+ this.packumentCache.set(this.packumentUrl, p)
+ return p
}
manifest () {
diff --git a/deps/npm/node_modules/pacote/package.json b/deps/npm/node_modules/pacote/package.json
index 085e8f66af175f..b55685a48b2411 100644
--- a/deps/npm/node_modules/pacote/package.json
+++ b/deps/npm/node_modules/pacote/package.json
@@ -1,6 +1,6 @@
{
"name": "pacote",
- "version": "11.1.14",
+ "version": "11.2.3",
"description": "JavaScript package downloader",
"author": "Isaac Z. Schlueter (https://izs.me)",
"bin": {
@@ -13,7 +13,7 @@
"snap": "tap",
"preversion": "npm test",
"postversion": "npm publish",
- "postpublish": "git push origin --follow-tags"
+ "prepublishOnly": "git push origin --follow-tags"
},
"tap": {
"timeout": 300,
diff --git a/deps/npm/package.json b/deps/npm/package.json
index 9f0aacbda26880..da6175dfe80b8e 100644
--- a/deps/npm/package.json
+++ b/deps/npm/package.json
@@ -1,5 +1,5 @@
{
- "version": "7.4.0",
+ "version": "7.4.3",
"name": "npm",
"description": "a package manager for JavaScript",
"keywords": [
@@ -42,7 +42,7 @@
"./package.json": "./package.json"
},
"dependencies": {
- "@npmcli/arborist": "^2.0.3",
+ "@npmcli/arborist": "^2.0.6",
"@npmcli/ci-detect": "^1.2.0",
"@npmcli/config": "^1.2.8",
"@npmcli/run-script": "^1.8.1",
@@ -74,7 +74,7 @@
"libnpmsearch": "^3.1.0",
"libnpmteam": "^2.0.2",
"libnpmversion": "^1.0.7",
- "make-fetch-happen": "^8.0.12",
+ "make-fetch-happen": "^8.0.13",
"minipass": "^3.1.3",
"minipass-pipeline": "^1.2.4",
"mkdirp": "^1.0.4",
@@ -90,7 +90,7 @@
"npm-user-validate": "^1.0.1",
"npmlog": "~4.1.2",
"opener": "^1.5.2",
- "pacote": "^11.1.14",
+ "pacote": "^11.2.3",
"parse-conflict-json": "^1.1.1",
"qrcode-terminal": "^0.12.0",
"read": "~1.0.7",
@@ -180,7 +180,7 @@
],
"devDependencies": {
"cmark-gfm": "^0.8.5",
- "eslint": "^7.14.0",
+ "eslint": "^7.18.0",
"eslint-plugin-import": "^2.22.1",
"eslint-plugin-node": "^11.1.0",
"eslint-plugin-promise": "^4.2.1",
diff --git a/deps/npm/tap-snapshots/test-lib-link.js-TAP.test.js b/deps/npm/tap-snapshots/test-lib-link.js-TAP.test.js
index de7f483b60de85..ab1d5c6b830fbe 100644
--- a/deps/npm/tap-snapshots/test-lib-link.js-TAP.test.js
+++ b/deps/npm/tap-snapshots/test-lib-link.js-TAP.test.js
@@ -19,6 +19,11 @@ exports[`test/lib/link.js TAP link pkg already in global space > should create a
`
+exports[`test/lib/link.js TAP link pkg already in global space when prefix is a symlink > should create a local symlink to global pkg 1`] = `
+{CWD}/test/lib/link-link-pkg-already-in-global-space-when-prefix-is-a-symlink/my-project/node_modules/@myscope/linked -> {CWD}/test/lib/link-link-pkg-already-in-global-space-when-prefix-is-a-symlink/scoped-linked
+
+`
+
exports[`test/lib/link.js TAP link to globalDir when in current working dir of pkg and no args > should create a global link to current pkg 1`] = `
{CWD}/test/lib/link-link-to-globalDir-when-in-current-working-dir-of-pkg-and-no-args/global-prefix/lib/node_modules/test-pkg-link -> {CWD}/test/lib/link-link-to-globalDir-when-in-current-working-dir-of-pkg-and-no-args/test-pkg-link
diff --git a/deps/npm/test/lib/link.js b/deps/npm/test/lib/link.js
index a478259f7b409a..c39026a49163f6 100644
--- a/deps/npm/test/lib/link.js
+++ b/deps/npm/test/lib/link.js
@@ -259,6 +259,64 @@ t.test('link pkg already in global space', (t) => {
})
})
+t.test('link pkg already in global space when prefix is a symlink', (t) => {
+ t.plan(3)
+
+ const testdir = t.testdir({
+ 'global-prefix': t.fixture('symlink', './real-global-prefix'),
+ 'real-global-prefix': {
+ lib: {
+ node_modules: {
+ '@myscope': {
+ linked: t.fixture('symlink', '../../../../scoped-linked'),
+ },
+ },
+ },
+ },
+ 'scoped-linked': {
+ 'package.json': JSON.stringify({
+ name: '@myscope/linked',
+ version: '1.0.0',
+ }),
+ },
+ 'my-project': {
+ 'package.json': JSON.stringify({
+ name: 'my-project',
+ version: '1.0.0',
+ }),
+ },
+ })
+ npm.globalDir = resolve(testdir, 'global-prefix', 'lib', 'node_modules')
+ npm.prefix = resolve(testdir, 'my-project')
+
+ npm.config.find = () => 'default'
+
+ const _cwd = process.cwd()
+ process.chdir(npm.prefix)
+
+ reifyOutput = async () => {
+ reifyOutput = undefined
+ process.chdir(_cwd)
+ npm.config.find = () => null
+
+ const links = await printLinks({
+ path: npm.prefix,
+ })
+
+ t.equal(
+ require(resolve(testdir, 'my-project', 'package.json')).dependencies,
+ undefined,
+ 'should not save to package.json upon linking'
+ )
+
+ t.matchSnapshot(links, 'should create a local symlink to global pkg')
+ }
+
+ link(['@myscope/linked'], (err) => {
+ t.ifError(err, 'should not error out')
+ })
+})
+
t.test('completion', (t) => {
const testdir = t.testdir({
'global-prefix': {
diff --git a/deps/npm/test/lib/ls.js b/deps/npm/test/lib/ls.js
index 7bbfc5f772b9f6..a9504a2ad055ca 100644
--- a/deps/npm/test/lib/ls.js
+++ b/deps/npm/test/lib/ls.js
@@ -3795,6 +3795,7 @@ t.test('ls --json', (t) => {
t.deepEqual(
jsonParse(result),
{
+ name: 'ls-ls-json-global',
dependencies: {
a: {
version: '1.0.0',
diff --git a/deps/npm/test/lib/outdated.js b/deps/npm/test/lib/outdated.js
index 7a5bd8f0ef870c..da53b6031d6f93 100644
--- a/deps/npm/test/lib/outdated.js
+++ b/deps/npm/test/lib/outdated.js
@@ -131,6 +131,9 @@ t.test('should display outdated deps', t => {
devDependencies: {
zeta: '^1.0.0',
},
+ optionalDependencies: {
+ lorem: '^1.0.0',
+ },
peerDependencies: {
beta: '^1.0.0',
},
diff --git a/deps/v8/src/ast/ast-source-ranges.h b/deps/v8/src/ast/ast-source-ranges.h
index 1b42a055dd642d..1e96ec4c27c58b 100644
--- a/deps/v8/src/ast/ast-source-ranges.h
+++ b/deps/v8/src/ast/ast-source-ranges.h
@@ -47,6 +47,7 @@ struct SourceRange {
V(Block) \
V(CaseClause) \
V(Conditional) \
+ V(Expression) \
V(FunctionLiteral) \
V(IfStatement) \
V(IterationStatement) \
@@ -281,6 +282,24 @@ class NaryOperationSourceRanges final : public AstNodeSourceRanges {
ZoneVector ranges_;
};
+class ExpressionSourceRanges final : public AstNodeSourceRanges {
+ public:
+ explicit ExpressionSourceRanges(const SourceRange& right_range)
+ : right_range_(right_range) {}
+
+ SourceRange GetRange(SourceRangeKind kind) override {
+ DCHECK(HasRange(kind));
+ return right_range_;
+ }
+
+ bool HasRange(SourceRangeKind kind) override {
+ return kind == SourceRangeKind::kRight;
+ }
+
+ private:
+ SourceRange right_range_;
+};
+
class SuspendSourceRanges final : public ContinuationSourceRanges {
public:
explicit SuspendSourceRanges(int32_t continuation_position)
diff --git a/deps/v8/src/interpreter/bytecode-generator.cc b/deps/v8/src/interpreter/bytecode-generator.cc
index 87c537879c5f68..74a4f66a5626bd 100644
--- a/deps/v8/src/interpreter/bytecode-generator.cc
+++ b/deps/v8/src/interpreter/bytecode-generator.cc
@@ -4575,8 +4575,11 @@ void BytecodeGenerator::VisitThrow(Throw* expr) {
void BytecodeGenerator::VisitPropertyLoad(Register obj, Property* property) {
if (property->is_optional_chain_link()) {
DCHECK_NOT_NULL(optional_chaining_null_labels_);
+ int right_range =
+ AllocateBlockCoverageSlotIfEnabled(property, SourceRangeKind::kRight);
builder()->LoadAccumulatorWithRegister(obj).JumpIfUndefinedOrNull(
optional_chaining_null_labels_->New());
+ BuildIncrementBlockCoverageCounterIfEnabled(right_range);
}
AssignType property_kind = Property::GetAssignType(property);
@@ -4902,8 +4905,11 @@ void BytecodeGenerator::VisitCall(Call* expr) {
if (expr->is_optional_chain_link()) {
DCHECK_NOT_NULL(optional_chaining_null_labels_);
+ int right_range =
+ AllocateBlockCoverageSlotIfEnabled(expr, SourceRangeKind::kRight);
builder()->LoadAccumulatorWithRegister(callee).JumpIfUndefinedOrNull(
optional_chaining_null_labels_->New());
+ BuildIncrementBlockCoverageCounterIfEnabled(right_range);
}
// Evaluate all arguments to the function call and store in sequential args
@@ -5175,7 +5181,10 @@ void BytecodeGenerator::VisitDelete(UnaryOperation* unary) {
OptionalChainNullLabelScope label_scope(this);
VisitForAccumulatorValue(property->obj());
if (property->is_optional_chain_link()) {
+ int right_range = AllocateBlockCoverageSlotIfEnabled(
+ property, SourceRangeKind::kRight);
builder()->JumpIfUndefinedOrNull(label_scope.labels()->New());
+ BuildIncrementBlockCoverageCounterIfEnabled(right_range);
}
Register object = register_allocator()->NewRegister();
builder()->StoreAccumulatorInRegister(object);
diff --git a/deps/v8/src/parsing/parser-base.h b/deps/v8/src/parsing/parser-base.h
index 608427664961b5..863f645f781a1a 100644
--- a/deps/v8/src/parsing/parser-base.h
+++ b/deps/v8/src/parsing/parser-base.h
@@ -3289,6 +3289,7 @@ ParserBase::ParseLeftHandSideContinuation(ExpressionT result) {
bool optional_chaining = false;
bool is_optional = false;
+ int optional_link_begin;
do {
switch (peek()) {
case Token::QUESTION_PERIOD: {
@@ -3296,10 +3297,16 @@ ParserBase::ParseLeftHandSideContinuation(ExpressionT result) {
ReportUnexpectedToken(peek());
return impl()->FailureExpression();
}
+ // Include the ?. in the source range position.
+ optional_link_begin = scanner()->peek_location().beg_pos;
Consume(Token::QUESTION_PERIOD);
is_optional = true;
optional_chaining = true;
- continue;
+ if (Token::IsPropertyOrCall(peek())) continue;
+ int pos = position();
+ ExpressionT key = ParsePropertyOrPrivatePropertyName();
+ result = factory()->NewProperty(result, key, pos, is_optional);
+ break;
}
/* Property */
@@ -3379,14 +3386,7 @@ ParserBase::ParseLeftHandSideContinuation(ExpressionT result) {
}
default:
- /* Optional Property */
- if (is_optional) {
- DCHECK_EQ(scanner()->current_token(), Token::QUESTION_PERIOD);
- int pos = position();
- ExpressionT key = ParsePropertyOrPrivatePropertyName();
- result = factory()->NewProperty(result, key, pos, is_optional);
- break;
- }
+ // Template literals in/after an Optional Chain not supported:
if (optional_chaining) {
impl()->ReportMessageAt(scanner()->peek_location(),
MessageTemplate::kOptionalChainingNoTemplate);
@@ -3397,8 +3397,12 @@ ParserBase::ParseLeftHandSideContinuation(ExpressionT result) {
result = ParseTemplateLiteral(result, position(), true);
break;
}
- is_optional = false;
- } while (is_optional || Token::IsPropertyOrCall(peek()));
+ if (is_optional) {
+ SourceRange chain_link_range(optional_link_begin, end_position());
+ impl()->RecordExpressionSourceRange(result, chain_link_range);
+ is_optional = false;
+ }
+ } while (Token::IsPropertyOrCall(peek()));
if (optional_chaining) return factory()->NewOptionalChain(result);
return result;
}
diff --git a/deps/v8/src/parsing/parser.h b/deps/v8/src/parsing/parser.h
index 46abe16d4fc9c1..1633de604099eb 100644
--- a/deps/v8/src/parsing/parser.h
+++ b/deps/v8/src/parsing/parser.h
@@ -997,6 +997,14 @@ class V8_EXPORT_PRIVATE Parser : public NON_EXPORTED_BASE(ParserBase) {
node, zone()->New(body_range));
}
+ // Used to record source ranges of expressions associated with optional chain:
+ V8_INLINE void RecordExpressionSourceRange(Expression* node,
+ const SourceRange& right_range) {
+ if (source_range_map_ == nullptr) return;
+ source_range_map_->Insert(node,
+ zone()->New(right_range));
+ }
+
V8_INLINE void RecordSuspendSourceRange(Expression* node,
int32_t continuation_position) {
if (source_range_map_ == nullptr) return;
diff --git a/deps/v8/test/mjsunit/code-coverage-block.js b/deps/v8/test/mjsunit/code-coverage-block.js
index 4584f3134a90db..e9d38d71466a9b 100644
--- a/deps/v8/test/mjsunit/code-coverage-block.js
+++ b/deps/v8/test/mjsunit/code-coverage-block.js
@@ -1177,7 +1177,7 @@ a(true); // 0500
{"start":0,"end":401,"count":2},
{"start":154,"end":254,"count":0}]);
- TestCoverage(
+TestCoverage(
"https://crbug.com/v8/11231 - nullish coalescing",
`
const a = true // 0000
@@ -1195,4 +1195,41 @@ const i = c ?? b ?? 'hello' // 0400
{"start":262,"end":274,"count":0},
{"start":417,"end":427,"count":0}]);
+TestCoverage(
+"Optional Chaining",
+`
+const a = undefined || null // 0000
+const b = a?.b // 0050
+const c = a?.['b'] // 0100
+const d = { // 0150
+ e: {f: 99, g: () => {return undefined}} // 0200
+} // 0250
+const e = d?.e?.f // 0300
+const f = d?.e?.['f'] // 0350
+const g = d?.e?.f?.g // 0400
+const h = d?.e?.f?.g?.h // 0450
+const i = d?.['d']?.['e']?.['h'] // 0500
+const k = a?.('b') // 0550
+const l = d?.e?.g?.() // 0600
+const m = d?.e?.g?.()?.a?.b // 0650
+delete a?.b // 0700
+const n = d?.[d?.x?.f] // 0750
+if (a?.[d?.x?.f]) { const p = 99 } else {}// 0800
+const p = d?.[d?.x?.f]?.x // 0850
+`,
+[{"start":0,"end":899,"count":1},
+ {"start":61,"end":64,"count":0},
+ {"start":111,"end":118,"count":0},
+ {"start":470,"end":473,"count":0},
+ {"start":518,"end":532,"count":0},
+ {"start":561,"end":568,"count":0},
+ {"start":671,"end":677,"count":0},
+ {"start":708,"end":711,"count":0},
+ {"start":768,"end":771,"count":0},
+ {"start":805,"end":816,"count":0},
+ {"start":818,"end":834,"count":0},
+ {"start":868,"end":871,"count":0},
+ {"start":872,"end":875,"count":0},
+ {"start":216,"end":240,"count":2}]);
+
%DebugToggleBlockCoverage(false);
diff --git a/doc/api/buffer.md b/doc/api/buffer.md
index 765aa2dd088e84..d04650ba09ea12 100644
--- a/doc/api/buffer.md
+++ b/doc/api/buffer.md
@@ -50,6 +50,9 @@ const buf7 = Buffer.from('tést', 'latin1');
## Buffers and character encodings
+
+> Stability: 1 - Experimental
+
+A [`Blob`][] encapsulates immutable, raw data that can be safely shared across
+multiple worker threads.
+
+### `new buffer.Blob([sources[, options]])`
+
+
+* `sources` {string[]|ArrayBuffer[]|TypedArray[]|DataView[]|Blob[]} An array
+ of string, {ArrayBuffer}, {TypedArray}, {DataView}, or {Blob} objects, or
+ any mix of such objects, that will be stored within the `Blob`.
+* `options` {Object}
+ * `encoding` {string} The character encoding to use for string sources.
+ **Default**: `'utf8'`.
+ * `type` {string} The Blob content-type. The intent is for `type` to convey
+ the MIME media type of the data, however no validation of the type format
+ is performed.
+
+Creates a new `Blob` object containing a concatenation of the given sources.
+
+{ArrayBuffer}, {TypedArray}, {DataView}, and {Buffer} sources are copied into
+the 'Blob' and can therefore be safely modified after the 'Blob' is created.
+
+String sources are also copied into the `Blob`.
+
+### `blob.arrayBuffer()`
+
+
+* Returns: {Promise}
+
+Returns a promise that fulfills with an {ArrayBuffer} containing a copy of
+the `Blob` data.
+
+### `blob.size`
+
+
+The total size of the `Blob` in bytes.
+
+### `blob.slice([start, [end, [type]]])`
+
+
+* `start` {number} The starting index.
+* `end` {number} The ending index.
+* `type` {string} The content-type for the new `Blob`
+
+Creates and returns a new `Blob` containing a subset of this `Blob` objects
+data. The original `Blob` is not alterered.
+
+### `blob.text()`
+
+
+* Returns: {Promise}
+
+Returns a promise that resolves the contents of the `Blob` decoded as a UTF-8
+string.
+
+### `blob.type`
+
+
+* Type: {string}
+
+The content-type of the `Blob`.
+
+### `Blob` objects and `MessageChannel`
+
+Once a {Blob} object is created, it can be sent via `MessagePort` to multiple
+destinations without transfering or immediately copying the data. The data
+contained by the `Blob` is copied only when the `arrayBuffer()` or `text()`
+methods are called.
+
+```js
+const { Blob } = require('buffer');
+const blob = new Blob(['hello there']);
+const { setTimeout: delay } = require('timers/promises');
+
+const mc1 = new MessageChannel();
+const mc2 = new MessageChannel();
+
+mc1.port1.onmessage = async ({ data }) => {
+ console.log(await data.arrayBuffer());
+ mc1.port1.close();
+};
+
+mc2.port1.onmessage = async ({ data }) => {
+ await delay(1000);
+ console.log(await data.arrayBuffer());
+ mc2.port1.close();
+};
+
+mc1.port2.postMessage(blob);
+mc2.port2.postMessage(blob);
+
+// The Blob is still usable after posting.
+data.text().then(console.log);
+```
+
## Class: `Buffer`
The `Buffer` class is a global type for dealing with binary data directly.
@@ -482,9 +603,10 @@ Returns the byte length of a string when encoded using `encoding`.
This is not the same as [`String.prototype.length`][], which does not account
for the encoding that is used to convert the string into bytes.
-For `'base64'` and `'hex'`, this function assumes valid input. For strings that
-contain non-base64/hex-encoded data (e.g. whitespace), the return value might be
-greater than the length of a `Buffer` created from the string.
+For `'base64'`, `'base64url'`, and `'hex'`, this function assumes valid input.
+For strings that contain non-base64/hex-encoded data (e.g. whitespace), the
+return value might be greater than the length of a `Buffer` created from the
+string.
```js
const str = '\u00bd + \u00bc = \u00be';
@@ -3380,6 +3502,7 @@ introducing security vulnerabilities into an application.
[UTF-8]: https://en.wikipedia.org/wiki/UTF-8
[WHATWG Encoding Standard]: https://encoding.spec.whatwg.org/
[`ArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer
+[`Blob`]: https://developer.mozilla.org/en-US/docs/Web/API/Blob
[`Buffer.alloc()`]: #buffer_static_method_buffer_alloc_size_fill_encoding
[`Buffer.allocUnsafe()`]: #buffer_static_method_buffer_allocunsafe_size
[`Buffer.allocUnsafeSlow()`]: #buffer_static_method_buffer_allocunsafeslow_size
@@ -3418,6 +3541,7 @@ introducing security vulnerabilities into an application.
[`buffer.constants.MAX_STRING_LENGTH`]: #buffer_buffer_constants_max_string_length
[`buffer.kMaxLength`]: #buffer_buffer_kmaxlength
[`util.inspect()`]: util.md#util_util_inspect_object_options
+[base64url]: https://tools.ietf.org/html/rfc4648#section-5
[binary strings]: https://developer.mozilla.org/en-US/docs/Web/API/DOMString/Binary
[endianness]: https://en.wikipedia.org/wiki/Endianness
[iterator]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols
diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index 797e17bdecb20a..7a8007ba90d147 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -1284,6 +1284,25 @@ passing keys as strings or `Buffer`s due to improved security features.
The receiver obtains a cloned `KeyObject`, and the `KeyObject` does not need to
be listed in the `transferList` argument.
+### `keyObject.asymmetricKeyDetails`
+
+
+* {Object}
+ * `modulusLength`: {number} Key size in bits (RSA, DSA).
+ * `publicExponent`: {bigint} Public exponent (RSA).
+ * `divisorLength`: {number} Size of `q` in bits (DSA).
+ * `namedCurve`: {string} Name of the curve (EC).
+
+This property exists only on asymmetric keys. Depending on the type of the key,
+this object contains information about the key. None of the information obtained
+through this property can be used to uniquely identify a key or to compromise
+the security of the key.
+
+RSA-PSS parameters, DH, or any future key type details might be exposed via this
+API using additional attributes.
+
### `keyObject.asymmetricKeyType`
Encapsulates an X509 certificate and provides read-only access to
-it's information.
+its information.
```js
const { X509Certificate } = require('crypto');
@@ -2490,7 +2509,7 @@ added: v15.0.0
* If `type` is `'hmac'`, the minimum is 1, and the maximum length is
231 -1. If the value is not a multiple of 8, the generated
key will be truncated to `Math.floor(length / 8)`.
- * If `type` is `'aes'`, the length must be one of `128` or `256`.
+ * If `type` is `'aes'`, the length must be one of `128`, `192`, or `256`.
* `callback`: {Function}
* `err`: {Error}
* `key`: {KeyObject}
@@ -2519,7 +2538,7 @@ added: v15.0.0
* If `type` is `'hmac'`, the minimum is 1, and the maximum length is
231 -1. If the value is not a multiple of 8, the generated
key will be truncated to `Math.floor(length / 8)`.
- * If `type` is `'aes'`, the length must be one of `128` or `256`.
+ * If `type` is `'aes'`, the length must be one of `128`, `192`, or `256`.
* Returns: {KeyObject}
Synchronously generates a new random secret key of the given `length`. The
diff --git a/doc/api/documentation.md b/doc/api/documentation.md
index 979d85ef0a3005..d39aa30438aefc 100644
--- a/doc/api/documentation.md
+++ b/doc/api/documentation.md
@@ -43,6 +43,9 @@ Bugs or behavior changes may surprise users when Experimental API
modifications occur. To avoid surprises, use of an Experimental feature may need
a command-line flag. Experimental features may also emit a [warning][].
+## Stability overview
+
+
## JSON output
+
+* {http.IncomingMessage}
+
+A reference to the original HTTP `request` object.
+
### `response.sendDate`
@@ -1957,7 +1957,7 @@ the request body.
When this event is emitted and handled, the [`'request'`][] event will
not be emitted.
-### Event: `'connection'`
+#### Event: `'connection'`
@@ -3437,6 +3437,15 @@ Removes a header that has been queued for implicit sending.
response.removeHeader('Content-Encoding');
```
+### `response.req`
+
+
+* {http2.Http2ServerRequest}
+
+A reference to the original HTTP2 `request` object.
+
#### `response.sendDate`
-
-* Type: {boolean} `true` if the module is running during the Node.js preload
- phase.
-
### `module.syncBuiltinESMExports()`
+
+* Type: {boolean} `true` if the module is running during the Node.js preload
+ phase.
+
### `module.loaded`
-* `percentile` {number} A percentile value between 1 and 100.
+* `percentile` {number} A percentile value in the range (0, 100].
* Returns: {number}
Returns the value at the given percentile.
diff --git a/doc/api/tls.md b/doc/api/tls.md
index bedf4e28e7bc04..2c8414f2988c9c 100644
--- a/doc/api/tls.md
+++ b/doc/api/tls.md
@@ -627,6 +627,9 @@ added: v0.5.3
The `server.addContext()` method adds a secure context that will be used if
the client request's SNI name matches the supplied `hostname` (or wildcard).
+When there are multiple matching contexts, the most recently added one is
+used.
+
### `server.address()`
+
+* `url` {URL} The [WHATWG URL][] object to convert to an options object.
+* Returns: {Object} Options object
+ * `protocol` {string} Protocol to use.
+ * `hostname` {string} A domain name or IP address of the server to issue the
+ request to.
+ * `hash` {string} The fragment portion of the URL.
+ * `search` {string} The serialized query portion of the URL.
+ * `pathname` {string} The path portion of the URL.
+ * `path` {string} Request path. Should include query string if any.
+ E.G. `'/index.html?page=12'`. An exception is thrown when the request path
+ contains illegal characters. Currently, only spaces are rejected but that
+ may change in the future.
+ * `href` {string} The serialized URL.
+ * `port` {number} Port of remote server.
+ * `auth` {string} Basic authentication i.e. `'user:password'` to compute an
+ Authorization header.
+
+This utility function converts a URL object into an ordinary options object as
+expected by the [`http.request()`][] and [`https.request()`][] APIs.
+
+```js
+const { urlToHttpOptions } = require('url');
+const myURL = new URL('https://a:b@測試?abc#foo');
+
+console.log(urlToHttpOptions(myUrl));
+/**
+{
+ protocol: 'https:',
+ hostname: 'xn--g6w251d',
+ hash: '#foo',
+ search: '?abc',
+ pathname: '/',
+ path: '/?abc',
+ href: 'https://a:b@xn--g6w251d/?abc#foo',
+ auth: 'a:b'
+}
+*/
+```
+
## Legacy URL API
-
-* **Version**:
-* **Platform**:
-* **Subsystem**:
-
-
-```
-
-If you believe that you have uncovered a bug in Node.js, please fill out this
-form, following the template to the best of your ability. Do not worry if you
-cannot answer every detail, just fill in what you can.
+presented with a choice of issue templates. If you believe that you have
+uncovered a bug in Node.js, please fill out the `Bug Report` template to the
+best of your ability. Do not worry if you cannot answer every detail; just fill
+in what you can.
The two most important pieces of information we need in order to properly
evaluate the report is a description of the behavior you are seeing and a simple
@@ -105,13 +60,5 @@ activities, such as applying labels and closing/reopening/assigning issues.
For more information on the roles and permissions, see ["Permission levels for
repositories owned by an organization"](https://docs.github.com/en/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization#permission-levels-for-repositories-owned-by-an-organization).
-## Resolving a Bug Report
-
-In the vast majority of cases, issues are resolved by opening a Pull Request.
-The process for opening and reviewing a Pull Request is similar to that of
-opening and triaging issues, but carries with it a necessary review and approval
-workflow that ensures that the proposed changes meet the minimal quality and
-functional guidelines of the Node.js project.
-
[Node.js help repository]: https://github.com/nodejs/help/issues
[Technical Steering Committee (TSC) repository]: https://github.com/nodejs/TSC/issues
diff --git a/doc/guides/contributing/pull-requests.md b/doc/guides/contributing/pull-requests.md
index 4ca1df219bb941..8ec694cb949962 100644
--- a/doc/guides/contributing/pull-requests.md
+++ b/doc/guides/contributing/pull-requests.md
@@ -1,10 +1,5 @@
# Pull Requests
-There are two fundamental components of the Pull Request process: one concrete
-and technical, and one more process oriented. The concrete and technical
-component involves the specific details of setting up your local environment
-so that you can make the actual changes. This is where we will start.
-
* [Dependencies](#dependencies)
* [Setting up your local environment](#setting-up-your-local-environment)
* [Step 1: Fork](#step-1-fork)
diff --git a/doc/guides/maintaining-icu.md b/doc/guides/maintaining-icu.md
index 4b0c413c3f9fcb..f98e129c5a86df 100644
--- a/doc/guides/maintaining-icu.md
+++ b/doc/guides/maintaining-icu.md
@@ -158,7 +158,7 @@ process.versions.icu;
new Intl.DateTimeFormat('es', { month: 'long' }).format(new Date(9E8));
```
-(This should print your updated ICU version number, and also `January` again.)
+(This should print your updated ICU version number, and also `enero` again.)
You are ready to check in the updated `deps/icu-small`. This is a big commit,
so make this a separate commit from the smaller changes.
diff --git a/doc/template.html b/doc/template.html
index d7cc96062eaf6a..51f3738e1be15a 100644
--- a/doc/template.html
+++ b/doc/template.html
@@ -55,10 +55,10 @@ Node.js __VERSION__ Documentation
-
Table of Contents
+
+ Table of Contents
__TOC__
-
+
__CONTENT__
@@ -66,8 +66,7 @@
Table of Contents