compare-versions

Compare-versions is a lightweight, zero-dependency semver version comparison library that enables developers to compare, validate, and work with semantic version strings in both Node.js and browser environments. It offers comprehensive version comparison capabilities including standard semver versions, pre-releases, wildcards, Chromium-style 4-part versions, and npm version ranges with support for operators and complex range expressions.

Package Information

• Package Name: compare-versions
• Package Type: npm
• Language: TypeScript
• Installation: npm install compare-versions

Core Imports

import { compareVersions, compare, satisfies, validate, validateStrict, CompareOperator } from "compare-versions";

For CommonJS:

const { compareVersions, compare, satisfies, validate, validateStrict } = require("compare-versions");

For browser usage:

<script src="https://unpkg.com/compare-versions/lib/umd/index.js"></script>
<script>
  const { compareVersions, compare, satisfies, validate, validateStrict } = window.compareVersions;
</script>

Basic Usage

import { compareVersions, compare } from "compare-versions";

// Numeric comparison (-1, 0, 1) compatible with Array.sort
compareVersions('11.1.1', '10.0.0'); //  1
compareVersions('10.0.0', '10.0.0'); //  0  
compareVersions('10.0.0', '11.1.1'); // -1

// Human-readable comparison
compare('10.1.8', '10.0.4', '>');  // true
compare('10.0.1', '10.0.1', '=');  // true
compare('10.1.1', '10.2.2', '<');  // true

// Sorting versions
const versions = ['1.5.19', '1.2.3', '1.5.5'];
const sorted = versions.sort(compareVersions);
// Result: ['1.2.3', '1.5.5', '1.5.19']

Architecture

Compare-versions is built around several key components:

• Core Comparison Engine: compareVersions function providing numeric comparison compatible with sorting
• Human-Readable Interface: compare function with operator-based comparisons (>, >=, =, <=, <, !=)
• Range Matching: satisfies function supporting npm-style version ranges and complex expressions
• Validation System: Both permissive and strict validation functions for version string validation
• Cross-Platform Support: Works in Node.js, browsers, and React Native environments with zero dependencies

Capabilities

Core Version Comparison

Fundamental version comparison functionality providing both numeric and boolean comparison modes. Supports the full semver specification with flexible format handling.

function compareVersions(v1: string, v2: string): number;

function compare(v1: string, v2: string, operator: CompareOperator): boolean;

type CompareOperator = '>' | '>=' | '=' | '<' | '<=' | '!=';

Version Comparison

Version Range Matching

Advanced range matching supporting npm semver range expressions, multiple operators, and complex range combinations.

function satisfies(version: string, range: string): boolean;

Range Matching

Version Validation

Validation functions for ensuring version strings conform to semver standards, with both permissive and strict validation modes.

function validate(version: string): boolean;

function validateStrict(version: string): boolean;

Version Validation

Version Format Support

• Standard semver: 1.0.0, 1.0.0-alpha, 1.0.0+build
• Flexible formats: 1.0, 1, 1.0.x, 1.0.*
• Chromium 4-part: 25.0.1364.126
• Leading v ignored: v1.0.0 → 1.0.0
• Leading zeros ignored: 1.01.1 → 1.1.1
• Pre-release versions: 1.0.0-alpha.1, 1.0.0-beta.2
• Build metadata: 1.0.0+20130313144700