semver-explain

Explain semver ranges in plain English. The cronstrue for version constraints.

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"

Installation

npm install @credentum/semver-explain

Why?

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.

API

explain(range: string): string

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 \| |

expandRange(range: string): string

Returns only the expanded comparator form without the English description. Useful for tooling.

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"

Zero Dependencies

Pure TypeScript. No dependency on the semver package. Implements range expansion from the node-semver specification directly.

License

MIT