semver

semver is the JavaScript implementation of the Semantic Versioning 2.0.0 specification, maintained by the npm CLI team and used internally by npm to parse, validate, compare, and sort package versions. It exposes both a full range-matching engine (tilde, caret, hyphen, and x-ranges) and a collection of small, pure comparison functions that can be imported individually to minimize bundle size.

Beyond the library API, semver ships a standalone command-line tool for validating and incrementing version strings from shell scripts and CI pipelines. Because it underpins version resolution across the entire npm ecosystem, it has become the de facto standard for semver parsing in JavaScript, with hundreds of millions of weekly downloads.

What You Get

• SemVer, Comparator, and Range classes for structured version and range objects
• A full set of comparison functions (gt, lt, eq, satisfies, compare, diff, etc.) importable individually
• Range utilities for max/min satisfying versions, intersection checks, and range simplification
• A standalone semver CLI binary for shell and CI version comparisons and increments

Common Use Cases

• Resolving which published version satisfies a dependency’s declared range
• Validating and normalizing user- or config-supplied version strings
• Bumping a package’s version programmatically during a release script
• Sorting a list of tags or releases by semantic precedence

Under The Hood

Architecture

semver’s execution flow starts at index.js, which eagerly requires every submodule and re-exports them as a single flat object; a preload.js entry point exists solely to force this eager loading for environments that need pre-warmed regex caches. Parsing centers on classes/semver.js, whose SemVer constructor runs the input string through a single greedy regex (internal/re.js, built from anchored token fragments in internal/constants.js) to populate major/minor/patch/prerelease/build fields, memoizing repeat parses of the same version+options pair via an LRU cache in internal/lrucache.js. Range matching layers classes/range.js (which desugars hyphen, tilde, caret, and x-range syntax into primitive comparator sets) on top of classes/comparator.js (a single operator+SemVer pair), with the ranges/ directory (max-satisfying.js, min-version.js, outside.js, subset.js, etc.) implementing higher-level range algebra by iterating candidate comparators rather than re-parsing strings. Nearly all consumer-facing behavior in functions/ (compare.js, satisfies.js, diff.js, coerce.js, etc.) is a thin wrapper that constructs a SemVer or Range and delegates to its methods, keeping the public API a flat set of pure functions layered over a small, well-isolated OOP core.

Tech Stack

semver is dependency-free at runtime — package.json declares zero production dependencies, keeping it safe to install transitively without pulling in an ecosystem. Its devDependencies are entirely tooling: tap for testing (configured in package.json’s tap block with a coverage-map pointing at map.js), @npmcli/eslint-config and @npmcli/template-oss for lint and style enforcement shared across npm’s own packages, and benchmark for the perf suite under benchmarks/. The engines field requires a modern Node.js runtime, and the code is plain CommonJS (require/module.exports) with no build or transpile step — index.js and every submodule ship as-is, and the files field in package.json whitelists exactly the directories published to the registry (bin/, lib/, classes/, functions/, internal/, ranges/).

Code Quality

Test coverage is comprehensive and mirrors the source layout 1:1 — test/classes/, test/functions/, test/internal/, and test/ranges/ each contain a file per corresponding source module, plus test/bin/semver.js for the CLI and test/integration/whitespace.js for edge-case regression coverage, all run through tap with an nyc coverage-map (map.js) that excludes tap-snapshots/. Error handling is explicit and typed: the SemVer constructor throws TypeError with descriptive messages (“Invalid Version: …”, version-too-long errors) rather than returning null or undefined, while the top-level functions/ wrappers instead catch and return null for invalid input, giving callers a predictable choice between throw-on-parse and null-on-check semantics. Naming is consistent and short (gt/lt/eq/gte/lte/cmp/rcompare mirror mathematical comparison conventions), internal state is guarded (the LRU cache size is capped via constants in internal/constants.js), and a debug() helper (internal/debug.js) gated behind an environment flag replaces ad hoc console.log calls.

API Design The public API favors small, single-purpose pure functions (gt, lt, satisfies, coerce, diff, inc) that can be required individually straight from functions/ or ranges/ to minimize bundle size, alongside three classes (SemVer, Comparator, Range) for callers who need richer objects — this dual surface lets consumers pick the minimal-footprint or object-oriented style per use case. Naming directly mirrors mathematical and spec vocabulary (gt/lt/gte/lte/eq/neq/cmp) so experienced developers can guess most of the API without reading docs, and the top-level require(‘semver’) convenience export needs zero configuration to produce a working comparison. The README is exhaustive, documenting every range-syntax edge case (hyphen ranges, x-ranges, tilde/caret semantics, prerelease-tag matching rules) with runnable examples for each exported function, and the CLI (semver -h) mirrors the library’s flag names closely, reducing the conceptual gap between scripting and programmatic use.