npm-package-arg
Parses package name and specifier passed to commands like npm install
or
npm cache add
, or as found in package.json
dependency sections.
EXAMPLES
var assert = require("assert")
var npa = require("npm-package-arg")
// Pass in the descriptor, and it'll return an object
try {
var parsed = npa("@bar/[email protected]")
} catch (ex) {
…
}
USING
var npa = require('npm-package-arg')
var result = npa(arg[, where])
- arg - a string that you might pass to
npm install
, like:[email protected]
,@bar/[email protected]
,foo@user/foo
,http://x.com/foo.tgz
,git+https://github.com/user/foo
,bitbucket:user/foo
,foo.tar.gz
,../foo/bar/
orbar
. If the arg you provide doesn't have a specifier part, egfoo
then the specifier will default tolatest
. - where - Optionally the path to resolve file paths relative to. Defaults to
process.cwd()
Throws if the package name is invalid, a dist-tag is invalid or a URL's protocol is not supported.
var result = npa.resolve(name, spec[, where])
- name - The name of the module you want to install. For example:
foo
or@bar/foo
. - spec - The specifier indicating where and how you can get this module. Something like:
1.2
,^1.7.17
,http://x.com/foo.tgz
,git+https://github.com/user/foo
,bitbucket:user/foo
,file:foo.tar.gz
orfile:../foo/bar/
. If not included then the default islatest
. - where - Optionally the path to resolve file paths relative to. Defaults to
process.cwd()
Throws if the package name is invalid, a dist-tag is invalid or a URL's protocol is not supported.
var purl = npa.toPurl(arg, reg)
Returns the purl (package URL) form of the given pacakge name/spec.
- arg - A package/version string. For example:
[email protected]
or@bar/[email protected]
. - reg - Optionally the URL to the package registry. If not specified, assumes the default
https://registry.npmjs.org
.
Throws if the package name is invalid, or the supplied arg can't be resolved to a purl.
RESULT OBJECT
The objects that are returned by npm-package-arg contain the following keys:
type
- One of the following strings:git
- A git repotag
- A tagged version, like"foo@latest"
version
- A specific version number, like"[email protected]"
range
- A version range, like"[email protected]"
file
- A local.tar.gz
,.tar
or.tgz
file.directory
- A local directory.remote
- An http url (presumably to a tgz)alias
- A specifier with an alias, likemyalias@npm:[email protected]
registry
- If true this specifier refers to a resource hosted on a registry. This is true fortag
,version
andrange
types.name
- If known, thename
field expected in the resulting pkg.scope
- If a name is something like@org/module
then thescope
field will be set to@org
. If it doesn't have a scoped name, then scope isnull
.escapedName
- A version ofname
escaped to match the npm scoped packages specification. Mostly used when making requests against a registry. Whenname
isnull
,escapedName
will also benull
.rawSpec
- The specifier part that was parsed out in calls tonpa(arg)
, or the value ofspec
in calls to `npa.resolve(name, spec).saveSpec
- The normalized specifier, for saving to package.json files.null
for registry dependencies.fetchSpec
- The version of the specifier to be used to fetch this resource.null
for shortcuts to hosted git dependencies as there isn't just one URL to try with them.gitRange
- If set, this is a semver specifier to match against git tags withgitCommittish
- If set, this is the specific committish to use with a git dependency.hosted
- Iffrom === 'hosted'
then this will be ahosted-git-info
object. This property is not included when serializing the object as JSON.raw
- The original un-modified string that was provided. If called asnpa.resolve(name, spec)
then this will bename + '@' + spec
.subSpec
- Iftype === 'alias'
, this is a Result Object for parsing the target specifier for the alias.