Edit

Version class

  • Reference
Package:
@microsoft/sp-core-library

Represents a version number with two, three, or four parts.

Remarks

This class represents versions that follow the string format of MAJOR.MINOR[.PATCH[.REVISION]] where the MAJOR, MINOR, PATCH and REVISION parts are integers. PATCH and REVISION are optional. Leading zero digits are allowed, but they are discarded. Missing parts are treated as zeroes for comparisons.

Examples: 1.0, 1.0.0, 1.0.0.0, 1.01, 01.02.03, 001.002.003.004

Properties

major

Returns the first component of the version string.
minor

Returns the second component of the version string.
patch

The third number in the version string, or undefined if unspecified.
revision

The fourth number in the version string, or undefined if unspecified.

Methods

compare(v1, v2)

Compares two Version objects to determine which version is newer.
equals(compareWith)

Tests whether this version is equal to the input parameter.
greaterThan(compareWith)

Tests whether this version is greater than (i.e. newer than) the input parameter.
isValid(versionString)

Test whether a string is a valid version specifier.
lessThan(compareWith)

Tests whether this version is less than (i.e. older than) the input parameter.
parse(versionString)

Constructs a new Version instance using the version string. An exception is thrown if the string cannot be parsed.
satisfies(compareWith)

Tests whether this version satisfies the compatibility requirements of the input version, i.e. is backwards compatible.
toString()

Returns a string representation of the version.
tryParse(versionString)

Attempts to parse the input string to construct a new Version object. If the string cannot be parsed, then undefined is returned.

Property Details

major

Returns the first component of the version string.

get major(): number;

Property Value

number

Remarks

Typically a change in the major version number indicates a compatibility break with previous versions.

minor

Returns the second component of the version string.

get minor(): number;

Property Value

number

Remarks

Typically a change in the minor version number indicates that new features were added, while remaining backwards compatible with previous releases.

patch

The third number in the version string, or undefined if unspecified.

get patch(): number | undefined;

Property Value

number | undefined

Remarks

Typically a change in the patch version number indicates a small fix that does not affect the compatibility contract for the library. For a .NET System.Version object, this is referred to as the "build" number.

revision

The fourth number in the version string, or undefined if unspecified.

get revision(): number | undefined;

Property Value

number | undefined

Remarks

This number is not part of the Semantic Versioning (SemVer) standard used in JavaScript, but it is used by .NET version numbers.

Method Details

compare(v1, v2)

Compares two Version objects to determine which version is newer.

static compare(v1: Version, v2: Version): number;

Parameters

v1
Version

The first version class for comparison

v2
Version

The second version class for comparison

Returns

number

-1 if the first input is less than the second input; 0 if the first input is equal to the second input; 1 if the first input is greater than the second input.

equals(compareWith)

Tests whether this version is equal to the input parameter.

equals(compareWith: Version): boolean;

Parameters

compareWith
Version

The version to compare with

Returns

boolean

A boolean indicating if this version is equal to the input parameter

Remarks

Examples:

1.0.0 equals 1.0.0 -> true;
2.0.1 equals 2.0.0 -> false;
3.0   equals 3.0.0 -> true;
04.01 equals 4.1   -> true

greaterThan(compareWith)

Tests whether this version is greater than (i.e. newer than) the input parameter.

greaterThan(compareWith: Version): boolean;

Parameters

compareWith
Version

The version to compare with

Returns

boolean

A boolean indicating if this version is greater than the input parameter

Remarks

Examples:

1.0.0 greaterThan 0.0.9 -> true;
2.0   greaterThan 2.0.0 -> false;
3.0.1 greaterThan 3.0   -> true

isValid(versionString)

Test whether a string is a valid version specifier.

static isValid(versionString: string | undefined | null): boolean;

Parameters

versionString

string | undefined | null

The version string

Returns

boolean

true if the versionString is a valid version specifier

lessThan(compareWith)

Tests whether this version is less than (i.e. older than) the input parameter.

lessThan(compareWith: Version): boolean;

Parameters

compareWith
Version

The version to compare with

Returns

boolean

A boolean indicating if this version is less than the input parameter

Remarks

Examples:

0.9.9 lessThan 1.0.0 -> true;
2.0   lessThan 2.0.0 -> false;
3.0   lessThan 3.0.1 -> true;
04.01 lessThan 4.1   -> false

parse(versionString)

Constructs a new Version instance using the version string. An exception is thrown if the string cannot be parsed.

static parse(versionString: string | undefined | null): Version;

Parameters

versionString

string | undefined | null

A version string

Returns

Version

a new Version object

satisfies(compareWith)

Tests whether this version satisfies the compatibility requirements of the input version, i.e. is backwards compatible.

satisfies(compareWith: Version): boolean;

Parameters

compareWith
Version

The version to compare with

Returns

boolean

A boolean indicating if this version is compatible with the input parameter

Remarks

In order to satisfy the compatibility requirements, this object must have the same major version number as the input parameter, and it must NOT be older than the input parameter.

Examples:

1.0.0 satisfies 1.0.0 -> true;
1.1.0 satisfies 1.0.0 -> true;
2.0.0 satisfies 1.0.0 -> false;
1.0.0 satisfies 1.1.0 -> false

toString()

Returns a string representation of the version.

toString(): string;

Returns

string

Remarks

The value is normalized and may be different from the original string (e.g. leading zeroes may be removed). However, the number of version parts will be unchanged.

tryParse(versionString)

Attempts to parse the input string to construct a new Version object. If the string cannot be parsed, then undefined is returned.

static tryParse(versionString: string | undefined | null): Version | undefined;

Parameters

versionString

string | undefined | null

A version string

Returns

Version | undefined

The Version object, or undefined if the string could not be parsed.