Modules | @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

Parameters

• comp: string

• includePrerelease: boolean = false

Returns

Comparator

Defined in

comparator.ts:160

Properties

includePrerelease

includePrerelease: boolean

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

Defined in

comparator.ts:128

isAny

isAny: boolean = false

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.

Defined in

comparator.ts:148

isNone

isNone: boolean = false

true if this comparator can not match anything

Defined in

comparator.ts:139

raw

raw: string

raw string used to create this comparator

Defined in

comparator.ts:130

tokens

tokens: string[];

tokens extracted from the raw string input

Defined in

comparator.ts:132

tuples

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

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

Defined in

comparator.ts:137

Methods

test()

test(v): boolean

return true if the version is a match for this comparator

Parameters

• v: Version

Returns

boolean

Defined in

comparator.ts:634

toString()

toString(): string

the canonical strict simplified parsed form of this constructor

Returns

string

Defined in

comparator.ts:151

Range

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

Parameters

• range: string

• includePrerelease: boolean = false

Returns

Range

Defined in

range.ts:36

Properties

includePrerelease

includePrerelease: boolean

true if all prerelease versions should be included

Defined in

range.ts:31

isAny

isAny: boolean

true if the range is *

Defined in

range.ts:16

isSingle

isSingle: boolean

true if the range is a single semver version

Defined in

range.ts:19

raw

raw: string

raw string used to create this Range

Defined in

range.ts:13

set

set: Comparator[] = [];

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

Defined in

range.ts:28

Methods

test()

test(v): boolean

test a Version against the range

Parameters

• v: Version

Returns

boolean

Defined in

range.ts:67

toString()

toString(): string

return the simplified canonical form of this range

Returns

string

Defined in

range.ts:72

Version

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

Parameters

• version: string

• major: number

• minor: number

• patch: number

• prerelease: undefined | string

• build: undefined | string

Returns

Version

Defined in

version.ts:143

Properties

build?

optional build: string[];

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

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

Defined in

version.ts:87

major

major: number

major version number

Defined in

version.ts:70

minor

minor: number

minor version number

Defined in

version.ts:72

patch

patch: number

patch version number

Defined in

version.ts:74

prerelease?

optional prerelease: (string | number)[];

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.

Defined in

version.ts:81

raw

raw: string

raw string provided to create this Version

Defined in

version.ts:67

Methods

compare()

compare(v): -1 | 0 | 1

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

Defined in

version.ts:194

equals()

equals(v): boolean

true if these two versions have equal SemVer precedence

Parameters

• v: Version

Returns

boolean

Defined in

version.ts:255

greaterThan()

greaterThan(v): boolean

true if this version is > the argument

Parameters

• v: Version

Returns

boolean

Defined in

version.ts:235

greaterThanEqual()

greaterThanEqual(v): boolean

true if this version is >= the argument

Parameters

• v: Version

Returns

boolean

Defined in

version.ts:240

inc()

inc(part, prereleaseIdentifier?): Version

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

Defined in

version.ts:327

lessThan()

lessThan(v): boolean

true if this version is < the argument

Parameters

• v: Version

Returns

boolean

Defined in

version.ts:245

lessThanEqual()

lessThanEqual(v): boolean

true if this version is <= the argument

Parameters

• v: Version

Returns

boolean

Defined in

version.ts:250

rcompare()

rcompare(v): number

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

Parameters

• v: Version

Returns

number

Defined in

version.ts:230

satisfies()

satisfies(r): boolean

true if this version satisfies the range

Parameters

• r: Range

Returns

boolean

Defined in

version.ts:269

toString()

toString(): string

Canonical strict form of this version

Returns

string

Defined in

version.ts:90

tupleEquals()

tupleEquals(v): boolean

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

Parameters

• v: Version

Returns

boolean

Defined in

version.ts:260

parse()

static parse(version): Version

Generate a Version object from a SemVer string

Parameters

• version: string

Returns

Version

Defined in

version.ts:97

Type Aliases

ComplexOperator

type ComplexOperator: "^" | "~" | "~>";

operators that are expanded to simpler forms

Defined in

comparator.ts:10

IncrementType

type IncrementType:
  | "major"
  | "minor"
  | "patch"
  | "pre"
  | "premajor"
  | "preminor"
  | "prepatch"
  | "prerelease";

Types of incrementing supported by Version#inc

Defined in

version.ts:49

OVTuple

type OVTuple: [SimpleOperator, Version];

comparator expressed as a [operator,version] tuple

Defined in

comparator.ts:26

ParsedXMajor

