npm-package-arg

What is npm-package-arg?

The npm-package-arg package is a utility for parsing package names and specifiers in the npm ecosystem. It helps in understanding and manipulating package references, whether they are simple names, version ranges, GitHub URLs, or local paths.

What are npm-package-arg's main functionalities?

Parsing Package Names

This feature allows you to parse a simple package name. The output will be an object containing details about the package, such as its name, type, and registry.

const npa = require('npm-package-arg');
const parsed = npa('express');
console.log(parsed);

Parsing Version Ranges

This feature allows you to parse a package name with a version range. The output will include the specified version range and other details.

const npa = require('npm-package-arg');
const parsed = npa('express@^4.0.0');
console.log(parsed);

Parsing GitHub URLs

This feature allows you to parse a GitHub URL. The output will include details about the repository, such as the user and repo names.

const npa = require('npm-package-arg');
const parsed = npa('github:user/repo');
console.log(parsed);

Parsing Local Paths

This feature allows you to parse a local file path. The output will include details about the local path and the type of reference.

const npa = require('npm-package-arg');
const parsed = npa('file:./local-package');
console.log(parsed);

Other packages similar to npm-package-arg

validate-npm-package-name

The validate-npm-package-name package is used to validate whether a string is a valid npm package name. Unlike npm-package-arg, it focuses solely on validation and does not parse version ranges, URLs, or paths.

semver

The semver package is used for parsing, validating, and comparing semantic versioning strings. While npm-package-arg can parse version ranges as part of a package specifier, semver provides more comprehensive tools for working with version numbers.

npm-registry-fetch

The npm-registry-fetch package is used to make requests to the npm registry. It can fetch package metadata and tarballs. While npm-package-arg helps in parsing package specifiers, npm-registry-fetch is focused on interacting with the npm registry.

README

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/foo@1.2")
} 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: foo@1.2, @bar/foo@1.2, foo@user/foo, http://x.com/foo.tgz, git+https://github.com/user/foo, bitbucket:user/foo, foo.tar.gz, ../foo/bar/ or bar. If the arg you provide doesn't have a specifier part, eg foo then the specifier will default to latest.
• 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 or file:../foo/bar/. If not included then the default is latest.
• 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 package name/spec.

• arg - A package/version string. For example: foo@1.0.0 or @bar/foo@2.0.0-alpha.1.
• 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 repo
  • tag - A tagged version, like "foo@latest"
  • version - A specific version number, like "foo@1.2.3"
  • range - A version range, like "foo@2.x"
  • 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, like myalias@npm:foo@1.2.3
• registry - If true this specifier refers to a resource hosted on a registry. This is true for tag, version and range types.
• name - If known, the name field expected in the resulting pkg.
• scope - If a name is something like @org/module then the scope field will be set to @org. If it doesn't have a scoped name, then scope is null.
• escapedName - A version of name escaped to match the npm scoped packages specification. Mostly used when making requests against a registry. When name is null, escapedName will also be null.
• rawSpec - The specifier part that was parsed out in calls to npa(arg), or the value of spec 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 with
• gitCommittish - If set, this is the specific committish to use with a git dependency.
• hosted - If from === 'hosted' then this will be a hosted-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 as npa.resolve(name, spec) then this will be name + '@' + spec.
• subSpec - If type === 'alias', this is a Result Object for parsing the target specifier for the alias.

Changelog

12.0.0 (2024-09-25)

⚠️ BREAKING CHANGES

• npm-package-arg now supports node ^18.17.0 || >=20.5.0

Bug Fixes

• 6bf84db #194 align to npm 10 node engine range (@reggi)

Dependencies

• 3361e59 #194 validate-npm-package-name@6.0.0
• 06e3bd6 #194 proc-log@5.0.0
• 96dd671 #194 hosted-git-info@8.0.0

Chores

• 163925e #194 run template-oss-apply (@reggi)
• a8a9bdd #190 bump @npmcli/eslint-config from 4.0.5 to 5.0.0 (@dependabot[bot])
• f8d32ec #188 postinstall for dependabot template-oss PR (@hashtagchris)
• a867f96 #188 bump @npmcli/template-oss from 4.23.1 to 4.23.3 (@dependabot[bot])