Introduction and SemVer Basics

Relevant source files

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

• README.md
• index.js
• semver.js
• classes/semver.js
• internal/constants.js
• package.json

The node-semver project is the semantic version parser implementation used by npm. It provides a robust set of tools for parsing, validating, and comparing version strings according to the Semantic Versioning (SemVer) specification. This module is critical for dependency management, ensuring that version constraints are strictly adhered to or loosely interpreted based on configuration.

At its core, the project implements the SemVer 2.0.0 specification. It handles the extraction of major, minor, and patch versions, as well as complex pre-release tags and build metadata. Beyond simple parsing, it provides advanced range matching logic, including Tilde, Caret, and Hyphen ranges, which are essential for defining package compatibility in modern JavaScript development.
Sources: package.json:3, semver.js:28, internal/constants.js:5

SemVer Structure and Components

A semantic version string consists of three mandatory numeric components and two optional metadata components. The project enforces specific constraints on these components to ensure reliability and prevent Regular Expression Denial of Service (ReDoS) attacks.

Version Components

• Major: Incremented for incompatible API changes.
• Minor: Incremented for backwards-compatible functionality.
• Patch: Incremented for backwards-compatible bug fixes.
• Pre-release: Optional hyphen-separated identifiers (e.g., -alpha.1).
• Build Metadata: Optional plus-sign-separated identifiers (e.g., +20130313144700).

Sources: README.md:88-110, semver.js:93-138

Technical Constraints

To maintain performance and safety, the library defines several maximum lengths and integer limits.

Constant	Value	Description
MAX_LENGTH	256	Maximum character length for a full version string.
MAX_SAFE_INTEGER	Number.MAX_SAFE_INTEGER	Maximum value for any numeric version component.
MAX_SAFE_COMPONENT_LENGTH	16	Maximum segment length allowed during coercion.
MAX_SAFE_BUILD_LENGTH	250	Maximum length for build metadata identifiers.

Sources: internal/constants.js:7-17, semver.js:31-38

The SemVer Class

The SemVer class is the primary data structure used to represent a semantic version. When instantiated, it parses the input string, validates its components against the specification, and provides methods for comparison and formatting.

Class Architecture

The following diagram illustrates the internal structure of a SemVer instance and its primary data flow during initialization.

The constructor performs whitespace trimming and regex matching. It then converts numeric segments to actual JavaScript numbers and splits metadata into arrays.
Sources: classes/semver.js:10-101, semver.js:267-333

Initialization Logic

The process of creating a SemVer object involves several validation steps:

Parsing and Validation Modes

The library supports three primary modes of operation, controlled via an options object or boolean flags passed to functions like parse() or valid().

1. Strict Mode

Strict mode is the default behavior in many internal functions. It requires a exact match to the SemVer 2.0.0 specification. In recent versions, a strict option can be explicitly set to true to reject versions with leading 'v' or 'V' prefixes, which would otherwise be allowed.
Sources: classes/semver.js:41-43, README.md:27-29

2. Loose Mode

Loose mode allows for common variations in version strings that do not strictly follow the spec but are frequently found in the wild (e.g., v1.2.3, =1.2.3, or 1.0.0alpha1).
Sources: semver.js:150-157, README.md:237-241

3. Coercion

Coercion is a "best effort" attempt to extract a valid SemVer from arbitrary text. It identifies the first digit and consumes characters until a partial or full version is found.

const semver = require('semver')
semver.coerce('v2') // '2.0.0'
semver.coerce('42.6.7.9.3-alpha') // '42.6.7'
semver.coerce('version 1.2.3 is here') // '1.2.3'

Sources: README.md:24-25, functions/coerce.js:7-60

Version Incrementing (The .inc Method)

The inc method transitions a version to the next logical state based on a release type. This is fundamental for automation tools that handle package publishing.

Release Types

The library supports the following increment strategies:

• major / premajor: Increments the major version, sets others to zero.
• minor / preminor: Increments the minor version, sets patch to zero.
• patch / prepatch: Increments the patch version.
• prerelease: Increments the pre-release segment or creates a new one.

Sources: internal/constants.js:19-27, classes/semver.js:168-255

Increment State Machine

This diagram shows how different increment types affect the version components.

Summary

node-semver provides the industry-standard implementation for handling JavaScript package versions. By encapsulating complex regex-based parsing into the SemVer class and providing flexible modes (Strict, Loose, Coerce), it ensures that developers can safely validate and compare versions across a wide variety of environments and use cases.
Sources: index.js:1-73, README.md:1-5