compare-versions

What is compare-versions?

The compare-versions npm package is used to compare and sort semantic version numbers. It provides a simple API for comparing version strings in 'major.minor.patch' format, and it can be used in various environments such as Node.js, browsers, and as a command-line tool.

What are compare-versions's main functionalities?

Compare versions

Compares two semantic version numbers and returns -1, 0, or 1 if the first version is less than, equal to, or greater than the second version, respectively.

const compareVersions = require('compare-versions');
console.log(compareVersions('1.2.3', '4.11.6')); // -1

Check if a version satisfies a range

Determines if a version satisfies a given range. It returns true if the version meets the criteria of the range, false otherwise.

const compareVersions = require('compare-versions');
console.log(compareVersions.satisfies('1.2.3', '>=1.0.0')); // true

Sort an array of versions

Sorts an array of semantic version numbers in ascending order.

const compareVersions = require('compare-versions');
const versions = ['1.2.3', '4.11.6', '2.0.0'];
versions.sort(compareVersions);
console.log(versions); // ['1.2.3', '2.0.0', '4.11.6']

Other packages similar to compare-versions

semver

semver is a popular package that provides a wide range of functions for manipulating and comparing semantic versions. It is more feature-rich than compare-versions, offering functions like coercion, ranges, and prerelease comparisons.

node-version-compare

node-version-compare is another package for comparing version numbers. It is less popular and has a simpler API compared to compare-versions, focusing mainly on the comparison of version strings without additional features like range checking.

README

compare-versions

Compare semver version strings to find greater, equal or lesser. Runs in the browser as well as Node.js/React Native etc. Has no dependencies and is tiny.

Supports the full semver specification including versions with different number of digits like 1.0.0, 1.0, 1 and pre-releases like 1.0.0-alpha. Additionally supports the following variations:

• Wildcards for minor and patch version like 1.0.x or 1.0.*.
• Chromium version numbers with 4 parts, e.g. version 25.0.1364.126.
• Any leading v is ignored, e.g. v1.0 is interpreted as 1.0.
• Leading zero is ignored, e.g. 1.01.1 is interpreted as 1.1.1.

Install

$ npm install compare-versions

Note: Starting from v4 this library includes a ESM version which will automatically be selected by your bundler (webpack, parcel etc). The old CJS version is index.js and the new ESM version is index.mjs.

Usage

Will return 1 if first version is greater, 0 if versions are equal, and -1 if the second version is greater:

import compareVersions from 'compare-versions';

compareVersions('11.1.1', '10.0.0'); //  1
compareVersions('10.0.0', '10.0.0'); //  0
compareVersions('10.0.0', '11.1.1'); // -1

Can also be used for sorting:

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

"Human Readable" Compare

The alternative compare function accepts an operator which will be more familiar to humans:

import { compare } from 'compare-versions';

compare('10.1.8', '10.0.4', '>');  // true
compare('10.0.1', '10.0.1', '=');  // true
compare('10.1.1', '10.2.2', '<');  // true
compare('10.1.1', '10.2.2', '<='); // true
compare('10.1.1', '10.2.2', '>='); // false

Version ranges

The satisfies function accepts a range to compare, compatible with npm package versioning:

import { satisfies } from 'compare-versions';

satisfies('10.0.1', '~10.0.0');  // true
satisfies('10.1.0', '~10.0.0');  // false
satisfies('10.1.2', '^10.0.0');  // true
satisfies('11.0.0', '^10.0.0');  // false
satisfies('10.1.8', '>10.0.4');  // true
satisfies('10.0.1', '=10.0.1');  // true
satisfies('10.1.1', '<10.2.2');  // true
satisfies('10.1.1', '<=10.2.2'); // true
satisfies('10.1.1', '>=10.2.2'); // false

Validate version numbers

Applies the same ruleset used comparing version numbers and returns a boolean:

import { validate } from 'compare-versions';

validate('1.0.0-rc.1'); // true
validate('1.0-rc.1');   // false
validate('foo');        // false

Browser

If included directly in the browser, compareVersions() is available on the global window:

<script src="compare-versions/index.js"></script>
<script>
  window.compareVersions('11.0.0', '10.0.0');
  window.compareVersions.compare('11.0.0', '10.0.0', '>');
  window.compareVersions.validate('11.0.0');
</script>

Changelog

4.1.0 - 2021-11-12

• Add satisfies() function to test for range match.