@vltpkg/semver

Classes

Comparator

Class used to parse the || separated portions of a range, and evaluate versions against it.

This does most of the heavy lifting of range testing, and provides little affordance for improperly formatted strings. It should be considered an internal class, and usually not accessed directly.

Constructors

new Comparator()

new Comparator(comp, includePrerelease): Comparator

Defined in: comparator.ts:160

Parameters

comp

string

includePrerelease

boolean = false

Returns

Comparator

Properties

includePrerelease

includePrerelease: boolean

Defined in: comparator.ts:128

does this range include prereleases, even when they do not match the tuple in the comparator?

isAny

isAny: boolean = false

Defined in: comparator.ts:148

true if this comparator is a '*' type of range.

Note that it still will not match versions with a prerelease value, unless the tuple in the version matches the tuple provided to the comparator, and the comparator version also has a prerelease value, unless includePrerelease is set.

isNone

isNone: boolean = false

Defined in: comparator.ts:139

true if this comparator can not match anything

raw

raw: string

Defined in: comparator.ts:130

raw string used to create this comparator

tokens

tokens: string[];

Defined in: comparator.ts:132

tokens extracted from the raw string input

tuples

tuples: (
  | Comparator
  | OVTuple)[] = [];

Defined in: comparator.ts:137

Either the any comparator, the none comparator, or an operator and a ParsedXRange

Methods

test()

test(v): boolean

Defined in: comparator.ts:634

return true if the version is a match for this comparator

Parameters

v

Version

Returns

boolean

toString()

toString(): string

Defined in: comparator.ts:151

the canonical strict simplified parsed form of this constructor

Returns

string

Range

Defined in: range.ts:11

A representation of a semver range, used to test versions.

Includes a set of comparators representing the ||-separated sections of the range string

Constructors

new Range()

new Range(range, includePrerelease): Range

Defined in: range.ts:36

Parameters

range

string

includePrerelease

boolean = false

Returns

Range

Properties

includePrerelease

includePrerelease: boolean

Defined in: range.ts:31

true if all prerelease versions should be included

isAny

isAny: boolean

Defined in: range.ts:16

true if the range is *

isSingle

isSingle: boolean

Defined in: range.ts:19

true if the range is a single semver version

raw

raw: string

Defined in: range.ts:13

raw string used to create this Range

set

set: Comparator[] = [];

Defined in: range.ts:28

set of Comparator objects representing the ||-separated sections of the range. If at least one of these matches, then the version is a match.

Methods

test()

test(v): boolean

Defined in: range.ts:67

test a Version against the range

Parameters

v

Version

Returns

boolean

toString()

toString(): string

Defined in: range.ts:72

return the simplified canonical form of this range

Returns

string

Version

Defined in: version.ts:65

A parsed object representation of a SemVer version string

This is a bit less forgiving than node-semver, in that prerelease versions MUST start with ’-’. Otherwise, the allowed syntax is identical.

Constructors

new Version()

new Version(
   version,
   major,
   minor,
   patch,
   prerelease,
   build): Version

Defined in: version.ts:143

Parameters

version

string

major

number

minor

number

patch

number

prerelease

undefined | string

build

undefined | string

Returns

Version

Properties

build?

optional build: string[];

Defined in: version.ts:87

List of '.'-separated strings in the build section.

This is undefined if the version does not have a build.

major

major: number

Defined in: version.ts:70

major version number

minor

minor: number

Defined in: version.ts:72

minor version number

patch

patch: number

Defined in: version.ts:74

patch version number

prerelease?

optional prerelease: (string | number)[];

Defined in: version.ts:81

List of '.'-separated strings and numbers indicating that this version is a prerelease.

This is undefined if the version does not have a prerelease section.

raw

raw: string

Defined in: version.ts:67

raw string provided to create this Version

Methods

compare()

compare(v): -1 | 0 | 1

Defined in: version.ts:194

Return 1 if this is > the provided version, -1 if we’re less, or 0 if they are equal.

No special handling for prerelease versions, this is just a precedence comparison.

This can be used to sort a list of versions by precedence:

