Version Differences

Relevant source files

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

• functions/diff.js
• test/functions/diff.js
• classes/semver.js
• semver.js
• index.js
• internal/identifiers.js

The "Version Differences" feature in the node-semver library provides a mechanism to identify the specific magnitude of change between two Semantic Versioning (SemVer) strings. It determines whether the difference between versions represents a major, minor, patch, or prerelease change, including prefixed variations for transitions involving prerelease tags.

Sources: functions/diff.js:1-6, index.js:14

Core Differencing Logic

The primary utility for determining differences is the diff(v1, v2) function. This function compares two versions and returns a string representing the release type that distinguishes them. If the versions are identical, it returns null.

Sources: functions/diff.js:5-13, semver.js:562-565

Comparison Workflow

The logic follows a hierarchical check of SemVer components:

1. Parsing: Both inputs are parsed into SemVer objects.
2. Equality Check: If v1.compare(v2) returns 0, no difference exists.
3. Magnitude Determination: The function identifies which part of the version tuple (major, minor, patch, prerelease) has changed, prioritizing the highest-order component.

The following flowchart illustrates the decision-making process within the diff function:

Release Types and Prefixes

Differences are categorized based on standard release types. When a transition involves moving into a prerelease state, the resulting string is prefixed with pre.

Result Type	Description	Example (v1 -> v2)
major	Change in the major version number.	1.2.3 -> 2.0.0
minor	Change in the minor version number.	1.2.3 -> 1.3.0
patch	Change in the patch version number.	1.2.3 -> 1.2.4
premajor	Moving to a prerelease of a higher major version.	1.2.3 -> 2.0.0-alpha.0
preminor	Moving to a prerelease of a higher minor version.	1.2.3 -> 1.3.0-alpha.0
prepatch	Moving to a prerelease of a higher patch version.	1.2.3 -> 1.2.4-alpha.0
prerelease	Change only within the prerelease identifiers.	1.2.3-alpha.0 -> 1.2.3-alpha.1

Sources: functions/diff.js:41-61, test/functions/diff.js:11-46

Prerelease to Stable Transitions

Special handling is implemented for versions moving from a prerelease state (e.g., 1.0.0-rc.1) to a stable state (e.g., 1.0.0).

• If the prerelease version has zero minor and patch components (e.g., 1.0.0-1), the difference to the stable version is considered major.
• If the main version components are identical, it is categorized as minor if a minor version exists, otherwise patch.

Sources: functions/diff.js:21-38

Internal Comparison Logic

The diff logic relies heavily on the SemVer class's internal comparison methods. Differences are determined by checking the major, minor, and patch properties sequentially.

Identifier Comparison

Components are compared using compareIdentifiers. This utility handles both numeric and string identifiers:

• Numeric identifiers are compared as numbers.
• Non-numeric identifiers are compared lexically.
• Numeric identifiers always have lower precedence than non-numeric ones.

Sources: classes/semver.js:103-125, semver.js:584-601, internal/identifiers.js

Conclusion

The Version Differences module ensures that developers can programmatically identify the semantic "distance" between two versions. By accounting for the nuances of prerelease transitions and hierarchical version components, it provides the necessary metadata to drive automated release workflows and dependency management.

Sources: functions/diff.js