Semver Comparator

About this semantic version comparator

Semantic Versioning 2.0.0 defines a version as MAJOR.MINOR.PATCH, optionally followed by a hyphen and a prerelease tag and a plus sign and build metadata — 1.2.3-beta.1+build.456. Precedence is decided by comparing major, then minor, then patch, each as an integer. That is the single most common source of surprise: 1.10.0 is newer than 1.9.0, because 10 is greater than 9 numerically, even though the string "1.10.0" sorts before "1.9.0" in a plain text comparison. Sorting version strings without parsing them is a bug waiting to happen.

Prerelease tags follow their own rules. A version with a prerelease tag always has lower precedence than the same version without one, so 1.0.0-rc.1 comes before 1.0.0. Identifiers made only of digits are compared numerically, identifiers containing letters are compared as ASCII strings, and a longer list of identifiers wins when all the preceding ones are equal. The canonical ordering is 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0. Build metadata after the plus sign is ignored entirely when comparing.

Range expressions are a separate language layered on top, and the operators are not interchangeable. A caret range ^1.2.0 allows any change that does not alter the leftmost non-zero number, so it means >=1.2.0 <2.0.0 — but ^0.2.3 means >=0.2.3 <0.3.0, because in a 0.x version the minor number is the one that carries breaking-change risk. A tilde range ~1.2.3 is narrower and allows only patch-level changes, meaning >=1.2.3 <1.3.0. A space between comparators is an AND, and a double pipe is an OR.