const versions: Version[] = getVersionsSomehow()
const sorted = versions.sort((a, b) => a.compare(b))

Parameters

v

Version

Returns

-1 | 0 | 1

equals()

equals(v): boolean

Defined in: version.ts:255

true if these two versions have equal SemVer precedence

Parameters

v

Version

Returns

boolean

greaterThan()

greaterThan(v): boolean

Defined in: version.ts:235

true if this version is > the argument

Parameters

v

Version

Returns

boolean

greaterThanEqual()

greaterThanEqual(v): boolean

Defined in: version.ts:240

true if this version is >= the argument

Parameters

v

Version

Returns

boolean

inc()

inc(part, prereleaseIdentifier?): Version

Defined in: version.ts:327

Increment the version in place, in the manner specified.

Part behaviors:

'major' If the version is a M.0.0-... version with a prerelease, then simply drop the prerelease. Otherwise, set the minor and patch to 0, and increment the major. So 1.0.0-beta becomes 1.0.0, and 1.2.3 becomes 2.0.0
'minor' If the version is a M.m.0-... version with a prerelease, then simply drop the prerelease. Otherwise, set the patch to 0, and increment the minor. So 1.2.0-beta becomes 1.2.0, and 1.2.3 becomes 1.3.0.
'patch' If the version has a prerelease, then simply drop the prerelease. Otherwise, increment the patch value. So 1.2.3-beta becomes 1.2.3 and 1.2.3 becomes 1.2.4.
'premajor' Set the patch and minor versions to 0, increment the major version, and add a prerelease, using the optional identifier.
'preminor' Set the patch version to 0, increment the minor version, and add a prerelease, using the optional identifier.
'prepatch' If a prerelease is already present, increment the patch version, otherwise leave it untouched, and add a prerelease, using the optional identifier.
'prerelease' If a prerelease version is present, then behave the same as 'prepatch'. Otherwise, add a prerelease, using the optional identifier.
'pre' This is mostly for use by the other prerelease incrementers.
- If a prerelease identifier is provided:
  
  Update that named portion of the prerelease. For example, inc('1.2.3-beta.4', 'pre', 'beta') would result in 1.2.3-beta.5.
  
  If there is no prerelease identifier by that name, then replace the prerelease with [name]. So inc('1.2.3-alpha.4', 'pre', 'beta') would result in 1.2.3-beta.
  
  If the prerelease identifer is present, but has no numeric value following it, then add 0. So inc('1.2.3-beta', 'pre', 'beta') would result in 1.2.3-beta.0.
- If no prerelease identifier is provided:
  
  If there is no current prerelease, then set the prerelease to 0. So, inc('1.2.3', 'pre') becomes 1.2.3-0.
  
  If the last item in the prerelease is numeric, then increment it. So, inc('1.2.3-beta.3', 'pre') becomes 1.2.3-beta.4.

Parameters

part

IncrementType

prereleaseIdentifier?

string

Returns

Version

lessThan()

lessThan(v): boolean

Defined in: version.ts:245

true if this version is < the argument

Parameters

v

Version

Returns

boolean

lessThanEqual()

lessThanEqual(v): boolean

Defined in: version.ts:250

true if this version is <= the argument

Parameters

v

Version

Returns

boolean

rcompare()

rcompare(v): number

Defined in: version.ts:230

The inverse of compare, for sorting version lists in reverse order

Parameters

v

Version

Returns

number

satisfies()

satisfies(r): boolean

Defined in: version.ts:269

true if this version satisfies the range

Parameters

r

Range

Returns

boolean

toString()

toString(): string

Defined in: version.ts:90

Canonical strict form of this version

Returns

string

tupleEquals()

tupleEquals(v): boolean

Defined in: version.ts:260

just compare the M.m.p parts of the version

Parameters

v

Version

Returns

boolean

parse()

static parse(version): Version

Defined in: version.ts:97

Generate a Version object from a SemVer string

Parameters

version

string

Returns

Version

Type Aliases

ComplexOperator

type ComplexOperator = '^' | '~' | '~>'

