#semver API reference

Strict Semantic Versioning 2.0.0 (https://semver.org): parse, compare, increment, and range-match version numbers - the full surface a package registry or dependency resolver needs. A pure-Jennifer reference module (no Go, no system library): parsing uses the canonical SemVer regex (via the regex library); precedence comparison, sorting, and range matching are hand-written Jennifer.

Ranges follow the npm / Composer grammar: caret ^1.2.0, tilde ~1.2, comparators >=1.0.0 <2.0.0 (space or comma = AND), OR sets ^1 || ^2, hyphen ranges 1.2.3 - 2.3.4, x-ranges 1.x / 1.2.*, and * for any. A prerelease version satisfies a range only when a comparator in the same clause pins a prerelease at the same major.minor.patch (the npm rule).

Import with import "semver.j" as semver;. See the semver guide for prose and examples.

#Functions

#semver.clean(s as string)

Normalise a version string: trim whitespace and a leading = / v, then return the canonical form if it is a valid full version, else "". Strict (unlike coerce): clean("v1.2.3") -> "1.2.3", but clean("1.2") -> "".

Parameters

• s {string} - the version text

Returns {string} - the canonical version, or "" if not valid

#semver.coerce(s as string)

Extract a version from a loose string - a git tag, a partial, or text with a version-like run - and return canonical major.minor.patch (missing parts are 0). Handles a leading v and surrounding noise. Returns "" when no numeric core is found. coerce("v1.2.3") -> "1.2.3", coerce("1.2") -> "1.2.0".

Parameters

• s {string} - the loose text

Returns {string} - a canonical version, or "" if none was found

#semver.compare(a as Version, b as Version)

Compare two versions by SemVer precedence: numeric core, then a prerelease ranks below its release, then prerelease fields. Build metadata is ignored.

Parameters

• a {Version} - the left version
• b {Version} - the right version

Returns {int} - -1 if a < b, 0 if equal, 1 if a > b

#semver.diff(a as Version, b as Version)

The kind of change from a to b: "major", "minor", "patch", "prerelease" (only the prerelease tag differs), or "" when the two are equal. The highest-order difference wins.

Parameters

• a {Version} - the left version
• b {Version} - the right version

Returns {string} - the release-type difference

#semver.eq(a as Version, b as Version)

Report whether a and b have equal precedence (build metadata ignored).

Parameters

• a {Version} - the left version
• b {Version} - the right version

Returns {bool} - true when a and b compare equal

#semver.gt(a as Version, b as Version)

Report whether a orders after b.

Parameters

• a {Version} - the left version
• b {Version} - the right version

Returns {bool} - true when a > b by SemVer precedence

#semver.gte(a as Version, b as Version)

Report whether a orders at or after b.

Parameters

• a {Version} - the left version
• b {Version} - the right version

Returns {bool} - true when a >= b

#semver.gtr(version as string, range as string)

Report whether a version is greater than every version a range allows (beyond its upper extreme). False for an unbounded range or a version in an interior gap.

Parameters

• version {string} - the version to test
• range {string} - the range expression

Returns {bool} - true when version is above the whole range

#semver.incMajor(v as Version)

Bump the major version, resetting minor / patch and clearing the tags.

Parameters

• v {Version} - the starting version

Returns {Version} - a new version with major + 1 and minor = patch = 0

#semver.incMinor(v as Version)

Bump the minor version, resetting patch and clearing the tags.

Parameters

• v {Version} - the starting version

Returns {Version} - a new version with minor + 1 and patch = 0

#semver.incPatch(v as Version)

Bump the patch version, clearing the tags.

Parameters

• v {Version} - the starting version

Returns {Version} - a new version with patch + 1

#semver.intersects(rangeA as string, rangeB as string)

Report whether two ranges share at least one satisfying version, prereleases included (a prerelease overlap needs both ranges to pin the same major.minor.patch). ^1.2.0 intersects >=1.5.0 (true) but not ^2.0.0. Invalid ranges never intersect.

Parameters

• rangeA {string} - the first range
• rangeB {string} - the second range

Returns {bool} - true when the ranges overlap

#semver.isPrerelease(v as Version)

Report whether the version carries a prerelease tag.

Parameters

• v {Version} - the version to classify

Returns {bool} - true when a prerelease tag is present

#semver.isStable(v as Version)

Report whether the version is stable: a released (major >= 1) version with no prerelease tag. A 0.y.z version is unstable by SemVer convention.

Parameters

• v {Version} - the version to classify

Returns {bool} - true when major >= 1 and there is no prerelease tag

#semver.isValid(s as string)

Report whether a string is a valid SemVer 2.0.0 version.

Parameters

• s {string} - the candidate version text

Returns {bool} - true when s parses as a valid version

#semver.lt(a as Version, b as Version)

Report whether a orders before b.

Parameters

• a {Version} - the left version
• b {Version} - the right version

Returns {bool} - true when a < b by SemVer precedence

#semver.lte(a as Version, b as Version)

Report whether a orders at or before b.

Parameters

• a {Version} - the left version
• b {Version} - the right version

Returns {bool} - true when a <= b

#semver.ltr(version as string, range as string)

Report whether a version is less than every version a range allows (below its lower extreme).

Parameters

• version {string} - the version to test
• range {string} - the range expression

Returns {bool} - true when version is below the whole range

#semver.maxSatisfying(versions as list of string, range as string)

Pick the highest version from a list that satisfies the range. Versions that are not valid SemVer are skipped. Returns "" when none match.

Parameters

• versions {list of string} - the candidate versions
• range {string} - the range expression

Returns {string} - the highest satisfying version, or "" if none match

#semver.minSatisfying(versions as list of string, range as string)

Pick the lowest version from a list that satisfies the range. Versions that are not valid SemVer are skipped. Returns "" when none match.

Parameters

• versions {list of string} - the candidate versions
• range {string} - the range expression

Returns {string} - the lowest satisfying version, or "" if none match

#semver.minVersion(range as string)

The lowest version that could satisfy a range (its floor), or "" when the range is empty or invalid. Prerelease-precise: minVersion(">=1.2.3-rc.1") is "1.2.3-rc.1", minVersion("^1.2.0") is "1.2.0", minVersion(">1.2.3") is "1.2.4".

Parameters

• range {string} - the range expression

Returns {string} - the lowest satisfying version, or ""

#semver.neq(a as Version, b as Version)

Report whether a and b differ in precedence.

Parameters

• a {Version} - the left version
• b {Version} - the right version

Returns {bool} - true when a and b are not equal

#semver.outside(version as string, range as string)

Report whether a version is beyond a range's extremes (above it or below it). A version in an interior gap of a multi-clause range is not "outside".

Parameters

• version {string} - the version to test
• range {string} - the range expression

Returns {bool} - true when version is above or below the whole range

#semver.parse(s as string)

Parse a version string into a Version.

Parameters

• s {string} - the version text (e.g. "1.2.3-rc.1+build.5")

Returns {Version} - the parsed version

Throws

• {Error} - when s is not a valid SemVer 2.0.0 string

#semver.rsort(vs as list of Version)

Return a new list ordered descending by SemVer precedence (highest first).

Parameters

• vs {list of Version} - the versions to order

Returns {list of Version} - a new list sorted descending

#semver.satisfies(version as string, range as string)

Report whether a concrete version satisfies a range. The range grammar is the npm / Composer set: caret ^1.2.0, tilde ~1.2, comparators >=1.0.0 <2.0.0 (space or comma = AND), OR sets ^1 || ^2, hyphen ranges 1.2.3 - 2.3.4, x-ranges 1.x / 1.2.*, and * / "" / "any" for any release. A prerelease version matches only when a comparator in the same clause pins a prerelease at the same major.minor.patch. An invalid version never satisfies anything.

Parameters

• version {string} - the concrete version to test (e.g. "1.4.0")
• range {string} - the range expression

Returns {bool} - true when version satisfies range

#semver.simplifyRange(versions as list of string, range as string)

Simplify a range against a known list of versions: return the shortest range that matches exactly the same subset of versions. Runs of consecutive matching versions collapse to >=lo <=hi clauses joined by ||; the original range is kept when it is already at least as short. "*" when every listed version matches, <0.0.0-0 (matches nothing) when none do.

Parameters

• versions {list of string} - the known versions
• range {string} - the range to simplify

Returns {string} - the simplified range

#semver.sort(vs as list of Version)

Return a new list ordered ascending by SemVer precedence. lists.sort is scalar-only, so this is a merge sort over compare() - O(n log n), where an insertion sort was O(n^2).

Parameters

• vs {list of Version} - the versions to order

Returns {list of Version} - a new list sorted ascending

#semver.subset(inner as string, outer as string)

Report whether every version allowed by inner is also allowed by outer (inner is the tighter / implied constraint), prereleases included. subset("^1.5.0", "^1.0.0") is true; subset("^1.0.0", "^1.5.0") is false.

Parameters

• inner {string} - the candidate subset range
• outer {string} - the superset range

Returns {bool} - true when inner is a subset of outer

#semver.toString(v as Version)

Render a Version back to its canonical string form.

Parameters

• v {Version} - the version to format

Returns {string} - the "major.minor.patch[-prerelease][+build]" text

#semver.validRange(range as string)

Report whether a range expression is well-formed (parseable). Does not evaluate it against any version.

Parameters

• range {string} - the range expression

Returns {bool} - true when the range is valid

#Structs

#semver.Version

A parsed SemVer version: numeric core plus optional prerelease / build tags.