@hyperfrontend/versioning/semversemver/
Semantic versioning utilities for parsing, comparing, formatting, and incrementing versions.
Overview
Complete implementation of the Semantic Versioning 2.0.0 specification. Parsing uses character-by-character state machines for predictable O(n) performance.
Usage Examples
Parsing Versions
import { parseVersion, parseVersionOrThrow, coerceVersion } from '@hyperfrontend/versioning'
// Safe parsing (returns null on invalid)
const v1 = parseVersion('1.2.3') // SemVer { major: 1, minor: 2, patch: 3 }
const v2 = parseVersion('invalid') // null
// Strict parsing (throws on invalid)
const v3 = parseVersionOrThrow('2.0.0-beta.1')
// Coerce with best effort
const v4 = coerceVersion('v1.2.3') // strips 'v' prefix
const v5 = coerceVersion('1.2') // normalizes to 1.2.0Comparing Versions
import { compare, gt, lt, satisfies, parseVersion, parseRange } from '@hyperfrontend/versioning'
const a = parseVersion('1.0.0')!
const b = parseVersion('2.0.0')!
compare(a, b) // -1 (a < b)
gt(b, a) // true
lt(a, b) // true
// Range satisfaction
const range = parseRange('^1.0.0')!
satisfies(parseVersion('1.5.0')!, range) // true
satisfies(parseVersion('2.0.0')!, range) // falseIncrementing Versions
import { bump, parseVersion, format } from '@hyperfrontend/versioning'
const version = parseVersion('1.2.3')!
format(bump(version, 'major')) // '2.0.0'
format(bump(version, 'minor')) // '1.3.0'
format(bump(version, 'patch')) // '1.2.4'
format(bump(version, 'prerelease')) // '1.2.4-0'Sorting Versions
import { sort, max, min, parseVersion, format } from '@hyperfrontend/versioning'
const versions = ['2.0.0', '1.0.0', '1.5.0'].map((raw) => parseVersion(raw)!)
sort(versions).map(format) // ['1.0.0', '1.5.0', '2.0.0']
format(max(versions)!) // '2.0.0'
format(min(versions)!) // '1.0.0'Design Principles
- Immutable: All operations return new objects
- Pure Functions: No side effects, deterministic output
- No Regex: Character-by-character parsing eliminates ReDoS
- Null Safety: Parse functions return
nullon invalid input - Factory Pattern: Use
create*functions for object construction
See Also
- changelog/: Uses semver for version entries
- flow/: Uses semver for bump calculations
- commits/: Maps commit types to bump types
- registry/: Queries published versions
- workspace/: Cascade bump calculations
- Main README: Package overview and quick start
- ARCHITECTURE.md: Design principles and data flow
API Reference§
ƒ Functions
Attempts to coerce a string into a valid semver. More lenient than parseVersion - accepts partial versions.
Parameters
| Name | Type | Description |
|---|---|---|
§input | string | The string to coerce |
Returns
SemVerThe parsed SemVer or null if coercion failed
Example
Coerce partial versions to valid semver
coerceVersion('1') // { major: 1, minor: 0, patch: 0, ... }
coerceVersion('1.2') // { major: 1, minor: 2, patch: 0, ... }
coerceVersion('v2.0') // { major: 2, minor: 0, patch: 0, ... }Compares two semantic versions.
Returns
-1 | 0 | 1-1 if a < b, 0 if a == b, 1 if a > b
Example
Compare two semantic versions
compare(parseVersion('1.0.0'), parseVersion('2.0.0')) // -1
compare(parseVersion('1.0.0'), parseVersion('1.0.0')) // 0
compare(parseVersion('2.0.0'), parseVersion('1.0.0')) // 1Creates a range that matches any version.
Returns
RangeA Range matching any version (*)
Example
Create a range that matches any version
const anyRange = createAnyRange()
satisfies(parseVersionStrict('999.999.999'), anyRange) // => trueCreates a new Comparator.
Parameters
| Name | Type | Description |
|---|---|---|
§operator | RangeOperator | The comparison operator |
§version | SemVer | The version to compare against |
Returns
ComparatorA new Comparator
Example
Create a comparator for version comparison
createComparator('>=', parseVersionStrict('1.0.0'))
// => { operator: '>=', version: { major: 1, minor: 0, patch: 0, ... } }Creates a new ComparatorSet.
Parameters
| Name | Type | Description |
|---|---|---|
§comparators | unknown | Array of comparators (AND logic) |
Returns
ComparatorSetA new ComparatorSet
Example
Create a comparator set with AND logic
createComparatorSet([gte100, lt200]) // AND: >=1.0.0 AND <2.0.0Creates a range that matches exactly one version.
Returns
RangeA Range matching exactly the specified version
Example
Create a range that matches exactly one version
const exact = createExactRange(parseVersionStrict('1.2.3'))
satisfies(parseVersionStrict('1.2.3'), exact) // => true
satisfies(parseVersionStrict('1.2.4'), exact) // => falseCreates a SemVer representing version 1.0.0.
Returns
SemVerA SemVer at version 1.0.0
Example
Create first 1.0.0 release version
const first = createFirstRelease()
format(first) // => '1.0.0'Creates a SemVer representing version 0.0.0.
Returns
SemVerA SemVer at version 0.0.0
Example
Create initial 0.0.0 version
const initial = createInitialVersion()
format(initial) // => '0.0.0'Creates a new Range.
Parameters
Returns
RangeA new Range
Example
Create a range with OR logic between sets
createRange([set1, set2], '>=1.0.0 || >=2.0.0 <3.0.0')Creates a new SemVer object.
Returns
SemVerA new SemVer object
Example
Create a SemVer object from components
createSemVer({ major: 1, minor: 2, patch: 3 })
// => { major: 1, minor: 2, patch: 3, prerelease: [], build: [] }
createSemVer({ major: 1, minor: 0, patch: 0, prerelease: ['beta', '1'] })
// => 1.0.0-beta.1Calculates the difference type between two versions.
Returns
BumpTypeThe type of difference, or null if versions are equal
Example
Calculate the difference type between two versions
diff(parseVersion('1.0.0'), parseVersion('2.0.0')) // 'major'
diff(parseVersion('1.0.0'), parseVersion('1.1.0')) // 'minor'
diff(parseVersion('1.0.0'), parseVersion('1.0.1')) // 'patch'Checks if two versions are equal (ignoring build metadata).
Returns
booleanTrue if versions are equal
Example
Check if two versions are equal
eq(parseVersionStrict('1.0.0'), parseVersionStrict('1.0.0')) // => true
eq(parseVersionStrict('1.0.0'), parseVersionStrict('1.0.1')) // => falseConverts a SemVer to its canonical string representation.
Returns
stringThe version string (e.g., "1.2.3-alpha.1+build.123")
Example
Format a version to its canonical string
format(parseVersionStrict('1.2.3')) // => '1.2.3'
format(createSemVer({ major: 1, minor: 0, patch: 0, prerelease: ['beta', '1'] }))
// => '1.0.0-beta.1'Converts a Comparator to its string representation.
Parameters
| Name | Type | Description |
|---|---|---|
§comparator | Comparator | The comparator to format |
Returns
stringThe comparator string (e.g., ">=1.0.0")
Example
Format a comparator to its string representation
formatComparator(createComparator('>=', parseVersionStrict('1.0.0')))
// => '>=1.0.0'Converts a Range to its string representation.
Returns
stringThe range string
Example
Format a range to its string representation
formatRange(parseRangeStrict('^1.0.0')) // => '^1.0.0'
formatRange(createAnyRange()) // => '*'Converts a SemVer to a string without prerelease/build.
Returns
stringThe version string (e.g., "1.2.3")
Example
Format version without prerelease/build metadata
formatSimple(parseVersionStrict('1.2.3-beta.1+build')) // => '1.2.3'Checks if a > b.
Returns
booleanTrue if a is greater than b
Example
Check if version a is greater than b
gt(parseVersionStrict('2.0.0'), parseVersionStrict('1.0.0')) // => true
gt(parseVersionStrict('1.0.0'), parseVersionStrict('2.0.0')) // => falseChecks if a >= b.
Returns
booleanTrue if a is greater than or equal to b
Example
Check if version a is greater than or equal to b
gte(parseVersionStrict('2.0.0'), parseVersionStrict('1.0.0')) // => true
gte(parseVersionStrict('1.0.0'), parseVersionStrict('1.0.0')) // => trueIncrements a version based on the bump type.
Parameters
Returns
SemVerA new incremented SemVer
Example
Increment version by bump type
increment(parseVersion('1.2.3'), 'minor') // 1.3.0
increment(parseVersion('1.2.3'), 'major') // 2.0.0
increment(parseVersion('1.2.3'), 'prerelease', 'alpha') // 1.2.4-alpha.0Increments the prerelease portion of a version.
Parameters
Returns
SemVerA new version with incremented prerelease
Example
Increment the prerelease portion of a version
incrementPrerelease(parseVersionStrict('1.0.0')) // => 1.0.1-alpha.0
incrementPrerelease(parseVersionStrict('1.0.0-alpha.0')) // => 1.0.0-alpha.1
incrementPrerelease(parseVersionStrict('1.0.0'), 'beta') // => 1.0.1-beta.0Checks if the version has prerelease identifiers.
Returns
booleanTrue if version has prerelease identifiers
Example
Check if version has prerelease identifiers
isPrerelease(parseVersionStrict('1.0.0-beta.1')) // => true
isPrerelease(parseVersionStrict('1.0.0')) // => falseChecks if the version is a stable release (>= 1.0.0 with no prerelease).
Returns
booleanTrue if version is stable
Example
Check if version is a stable release
isStable(parseVersionStrict('1.0.0')) // => true
isStable(parseVersionStrict('0.9.0')) // => false (< 1.0.0)
isStable(parseVersionStrict('1.0.0-beta')) // => false (prerelease)Checks if a range represents a wildcard/any match.
Returns
booleanTrue if the range matches any version
Example
Check if a range represents a wildcard
isWildcard(parseRangeStrict('*')) // => true
isWildcard(parseRangeStrict('^1.0.0')) // => falseChecks if a < b.
Returns
booleanTrue if a is less than b
Example
Check if version a is less than b
lt(parseVersionStrict('1.0.0'), parseVersionStrict('2.0.0')) // => true
lt(parseVersionStrict('2.0.0'), parseVersionStrict('1.0.0')) // => falseChecks if a <= b.
Returns
booleanTrue if a is less than or equal to b
Example
Check if version a is less than or equal to b
lte(parseVersionStrict('1.0.0'), parseVersionStrict('1.0.0')) // => true
lte(parseVersionStrict('1.0.0'), parseVersionStrict('2.0.0')) // => trueReturns the maximum version from an array.
Parameters
| Name | Type | Description |
|---|---|---|
§versions | unknown | Array of versions |
Returns
SemVerThe maximum version, or null if array is empty
Example
Get the maximum version from an array
const versions = [parseVersionStrict('1.0.0'), parseVersionStrict('2.0.0')]
max(versions) // => { major: 2, minor: 0, patch: 0, ... }
max([]) // => nullFinds the maximum version that satisfies a range.
Parameters
Returns
SemVerThe maximum satisfying version, or null if none satisfy
Example
Find the maximum version satisfying a range
const versions = ['1.0.0', '1.5.0', '2.0.0'].map(parseVersionStrict)
maxSatisfying(versions, parseRangeStrict('^1.0.0'))
// => { major: 1, minor: 5, patch: 0, ... }Returns the minimum version from an array.
Parameters
| Name | Type | Description |
|---|---|---|
§versions | unknown | Array of versions |
Returns
SemVerThe minimum version, or null if array is empty
Example
Get the minimum version from an array
const versions = [parseVersionStrict('1.0.0'), parseVersionStrict('2.0.0')]
min(versions) // => { major: 1, minor: 0, patch: 0, ... }
min([]) // => nullFinds the minimum version that satisfies a range.
Parameters
Returns
SemVerThe minimum satisfying version, or null if none satisfy
Example
Find the minimum version satisfying a range
const versions = ['1.0.0', '1.5.0', '2.0.0'].map(parseVersionStrict)
minSatisfying(versions, parseRangeStrict('^1.0.0'))
// => { major: 1, minor: 0, patch: 0, ... }Checks if a != b.
Returns
booleanTrue if versions are not equal
Example
Check if two versions are not equal
neq(parseVersionStrict('1.0.0'), parseVersionStrict('2.0.0')) // => true
neq(parseVersionStrict('1.0.0'), parseVersionStrict('1.0.0')) // => falseParses a semver range string.
Supports:
Supports:
- Exact: 1.2.3, =1.2.3
- Comparators: >1.0.0, >=1.0.0, <2.0.0, <=2.0.0
- Caret: ^1.2.3 (compatible with version)
- Tilde: ~1.2.3 (approximately equivalent)
- X-ranges: 1.x, 1.2.x, *
- Hyphen ranges: 1.0.0 - 2.0.0
- OR: 1.0.0 || 2.0.0
- AND: >=1.0.0 <2.0.0
Parameters
| Name | Type | Description |
|---|---|---|
§input | string | The range string to parse |
Returns
ParseRangeResultA ParseRangeResult with the parsed range or error
Example
Parse semver range strings
parseRange('^1.0.0') // => { success: true, range: ... }
parseRange('>=1.0.0 <2.0.0') // => { success: true, range: ... }
parseRange('1.0.0 || 2.0.0') // => { success: true, range: ... }Parses a range string, throwing on invalid input.
Parameters
| Name | Type | Description |
|---|---|---|
§input | string | The range string to parse |
Returns
RangeThe parsed Range
Example
Parse range with strict validation
const range = parseRangeStrict('^1.0.0')
parseRangeStrict('invalid range!!!') // throws ErrorParses a semantic version string.
Accepts versions in the format: MAJOR.MINOR.PATCH[-prerelease][+build] Optional leading 'v' or '=' prefixes are stripped.
Accepts versions in the format: MAJOR.MINOR.PATCH[-prerelease][+build] Optional leading 'v' or '=' prefixes are stripped.
Parameters
| Name | Type | Description |
|---|---|---|
§input | string | The version string to parse |
Returns
ParseVersionResultA ParseVersionResult with the parsed version or error
Example
Parse a semantic version string
parseVersion('1.2.3') // { success: true, version: { major: 1, minor: 2, patch: 3, ... } }
parseVersion('v1.0.0-alpha.1+build.123') // { success: true, ... }
parseVersion('invalid') // { success: false, error: '...' }Parses a version string, throwing on invalid input.
Parameters
| Name | Type | Description |
|---|---|---|
§input | string | The version string to parse |
Returns
SemVerThe parsed SemVer
Example
Parse version with strict validation
const v = parseVersionStrict('1.2.3')
// => { major: 1, minor: 2, patch: 3, prerelease: [], build: [] }
parseVersionStrict('invalid') // throws ErrorChecks if a version satisfies a range.
Returns
booleanTrue if version satisfies the range
Example
Check if version satisfies a range
satisfies(parseVersion('1.2.3'), parseRange('^1.0.0')) // true
satisfies(parseVersion('2.0.0'), parseRange('^1.0.0')) // falseChecks if a version satisfies a comparator.
Parameters
| Name | Type | Description |
|---|---|---|
§version | SemVer | Version to check |
§comparator | Comparator | Comparator to test against |
Returns
booleanTrue if version satisfies the comparator
Example
Check if version satisfies a comparator
const gte100 = createComparator('>=', parseVersionStrict('1.0.0'))
satisfiesComparator(parseVersionStrict('2.0.0'), gte100) // => true
satisfiesComparator(parseVersionStrict('0.9.0'), gte100) // => falseSorts an array of versions in ascending order.
Parameters
| Name | Type | Description |
|---|---|---|
§versions | unknown | Array of versions to sort |
Returns
SemVer[A new sorted array
Example
Sort versions in ascending order
sort([v2, v1, v3]) // [v1, v2, v3]Sorts an array of versions in descending order.
Parameters
| Name | Type | Description |
|---|---|---|
§versions | unknown | Array of versions to sort |
Returns
SemVer[A new sorted array
Example
Sort versions in descending order
sortDescending([v1, v3, v2]) // [v3, v2, v1]Returns a new version with build metadata stripped.
Returns
SemVerA new SemVer without build metadata
Example
Strip build metadata from version
const v = parseVersionStrict('1.0.0+build.123')
format(stripBuild(v)) // => '1.0.0'Returns a new version with prerelease identifiers stripped.
Returns
SemVerA new SemVer without prerelease identifiers
Example
Strip prerelease identifiers from version
const v = parseVersionStrict('1.0.0-beta.1')
format(stripPrerelease(v)) // => '1.0.0'◈ Interfaces
A single comparator in a range set.
Examples:
Examples:
- >=1.2.3 -> { operator: '>=', version: { major: 1, minor: 2, patch: 3 } }
- ^1.2.0 -> { operator: '^', version: { major: 1, minor: 2, patch: 0 } }
Properties
A set of comparators that must all be satisfied. Represents the space-separated part of a range (AND logic).
Example: ">=1.0.0 <2.0.0" -> two comparators in one set
Example: ">=1.0.0 <2.0.0" -> two comparators in one set
Properties
Result of parsing a range string.
Properties
Result of parsing a version string.
Properties
A version range that can contain multiple comparator sets. Represents the || separated parts (OR logic).
Example: "^1.0.0 || ^2.0.0" -> two comparator sets
Example: "^1.0.0 || ^2.0.0" -> two comparator sets
Properties
Semantic Version
A version number in the format MAJOR.MINOR.PATCH with optional prerelease and build metadata.
A version number in the format MAJOR.MINOR.PATCH with optional prerelease and build metadata.
Properties
◆ Types
Bump type for version increments.
type BumpType = "major" | "minor" | "patch" | "premajor" | "preminor" | "prepatch" | "prerelease" | "none"Comparison operator for version ranges.
type RangeOperator = "=" | ">" | ">=" | "<