Defined in: comparator.ts:10

operators that are expanded to simpler forms

IncrementType

type IncrementType =
  | 'major'
  | 'minor'
  | 'patch'
  | 'pre'
  | 'premajor'
  | 'preminor'
  | 'prepatch'
  | 'prerelease'

Defined in: version.ts:49

Types of incrementing supported by Version#inc

OVTuple

type OVTuple = [SimpleOperator, Version]

Defined in: comparator.ts:26

comparator expressed as a [operator,version] tuple

ParsedXMajor

type ParsedXMajor = []

Defined in: comparator.ts:85

a ParsedXRange that is just a *

ParsedXMinor

type ParsedXMinor = [number]

Defined in: comparator.ts:89

a ParsedXRange that is just a major version

ParsedXPatch

type ParsedXPatch = [number, number]

Defined in: comparator.ts:93

a ParsedXRange that is just a major and minor version

ParsedXRange

type ParsedXRange =
  | ParsedXMajor
  | ParsedXMinor
  | ParsedXPatch
  | ParsedXVersion

Defined in: comparator.ts:77

The result of parsing a version value that might be either a full version like 1.2.3 or an X-Range like 1.2.x

ParsedXVersion

type ParsedXVersion = [
  number,
  number,
  number,
  string | undefined,
  string | undefined,
]

Defined in: comparator.ts:97

a ParsedXRange that is a full version

SimpleOperator

type SimpleOperator = '' | '<' | '<=' | '>' | '>='

Defined in: comparator.ts:8

all comparators are expressed in terms of these operators

Functions

build()

function build(version): undefined | string[]

Defined in: index.ts:416

extract the list of build identifiers, or undefined if the version is invalid. If no build identifiers are present, returns [].

Parameters

version

string | Version

Returns

undefined | string[]

compare()

function compare(versionA, versionB): -1 | 0 | 1

Defined in: index.ts:334

Same as sortMethod, but throws if either version is not valid. 1 if versionA is higher precedence than versionB -1 if versionA is lower precedence than versionB 0 if they have equal precedence

Parameters

versionA

string | Version

versionB

string | Version

Returns

-1 | 0 | 1

eq()

function eq(versionA, versionB): boolean

Defined in: index.ts:389

true if versionA is equal to versionB. throws on invalid values

Parameters

versionA

string | Version

versionB

string | Version

Returns

boolean

filter()

function filter<T>(list, range, includePrerelease): T[]

Defined in: index.ts:201

Filter a list of versions to find all that match a given range.

Type Parameters

• T extends string | Version = string | Version

Parameters

list

T[]

range

string | Range

includePrerelease

boolean = false

Returns

T[]

filterMethod()

function filterMethod(range, includePrerelease): (version) => boolean

Defined in: index.ts:188

Method used by filter, for use in Array.filter directly.

Usage:

import { filterMethod } from '@vltpkg/semver'
const versions = ['1.2.3', '5.2.3', '2.3.4']
console.log(versions.filter(filterMethod('>=2.x')))
// ['5.2.3', '2.3.4']

Parameters

range

string | Range

includePrerelease

boolean = false

Returns

Function

Parameters

version

string | Version

Returns

boolean

gt()

function gt(versionA, versionB): boolean

Defined in: index.ts:364

true if versionA is > versionB. throws on invalid values

Parameters

versionA

string | Version

versionB

string | Version

Returns

boolean

gte()

function gte(versionA, versionB): boolean

Defined in: index.ts:369

true if versionA is >= versionB. throws on invalid values

Parameters

versionA

string | Version

versionB

string | Version

Returns

boolean

highest()

function highest(list, range, includePrerelease): undefined | Version

Defined in: index.ts:212

Find the highest-precedence match for a range within a list of versions

Returns undefined if no match was found.

Parameters

list

(string | Version)[]

range

string | Range

includePrerelease

boolean = false

Returns

undefined | Version

inc()

function inc(version, part, prereleaseIdentifier?): Version

Defined in: index.ts:82

Increment the specified part of the version, and return the resulting object. If a Version object is provided, it will be modified in-place.

