@liquid-labs/semver-plus

Adds additional functionality to and fixes limitations in the base semver package.

Installation

npm i @liquid-labs/semver-plus

Usage

import * as semverplus from '@liquid-labs/semver-plus'

// use recognized 'alpha' -> 'beta' -> 'rc' -> gold/production progression with 'pretype'
const nextVer = semverplus.nextVersion('v1.0.0-alpha.8', 'pretype')
console.log(`next version: ${nextVer}`) // 'v1.0.0-beta.0'

API reference

API generated with dmd-readme-api.

• Functions:
  • Comparison operations
    • cmp(): Returns a number indicating whether a version is greater than, equal to, or less than another version.
    • compare(): Returns 0 if v1 == v2, 1 if v1 > v2, and -1 if v1 < v2.
    • compareBuild(): Same as compare except it compares build if two versions are otherwise equal.
    • compareLoose(): Short for compare with options.loose = true.
    • diff(): Returns the difference between two versions.
    • eq(): Returns true if v1 is equal to v2, false otherwise.
    • gt(): Returns true if v1 is greater than v2, false otherwise.
    • gte(): Returns true if v1 is greater than or equal to v2, false otherwise.
    • lt(): Returns true if v1 is less than v2, false otherwise.
    • lte(): Returns true if v1 is less than or equal to v2, false otherwise.
    • neq(): Returns true if v1 is not equal to v2, false otherwise.
    • rcompare(): Reverse of compare.
    • rsort(): Sorts an array of versions in descending order using compareBuild.
    • sort(): Sorts an array of versions in ascending order using compareBuild.
    • xSort(): Ascend sorts a mix of semver versions and x-range specified ranges (e.g., 1.2.* or 1.2.x).
  • Range operations
    • gtr(): Returns true if version is greater than is greater than any version in range, false otherwise.
    • intersects(): Returns true if any of the comparators in the range intersect with each other.
    • ltr(): Returns true if version is less than is less than any version in range, false otherwise.
    • maxSatisfying(): Returns the highest version in versions that satisfies the range, or null if no version satisfies the range.
    • minSatisfying(): Returns the lowest version in versions that satisfies the range, or null if no version satisfies the range.
    • minVersion(): Returns the lowest version that satisfies the range, or null if no version satisfies the range.
    • outside(): Returns true if version is outside of range in the indicated direction, false otherwise.
    • satisfies(): Returns true if the version satisfies the range, false otherwise.
    • simplifyRange(): Return a "simplified" range that matches the same items in the versions list as the range specified.
    • subset(): Returns true if subRange is a subset of superRange, false otherwise.
    • upperBound(): Finds the ceiling of a range.
    • validRange(): Returns a parsed, normalized range string or null if the range is invalid.
    • validVersionOrRange(): Validates a string to be a valid version or range.
  • Version operations
    • clean(): Returns a cleaned version string removing unecessary comparators and, if options.loose is true, fixing space issues.
    • coerce(): Aggressively attempts to coerce a string into a valid semver string.
    • inc(): Returns a new version string incremented by the specified part.
    • major(): Returns the major version number.
    • minor(): Returns the minor version number.
    • nextVersion(): Given a current version generates the next version string accourding to increment.
    • parse(): Attempts to parse and normalize a string as a semver string.
    • patch(): Returns the patch version number.
    • prerelease(): Returns an array of prerelease components or null if the version is not a prerelease.
    • valid(): Returns a parsed, normalized version string or null if the version is invalid.

cmp(v1, comparator, v2, options) ⇒ number ↱source code ⇧global index

Returns a number indicating whether a version is greater than, equal to, or less than another version.

| Param | Type | Description | | --- | --- | --- | | v1 | string | The first version to compare. | | comparator | string | The comparator to use. May be '<', '<=', '>', '>=', '=', '==', '!=', '===', or '!=='. An exception is thrown if an invalid comparator is provided. | | v2 | string | The second version to compare. | | options | object | The options to pass to the semver.cmp function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. |

Returns: number - - A number indicating whether a version is greater than, equal to, or less than another version.

Category: Comparison operations

compare(v1, v2, options) ⇒ number ↱source code ⇧global index

Returns 0 if v1 == v2, 1 if v1 > v2, and -1 if v1 < v2. Will sort an array of versions in ascending order if passed to Array.sort().

| Param | Type | Description | | --- | --- | --- | | v1 | string | The first version to compare. | | v2 | string | The second version to compare. | | options | object | The options to pass to the semver.compare function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. |

