SemiVer String Comparator

1.1.0 · active · verified Sun Apr 19

SemiVer is a lightweight (187B) utility designed for accurate comparison of semantic version strings, including those with pre-release identifiers (e.g., `1.0.0-alpha.1` vs `1.0.0-beta`). It leverages the native JavaScript `Intl.Collator` API to perform language-sensitive string comparisons, ensuring correctness across various versioning formats. The library is currently stable at version 1.1.0 and is actively maintained with an as-needed release cadence for bug fixes and minor enhancements. Its primary differentiators are its minimal bundle size, its reliance on a native Web API rather than a heavy parsing library, and its direct compatibility with `Array.sort()` as a comparison function, making it an efficient choice for sorting version lists without external dependencies. Unlike other semver utilities that provide parsing and range matching, SemiVer focuses solely on providing a three-way comparison, outputting `0`, `1`, or `-1`.

Common errors

```
ReferenceError: Intl is not defined
```
cause The JavaScript runtime environment does not provide the global `Intl` object or `Intl.Collator` constructor.

fix Update your Node.js version (Node.js 6+ includes `Intl.Collator`) or ensure your browser environment is modern enough (Chrome 24+, Firefox 29+, Edge 12+, Safari 10+).
```
TypeError: The comparison function must be either a function or undefined
```
cause The `semiver` function was not correctly imported or passed to `Array.sort()`, or a non-function value was provided.

fix Verify that `semiver` is correctly imported via `import semiver from 'semiver';` (ESM) or `const semiver = require('semiver');` (CJS) and then passed directly to `Array.sort()` like `arr.sort(semiver)`.

Warnings

gotcha SemiVer relies on the native `Intl.Collator` API for string comparison. While widely supported in modern browsers and Node.js environments (generally since 2017), very old or highly constrained JavaScript runtimes may lack full support or exhibit inconsistent behavior.
Fix: Ensure the target environment supports `Intl.Collator`. For extremely old environments, consider polyfills, though this is rarely necessary for current usage.
gotcha SemiVer is designed to compare strings that adhere to the Semantic Versioning 2.0.0 specification. Providing malformed or non-compliant version strings may lead to unexpected or incorrect sorting results, as the underlying `Intl.Collator` will perform a standard string comparison rather than a semver-aware one for invalid inputs.
Fix: Always ensure that input strings are valid semantic versions to guarantee accurate comparisons.

Install

npm install semiver npm
yarn add semiver yarn
pnpm add semiver pnpm

Imports

semiver
wrong:
```
import { semiver } from 'semiver';
```
correct:
```
import semiver from 'semiver';
```
`semiver` is a default export. Attempting to destructure it as a named export will result in `undefined`.
semiver
```
const semiver = require('semiver');
```
The package provides a CommonJS build, so `require` is fully supported in Node.js environments.
SemiVerFunction
```
import type semiver from 'semiver';
```
When using TypeScript, you can import the type of the default export using `import type` for type-only imports.

Quickstart

Demonstrates how `semiver` can be used directly as a comparison function for `Array.sort()` to sort an array of semantic version strings, including pre-release identifiers, in ascending order.

import semiver from 'semiver';

const versions = [
  '4.11.6', '4.2.0',
  '1.5.19', '1.5.5',
  '1.0.0', '1.0.0-rc.1',
  '1.2.3', '1.2.3-alpha',
  '1.0.0-alpha.1', '1.0.0-alpha',
  '1.0.0-beta.11', '1.0.0-beta'
];

// Sort an array of semver strings using semiver directly
versions.sort(semiver);

console.log(versions);
/* Expected output:
[
  '1.0.0-alpha',
  '1.0.0-alpha.1',
  '1.0.0-beta',
  '1.0.0-beta.11',
  '1.0.0-rc.1',
  '1.0.0',
  '1.2.3-alpha',
  '1.2.3',
  '1.5.5',
  '1.5.19',
  '4.2.0',
  '4.11.6'
]
*/

view raw JSON →