1# npm-package-arg
2
3[![Build Status](https://travis-ci.org/npm/npm-package-arg.svg?branch=master)](https://travis-ci.org/npm/npm-package-arg)
4
5Parses package name and specifier passed to commands like `npm install` or
6`npm cache add`, or as found in `package.json` dependency sections.
7
8## EXAMPLES
9
10```javascript
11var assert = require("assert")
12var npa = require("npm-package-arg")
13
14// Pass in the descriptor, and it'll return an object
15try {
16  var parsed = npa("@bar/foo@1.2")
17} catch (ex) {
18  …
19}
20```
21
22## USING
23
24`var npa = require('npm-package-arg')`
25
26### var result = npa(*arg*[, *where*])
27
28* *arg* - a string that you might pass to `npm install`, like:
29`foo@1.2`, `@bar/foo@1.2`, `foo@user/foo`, `http://x.com/foo.tgz`,
30`git+https://github.com/user/foo`, `bitbucket:user/foo`, `foo.tar.gz`,
31`../foo/bar/` or `bar`.  If the *arg* you provide doesn't have a specifier
32part, eg `foo` then the specifier will default to `latest`.
33* *where* - Optionally the path to resolve file paths relative to. Defaults to `process.cwd()`
34
35**Throws** if the package name is invalid, a dist-tag is invalid or a URL's protocol is not supported.
36
37### var result = npa.resolve(*name*, *spec*[, *where*])
38
39* *name* - The name of the module you want to install. For example: `foo` or `@bar/foo`.
40* *spec* - The specifier indicating where and how you can get this module. Something like:
41`1.2`, `^1.7.17`, `http://x.com/foo.tgz`, `git+https://github.com/user/foo`,
42`bitbucket:user/foo`, `file:foo.tar.gz` or `file:../foo/bar/`.  If not
43included then the default is `latest`.
44* *where* - Optionally the path to resolve file paths relative to. Defaults to `process.cwd()`
45
46**Throws** if the package name is invalid, a dist-tag is invalid or a URL's protocol is not supported.
47
48## RESULT OBJECT
49
50The objects that are returned by npm-package-arg contain the following
51keys:
52
53* `type` - One of the following strings:
54  * `git` - A git repo
55  * `tag` - A tagged version, like `"foo@latest"`
56  * `version` - A specific version number, like `"foo@1.2.3"`
57  * `range` - A version range, like `"foo@2.x"`
58  * `file` - A local `.tar.gz`, `.tar` or `.tgz` file.
59  * `directory` - A local directory.
60  * `remote` - An http url (presumably to a tgz)
61* `registry` - If true this specifier refers to a resource hosted on a
62  registry.  This is true for `tag`, `version` and `range` types.
63* `name` - If known, the `name` field expected in the resulting pkg.
64* `scope` - If a name is something like `@org/module` then the `scope`
65  field will be set to `@org`.  If it doesn't have a scoped name, then
66  scope is `null`.
67* `escapedName` - A version of `name` escaped to match the npm scoped packages
68  specification. Mostly used when making requests against a registry. When
69  `name` is `null`, `escapedName` will also be `null`.
70* `rawSpec` - The specifier part that was parsed out in calls to `npa(arg)`,
71  or the value of `spec` in calls to `npa.resolve(name, spec).
72* `saveSpec` - The normalized specifier, for saving to package.json files.
73  `null` for registry dependencies.
74* `fetchSpec` - The version of the specifier to be used to fetch this
75  resource.  `null` for shortcuts to hosted git dependencies as there isn't
76  just one URL to try with them.
77* `gitRange` - If set, this is a semver specifier to match against git tags with
78* `gitCommittish` - If set, this is the specific committish to use with a git dependency.
79* `hosted` - If `from === 'hosted'` then this will be a `hosted-git-info`
80  object. This property is not included when serializing the object as
81  JSON.
82* `raw` - The original un-modified string that was provided.  If called as
83  `npa.resolve(name, spec)` then this will be `name + '@' + spec`.
84