HyperFrontend
← Back to @hyperfrontend/versioning
@hyperfrontend/versioning/semver/parse

parse

Version and range parsing, with both strict and permissive variants.

parseVersion(input) accepts the common loose forms (leading v, missing patch, etc.) and returns a ParseVersionResult; parseVersionStrict rejects anything that isn't fully spec-compliant. coerceVersion is the most permissive option — it pulls a usable SemVer out of arbitrary inputs like "v1", "1.2", or "1.2.3.4" for use cases where semver-ish input must be normalized. parseRange and parseRangeStrict are the equivalents for npm-style range syntax (^1.2.0, ~1.2, >=1.0.0 <2.0.0, ...) and return a ParseRangeResult carrying either the parsed Range or a structured failure reason.

API Reference

ƒ Functions

§function

coerceVersion(input: string): SemVer

Attempts to coerce a string into a valid semver. More lenient than parseVersion - accepts partial versions.

Parameters

NameTypeDescription
§input
string
The string to coerce

Returns

SemVer
The 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, ... }
§function

parseRange(input: string): ParseRangeResult

Parses a semver range string.
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

NameTypeDescription
§input
string
The range string to parse

Returns

ParseRangeResult
A 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: ... }
§function

parseRangeStrict(input: string): Range

Parses a range string, throwing on invalid input.

Parameters

NameTypeDescription
§input
string
The range string to parse

Returns

Range
The parsed Range

Example

Parse range with strict validation

const range = parseRangeStrict('^1.0.0')
parseRangeStrict('invalid range!!!') // throws Error
§function

parseVersion(input: string): ParseVersionResult

Parses a semantic version string.
Accepts versions in the format: MAJOR.MINOR.PATCH[-prerelease][+build] Optional leading 'v' or '=' prefixes are stripped.

Parameters

NameTypeDescription
§input
string
The version string to parse

Returns

ParseVersionResult
A 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: '...' }
§function

parseVersionStrict(input: string): SemVer

Parses a version string, throwing on invalid input.

Parameters

NameTypeDescription
§input
string
The version string to parse

Returns

SemVer
The 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 Error

◈ Interfaces

§interface

ParseRangeResult

Result of parsing a range string.

Properties

§readonly error?:string—
Error message (if failed)
§readonly range?:Range—
The parsed range (if successful)
§readonly success:boolean—
Whether parsing succeeded
§interface

ParseVersionResult

Result of parsing a version string.

Properties

§readonly error?:string—
Error message (if failed)
§readonly success:boolean—
Whether parsing succeeded
§readonly version?:SemVer—
The parsed version (if successful)