Regular Expressions and Constants

Relevant source files

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

• internal/re.js
• internal/constants.js
• semver.js
• index.js
• functions/coerce.js
• test/integration/whitespace.js

The node-semver library relies on a robust foundation of shared constants and complex regular expressions to tokenize, validate, and parse Semantic Versioning strings. These components ensure strict adherence to the SemVer 2.0.0 specification while providing mechanisms to mitigate security risks such as Regular Expression Denial of Service (ReDoS).

Regular expressions are managed through a centralized system that separates the raw source strings from the compiled RegExp objects. This architecture allows the library to maintain two sets of patterns: a standard set for general use and a "safe" set that limits greedy token repetition to prevent catastrophic backtracking when processing untrusted input.

Sources: internal/re.js:1-55, internal/constants.js:1-10, semver.js:50-70

Global Constants

The project defines several numerical and structural constants that govern version parsing and comparison limits. These constants are primarily centralized in internal/constants.js and re-exported through the main entry points.

Constant	Value	Description
SEMVER_SPEC_VERSION	'2.0.0'	The version of the SemVer specification implemented.
MAX_LENGTH	256	Maximum allowed length for a version string.
MAX_SAFE_INTEGER	Number.MAX_SAFE_INTEGER	The maximum safe integer for version segments (9,007,199,254,740,991).
MAX_SAFE_COMPONENT_LENGTH	16	Maximum character length for a single version segment during coercion.
MAX_SAFE_BUILD_LENGTH	250	Calculated as MAX_LENGTH - 6 (minimum length of 0.0.0+).

Sources: internal/constants.js:4-21, semver.js:25-35

Regular Expression Architecture

The library implements a systematic approach to building complex regular expressions by combining smaller "tokens" into larger patterns.

Token Creation and Management

Patterns are stored in four primary arrays/objects within internal/re.js:

• src: Raw string representations of the regular expressions.
• re: Compiled RegExp objects using the raw source.
• safeSrc: Modified string patterns with limited repetition.
• safeRe: Compiled "safe" RegExp objects designed to prevent ReDoS.
• t: An object mapping human-readable names (e.g., FULL) to their index in the arrays.

Sources: internal/re.js:12-20, semver.js:41-45

ReDoS Mitigation Logic

The project uses a makeSafeRegex utility to transform greedy quantifiers into bounded ones. This is critical for handling large inputs or excessive whitespace.

The transformation replaces standard greedy tokens with explicit ranges based on MAX_LENGTH and MAX_SAFE_BUILD_LENGTH. For example, \d+ becomes \d{1,256}.

Sources: internal/re.js:33-42, semver.js:52-66, test/integration/whitespace.js:14-25

Pattern Categories

Version Parsing Patterns

These patterns define the core structure of a semantic version, including major, minor, patch, prerelease, and build metadata.

Token Name	Source Pattern (Simplified)
NUMERICIDENTIFIER	0|[1-9]\d*
MAINVERSION	(major)\.(minor)\.(patch)
PRERELEASE	(?:-(prerelease identifiers))
BUILD	(?:\+(build identifiers))
FULL	^v?(MAINVERSION)(PRERELEASE)?(BUILD)?$

Sources: internal/re.js:57-118, semver.js:80-135

Range and Comparator Patterns

These patterns are used to parse complex range strings like ^1.2.3 or 1.0.0 - 2.0.0.

• X-Ranges: Handles wildcards (*, x, X) in version segments.
• Tilde/Caret: Patterns to identify ~ and ^ operators.
• Hyphen Ranges: Captures the X.Y.Z - A.B.C syntax.
• Trimming: Patterns specifically designed to collapse whitespace between operators and versions (e.g., > 1.2.3 to >1.2.3).

Sources: internal/re.js:141-210, semver.js:150-230

Coercion Logic Flow

The coerce feature utilizes specific regular expressions to extract version-like strings from non-compliant text.

Coercion uses MAX_SAFE_COMPONENT_LENGTH (16) to ensure that very long strings of digits do not cause overflow issues before the MAX_SAFE_INTEGER check occurs in the SemVer class.

Sources: functions/coerce.js:7-60, internal/re.js:160-170, semver.js:235-245

Summary of Release Types

The library formalizes the valid ways a version can be incremented via the RELEASE_TYPES constant.

• Major: Increments major, resets others.
• Minor: Increments minor, resets patch/prerelease.
• Patch: Increments patch.
• Pre-types: premajor, preminor, prepatch, prerelease (handles transitions to/from prerelease states).

Sources: internal/constants.js:23-31, index.js:84-85