npm-pick-manifest
Advanced tools
Resolves a matching manifest from a package metadata document according to standard npm semver resolution rules.
The npm-pick-manifest package is designed to help users select a specific package version from a registry metadata object based on a desired version range. It is particularly useful for automating package selection tasks in package management and deployment scripts, ensuring that the most appropriate version of a package is selected according to semantic versioning rules.
Selecting a package version
This feature allows users to input a package metadata object and a version range. The function then returns the metadata for the version that best matches the range according to semantic versioning. This is particularly useful for resolving dependencies in package management.
const pickManifest = require('npm-pick-manifest');
const metadata = {
'name': 'some-package',
'versions': {
'1.0.0': {},
'1.2.0': {},
'2.0.0': {}
}
};
const range = '^1.0.0';
const selected = pickManifest(metadata, range);
console.log(selected.version); // Outputs: '1.2.0'The semver package is a module for semantic versioning comparison. While npm-pick-manifest focuses on selecting a package version from a metadata object, semver provides a broader set of utilities for comparing versions, checking ranges, and more. It's more general-purpose compared to the specific use case addressed by npm-pick-manifest.
Pacote is a package fetching library that supports the entire package lifecycle, from resolving and fetching to extracting packages. While it includes functionality for selecting package versions similar to npm-pick-manifest, it is a more comprehensive tool that handles many aspects of package management beyond just version selection.
npm-pick-manifest is a standalone
implementation of npm's semver range resolution algorithm.
$ npm install --save npm-pick-manifest
const pickManifest = require('npm-pick-manifest')
fetch('https://registry.npmjs.org/npm-pick-manifest').then(res => {
return res.json()
}).then(packument => {
return pickManifest(packument, '^1.0.0')
}) // get same manifest as npm would get if you `npm i npm-pick-manifest@^1.0.0`
engines requirements are satisfied over those
that will raise a warning or error at install time.> pickManifest(packument, selector, [opts]) -> manifestReturns the manifest that best matches selector, or throws an error.
Packuments are anything returned by metadata URLs from the npm registry. That
is, they're objects with the following shape (only fields used by
npm-pick-manifest included):
{
name: 'some-package',
'dist-tags': {
foo: '1.0.1'
},
versions: {
'1.0.0': { version: '1.0.0' },
'1.0.1': { version: '1.0.1' },
'1.0.2': { version: '1.0.2' },
'2.0.0': { version: '2.0.0' }
}
}
The algorithm will follow npm's algorithm for semver resolution, and only
tag, range, and version selectors are supported.
The function will throw ETARGET if there was no matching manifest, and
ENOVERSIONS if the packument object has no valid versions in versions.
If the only matching manifest is included in a policyRestrictions section
of the packument, then an E403 is raised.
All options are optional.
includeStaged - Boolean, default false. Include manifests in the
stagedVersions.versions set, to support installing staged
packages when appropriate. Note
that staged packages are always treated as lower priority than actual
publishes, even when includeStaged is set.defaultTag - String, default 'latest'. The default dist-tag to
install when no specifier is provided. Note that the version indicated
by this specifier will be given top priority if it matches a supplied
semver range.before - String, Date, or Number, default null. This is passed to
new Date(), so anything that works there will be valid. Do not
consider any manifests that were published after the date indicated.
Note that this is only relevant when the packument includes a time
field listing the publish date of all the packages.nodeVersion - String, default process.version. The Node.js version
to use when checking manifests for engines requirement satisfaction.npmVersion - String, default null. The npm version to use when
checking manifest for engines requirement satisfaction. (If null,
then this particular check is skipped.)avoid - String, default null. A SemVer range of
versions that should be avoided. An avoided version MAY be selected if
there is no other option, so when using this for version selection ensure
that you check the result against the range to see if there was no
alternative available.avoidStrict Boolean, default false. If set to true, then
pickManifest will never return a version in the avoid range. If the
only available version in the wanted range is a version that should be
avoided, then it will return a version outside the wanted range,
preferring to do so without making a SemVer-major jump, if possible. If
there are no versions outside the avoid range, then throw an
ETARGET error. It does this by calling pickManifest first with the
wanted range, then with a ^ affixed to the version returned by the
wanted range, and then with a * version range, and throwing if
nothing could be found to satisfy the avoidance request.Return value is the manifest as it exists in the packument, possibly decorated with the following boolean flags:
_shouldAvoid The version is in the avoid range. Watch out!_outsideDependencyRange The version is outside the wanted range,
because avoidStrict: true was set._isSemVerMajor The _outsideDependencyRange result is a SemVer-major
step up from the version returned by the wanted range.versions,
policyRestrictions.versions, and (if includeStaged is set)
stagedVersions.versions.dist-tag is requested,
before date, then
select that from the set.before date, then re-start
the selection looking for the highest SemVer range that is equal to
or less than the dist-tag target.before date, then
select the specified manifest.before date, then raise
ETARGET error. (NB: this is a breaking change from v5, where a
specified version would override the before setting.)defaultTag refers to a dist-tag that satisfies the range (or
if the range is '*' or ''), and the manifest is published before the
before setting, then select that manifest.avoid range over those
that are.policyRestrictions over those
that are.ETARGET error.policyRestrictions.versions list, raise
an E403 error.FAQs
Resolves a matching manifest from a package metadata document according to standard npm semver resolution rules.
The npm package npm-pick-manifest receives a total of 6,284,560 weekly downloads. As such, npm-pick-manifest popularity was classified as popular.
We found that npm-pick-manifest demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 6 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.
Security News
vlt introduced its new package manager and a serverless registry this week, innovating in a space where npm has stagnated.