See Version.inc for full description.

Parameters

version

string | Version

part

IncrementType

prereleaseIdentifier?

string

Returns

Version

lowest()

function lowest(list, range, includePrerelease): undefined | Version

Defined in: index.ts:282

Find the lowest-precedence match for a range within a list of versions

Returns undefined if no match was found.

Parameters

list

(string | Version)[]

range

string | Range

includePrerelease

boolean = false

Returns

undefined | Version

lt()

function lt(versionA, versionB): boolean

Defined in: index.ts:374

true if versionA is < versionB. throws on invalid values

Parameters

versionA

string | Version

versionB

string | Version

Returns

boolean

lte()

function lte(versionA, versionB): boolean

Defined in: index.ts:379

true if versionA is <= versionB. throws on invalid values

Parameters

versionA

string | Version

versionB

string | Version

Returns

boolean

major()

function major(version): undefined | number

Defined in: index.ts:395

extract the major version number, or undefined if invalid

Parameters

version

string | Version

Returns

undefined | number

minor()

function minor(version): undefined | number

Defined in: index.ts:398

extract the minor version number, or undefined if invalid

Parameters

version

string | Version

Returns

undefined | number

neq()

function neq(versionA, versionB): boolean

Defined in: index.ts:384

true if versionA is not equal to versionB. throws on invalid values

Parameters

versionA

string | Version

versionB

string | Version

Returns

boolean

parse()

function parse(version): undefined | Version

Defined in: index.ts:11

Return the parsed version string, or undefined if invalid

Parameters

version

string | Version

Returns

undefined | Version

parseRange()

function parseRange(range, includePrerelease): undefined | Range

Defined in: index.ts:21

Return the parsed version range, or undefined if invalid

Parameters

range

string | Range

includePrerelease

boolean = false

Returns

undefined | Range

patch()

function patch(version): undefined | number

Defined in: index.ts:401

extract the patch version number, or undefined if invalid

Parameters

version

string | Version

Returns

undefined | number

prerelease()

function prerelease(version): undefined | (string | number)[]

Defined in: index.ts:407

extract the list of prerelease identifiers, or undefined if the version is invalid. If no prerelease identifiers are present, returns [].

Parameters

version

string | Version

Returns

undefined | (string | number)[]

rcompare()

function rcompare(versionA, versionB): -1 | 0 | 1

Defined in: index.ts:358

Inverse of compare

Same as rsortMethod, but throws if either version is not valid.

-1 if versionA is higher precedence than versionB 1 if versionA is lower precedence than versionB 0 if they have equal precedence

Parameters

versionA

string | Version

versionB

string | Version

Returns

-1 | 0 | 1

rsort()

function rsort<T>(list): T[]

Defined in: index.ts:145

Sort an array of version strings or objects in descending SemVer precedence order (ie, highest versions first).

Invalid version strings are sorted to the end of the array in ascending alphabetical order.

Note: when using this method, the list is cloned prior to sorting, to prevent surprising mutation. To sort the list in place, see rsortMethod.

Type Parameters

• T extends string | Version = string | Version

Parameters

list

T[]

Returns

T[]

rsortedHighest()

function rsortedHighest(
  list,
  range,
  includePrerelease,
): undefined | Version

Defined in: index.ts:262

Faster form of highest, for use when the list is sorted in reverse precedence order (higher-precedence versions first).

Note: This stops at the first match, and will produce incorrect results when the list is not properly sorted!

Parameters

list

(string | Version)[]

range

string | Range

includePrerelease

boolean = false

Returns

undefined | Version

rsortedLowest()

function rsortedLowest(
  list,
  range,
  includePrerelease,
): undefined | Version

Defined in: index.ts:321

Faster form of lowest, for use when the list is sorted in reverse precedence order (higher-precedence versions first).

Note: This stops at the first match, and will produce incorrect results when the list is not properly sorted!

Parameters

list

(string | Version)[]

range

string | Range

includePrerelease

boolean = false

Returns

undefined | Version

rsortMethod()

