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.