Parsing Versions

Relevant source files

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

• functions/parse.js
• classes/semver.js
• internal/re.js
• functions/coerce.js
• functions/clean.js
• functions/valid.js
• internal/constants.js

Parsing versions is a core capability of the node-semver library, responsible for transforming string representations of semantic versions into structured SemVer objects. This process involves strict validation against the SemVer 2.0.0 specification, handling of optional metadata like prerelease tags and build identifiers, and supporting different parsing modes such as loose or strict.

The system utilizes a complex set of regular expressions defined internally to tokenize and validate input strings. Beyond standard parsing, the library provides specialized functions for cleaning input (removing prefixes/whitespace) and coercing non-compliant strings into valid semantic versions.
Sources: semver.js:23, README.md:104-106, package.json:3

Core Parsing Logic

The primary entry point for version parsing is the parse function, which serves as a wrapper for the SemVer class constructor.

The SemVer Class

The SemVer class is the central data structure. Upon instantiation, it performs the following steps:

1. Length Validation: Checks if the version string exceeds MAX_LENGTH (256 characters).
2. Strict Mode Check: If options.strict is enabled, it rejects strings starting with 'v' or 'V'.
3. Regex Matching: Applies either the FULL (strict) or LOOSE regular expression to tokenize the string.
4. Component Extraction: Extracts and converts the major, minor, and patch segments into numbers.
5. Numeric Validation: Ensures segments are within the range of 0 to MAX_SAFE_INTEGER.
6. Metadata Processing: Splits and identifies prerelease and build components.
   Sources: classes/semver.js:10-75, semver.js:296-339

Parsing Flow Diagram

The following diagram illustrates the logic flow when a version string is passed to the parser.

Configuration Options

Parsing behavior is influenced by an options object passed to functions or the constructor.

Option	Type	Default	Description
loose	Boolean	false	If true, be more forgiving about invalid strings (e.g., allow 1.2.3foo).
includePrerelease	Boolean	false	Allows prerelease versions to satisfy ranges that would otherwise exclude them.
strict	Boolean	false	If true, rejects versions with leading 'v' or 'V' prefixes.
Sources: classes/semver.js:11-40, internal/parse-options.js

Supporting Functions

The library provides utility functions to handle various states of input strings before or during parsing.

Validation and Cleaning

• valid(version, options): A convenience method that calls parse and returns the formatted version string if valid, otherwise null. Sources: functions/valid.js:5-8
• clean(version, options): Trims whitespace and strips leading = or v characters before attempting to parse the result. Sources: functions/clean.js:4-7

Version Coercion

The coerce function attempts to extract a valid semantic version from nearly any string by searching for the first digit and consuming characters that fit a partial version (e.g., 1.2). It ignores surrounding text and truncates components longer than 16 characters. Sources: functions/coerce.js:6-66, README.md:368-380

Internal Tokenization

The parsing engine relies on the internal/re.js module, which builds regular expressions from primitive tokens. This structure ensures that both "strict" and "loose" parsing use the same underlying grammar.

Component Tokens

• NUMERICIDENTIFIER: 0|[1-9]\d*
• MAINVERSION: Three dot-separated numeric identifiers.
• PRERELEASE: A hyphen followed by dot-separated identifiers (numeric or non-numeric).
• BUILD: A plus sign followed by dot-separated build metadata identifiers.
  Sources: internal/re.js:60-120, semver.js:65-120

Regular Expression Safety

To prevent Regular Expression Denial of Service (ReDoS), the library converts greedy operators in internal regexes into limited quantifiers (using MAX_LENGTH or MAX_SAFE_BUILD_LENGTH) via the makeSafeRegex utility.
Sources: internal/re.js:31-40, semver.js:42-60

Conclusion

Parsing versions in node-semver is a multi-stage process that prioritizes technical accuracy and safety. By combining a strict object-oriented model in the SemVer class with flexible utility functions like coerce and clean, the system can handle both standard-compliant strings and real-world "loose" versioning data commonly found in the npm ecosystem.