Reference

Classes

Comparator

Defined in: comparator.ts:120

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

Parameters

Returns

Comparator

Properties

Methods

test()

test(v): boolean

Defined in: comparator.ts:630

return true if the version is a match for this comparator

Parameters

Returns

boolean

toString()

toString(): string

Defined in: comparator.ts:148

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

Returns

Range

Properties

Methods

test()

test(v): boolean

Defined in: range.ts:100

test a Version against the range

Parameters

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

Returns

Version

Properties

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

Returns

-1 | 0 | 1

equals()

equals(v): boolean

Defined in: version.ts:257

true if these two versions have equal SemVer precedence

Parameters

Returns

boolean

greaterThan()

greaterThan(v): boolean

Defined in: version.ts:237

true if this version is > the argument

Parameters

Returns

boolean

greaterThanEqual()

greaterThanEqual(v): boolean

Defined in: version.ts:242

true if this version is >= the argument

Parameters

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

Returns

Version

lessThan()

lessThan(v): boolean

Defined in: version.ts:247

true if this version is < the argument

Parameters

Returns

boolean

lessThanEqual()

lessThanEqual(v): boolean

Defined in: version.ts:252

true if this version is <= the argument

Parameters

Returns

boolean

rcompare()

rcompare(v): number

Defined in: version.ts:232

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

Parameters

Returns

number

satisfies()

satisfies(r): boolean

Defined in: version.ts:271

true if this version satisfies the range

Parameters

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

Returns

boolean

parse()

static parse(version): Version

Defined in: version.ts:103

Generate a Version object from a SemVer string

Parameters

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

a ParsedXRange that is just a *

ParsedXMinor

type ParsedXMinor = [number];

Defined in: comparator.ts:86

a ParsedXRange that is just a major version

ParsedXPatch

type ParsedXPatch = [number, number];

Defined in: comparator.ts:90

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

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

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

Parameters

Returns

undefined | string[]

compare()

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

Defined in: index.ts:359

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

Returns

-1 | 0 | 1

eq()

function eq(versionA, versionB): boolean

Defined in: index.ts:414

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

Parameters

Returns

boolean

filter()

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

Defined in: index.ts:226

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

Type Parameters

Parameters

Returns

T[]

filterMethod()

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

Defined in: index.ts:213

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

Returns

Function

Parameters

Returns

boolean

gt()

function gt(versionA, versionB): boolean

Defined in: index.ts:389

true if versionA is > versionB. throws on invalid values

Parameters

Returns

boolean

gte()

function gte(versionA, versionB): boolean

Defined in: index.ts:394

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

Parameters

Returns

boolean

highest()

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

Defined in: index.ts:237

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

Returns undefined if no match was found.

Parameters

Returns

undefined | Version

inc()

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

Defined in: index.ts:107

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

Returns

Version

intersects()

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

Defined in: index.ts:473

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

Returns

boolean

isRange()

function isRange(range): range is Range

Defined in: range.ts:6

Parameters

Returns

range is Range

lowest()

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

Defined in: index.ts:307

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

Returns undefined if no match was found.

Parameters

Returns

undefined | Version

lt()

function lt(versionA, versionB): boolean

Defined in: index.ts:399

true if versionA is < versionB. throws on invalid values

Parameters

Returns

boolean

lte()

function lte(versionA, versionB): boolean

Defined in: index.ts:404

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

Parameters

Returns

boolean

major()

function major(version): undefined | number

Defined in: index.ts:420

extract the major version number, or undefined if invalid

Parameters

Returns

undefined | number

minor()

function minor(version): undefined | number

Defined in: index.ts:423

extract the minor version number, or undefined if invalid

Parameters

Returns

undefined | number

neq()

function neq(versionA, versionB): boolean

Defined in: index.ts:409

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

Parameters

Returns

boolean

parse()

function parse(version): undefined | Version

Defined in: index.ts:12

Return the parsed version string, or undefined if invalid

Parameters

Returns

undefined | Version

parseRange()

function parseRange(range, includePrerelease): undefined | Range

Defined in: index.ts:37

Return the parsed version range, or undefined if invalid

Parameters

Returns

undefined | Range

patch()

function patch(version): undefined | number

Defined in: index.ts:426

extract the patch version number, or undefined if invalid

Parameters

Returns

undefined | number

prerelease()

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

Defined in: index.ts:432

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

Parameters

Returns

undefined | (string | number)[]

rcompare()

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

Defined in: index.ts:383

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

Returns

-1 | 0 | 1

rsort()

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

Defined in: index.ts:170

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

Parameters

Returns

T[]

rsortedHighest()

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

Defined in: index.ts:287

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

Returns

undefined | Version

rsortedLowest()

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

Defined in: index.ts:346

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

Returns

undefined | Version

rsortMethod()

function rsortMethod(a, b): number

Defined in: index.ts:187

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

Returns

number

satisfies()

function satisfies(
   version, 
   range, 
   includePrerelease): boolean

Defined in: index.ts:83

Return true if the version satisfies the range.

Parameters

Returns

boolean

sort()

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

Defined in: index.ts:155

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

Parameters

Returns

T[]

sortedHighest()

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

Defined in: index.ts:262

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

Returns

undefined | Version

sortedLowest()

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

Defined in: index.ts:332

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

Returns

undefined | Version

sortMethod()

function sortMethod(a, b): number

Defined in: index.ts:130

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

Returns

number

stable()

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

Defined in: index.ts:448

return all versions that do not have any prerelease identifiers

Type Parameters

Parameters

Returns

T[]

subset()

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

Defined in: index.ts:508

Check if range r1 is a subset of range r2. Returns true if every version that satisfies r1 also satisfies r2.

Parameters

Returns

boolean

valid()

function valid(version): boolean

Defined in: index.ts:68

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

Returns

boolean

validRange()

function validRange(range): boolean

Defined in: index.ts:77

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

Returns

boolean