Returns: number - - 0 if v1 == v2, 1 if v1 > v2, and -1 if v1 < v2.

Category: Comparison operations

compareBuild(v1, v2, options) ⇒ number ↱source code ⇧global index

Same as compare except it compares build if two versions are otherwise equal.

| Param | Type | Description | | --- | --- | --- | | v1 | string | The first version to compare. | | v2 | string | The second version to compare. | | options | object | The options to pass to the semver.compareBuild function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. |

Returns: number - - 0 if v1 == v2, 1 if v1 > v2, and -1 if v1 < v2.

Category: Comparison operations

compareLoose(v1, v2) ⇒ number ↱source code ⇧global index

Short for compare with options.loose = true.

| Param | Type | Description | | --- | --- | --- | | v1 | string | The first version to compare. | | v2 | string | The second version to compare. |

Returns: number - - 0 if v1 == v2, 1 if v1 > v2, and -1 if v1 < v2.

Category: Comparison operations

diff(v1, v2, options) ⇒ string | null ↱source code ⇧global index

Returns the difference between two versions. I.e., the most significant version component by which v1 and v2 differ.

| Param | Type | Description | | --- | --- | --- | | v1 | string | The first version to compare. | | v2 | string | The second version to compare. | | options | object | The options to pass to the semver.diff function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. |

Returns: string | null - - major, 'minor', 'patch', 'prerelease', 'premajor', 'preminor', or 'prepatch' or null if the v1 and v2 are identical (disregarding build metadata).

Category: Comparison operations

eq(v1, v2, options) ⇒ boolean ↱source code ⇧global index

Returns true if v1 is equal to v2, false otherwise.

| Param | Type | Description | | --- | --- | --- | | v1 | string | The first version to compare. | | v2 | string | The second version to compare. | | options | object | The options to pass to the semver.eq function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. |

Returns: boolean - - true if v1 is equal to v2, false otherwise.

Category: Comparison operations

gt(v1, v2, options) ⇒ boolean ↱source code ⇧global index

Returns true if v1 is greater than v2, false otherwise.

| Param | Type | Description | | --- | --- | --- | | v1 | string | The first version to compare. | | v2 | string | The second version to compare. | | options | object | The options to pass to the semver.gt function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. |

Returns: boolean - - true if v1 is greater than v2, false otherwise.

Category: Comparison operations

gte(v1, v2, options) ⇒ boolean ↱source code ⇧global index

Returns true if v1 is greater than or equal to v2, false otherwise.

| Param | Type | Description | | --- | --- | --- | | v1 | string | The first version to compare. | | v2 | string | The second version to compare. | | options | object | The options to pass to the semver.gte function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. |

Returns: boolean - - true if v1 is greater than or equal to v2, false otherwise.

Category: Comparison operations

lt(v1, v2, options) ⇒ boolean ↱source code ⇧global index

Returns true if v1 is less than v2, false otherwise.

| Param | Type | Description | | --- | --- | --- | | v1 | string | The first version to compare. | | v2 | string | The second version to compare. | | options | object | The options to pass to the semver.lt function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. |

Returns: boolean - - true if v1 is less than v2, false otherwise.

Category: Comparison operations

lte(v1, v2, options) ⇒ boolean ↱source code ⇧global index

Returns true if v1 is less than or equal to v2, false otherwise.

| Param | Type | Description | | --- | --- | --- | | v1 | string | The first version to compare. | | v2 | string | The second version to compare. | | options | object | The options to pass to the semver.lte function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. |

Returns: boolean - - true if v1 is less than or equal to v2, false otherwise.

Category: Comparison operations

neq(v1, v2, options) ⇒ boolean ↱source code ⇧global index

Returns true if v1 is not equal to v2, false otherwise.

| Param | Type | Description | | --- | --- | --- | | v1 | string | The first version to compare. | | v2 | string | The second version to compare. | | options | object | The options to pass to the semver.neq function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. |

Returns: boolean - - true if v1 is not equal to v2, false otherwise.

Category: Comparison operations

rcompare(v1, v2, options) ⇒ number ↱source code ⇧global index

Reverse of compare.

| Param | Type | Description | | --- | --- | --- | | v1 | string | The first version to compare. | | v2 | string | The second version to compare. | | options | object | The options to pass to the semver.rcompare function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. |

