Explain semver ranges in plain English. The cronstrue for version constraints.
npm install @credentum/semver-explainExplain semver ranges in plain English. The cronstrue for version constraints.
``typescript
import { explain } from '@credentum/semver-explain';
explain('^1.2.3');
// => ">=1.2.3 <2.0.0 — Compatible with 1.2.3, allowing minor and patch updates"
explain('~1.2.3');
// => ">=1.2.3 <1.3.0 — Approximately 1.2.3, allowing only patch updates"
explain('1.2.x');
// => ">=1.2.0 <1.3.0 — Any patch version within 1.2"
explain('>=1.0.0 <2.0.0');
// => ">=1.0.0 and <2.0.0"
explain('^1.2.3 || ^2.0.0');
// => ">=1.2.3 <2.0.0 — Compatible with 1.2.3 | OR | >=2.0.0 <3.0.0 — Compatible with 2.0.0"
`
`bash`
npm install @credentum/semver-explain
Every team using npm encounters semver ranges. The ^ and ~ operators are unintuitive — even experienced developers confuse them. The answer is always a StackOverflow search:
- "What's the difference between tilde(~) and caret(^)?" — 2.1M views
- "What does ^0.0.1 mean?" — 200K+ views
- semver on npm — 498M weekly downloads, but no explain function
cronstrue converts cron to English (3.5M/week). No equivalent exists for semver. Until now.
Converts a semver range string into a human-readable English explanation.
Supports all npm semver range syntax:
| Input | Output |
|-------|--------|
| 1.2.3 | 1.2.3 — Exactly version 1.2.3 |^1.2.3
| | >=1.2.3 <2.0.0 — Compatible with 1.2.3, allowing minor and patch updates |^0.2.3
| | >=0.2.3 <0.3.0 — Compatible with 0.2.3, allowing only patch updates |^0.0.3
| | >=0.0.3 <0.0.4 — Only version 0.0.3 (caret on 0.0.x is exact) |~1.2.3
| | >=1.2.3 <1.3.0 — Approximately 1.2.3, allowing only patch updates |~1.2
| | >=1.2.0 <1.3.0 — Any patch version within 1.2 |~0.2
| | >=0.2.0 <0.3.0 — Any patch version within 0.2 |1.x
| | >=1.0.0 <2.0.0 — Any version starting with 1 |1.2.x
| | >=1.2.0 <1.3.0 — Any patch version within 1.2 |*
| | Any version |>=1.2.3
| | >=1.2.3 |1.2.3 - 2.3.4
| | >=1.2.3 <=2.3.4 — Between 1.2.3 and 2.3.4, inclusive |>=1.0.0 <2.0.0
| | >=1.0.0 and <2.0.0 |^1 \|\| ^2
| | Explains each branch separated by \| OR \| |
Returns only the expanded comparator form without the English description. Useful for tooling.
`typescript
import { expandRange } from '@credentum/semver-explain';
expandRange('^1.2.3'); // ">=1.2.3 <2.0.0"
expandRange('~1.2.3'); // ">=1.2.3 <1.3.0"
expandRange('1.2.x'); // ">=1.2.0 <1.3.0"
`
Pure TypeScript. No dependency on the semver` package. Implements range expansion from the node-semver specification directly.
MIT