function rsortMethod(a, b): number

Defined in: index.ts:162

The method used by rsort, exported for passing directly to Array.sort.

Usage:

import { rsortMethod } from '@vltpkg/semver'
const versions = ['1.2.3', '5.2.3', '2.3.4']
console.log(versions.sort(rsortMethod))
// ['5.2.3', '2.3.4', '1.2.3']

Parameters

a

string | Version

b

string | Version

Returns

number

satisfies()

function satisfies(version, range, includePrerelease): boolean

Defined in: index.ts:58

Return true if the version satisfies the range.

Parameters

version

string | Version

range

string | Range

includePrerelease

boolean = false

Returns

boolean

sort()

function sort<T>(list): T[]

Defined in: index.ts:130

Sort an array of version strings or objects in ascending SemVer precedence order (ie, lowest versions first).

Invalid version strings are sorted to the end of the array in ascending alphabetical order.

Note: when using this method, the list is cloned prior to sorting, to prevent surprising mutation. To sort the list in place, see sortMethod.

Type Parameters

• T extends string | Version = string | Version

Parameters

list

T[]

Returns

T[]

sortedHighest()

function sortedHighest(
  list,
  range,
  includePrerelease,
): undefined | Version

Defined in: index.ts:237

Faster form of highest, for use when the list is sorted in precedence order (lower-precedence versions first).

Note: This stops at the first match, and will produce incorrect results when the list is not properly sorted!

Parameters

list

(string | Version)[]

range

string | Range

includePrerelease

boolean = false

Returns

undefined | Version

sortedLowest()

function sortedLowest(
  list,
  range,
  includePrerelease,
): undefined | Version

Defined in: index.ts:307

Faster form of lowest, for use when the list is sorted in precedence order (lower-precedence versions first).

Note: This stops at the first match, and will produce incorrect results when the list is not properly sorted!

Parameters

list

(string | Version)[]

range

string | Range

includePrerelease

boolean = false

Returns

undefined | Version

sortMethod()

function sortMethod(a, b): number

Defined in: index.ts:105

The method used by sort, exported for passing directly to Array.sort.

Usage:

import { sortMethod } from '@vltpkg/semver'
const versions = ['1.2.3', '5.2.3', '2.3.4']
console.log(versions.sort(sortMethod))
// ['1.2.3', '2.3.4', '5.2.3']

Parameters

a

string | Version

b

string | Version

Returns

number

stable()

function stable<T>(versions): T[]

Defined in: index.ts:423

return all versions that do not have any prerelease identifiers

Type Parameters

• T extends string | Version = string | Version

Parameters

versions

T[]

Returns

T[]

valid()

function valid(version): boolean

Defined in: index.ts:43

return true if the version is valid

Note: do not use this if you intend to immediately parse the version if it’s valid. Just use parse, and guard the possible undefined value, or use Version.parse(..) to throw on invalid values.

Parameters

version

string | Version

Returns

boolean

validRange()

function validRange(range): boolean

Defined in: index.ts:52

return true if the range is valid

Note: do not use this if you intend to immediately parse the range if it’s valid. Just use parseRange, and guard the possible undefined value, or use new Range(..) to throw on invalid values.

Parameters

range

string | Range

Returns

boolean

On this page

@vltpkg/semver

Classes

Comparator

Constructors

new Comparator()

Parameters

comp

includePrerelease

Returns

Properties

includePrerelease

isAny

isNone

raw

tokens

tuples

Methods

test()

Parameters

v

Returns

toString()

Returns

Range

Constructors

new Range()

Parameters

range

includePrerelease

Returns

Properties

includePrerelease

isAny

isSingle

raw

set

Methods

test()

Parameters

v

Returns

toString()

Returns

Version

Constructors

new Version()

Parameters

version

major

minor

patch

prerelease

build

Returns

Properties

build?

major

minor

patch

prerelease?

raw

Methods

compare()

Parameters

v

Returns

equals()

Parameters

v

Returns

greaterThan()

Parameters

v

Returns

greaterThanEqual()

Parameters

v

Returns

inc()