@vltpkg/semver

Classes

Comparator

Defined in: comparator.ts:123

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:633

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:25

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:50

Parameters

range

string

includePrerelease

boolean = false

Returns

Range

Properties

includePrerelease

includePrerelease: boolean

Defined in: range.ts:45

true if all prerelease versions should be included

isAny

isAny: boolean

Defined in: range.ts:30

true if the range is *

isSingle

isSingle: boolean

Defined in: range.ts:33

true if the range is a single semver version

raw

raw: string

Defined in: range.ts:27

raw string used to create this Range

set

set: Comparator[] = [];

Defined in: range.ts:42

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:100

test a Version against the range

Parameters

v

Version

Returns

boolean

toString()

toString(): string

Defined in: range.ts:105

return the simplified canonical form of this range

Returns

string

---

Version

Defined in: version.ts:71

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:145

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:93

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:76

major version number

minor

minor: number

Defined in: version.ts:78

minor version number

patch

patch: number

Defined in: version.ts:80

patch version number

prerelease?

optional prerelease: (string | number)[];

Defined in: version.ts:87

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:73

raw string provided to create this Version

Methods

compare()

compare(v): -1 | 0 | 1

Defined in: version.ts:196

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:257

true if these two versions have equal SemVer precedence

Parameters

v

Version

Returns

boolean

greaterThan()

greaterThan(v): boolean

Defined in: version.ts:237

true if this version is > the argument

Parameters

v

Version

Returns

boolean

greaterThanEqual()

greaterThanEqual(v): boolean

Defined in: version.ts:242

true if this version is >= the argument

Parameters

v

Version

Returns

boolean

inc()

inc(part, prereleaseIdentifier?): Version

Defined in: version.ts:329

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

"major" | "minor" | "patch" | "pre" | "premajor" | "preminor" | "prepatch" | "prerelease"

prereleaseIdentifier?

string

Returns

Version

lessThan()

lessThan(v): boolean

Defined in: version.ts:247

true if this version is < the argument

Parameters

v

Version

Returns

boolean

lessThanEqual()

lessThanEqual(v): boolean

Defined in: version.ts:252

true if this version is <= the argument

Parameters

v

Version

Returns

boolean

rcompare()

rcompare(v): number

Defined in: version.ts:232

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

Parameters

v

Version

Returns

number

satisfies()

satisfies(r): boolean

Defined in: version.ts:271

true if this version satisfies the range

Parameters

r

Range

Returns

boolean

toString()

toString(): string

Defined in: version.ts:96

Canonical strict form of this version

Returns

string

tupleEquals()

tupleEquals(v): boolean

Defined in: version.ts:262

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

Parameters

v

Version

Returns

boolean

parse()

static parse(version): Version

Defined in: version.ts:103

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 = (typeof versionIncrements)[number]

Defined in: version.ts:63

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

Variables

versionIncrements

const versionIncrements: readonly [
  'major',
  'minor',
  'patch',
  'pre',
  'premajor',
  'preminor',
  'prepatch',
  'prerelease',
]

Defined in: version.ts:49

Values of valid increment types.

Functions

build()

function build(version): undefined | string[]

Defined in: index.ts:417

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:335

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:390

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:202

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:189

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:365

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:370

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:213

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:83

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

"major" | "minor" | "patch" | "pre" | "premajor" | "preminor" | "prepatch" | "prerelease"

prereleaseIdentifier?

string

Returns

Version

---

intersects()

function intersects(r1, r2, includePrerelease?): boolean

Defined in: index.ts:438

Return true if the range r1 intersects any of the ranges r2 r1 and r2 are either Range objects or range strings. Returns true if any version would satisfy both ranges.

Parameters

r1

string | Range

r2

string | Range

includePrerelease?

boolean

Returns

boolean

---

isRange()

function isRange(range): range is Range

Defined in: range.ts:6

Parameters

range

unknown

Returns

range is Range

---

lowest()

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

Defined in: index.ts:283

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:375

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:380

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:396

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:399

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:385

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:12

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:22

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:402

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:408

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:359

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:146

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:263

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:322

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:163

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:59

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:131

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:238

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:308

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:106

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:424

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:44

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:53

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