Sorting Collections

Relevant source files

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

• semver.js
• index.js
• test/functions/sort.js
• test/functions/rsort.js
• test/index.js

Sorting Collections in the node-semver library provides the capability to organize lists of semantic version strings based on their precedence rules as defined by the SemVer 2.0.0 specification. The system supports both ascending and descending order sorting, as well as configuration for loose parsing of version strings within a collection.

These sorting utilities leverage the core comparison logic of the library to determine the relative order of versions, ensuring that complex version components—including major, minor, patch, and prerelease identifiers—are handled correctly during the sort process.

Sources: semver.js:1-24, index.js:24-25

Core Sorting Functions

The library exports two primary functions for handling collections of versions: sort and rsort. Both functions operate on an array of version strings and return the array modified in-place, sorted according to SemVer precedence.

Sort Function (Ascending)

The sort function organizes a list in ascending order. It uses the compare function internally to evaluate version precedence.

exports.sort = sort
function sort (list, loose) {
  return list.sort(function (a, b) {
    return exports.compare(a, b, loose)
  })
}

Sources: semver.js:847-852

Reverse Sort Function (Descending)

The rsort function organizes a list in descending order (highest version first). It utilizes rcompare, which is a functional wrapper that flips the arguments of the standard compare logic.

exports.rsort = rsort
function rsort (list, loose) {
  return list.sort(function (a, b) {
    return exports.rcompare(a, b, loose)
  })
}

Sources: semver.js:854-859

Sorting Logic and Data Flow

The sorting process involves a multi-layered delegation of responsibility. When a collection is sorted, the library maps the strings to SemVer objects to perform deep comparisons of their constituent parts.

Precedence Flow

The following diagram illustrates how a sort request flows through the internal comparison logic:

This diagram shows the decision path taken when comparing two versions within a collection.
Sources: semver.js:338-344, semver.js:847-859

Comparison Parameters

Parameter	Type	Description
list	Array	An array of strings or SemVer objects to be sorted.
loose	Boolean/Object	When true, allows non-strict version strings (e.g., those with 'v' prefixes).

Sources: semver.js:847-859, index.js:90-100

Comparison Logic Implementation

The sorting outcome depends entirely on the SemVer.prototype.compare method. This method compares two versions by checking segments in a specific order of priority:

1. Main Version: Major, Minor, and Patch are compared numerically using compareIdentifiers.
2. Prerelease Presence: A version without a prerelease tag always has higher precedence than one with a prerelease tag if the main versions are equal.
3. Prerelease Identifiers: If both have prereleases, they are compared identifier by identifier. Numeric identifiers have lower precedence than non-numeric ones.

Identifier Comparison

The compareIdentifiers function handles the specific logic for individual segments:

function compareIdentifiers (a, b) {
  var anum = numeric.test(a)
  var bnum = numeric.test(b)

  if (anum && bnum) {
    a = +a
    b = +b
  }

  return a === b ? 0
    : (anum && !bnum) ? -1
    : (bnum && !anum) ? 1
    : a < b ? -1
    : 1
}

Sources: semver.js:346-384, semver.js:810-825

Usage in Tests

The behavior of these collection utilities is validated through integration tests that ensure build metadata is ignored for precedence but preserved in the output, and that prerelease versions are sorted correctly relative to their release counterparts.

Test File	Focus	Expected Behavior
test/functions/sort.js	Ascending order	0.1.2 < 1.2.3 < 5.9.6
test/functions/rsort.js	Descending order	5.9.6 > 1.2.3 > 0.1.2
test/index.js	Precedence Rules	Validates that 1.2.3-alpha is less than 1.2.3

Sources: test/functions/sort.js:6-27, test/functions/rsort.js:6-23, test/index.js:1455-1473

Conclusion

Sorting collections in this library provides a high-level API to organize versions according to the complex precedence rules of Semantic Versioning. By abstracting the Array.prototype.sort implementation with specialized compare and rcompare functions, it ensures consistency across different version formats and options.