About
Tool No. 56 of Pikkola
A version string is a promise about compatibility. SemVer is the short form of that promise, and a range is how a dependency says which promises it accepts. This page reads both, and does the arithmetic in the tab.
What it does
- Reads a Semantic Versioning 2.0.0 version: major, minor, patch, an optional prerelease and an optional build.
- Moves a version one step by major, minor, patch or prerelease, and drops a prerelease when the axis it belongs to is already at that number.
- Compares two versions by precedence, and names the field where they part.
- Expands a range into its comparators, matches a list against it, and marks the highest match.
- Puts two ranges together: whether any version satisfies both, the window they share, and the lowest version inside it.
- Speaks English, Korean and Japanese, follows the light and dark theme, and copies every result.
How a version is read
The parser works from the right. A plus sign ends the build, a hyphen ends the prerelease, and what is left is the core, three dot separated numbers. Each number is checked as text before it becomes a number, because the specification cares about the spelling: 01 in a version is not the same as 1, and it is refused rather than quietly cleaned up.
An identifier inside a prerelease is either all digits or a mix of letters, digits and hyphens. A numeric identifier may not start with a zero either, and 1.0.0-01 is refused while 1.0.0-1 is accepted. A build identifier may start with a zero, because build metadata is never compared and only has to be readable.
A leading v is taken off, since package manifests and tag names write v1.4.1 and mean the same version. Everything else that is not SemVer is named: a missing part, a stray letter in the core, an empty identifier, a character that is not allowed.
How a range becomes comparators
Every range shape is rewritten into a small set of comparisons before anything is tested. A caret becomes a floor and a ceiling that stops before the leftmost number that is not zero moves: ^1.4.0 is >=1.4.0 <2.0.0, while ^0.7.1 is >=0.7.1 <0.8.0. A tilde keeps the major and minor and moves the ceiling one minor up. An x-range fills missing parts with zeros and puts the ceiling at the next missing part.
Two vertical bars separate alternatives. A version only has to satisfy one of them. Inside an alternative, a space or a comma means both comparisons must hold, which is why >=1.0.0 <2.0.0 and >=1.0, <2.0 are the same range here.
Prereleases are the part most tools get wrong. A prerelease only matches when a comparator in the same alternative names the same major.minor.patch with a prerelease of its own. That is why ^1.4.0 never picks 1.5.0-rc.1, and why >=1.5.0-rc.1 <1.6.0 does pick it. Turning the option on lifts that rule and lets any prerelease inside the numeric window match, which is useful when you are the one publishing the prerelease.
How two ranges meet
The bench merges the comparator lists of both ranges into one list, then keeps the highest floor and the lowest ceiling. That pair of bounds is the window both allow, and it is what the panel shows. For each pair of alternatives the page then searches the window for a real version: the bound versions themselves, their neighbours one patch or one minor away, and the prerelease of each. The lowest candidate that satisfies both ranges is reported.
The bars are drawn from those bounds with the same arithmetic, so a picture and a sentence never disagree. When the floor sits above the ceiling there is no window, and the panel says which side started too high.
Where the limits are
- No registry is asked. A dist-tag such as latest, a Git URL, a file path or a workspace protocol is not a version and is refused.
- No package tree is read. Peer dependencies, optional dependencies and transitive resolution are outside what a range can decide on its own.
- Cargo has a few forms npm does not, such as a bare 1.2 meaning ^1.2, and it treats a prerelease the same way. The common shapes are read identically; an exotic Cargo-only form may be refused.
- Numbers are compared as JavaScript numbers, so a field above 9,007,199,254,740,991 is refused rather than rounded.
- A prerelease inside an intersection is only considered when the option is on, because otherwise the dereference rule from npm applies to both sides.
Why it is free
Pikkola builds small tools with one job each and keeps them free, with no account and no lock on the result. A page that runs in the browser costs almost nothing to serve, so there is no reason to charge for it or to watch who uses it.
Contact
A range this page refuses but npm accepts, an intersection you disagree with, a Korean or Japanese sentence that reads badly: hello@pikkola.com. The shortest pair of ranges that shows the problem is the most useful thing to send.