Basic Comparison Logic

Relevant source files

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

• functions/compare.js
• functions/compare-build.js
• semver.js
• classes/semver.js
• functions/cmp.js
• index.js

Basic Comparison Logic in the node-semver library provides the fundamental mechanism for ordering and equating Semantic Versioning strings. This logic is responsible for parsing raw version strings into structured objects and applying a set of precedence rules to determine if one version is greater than, less than, or equal to another.

The system supports various comparison modes, including strict, loose, and build-aware comparisons. It handles complex version components such as major, minor, and patch numbers, as well as pre-release identifiers and build metadata. The core logic is encapsulated within the SemVer class and exposed through a variety of utility functions that handle different comparison operators and edge cases.

Sources: semver.js:255-322, functions/compare.js, index.js:15-30

Core Comparison Components

The comparison logic relies on several key internal structures and classes to normalize and process version strings.

The SemVer Class

The SemVer class is the primary data structure. It breaks a version string into its constituent parts: major, minor, patch, prerelease (as an array of identifiers), and build.

The diagram below shows how the SemVer class relates to its internal comparison methods:

The SemVer constructor validates the version string against a set of regular expressions (strict or loose) and initializes the numeric segments.
Sources: semver.js:255-311, classes/semver.js:12-40

Precedence Rules

Precedence is determined by comparing segments in the following order:

1. Major version: If major versions differ, the higher number has precedence.
2. Minor version: If major versions are equal, minor versions are compared.
3. Patch version: If both major and minor are equal, patch versions are compared.
4. Pre-release identifiers: If the main version segments are equal, pre-release identifiers are compared. A version with no pre-release tag has higher precedence than one with a pre-release tag.

Sources: semver.js:342-350, classes/semver.js:140-155

Comparison Logic Flow

When a comparison is initiated via a function like compare(a, b), the library follows a specific sequence of operations.

This flowchart illustrates the standard compare method logic where main version segments take precedence over pre-release tags.
Sources: semver.js:334-340, functions/compare.js

Identifier Comparison

Identifiers (within pre-release segments) are compared based on their type:

• Numeric identifiers are compared as numbers.
• Non-numeric identifiers (strings) are compared lexically in ASCII sort order.
• Numeric identifiers always have lower precedence than non-numeric identifiers.

Sources: semver.js:476-490, index.js:84-85

Comparison Functions and Operators

The library provides multiple ways to compare versions, ranging from generic comparison functions to specific operator-based utilities.

Function	Description	Source
compare(a, b, loose)	Returns 0 if equal, 1 if a > b, or -1 if a < b.	functions/compare.js
compareBuild(a, b, loose)	Like compare, but includes build metadata in the comparison.	functions/compare-build.js
cmp(a, op, b, loose)	Evaluates a specific operator (e.g., >, <=, !==) between two versions.	functions/cmp.js
eq(a, b, loose)	Tests if a is equal to b.	semver.js:528-530
gt(a, b, loose)	Tests if a is greater than b.	semver.js:518-520

Operator Mapping in cmp

The cmp function acts as a dispatcher for various operators.

// Example implementation of operator dispatching
switch (op) {
  case '===': return a === b
  case '!==': return a !== b
  case '':
  case '=':
  case '==': return eq(a, b, loose)
  case '!=': return neq(a, b, loose)
  case '>':  return gt(a, b, loose)
  // ... and so on
}

Sources: semver.js:540-580, functions/cmp.js

Special Comparison Modes

Loose Mode

In loose mode, the parser is more permissive with version strings, allowing prefixes like v or = and ignoring certain formatting strictness. This is controlled by a loose boolean flag passed to the comparison functions.
Sources: semver.js:154-159, semver.js:256-261

Build Metadata Comparison

By default, build metadata (e.g., 1.0.0+build.123) is ignored in comparisons. To include it, the compareBuild function must be used. It first performs a standard comparison and, if the versions are otherwise equal, compares the build identifiers.
Sources: functions/compare-build.js:5-8, classes/semver.js:175-185

Summary

The basic comparison logic of node-semver ensures consistent ordering of version strings by strictly adhering to the Semantic Versioning spec. By leveraging the SemVer class and specialized comparison functions, the system handles everything from simple version checks to complex pre-release and build-aware logic, providing a robust foundation for dependency management and version resolution.