Returns: number - - 0 if v1 == v2, -1 if v1 > v2, and 1 if v1 < v2.

Category: Comparison operations

rsort(versions, options) ⇒ Array.<string> ↱source code ⇧global index

Sorts an array of versions in descending order using compareBuild.

| Param | Type | Description | | --- | --- | --- | | versions | Array.<string> | The versions to sort. | | options | object | The options to pass to the semver.rsort function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. |

Returns: Array.<string> - - The sorted versions.

Category: Comparison operations

sort(versions, options) ⇒ Array.<string> ↱source code ⇧global index

Sorts an array of versions in ascending order using compareBuild.

| Param | Type | Description | | --- | --- | --- | | versions | Array.<string> | The versions to sort. | | options | object | The options to pass to the semver.sort function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. |

Returns: Array.<string> - - The sorted versions.

Category: Comparison operations

xSort(versionsAndRanges) ⇒ Array.<string> ↱source code ⇧global index

Ascend sorts a mix of semver versions and x-range specified ranges (e.g., 1.2.* or 1.2.x). The ranges are sorted according to their highest version; e.g., 1.3.34 < 1.3.*. (I believe it can accept caret ranges too, but I would need to review the spec.)

| Param | Type | Description | | --- | --- | --- | | versionsAndRanges | Array.<string> | The versions and ranges to sort. |

Returns: Array.<string> - - The sorted versions and ranges.

Category: Comparison operations

gtr(version, range, options) ⇒ boolean ↱source code ⇧global index

Returns true if version is greater than is greater than any version in range, false otherwise.

| Param | Type | Description | | --- | --- | --- | | version | string | The version to check. | | range | string | The range to check. | | options | object | The options to pass to the semver.gtr function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. |

Returns: boolean - - true if version is greater than is greater than any version in range, false otherwise.

Category: Range operations

intersects(range, options) ⇒ boolean ↱source code ⇧global index

Returns true if any of the comparators in the range intersect with each other.

| Param | Type | Description | | --- | --- | --- | | range | string | The first version range or comparator. | | options | object | The options to pass to the semver.intersects function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. |

Returns: boolean - - true if any of the comparators in the range intersect with each other, false otherwise.

Category: Range operations

ltr(version, range, options) ⇒ boolean ↱source code ⇧global index

Returns true if version is less than is less than any version in range, false otherwise.

| Param | Type | Description | | --- | --- | --- | | version | string | The version to check. | | range | string | The range to check. | | options | object | The options to pass to the semver.ltr function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. |

Returns: boolean - - true if version is less than is less than any version in range, false otherwise.

Category: Range operations

maxSatisfying(versions, range, options) ⇒ string | null ↱source code ⇧global index

Returns the highest version in versions that satisfies the range, or null if no version satisfies the range. This implementation differs from the base semver.maxSatisfying in that it correctly handles the following case: maxSatisfying(['1.0.0-alpha.0', '1.0.0'], '<1.0.0') -> '1.0.0-alpha.0'. The base semver.maxSatisfying function returns null in this case. Note, support for this syntax is not comprehensive and more complicated expressions are likely to yield incorrect results.

| Param | Type | Description | | --- | --- | --- | | versions | Array.<string> | The versions to check. | | range | string | The range to check. | | options | object | The options to pass to the semver.maxSatisfying function. | | options.compat | boolean | If true, then uses the base semver.maxSatisfying function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. | | options.includePrerelease | boolean | Include prerelease versions in the result. This is effectively implied if the range contains prerelease components. | | options.throwIfInvalid | boolean | If true, throws an exception if any version or the range is invalid. |

Returns: string | null - - The highest version that satisfies the range, or null if no version satisfies the range.

Category: Range operations

minSatisfying(versions, range, options) ⇒ string | null ↱source code ⇧global index

Returns the lowest version in versions that satisfies the range, or null if no version satisfies the range.

| Param | Type | Description | | --- | --- | --- | | versions | Array.<string> | The versions to check. | | range | string | The range to check. | | options | object | The options to pass to the semver.minSatisfying function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. |

Returns: string | null - - The lowest version that satisfies the range, or null if no version satisfies the range.

Category: Range operations

minVersion(range, options) ⇒ string | null ↱source code ⇧global index

Returns the lowest version that satisfies the range, or null if no version satisfies the range. This implementation differs from the base semver.minVersion in that it correctly handles simple prerelease x-ranges. E.g., '1.0.0-alpha.x' -> '1.0.0-alpha.0'. To suppress this behavior, pass options.compat = true. Note, support for this syntax is not comprehensive and more complicated expressions are likely to yield incorrect results.

