Validation and Cleaning

Relevant source files

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

• functions/valid.js
• functions/clean.js
• test/functions/valid.js
• semver.js
• test/functions/clean.js
• test/integration/whitespace.js

The "Validation and Cleaning" module provides the foundational logic for ensuring that version strings adhere to the Semantic Versioning specification. It encompasses the identification of valid SemVer strings, the extraction of core version components from cluttered input, and the normalization of version data into a standard format used across the library.

At a high level, the system distinguishes between strict validation (ensuring a string is a perfect SemVer) and cleaning (attempting to find and format a valid SemVer within a string containing extra characters like prefixes or whitespace). These processes are critical for preventing malformed data from entering comparison or range-matching logic.
Sources: semver.js:464-477, functions/clean.js

Version Validation

Validation in node-semver is primarily handled by the valid function, which relies on the internal parse logic. The validation process checks if a string matches the required structure (Major.Minor.Patch) and optionally handles pre-release and build metadata.

The Validation Logic

A version is considered valid if it can be successfully parsed into a SemVer object. If the input is already a SemVer instance, it is returned directly. String inputs are checked against specific regular expressions defined in the library. If validation fails—due to incorrect formatting, excessive length, or invalid numeric components—the system returns null rather than throwing an exception.
Sources: semver.js:450-472, test/functions/valid.js:8-11

Logic Flow for Validation

The following diagram illustrates how the valid function processes an input string to determine its validity.

The valid function acts as a wrapper around parse, returning only the formatted version string or null.
Sources: semver.js:450-472, functions/valid.js

Version Cleaning

The clean function is designed to take "dirty" version strings—those containing leading/trailing whitespace or common prefixes like = or v—and transform them into a standardized SemVer string.

Cleaning Operations

The cleaning process performs the following transformations:

1. Trimming: Removes leading and trailing whitespace.
2. Prefix Removal: Strips any number of leading = or v characters.
3. Parsing: Passes the resulting string to the parse function to verify it is now a valid semantic version.

If the string cannot be reduced to a valid version (e.g., it contains range operators like > or ~), the function returns null.
Sources: semver.js:474-477, test/functions/clean.js:8-23

Component Cleaning Table

Input Type	Cleaning Action	Result Example
Whitespace	trim() called on input	" 1.2.3 " -> "1.2.3"
Prefixes	Regex replaces ^[=v]+	"v=1.2.3" -> "1.2.3"
Range Operators	Rejected by parse	">1.2.3" -> null
Build Metadata	Stripped during parsing	"1.2.3+build" -> "1.2.3"

Sources: semver.js:475, test/functions/clean.js:12-16

Internal Constraints and Security

The validation and cleaning systems enforce several technical constraints to maintain stability and protect against ReDoS (Regular Expression Denial of Service) attacks.

Constraints and Limits

• MAX_LENGTH: Version strings are capped at 256 characters. Any string exceeding this is immediately rejected.
• MAX_SAFE_INTEGER: Numeric components (Major, Minor, Patch) must be within the JavaScript safe integer range.
• Safe Regular Expressions: The library uses a safeRe internal object where greedy operators like \d* are replaced with bounded repetitions (e.g., \d{0,256}) to prevent catastrophic backtracking.

Security Implementation Sequence

The following sequence shows how the library handles potentially malicious whitespace in version strings during validation.

Summary of Key Functions

The following table summarizes the primary validation and cleaning functions.

Function	Purpose	Return Value	File Path
valid(v, opts)	Validates a version string.	String (clean version) or null.	functions/valid.js
clean(v, opts)	Strips prefixes and whitespace to find a version.	String (clean version) or null.	functions/clean.js
parse(v, opts)	Full parsing of a version string.	SemVer object or null.	semver.js
coerce(v)	Aggressively tries to extract a version from any string.	SemVer object or null.	semver.js

Sources: semver.js:450-477, semver.js:1152-1170

The validation and cleaning module ensures that subsequent operations—such as comparison, incrementing, and range satisfaction—operate on predictable, well-formatted data, thereby maintaining the integrity of the semantic versioning logic.