@hyperfrontend/versioning/semver/compare

compare

Version-comparison primitives: equality, strict ordering, range satisfaction, and sort utilities.

compare, eq, lt, lte, gt, gte, and neq are the basic ordering operators over SemVer values. satisfies, satisfiesComparator, maxSatisfying, and minSatisfying answer range-membership and best-fit questions against Range and Comparator shapes. sort and sortDescending produce stable orderings; max and min are the convenience reductions. Behavior is fully spec-compliant with semver precedence, including the prerelease tie-breaker rules.

API Reference

ƒ Functions

§function

compare(a: SemVer, b: SemVer): -1 | 0 | 1

Compares two semantic versions.

Parameters

Name	Type	Description
§a	`SemVer`	First version
§b	`SemVer`	Second version

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')) // 1

§function

eq(a: SemVer, b: SemVer): boolean

Checks if two versions are equal (ignoring build metadata).

Parameters

Name	Type	Description
§a	`SemVer`	First version
§b	`SemVer`	Second version

Returns

boolean

True 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')) // => false

§function

gt(a: SemVer, b: SemVer): boolean

Checks if a > b.

Parameters

Name	Type	Description
§a	`SemVer`	First version to compare
§b	`SemVer`	Second version to compare

Returns

boolean

True 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')) // => false

§function

gte(a: SemVer, b: SemVer): boolean

Checks if a >= b.

Parameters

Name	Type	Description
§a	`SemVer`	First version to compare
§b	`SemVer`	Second version to compare

Returns

boolean

True 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')) // => true

§function

lt(a: SemVer, b: SemVer): boolean

Checks if a < b.

Parameters

Name	Type	Description
§a	`SemVer`	First version to compare
§b	`SemVer`	Second version to compare

Returns

boolean

True 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')) // => false

§function

lte(a: SemVer, b: SemVer): boolean

Checks if a <= b.

Parameters

Name	Type	Description
§a	`SemVer`	First version to compare
§b	`SemVer`	Second version to compare

Returns

boolean

True 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')) // => true

§function

max(versions: unknown): SemVer

Returns the maximum version from an array.

Parameters

Name	Type	Description
§versions	`unknown`	Array of versions

Returns

SemVer

The 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([]) // => null

§function

maxSatisfying(versions: unknown, range: Range): SemVer

Finds the maximum version that satisfies a range.

Parameters

Name	Type	Description
§versions	`unknown`	Array of versions to check
§range	`Range`	Range to test against

Returns

SemVer

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

§function

min(versions: unknown): SemVer

Returns the minimum version from an array.

Parameters

Name	Type	Description
§versions	`unknown`	Array of versions

Returns

SemVer

The 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([]) // => null

§function

minSatisfying(versions: unknown, range: Range): SemVer

Finds the minimum version that satisfies a range.

Parameters

Name	Type	Description
§versions	`unknown`	Array of versions to check
§range	`Range`	Range to test against

Returns

SemVer

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

§function

neq(a: SemVer, b: SemVer): boolean

Checks if a != b.

Parameters

Name	Type	Description
§a	`SemVer`	First version to compare
§b	`SemVer`	Second version to compare

Returns

boolean

True 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')) // => false

§function

satisfies(version: SemVer, range: Range): boolean

Checks if a version satisfies a range.

Parameters

Name	Type	Description
§version	`SemVer`	Version to check
§range	`Range`	Range to test against

Returns

boolean

True 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')) // false

§function

satisfiesComparator(version: SemVer, comparator: Comparator): boolean

Checks if a version satisfies a comparator.

Parameters

Name	Type	Description
§version	`SemVer`	Version to check
§comparator	`Comparator`	Comparator to test against

Returns

boolean

True 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) // => false

§function

sort(versions: unknown): SemVer[]

Sorts 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]

§function

sortDescending(versions: unknown): SemVer[]

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]