| Param | Type | Description | | --- | --- | --- | | range | string | The range to check. | | options | object | The options to pass to the semver.minVersion function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. | | options.includePrerelease | boolean | Whether to include prerelease versions. | | options.compat | boolean | If true, prerelease ranges are treated the same as in the base semver package; e.g. minVersion('1.0.0-alpha.x', { compat: true }) -> '1.0.0-alpha.x'. |

Returns: string | null - - The lowest version that satisfies the range, or null if no version satisfies the range.

Category: Range operations

outside(version, range, direction, options) ⇒ boolean ↱source code ⇧global index

Returns true if version is outside of range in the indicated direction, false otherwise. outside(v, r, '>) is equivalent to gtr(v, r).

| Param | Type | Description | | --- | --- | --- | | version | string | The version to check. | | range | string | The range to check. | | direction | string | The direction to check. Must be '>' or '<'. | | options | object | The options to pass to the semver.outside function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. |

Returns: boolean - - true if version is outside of range in the indicated direction, false otherwise.

Category: Range operations

satisfies(version, range, options) ⇒ boolean ↱source code ⇧global index

Returns true if the version satisfies the range, false otherwise.

| Param | Type | Description | | --- | --- | --- | | version | string | The version to check. | | range | string | The range to check. | | options | object | The options to pass to the semver.satisfies function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. |

Returns: boolean - - true if the version satisfies the range, false otherwise.

Category: Range operations

simplifyRange(versions, range, options) ⇒ string ↱source code ⇧global index

Return a "simplified" range that matches the same items in the versions list as the range specified. Note that it does not guarantee that it would match the same versions in all cases, only for the set of versions provided. This is useful when generating ranges by joining together multiple versions with || programmatically, to provide the user with something a bit more ergonomic. If the provided range is shorter in string-length than the generated range, then that is returned.

| Param | Type | Description | | --- | --- | --- | | versions | Array.<string> | The versions to check. | | range | string | The range to simplify. | | options | object | The options to pass to the semver.simplifyRange function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. |

Returns: string - - The simplified range.

Category: Range operations

subset(subRange, superRange, options) ⇒ boolean ↱source code ⇧global index

Returns true if subRange is a subset of superRange, false otherwise.

| Param | Type | Description | | --- | --- | --- | | subRange | string | The sub-range to check. | | superRange | string | The super-range to check. | | options | object | The options to pass to the semver.subset function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. |

Returns: boolean - - true if subRange is a subset of superRange, false otherwise.

Category: Range operations

upperBound(range) ⇒ string ↱source code ⇧global index

Finds the ceiling of a range. For '', the ceiling is ''. For specific versions or any range capped by a specific version, the ceiling is that version. For any open-ended range, the ceiling is defined by a '-0' range function where 'verision-0' least range above the given range.

| Param | Type | Description | | --- | --- | --- | | range | string | The range to find the ceiling for. |

Returns: string - - Either '*', a specific version, or a '-0'.

Category: Range operations

validRange(range, options) ⇒ string | null ↱source code ⇧global index

Returns a parsed, normalized range string or null if the range is invalid.

| Param | Type | Description | | --- | --- | --- | | range | string | The range to parse. | | options | object | The options to pass to the semver.validRange function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. |

Returns: string | null - - The parsed, normalized range string or null if the range is invalid.

Category: Range operations

validVersionOrRange(input, options) ⇒ string | null ↱source code ⇧global index

Validates a string to be a valid version or range. By default, an exception is raised unless options.disallowVersions is true, in which case it filters out invalid strings and returns a new array.

| Param | Type | Description | | --- | --- | --- | | input | string | The string to validate. | | options | object | The options to pass to the semver.valid function. | | options.disallowRanges | boolean | Whether to disallow ranges. | | options.disallowVersions | boolean | Whether to disallow versions and ranges which are valid versions. | | options.includePrerelease | boolean | Whether to include prerelease versions. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. | | options.onlyXRange | boolean | Whether to only allow x-ranges. Note, even if this is true, and a valid x-range is presented, the returned string will still be normalized. | | options.throwIfInvalid | boolean | If true, throws an exception if the string is invalid. |

Returns: string | null - - A normalized version or range string or null if the string is invalid (if options.throwIfInvalid is true, in which case an exception is thrown).

Category: Range operations

clean(version, options) ⇒ string | null ↱source code ⇧global index

Returns a cleaned version string removing unecessary comparators and, if options.loose is true, fixing space issues. Only works for versions, not ranges.

| Param | Type | Description | | --- | --- | --- | | version | string | The version to clean. | | options | object | The options to pass to the semver.clean function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. |

Returns: string | null - - The cleaned version string or null if the version is invalid.

Category: Version operations

coerce(version, options) ⇒ string | null ↱source code ⇧global index

Aggressively attempts to coerce a string into a valid semver string. Basically, starting from the left side of the string, it looks for a digit and then includes anything to the right of the digit that looks like part of a semver. So, 'Number 1!' -> '1.0.0', 'Upgrade 1.2 to 1.3' -> '1.2.0', etc.

| Param | Type | Description | | --- | --- | --- | | version | string | The version to coerce. | | options | object | The options to pass to the semver.coerce function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. | | options.includePrerelease | boolean | Unless true, prerelease tags (and build metadata) are stripped. If | | options.rtl | boolean | Instead of searching for a digit from the left, start searching from the right. true, then they are preserved. |

Returns: string | null - - The coerced version string or null if the version is invalid.

Category: Version operations

inc(version, increment, options, identifier, identifierBase) ⇒ string ↱source code ⇧global index

Returns a new version string incremented by the specified part.

| Param | Type | Description | | --- | --- | --- | | version | string | The version to increment. | | increment | string | The increment to use. | | options | object | The options to pass to the semver.inc function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. | | options.includePrerelease | boolean | Whether to include prerelease versions. | | identifier | string | Used to specify the prerelease name for prerelease increments. | | identifierBase | false | 0 | 1 | When incrementing to a new prerelease name, specifies the base number or false for no number. |

Returns: string - - The new version string.

Category: Version operations

major(version, options) ⇒ number ↱source code ⇧global index

Returns the major version number.

| Param | Type | Description | | --- | --- | --- | | version | string | The version to parse. | | options | object | The options to pass to the semver.major function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. |

Returns: number - - The major version number.

Category: Version operations

minor(version, options) ⇒ number ↱source code ⇧global index

Returns the minor version number.

| Param | Type | Description | | --- | --- | --- | | version | string | The version to parse. | | options | object | The options to pass to the semver.minor function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. |

Returns: number - - The minor version number.

Category: Version operations

nextVersion(currVer, increment) ⇒ string ↱source code ⇧global index

Given a current version generates the next version string accourding to increment. This method is similar to inc from the base semver library with two differences.

1. It supports a specific pre-release sequence prototype -> 'alpha' -> 'beta' -> 'rc' -> released and the 'pretype' increment will advance the prerelease ID through these stages.
2. The 'prerelease' increment can only be used to advance the prerelease version number and does not function as 'prepatch' on a non-prerelease version.

| Param | Type | Description | | --- | --- | --- | | currVer | string | The current version to increment. | | increment | string | The increment to use. |

Returns: string - - The next version string.

Category: Version operations

parse() ↱source code ⇧global index

Attempts to parse and normalize a string as a semver string. An aliase for valid.

Category: Version operations

patch(version, options) ⇒ number ↱source code ⇧global index

Returns the patch version number.

| Param | Type | Description | | --- | --- | --- | | version | string | The version to parse. | | options | object | The options to pass to the semver.patch function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. |

Returns: number - - The patch version number.

Category: Version operations

prerelease(version, options) ⇒ Array.<string> | null ↱source code ⇧global index

Returns an array of prerelease components or null if the version is not a prerelease. A 'component' is just a '.' separated string.

| Param | Type | Description | | --- | --- | --- | | version | string | The version to parse. | | options | object | The options to pass to the semver.inc function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. |

Returns: Array.<string> | null - - The prerelease components or null if the version is not a prerelease.

Category: Version operations

valid(version, options) ⇒ string | null ↱source code ⇧global index

Returns a parsed, normalized version string or null if the version is invalid.

| Param | Type | Description | | --- | --- | --- | | version | string | The version to parse. | | options | object | The options to pass to the semver.valid function. | | options.loose | boolean | Allow non-conforming, but recognizable semver strings. | | options.includePrerelease | boolean | Whether to include prerelease versions. |

Returns: string | null - - The parsed, normalized version string or null if the version is invalid.

Category: Version operations