Incrementing Versions
Relevant source files
The following files were used as context for generating this wiki page:
The incrementing system in node-semver provides a robust mechanism for transitioning a Semantic Version from one state to the next based on defined release types. It supports standard increments (major, minor, patch) as well as complex pre-release transitions and custom identifier handling. This functionality is essential for automation tools that manage package lifecycles and versioning.
Sources: semver.js:468-577, classes/semver.js:189-322
Core Incrementing Logic
The primary logic for version incrementing is encapsulated within the SemVer class's inc method. This method modifies the instance's version components—major, minor, patch, and prerelease—according to the requested release type.
Release Types and Behaviors
The system supports several release types, each with specific rules for how version components are adjusted:
- Major: Increments the major version and resets minor, patch, and prerelease fields to zero/empty. If the current version is a pre-major version (e.g.,
1.0.0-5), it bumps to the same major version (1.0.0) unless it is already at a stable version. - Minor: Increments the minor version and resets patch and prerelease fields.
- Patch: Increments the patch version if no prerelease exists; otherwise, it bumps the prerelease version up to the stable patch.
- Pre-release Types (premajor, preminor, prepatch): These move the version to the next applicable stable segment and then immediately initialize or increment a prerelease component.
- Prerelease: Increments the prerelease component. If the version is not currently a prerelease, it acts like a
prepatch. - Release: Strips all prerelease information to transition to a stable version.
Sources: semver.js:485-555, classes/semver.js:218-316
The inc Function Data Flow
The standalone inc function acts as a wrapper that instantiates a SemVer object, performs the increment, and returns the formatted string.
Explanation: This diagram illustrates the high-level flow of the inc operation, showing how input parameters lead to specific component increments followed by string formatting.
Sources: semver.js:568-577, functions/inc.js
Prerelease and Identifier Handling
Incrementing with prereleases involves managing specific identifiers (e.g., 'beta', 'alpha') and an optional base for numeric increments.
Identifier Logic
When a prerelease increment is performed, the system checks for a provided identifier.
- If an identifier is provided and matches the existing one, the numeric part is incremented.
- If the identifier is new, the prerelease is reset to the new identifier followed by the base (usually
0or1).
Sources: semver.js:542-555, classes/semver.js:283-316
Increment Configuration Options
| Parameter | Type | Description |
|---|---|---|
release | String | The type of increment (major, minor, patch, premajor, preminor, prepatch, prerelease, release). |
identifier | String | Optional string to use as the prerelease prefix (e.g., "beta"). |
identifierBase | Number/Boolean | Defines the starting number for prerelease increments (typically 0 or 1). |
loose | Boolean | If true, allows parsing of non-strictly compliant semver strings. |
Sources: functions/inc.js, classes/semver.js:189-191, test/fixtures/increments.js
Implementation Details
The implementation ensures that input objects are not mutated when using the functional API, while the class-based API allows for in-place modification of SemVer instances.
// Example of the internal switch logic for 'premajor'
case 'premajor':
this.prerelease.length = 0;
this.patch = 0;
this.minor = 0;
this.major++;
this.inc('pre', identifier, identifierBase);
break;
Sources: classes/semver.js:219-225
Validation and Constraints
- Identifier Validation: Prerelease identifiers are validated against regular expressions to ensure they do not contain invalid characters (like
+or whitespace). - Numeric Limits: Version components (major, minor, patch) must be within
MAX_SAFE_INTEGER. - Error Handling: Providing an invalid increment argument or an invalid identifier in strict mode throws an Error.
Sources: classes/semver.js:192-216, internal/re.js:33-40
Conclusion
The incrementing module provides the logic required to traverse the versioning graph defined by the SemVer 2.0.0 specification. By separating the logic into discrete release types and providing support for custom identifiers and bases, it allows developers to implement complex release workflows—such as moving from 1.0.0 to 2.0.0-beta.0—with a single function call.
Sources: semver.js:28, index.js:69-80