The SemVer Class

Relevant source files

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

• classes/semver.js
• semver.js
• internal/constants.js
• test/classes/semver.js
• README.md

The SemVer class is the central data structure and logic engine for the node-semver project. It provides a robust implementation of the Semantic Versioning 2.0.0 specification, enabling developers to parse, validate, compare, and increment version strings. It handles complex versioning components including major, minor, and patch versions, as well as prerelease identifiers and build metadata.

Within the project, the SemVer class serves as the foundation for higher-level modules such as Comparator and Range. Most utility functions in the library, such as valid(), satisfies(), and compare(), either instantiate this class internally or accept SemVer instances as arguments to perform their operations.
Sources: semver.js:256, classes/semver.js:10, README.md:144

Architecture and Core Components

The class is designed to encapsulate a version's state and provide methods for manipulation. Upon instantiation, it parses a string input into its constituent parts while applying safety checks against length and integer overflows.

Data Structure

A SemVer instance maintains the following internal properties:

Property	Type	Description
major	Number	The first numeric component of the version.
minor	Number	The second numeric component of the version.
patch	Number	The third numeric component of the version.
prerelease	Array	A list of string or numeric identifiers following a hyphen.
build	Array	A list of identifiers following a plus sign.
raw	String	The original string passed to the constructor.
version	String	The formatted version string (excluding build metadata).
options	Object	Configuration for parsing (loose, strict, includePrerelease).

Sources: classes/semver.js:49-84, semver.js:296-324

Class Relationships

The following diagram illustrates the attributes of the SemVer class and its relationship with internal constants and configuration options.

Parsing Logic and Validation

The constructor performs a sequence of validations to ensure the version string adheres to the spec or the "loose" interpretations configured via options.

Initialization Flow

1. Option Normalization: Options are processed to set loose, strict, and includePrerelease flags.
2. Type & Length Check: The input must be a string and under 256 characters.
3. Strict Mode Check: If options.strict is true, strings starting with 'v' or 'V' are rejected.
4. RegExp Matching: The string is matched against either a strict or loose Regular Expression.
5. Numeric Validation: Major, minor, and patch values are checked against MAX_SAFE_INTEGER.

Version Comparison

Comparison is split into "Main" (major, minor, patch) and "Prerelease" logic. Build metadata is explicitly ignored in standard comparisons according to the SemVer spec.

Precedence Rules

• Main Version: Compared numerically (Major > Minor > Patch).
• Prerelease Presence: A version without a prerelease tag always has higher precedence than one with a prerelease tag (e.g., 1.0.0 > 1.0.0-alpha).
• Prerelease Comparison: Each dot-separated identifier is compared. Numeric identifiers have lower precedence than non-numeric ones. If both are numeric, they are compared numerically.

Version Incrementing

The inc() method modifies the SemVer instance based on a release type. It supports major, minor, patch, premajor, preminor, prepatch, and prerelease.

Increment Behavior

• Major/Minor/Patch: Resets lower-order segments to zero and clears prerelease tags.
• Pre-releases: Increments the version according to the requested level and then adds or increments a prerelease identifier.
• Identifier Management: If an identifier (like 'beta') is provided, it is used as the base for the prerelease segment.

Release Type	Logic Summary
major	Increments major, sets minor and patch to 0, clears prerelease.
minor	Increments minor, sets patch to 0, clears prerelease.
patch	Increments patch if no prerelease exists; otherwise, bumps to the version without the tag.
pre	Increments the numeric part of the last prerelease segment or appends .0.

Sources: classes/semver.js:174-252, semver.js:399-482

// Example of increment logic from the class
SemVer.prototype.inc = function (release, identifier) {
  switch (release) {
    case 'major':
      if (this.minor !== 0 || this.patch !== 0 || this.prerelease.length === 0) {
        this.major++
      }
      this.minor = 0
      this.patch = 0
      this.prerelease = []
      break;
    // ... logic continues for other types
  }
}

Sources: semver.js:433-445, classes/semver.js:213-228

Summary

The SemVer class provides the project's core functionality by encapsulating the Semantic Versioning spec into a programmable object. It ensures that all version manipulations—whether comparisons or increments—remain consistent and safe from common pitfalls like integer overflow or excessively long input strings. Its integration with safeRe protects against Regular Expression Denial of Service (ReDoS) attacks by normalizing whitespace and limiting repetition.
Sources: semver.js:46-55, internal/constants.js:7-14