type ParsedXMajor: [];

a ParsedXRange that is just a *

Defined in

comparator.ts:85

ParsedXMinor

type ParsedXMinor: [number];

a ParsedXRange that is just a major version

Defined in

comparator.ts:89

ParsedXPatch

type ParsedXPatch: [number, number];

a ParsedXRange that is just a major and minor version

Defined in

comparator.ts:93

ParsedXRange

type ParsedXRange: ParsedXMajor | ParsedXMinor | ParsedXPatch | ParsedXVersion;

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

Defined in

comparator.ts:77

ParsedXVersion

type ParsedXVersion: [number, number, number, string | undefined, string | undefined];

a ParsedXRange that is a full version

Defined in

comparator.ts:97

SimpleOperator

type SimpleOperator:
  | ""
  | "<"
  | "<="
  | ">"
  | ">=";

all comparators are expressed in terms of these operators

Defined in

comparator.ts:8

Functions

build()

function build(version): undefined | string[]

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

Defined in

index.ts:415

compare()

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

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

Defined in

index.ts:333

eq()

function eq(versionA, versionB): boolean

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

Parameters

• versionA: string | Version

• versionB: string | Version

Returns

boolean

Defined in

index.ts:388

filter()

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

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

Defined in

index.ts:200

filterMethod()

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

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

Defined in

index.ts:187

gt()

function gt(versionA, versionB): boolean

true if versionA is > versionB. throws on invalid values

Parameters

• versionA: string | Version

• versionB: string | Version

Returns

boolean

Defined in

index.ts:363

gte()

function gte(versionA, versionB): boolean

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

Parameters

• versionA: string | Version

• versionB: string | Version

Returns

boolean

Defined in

index.ts:368

highest()

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

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

Defined in

index.ts:211

inc()

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

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

Defined in

index.ts:81

lowest()

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

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

Defined in

index.ts:281

lt()

function lt(versionA, versionB): boolean

true if versionA is < versionB. throws on invalid values

Parameters

• versionA: string | Version

• versionB: string | Version

Returns

boolean

Defined in

index.ts:373

lte()

function lte(versionA, versionB): boolean

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

Parameters

• versionA: string | Version

• versionB: string | Version

Returns

boolean

Defined in

index.ts:378

major()

function major(version): undefined | number

extract the major version number, or undefined if invalid

Parameters

• version: string | Version

Returns

undefined | number

Defined in

index.ts:394

minor()

function minor(version): undefined | number

extract the minor version number, or undefined if invalid

Parameters

• version: string | Version

Returns

undefined | number

Defined in

index.ts:397

neq()

function neq(versionA, versionB): boolean

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

Parameters

• versionA: string | Version

• versionB: string | Version

Returns

boolean

Defined in

index.ts:383

parse()

function parse(version): undefined | Version

Return the parsed version string, or undefined if invalid

Parameters

• version: string | Version

Returns

undefined | Version

Defined in

index.ts:10

parseRange()

function parseRange(range, includePrerelease): undefined | Range

Return the parsed version range, or undefined if invalid

Parameters

• range: string | Range

• includePrerelease: boolean = false

Returns

undefined | Range

Defined in

index.ts:20

patch()

function patch(version): undefined | number

extract the patch version number, or undefined if invalid

Parameters

• version: string | Version

Returns

undefined | number

Defined in

index.ts:400

prerelease()

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

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)[]

Defined in

index.ts:406

rcompare()

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

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

Defined in

index.ts:357

rsort()

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

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

Defined in

index.ts:144

rsortedHighest()

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

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

Defined in

index.ts:261

rsortedLowest()

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

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

Defined in

index.ts:320

rsortMethod()

function rsortMethod(a, b): number

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

Defined in

index.ts:161

satisfies()

function satisfies(version, range, includePrerelease): boolean

Return true if the version satisfies the range.

Parameters

• version: string | Version

• range: string | Range

• includePrerelease: boolean = false

Returns

boolean

Defined in

index.ts:57

sort()

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

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

Defined in

index.ts:129

sortedHighest()

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

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

Defined in

index.ts:236

sortedLowest()

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

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

Defined in

index.ts:306

sortMethod()

function sortMethod(a, b): number

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

Defined in

index.ts:104

stable()

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

return all versions that do not have any prerelease identifiers

Type Parameters

• T extends string | Version = string | Version

Parameters

• versions: T[]

Returns

T[]

Defined in

index.ts:422

valid()

function valid(version): boolean

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

Defined in

index.ts:42

validRange()

function validRange(range): boolean

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

Defined in

index.ts:51