List Matching (Min/Max Satisfying)

Relevant source files

The following files were used as context for generating this wiki page:

• ranges/max-satisfying.js
• ranges/min-satisfying.js
• semver.js
• index.js
• README.md
• test/ranges/max-satisfying.js
• test/ranges/min-satisfying.js

Introduction

List Matching in the node-semver project refers to the utility functions designed to filter a collection of semantic versions against a specific range and identify the single most appropriate version. Specifically, the project provides maxSatisfying to find the highest version that meets range criteria and minSatisfying to find the lowest. These functions are essential for dependency resolution where multiple valid versions might exist in a registry or local cache.

Sources: README.md:310-313, index.js:46-47

Architecture and Logic

The list matching system operates by iterating through an array of version strings, parsing them, and testing them against a compiled Range object. The logic is encapsulated in two primary modules that share a nearly identical structural pattern but differ in their comparison direction.

Core Components

• Versions Array: A list of strings or SemVer objects to be evaluated.
• Range Object: A compiled set of comparators derived from a range string (e.g., ^1.2.3).
• Options Object: Configuration for parsing, including loose mode and includePrerelease flags.

Sources: ranges/max-satisfying.js:6-9, ranges/min-satisfying.js:6-9

Logic Flow

Both functions follow this execution path:

1. Initialize a Range object using the provided range string and options.
2. Iterate through each version in the input array.
3. Test if the current version satisfies the range using rangeObj.test(v).
4. If satisfied, compare the version against the current "best" version stored.
5. Update the "best" version if the new version is higher (for max) or lower (for min).

The diagram shows the iterative process used by both satisfying functions to filter and select a version from a list.
Sources: ranges/max-satisfying.js:13-25, ranges/min-satisfying.js:13-25

Functions and API

maxSatisfying

The maxSatisfying function identifies the highest version in a list that meets the range requirements. If no versions satisfy the range, it returns null.

Parameter	Type	Description
versions	Array	List of version strings or SemVer objects.
range	String/Range	The range to match against.
options	Object	(Optional) Configuration including loose or includePrerelease.

Sources: ranges/max-satisfying.js:5, semver.js:1146-1165

minSatisfying

The minSatisfying function identifies the lowest version in a list that meets the range requirements. This is often used to resolve the most conservative dependency possible.

Parameter	Type	Description
versions	Array	List of version strings or SemVer objects.
range	String/Range	The range to match against.
options	Object	(Optional) Configuration including loose or includePrerelease.

Sources: ranges/min-satisfying.js:5, semver.js:1167-1186

Implementation Details

The internal implementation leverages the SemVer class for comparisons. When a satisfying version is found, a temporary SemVer object is created (referred to as maxSV or minSV) to facilitate accurate precedence comparison.

// From ranges/max-satisfying.js
if (!max || maxSV.compare(v) === -1) {
  max = v
  maxSV = new SemVer(max, options)
}

Sources: ranges/max-satisfying.js:18-21, ranges/min-satisfying.js:18-21

Comparison Mechanism

The comparison utilizes the standard SemVer.prototype.compare method, which evaluates major, minor, patch, and prerelease identifiers in order.

The sequence diagram illustrates how maxSatisfying coordinates between the Range object for validation and the SemVer object for precedence comparison.
Sources: semver.js:342-348, ranges/max-satisfying.js:14-23

Summary

The List Matching utilities provide a robust way to select specific versions from a set based on semantic precedence and range constraints. By utilizing the core Range and SemVer logic, maxSatisfying and minSatisfying ensure consistency across the library's filtering operations, handling both strict and loose versioning as configured by the user.

Sources: semver.js:1146-1186, test/ranges/max-satisfying.js:7-12