compare-versions

compare-versions is a tiny, dependency-free library for comparing semantic version strings to determine which is greater, equal, or lesser. It implements the full semver specification, including versions with a varying number of segments (1, 1.0, 1.0.0), pre-release identifiers (1.0.0-alpha), wildcards (1.0.x), 4-part Chromium-style versions (25.0.1364.126), and npm-style version ranges (^1.2.3, 1.2.7 || >=1.2.9 <2.0.0).

The library exposes a small set of composable functions — compareVersions, compare, satisfies, validate, and validateStrict — and ships as ESM, CJS/UMD, and a browser global, making it usable directly in Array.prototype.sort, feature-flagging logic, or dependency-range checks without pulling in a full semver toolchain.

What You Get

• compareVersions(v1, v2) returning -1/0/1, directly usable as an Array.sort comparator
• compare(v1, v2, operator) for human-readable comparisons using >, <, =, >=, <=
• satisfies(version, range) supporting npm-style semver ranges (^, ~, ||, hyphen ranges)
• validate/validateStrict for lenient vs. strict semver-format checking
• ESM, CJS/UMD, and browser-global builds with zero runtime dependencies

Common Use Cases

• Sorting a list of release/version strings into semantic order
• Gating a feature or migration behind a minimum required version check
• Validating user- or config-supplied version strings before further processing
• Checking whether an installed dependency version satisfies an npm-style range

Under The Hood

Architecture The library splits into single-purpose modules: utils.ts holds the shared validateAndParse/compareSegments parsing logic, and compareVersions.ts, compare.ts, satisfies.ts, and validate.ts each build a small, independent public function on top of that shared parser. index.ts simply re-exports each function, so the whole public API is composed from a handful of pure, side-effect-free functions rather than a single monolithic parser class.

Tech Stack Written in TypeScript, compiled to ESM via tsc and bundled to UMD via Rollup for the lib/umd browser/CJS build. It has zero runtime dependencies (sideEffects: false in package.json), and tests run under Mocha with c8 for coverage.

Code Quality The test/ directory maps directly onto the public API surface (compare.ts, satisfies.ts, sort.ts, validate.ts), giving each exported function its own dedicated suite. Functions are short, pure, and rely on shared parsing/validation helpers instead of duplicating segment-comparison logic across each entry point, keeping the exposed behavior consistent across compare, satisfies, and compareVersions.

API Design The API favors small, single-purpose functions over one configurable object, and documents each one with JSDoc directly in source. Since v5 the main export is named (import { compareVersions } from 'compare-versions') rather than default, aligning with modern ESM conventions, and the human-readable compare(v1, v2, '>') variant lowers the learning curve for callers unfamiliar with sort-comparator return values.