npm-pick-manifest

What is npm-pick-manifest?

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.

What are npm-pick-manifest's main functionalities?

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'

Other packages similar to npm-pick-manifest

semver

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

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.

README

npm-pick-manifest

npm-pick-manifest is a standalone implementation of npm's semver range resolution algorithm.

Install

$ npm install --save npm-pick-manifest

Table of Contents

• Example
• Features
• API
  • pickManifest()

Example

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`

Features

• Uses npm's exact semver resolution algorithm.
• Supports ranges, tags, and versions.
• Prefers non-deprecated versions to deprecated versions.
• Prefers versions whose engines requirements are satisfied over those that will raise a warning or error at install time.

API

> pickManifest(packument, selector, [opts]) -> manifest

Returns 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.

Options

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.

Algorithm

1. Create list of all versions in versions, policyRestrictions.versions, and (if includeStaged is set) stagedVersions.versions.
2. If a dist-tag is requested,
   1. If the manifest is not after the specified before date, then select that from the set.
   2. If the manifest is after the specified before date, then re-start the selection looking for the highest SemVer range that is equal to or less than the dist-tag target.
3. If a specific version is requested,
   1. If the manifest is not after the specified before date, then select the specified manifest.
   2. If the manifest is after the specified before date, then raise ETARGET error. (NB: this is a breaking change from v5, where a specified version would override the before setting.)
4. (At this point we know a range is requested.)
5. If the 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.
6. If nothing is yet selected, sort by the following heuristics in order, and select the top item:
   1. Prioritize versions that are not in the avoid range over those that are.
   2. Prioritize versions that are not in policyRestrictions over those that are.
   3. Prioritize published versions over staged versions.
   4. Prioritize versions that are not deprecated, and which have a satisfied engines requirement, over those that are either deprecated or have an engines mismatch.
   5. Prioritize versions that have a satisfied engines requirement over those that do not.
   6. Prioritize versions that are not are not deprecated (but have a mismatched engines requirement) over those that are deprecated.
   7. Prioritize higher SemVer precedence over lower SemVer precedence.
7. If no manifest was selected, raise an ETARGET error.
8. If the selected item is in the policyRestrictions.versions list, raise an E403 error.
9. Return the selected manifest.

Changelog

9.1.0 (2024-07-09)

Features

• 9f5560f #33 improve heuristics when dist-tags.latest is in range (#33) (@isaacs)