The Comparator Class

Relevant source files

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

• classes/comparator.js
• test/classes/comparator.js
• semver.js
• classes/range.js
• functions/cmp.js
• test/index.js

The Comparator class is a core component of the node-semver library, representing a single comparison rule composed of an operator and a semantic version. It serves as the building block for more complex Range objects. A comparator typically looks like >=1.2.3 or <2.0.0, where the operator defines the relationship and the version defines the boundary.

This class handles the parsing of comparator strings, the validation of versions against the specified rule, and the logic to determine if two comparators have overlapping version sets. It supports both strict and "loose" parsing modes, as well as specific handling for pre-release versions.

Sources: classes/comparator.js:5-11, semver.js:659-661

Class Architecture and Properties

The Comparator class stores the state of a single comparison rule. It integrates closely with the SemVer class to represent the version boundary.

Core Properties

Property	Type	Description
options	Object	Configuration object containing loose and includePrerelease flags.
loose	Boolean	A shortcut to options.loose, determining if parsing should be permissive.
semver	SemVer|Symbol	The parsed SemVer object or the ANY symbol for empty comparators.
operator	String	The comparison operator (e.g., >, >=, <, <=). Empty string implies =.
value	String	The normalized string representation of the comparator (e.g., >=1.2.3).

Sources: classes/comparator.js:14-38, semver.js:675-685

The ANY Symbol

The class defines a static getter ANY which returns a unique Symbol. This is used to represent a comparator that matches any version, typically resulting from an empty string or a * input.

Sources: classes/comparator.js:6-12, test/classes/comparator.js:53-58

Initialization and Parsing

When a Comparator is instantiated, it normalizes the input string and extracts the operator and version components using regular expressions.

Constructor Logic

The constructor handles existing Comparator instances by returning them if options match, or extracting their values if they do not. For string inputs, it collapses whitespace before calling the parse method.

Internal Parsing Logic

The parse method selects a regular expression based on the loose option. If the operator found is =, it is normalized to an empty string. If no version is found in the match, the semver property is set to the ANY symbol.

Sources: classes/comparator.js:41-61, semver.js:690-708

Version Testing

The primary function of a Comparator is to test whether a given version satisfies its rule.

Comparison Logic

The test method converts string inputs into SemVer objects before performing the comparison. If the comparator is ANY, the test always returns true. The actual comparison is delegated to the internal cmp function.

Intersection Logic

The intersects method determines if there is any version that could satisfy both the current comparator and another given comparator. This is critical for range optimization and overlap detection.

Intersection Scenarios

The logic accounts for different directions and inclusivity:

1. Same Direction: Two increasing comparators (e.g., >1.0.0 and >2.0.0) always intersect.
2. Opposite Directions: For >1.0.0 and <2.0.0, they intersect if the "greater than" boundary is less than the "less than" boundary.
3. Inclusive Boundaries: If boundaries are equal, they only intersect if both operators are inclusive (e.g., >=1.0.0 and <=1.0.0).

Operator 1	Operator 2	Condition	Result
> or >=	> or >=	Always	true
< or <=	< or <=	Always	true
>	<	Version 1 < Version 2	true
<	>	Version 1 > Version 2	true
>=	<=	Version 1 == Version 2	true

Sources: classes/comparator.js:85-131, semver.js:728-766

Prerelease Special Cases

If includePrerelease is not set, comparators like <0.0.0 are handled strictly to ensure no prerelease versions are accidentally included. Specifically, if a comparator value is <0.0.0-0 with prerelease inclusion, it cannot intersect with anything.

Sources: classes/comparator.js:103-110, test/classes/comparator.js:29-43

Integration with Range Class

While a Comparator represents a single rule, the Range class uses them to build complex sets. A Range is parsed into a "set of sets" of comparators (disjunctive normal form), where the inner arrays represent groups of comparators that must all be satisfied (AND), and the outer array represents different groups (OR).

Sources: classes/range.js:37-45, semver.js:782-793

Summary

The Comparator class provides the atomic logic for version comparison in the node-semver ecosystem. By encapsulate parsing, normalization, and intersection logic, it enables the library to handle complex versioning requirements while maintaining high performance through efficient regex usage and internal SemVer object management.

Sources: classes/comparator.js:140-145, index.js:35