Range Satisfaction
Relevant source files
The following files were used as context for generating this wiki page:
Range Satisfaction is a core mechanism in the node-semver library used to determine if a specific version (or set of versions) meets the criteria defined by a Semantic Versioning range. This system allows developers to specify flexible version dependencies using operators like hyphens, tildes, and carets, and then programmatically verify compliance.
The system is built around the Range class, which parses complex range strings into a structured set of comparators. These comparators are then tested against SemVer objects to determine a match. Beyond simple boolean checks, the library provides utilities to find the best matching version from a list, such as maxSatisfying and minSatisfying.
Sources: README.md, classes/range.js:1-15, functions/satisfies.js:1-10
Core Architecture and Logic
The satisfaction logic follows a hierarchical structure where a Range is composed of one or more "OR" sets (separated by ||), each containing multiple "AND" comparators.
The Satisfaction Flow
The satisfies function acts as the primary entry point. It instantiates a Range object and calls its test method. The test method evaluates whether a version satisfies at least one of the internal comparator sets.
The logic iterates through sets until a match is found; if all sets fail, the version is deemed not to satisfy the range.
Sources: functions/satisfies.js:4-9, classes/range.js:337-357
The Range Class
The Range class is responsible for the transformation of human-readable strings into logical instructions. During construction, it performs whitespace normalization and splits the range into a 2D array known as this.set.
Range Components
| Component | Description |
|---|---|
raw | The original range string, trimmed and normalized. |
set | A 2D array where the outer level represents OR (` |
options | Configuration for parsing, including loose and includePrerelease flags. |
Sources: classes/range.js:10-50
Advanced Range Desugaring
The Range class "desugars" advanced syntax into primitive comparators (>, <, >=, <=, =). This is handled by internal functions during the parseRange phase.
Sources: classes/range.js:134-165, semver.js:930-970
Version Selection Utilities
In addition to boolean satisfaction, the library provides methods to select specific versions from a provided array based on range criteria.
maxSatisfying and minSatisfying
These functions iterate through an array of versions, filter them based on the range using the satisfaction logic, and return either the highest or lowest matching version.
Configuration and Options
The behavior of range satisfaction can be modified using an options object passed to the functions.
| Option | Type | Default | Description |
|---|---|---|---|
loose | Boolean | false | If true, permits non-standard SemVer strings (e.g., missing patch, leading 'v'). |
includePrerelease | Boolean | false | If true, allows prerelease versions to satisfy ranges even if the range doesn't explicitly include a prerelease tag. |
strict | Boolean | false | If true, enforces strict compliance and rejects versions with 'v' prefixes. |
Sources: semver.js:527-535, classes/range.js:11-13, README.md
Implementation Details
Prerelease Matching Logic
By default, a version with a prerelease tag (e.g., 1.2.3-alpha) will not satisfy a range like ^1.2.0 unless includePrerelease is set. The internal testSet function ensures that if a version has a prerelease, it only matches if at least one comparator in the set specifically targets that same [major, minor, patch] tuple with a prerelease identifier.
Sources: classes/range.js:463-490, semver.js:1062-1088
Performance Optimization
The Range class utilizes an internal cache (often an LRU cache) to store parsed comparator sets. Since range parsing involves complex regex replacements, memoization ensures that repeated checks against the same range string are computationally inexpensive.
Sources: classes/range.js:136-141, semver.js:888-910
Conclusion
Range Satisfaction provides the logical backbone for version resolution. By decomposing complex strings into manageable comparator sets and providing specialized selection utilities like maxSatisfying, the system allows for robust and predictable dependency management. The architecture balances flexibility through desugaring with performance through internal caching.