Utilities relating to generating badges relating to version numbers. Includes comparing versions to determine the latest, and determining the color to use for the badge based on whether the version is a stable release. For utilities specific to PHP version ranges, see php-version.js.
- Source:
Methods
(inner) compareDottedVersion(v1, v2) → {number}
Compares two strings representing version numbers lexicographically and returns an integer value.
Parameters:
| Name | Type | Description |
|---|---|---|
v1 |
string | The first version to compare |
v2 |
string | The second version to compare |
- Source:
Returns:
-1 if v1 is smaller than v2, 1 if v1 is larger than v2, 0 if v1 and v2 are equal
- Type
- number
Example
compareDottedVersion('1.2.3', '1.2.4') // returns -1 because numeric part of first version is smaller than the numeric part of second version.(inner) latest(versions, optionsopt) → {string|undefined}
Finds the largest version number lexicographically or semantically from an array of strings representing version numbers and returns it as a string. latest() is looser than latestMaybeSemVer() as it will attempt to make sense of anything, falling back to alphabetic sorting. We should ideally prefer latest() over latestMaybeSemVer() when adding version badges.
Parameters:
| Name | Type | Attributes | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
versions |
Array.<string> | The array of version numbers to compare |
|||||||||||
options |
object |
<optional> |
An optional object that contains additional options Properties
|
- Source:
Returns:
The largest version number as a string, or undefined if the array is empty
- Type
- string | undefined
Example
latest(['1.2.3', '1.2.4', '1.3', '2.0'], { pre: false }) // returns '2.0' because it is the largest version number and pre-release versions are excluded.
latest(['1.2.3', '1.2.4', '1.3', '2.0'], { pre: true }) // returns '2.0' because pre-release versions are included but none of them are present in the array.
latest(['1.2.3', '1.2.4', '1.3-alpha', '2.0-beta'], { pre: false }) // returns '1.2.4' because pre-release versions are excluded and it is the largest version number among the remaining ones.
latest(['1.2.3', '1.2.4', '1.3-alpha', '2.0-beta'], { pre: true }) // returns '2.0-beta' because pre-release versions are included and it is the largest version number.(inner) latestDottedVersion(versions) → {string|undefined}
Finds the largest version number lexicographically from an array of strings representing version numbers and returns it as a string.
Parameters:
| Name | Type | Description |
|---|---|---|
versions |
Array.<string> | The array of version numbers to compare |
- Source:
Returns:
The largest version number as a string, or undefined if the array is empty
- Type
- string | undefined
Example
latestDottedVersion(['1.2.3', '1.2.4', '1.3', '2.0']) // returns '2.0' because it is the largest version number in the array.
latestDottedVersion([]) // returns undefined because the array is empty.(inner) latestMaybeSemVer(versions, pre) → {string|undefined}
Finds the largest version number lexicographically or semantically from an array of strings representing version numbers and returns it as a string. latestMaybeSemVer() is used for versions that match some kind of dotted version pattern.
Parameters:
| Name | Type | Description |
|---|---|---|
versions |
Array.<string> | The array of version numbers to compare |
pre |
boolean | Whether to include pre-release versions or not |
- Source:
Returns:
The largest version number as a string, or undefined if the array is empty
- Type
- string | undefined
Example
latestMaybeSemVer(['1.2.3', '1.2.4', '1.3', '2.0'], false) // returns '2.0' because it is the largest version number and pre-release versions are excluded.
latestMaybeSemVer(['1.2.3', '1.2.4', '1.3', '2.0'], true) // returns '2.0' because pre-release versions are included but none of them are present in the array.
latestMaybeSemVer(['1.2.3', '1.2.4', '1.3-alpha', '2.0-beta'], false) // returns '1.2.4' because pre-release versions are excluded and it is the largest version number among the remaining ones.
latestMaybeSemVer(['1.2.3', '1.2.4', '1.3-alpha', '2.0-beta'], true) // returns '2.0-beta' because pre-release versions are included and it is the largest version number.(inner) listCompare(a, b) → {number}
Compares two arrays of numbers lexicographically and returns an integer value.
Parameters:
| Name | Type | Description |
|---|---|---|
a |
Array.<number> | The first array to compare |
b |
Array.<number> | The second array to compare |
- Source:
Returns:
-1 if a is smaller than b, 1 if a is larger than b, 0 if a and b are equal
- Type
- number
Example
listCompare([1, 2, 3], [1, 2, 4]) // returns -1 because the third element of the first array is smaller than the third element of the second array.(inner) rangeStart(v) → {string}
Returns the start of the range that matches a given version string.
Parameters:
| Name | Type | Description |
|---|---|---|
v |
string | A version string that follows the Semantic Versioning specification. The function will accept and coerce invalid versions into valid ones. |
- Source:
Throws:
-
If v is an invalid semver range
- Type
- TypeError
Returns:
The start of the range that matches the given version string, or null if no match is found.
- Type
- string
Example
rangeStart('^1.2.3') // returns '1.2.3'
rangeStart('>=2.0.0') // returns '2.0.0'
rangeStart('1.x || >=2.5.0 || 5.0.0 - 7.2.3') // returns '1.0.0'
rangeStart('1.2.x') // returns '1.2.0'
rangeStart('1.2.*') // returns '1.2.0-0'
rangeStart(null) // throws TypeError: Invalid Version: null
rangeStart('') // throws TypeError: Invalid Version:(inner) renderVersionBadge(options) → {object}
Creates a badge object that displays information about a version number. It should usually be used to output a version badge.
Parameters:
| Name | Type | Description | |||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
object | An object that contains the options for the badge Properties
|
- Source:
Returns:
A badge object that has three properties: label, message, and color
- Type
- object
Example
renderVersionBadge({version: '1.2.3', tag: 'alpha', defaultLabel: 'npm'}) // returns {label: 'npm@alpha', message: 'v1.2.3', color: 'orange'} because
it uses the tag and the defaultLabel to create the label, the addv function to add a 'v' prefix to the version in message,
and the versionColor function to assign an orange color based on the version.(inner) slice(v, releaseType) → {string|null}
Slices the specified number of dotted parts from the given semver version.
Parameters:
| Name | Type | Description |
|---|---|---|
v |
string | The semver version to slice |
releaseType |
string | The release type to slice up to. Can be one of "major", "minor", or "patch" |
- Source:
Returns:
The sliced version as a string, or null if the version is not valid
- Type
- string | null
Example
slice('2.4.7', 'minor') // returns '2.4' because it slices the version string up to the minor component.
slice('2.4.7-alpha', 'patch') // returns '2.4.7-alpha' because it slices the version string up to the patch component and preserves the prerelease component.
slice('2.4', 'patch') // returns null because the version string is not valid according to semver rules.