semiver

library1.1.0jsnpmunverified

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`.

serialization

npm install semiver

github ↗package ↗

INSTALL

IMPORT

SIG · SEMIVER

semiver

serializationjavascriptv1.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

semiver

✓ import semiver from 'semiver';

✗ 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.

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' ] */

Debug

Known issues

gotchaSemiVer 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.

affects: <1.0.0 (where support was less prevalent, though the package itself is recent)

gotchaSemiVer 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.

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: Intl is not defined

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

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)`.

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/lukeed/semiver ↗

packagehttps://www.npmjs.com/package/semiver ↗