semver

js/semver.ts

fino:semver — semantic version parsing, comparison, and range matching.

Implements the SemVer 2.0.0 precedence rules plus the npm-style range forms used by the Fino package installer: comparators, hyphen ranges, wildcards, tilde ranges, caret ranges, and || disjunctions. Build metadata is parsed and preserved but ignored for precedence comparisons.

The release API surface is intentionally smaller than npm's semver package. This module supports strict parsing, strict comparison, range matching, valid(), validRange(), and maxSatisfying(). It does not provide loose parsing, coercion, includePrerelease, mutation helpers such as inc()/diff(), range set helpers such as minVersion(), intersects(), or subset(), or sort helpers. Use the package loader to install npm semver when an application needs that larger compatibility surface.

import { parse, satisfies, maxSatisfying } from 'fino:semver';

const version = parse('1.2.3-beta.1+build.5');
const ok = satisfies(version.version, '^1.0.0');
const selected = maxSatisfying(['1.0.0', '1.4.0', '2.0.0'], '^1');

Interfaces

interface SemVer {

Parsed SemVer components with prerelease identifiers split by segment.

Numeric prerelease identifiers are converted to numbers so comparisons can follow SemVer precedence. Build metadata is preserved in build and version, but is ignored by compare() and range matching.

import { parse } from 'fino:semver';

const parsed = parse('1.2.3-beta.1+build.5');
parsed.major;      // 1
parsed.prerelease; // ['beta', 1]
parsed.build;      // ['build', '5']

Properties

major: number
minor: number
patch: number
prerelease: Array<string | number>
build: string[]
version: string

Functions

function parse(version: string): SemVer

Parse a version string and return its structured components.

import { parse } from 'fino:semver';

parse('1.2.3-beta.1+build.5').prerelease; // ['beta', 1]

function valid(version: string): string | null

Return the normalized version string, or null when the input is invalid.

This is the non-throwing companion to parse(). It trims input, validates strict SemVer syntax, normalizes prerelease numeric identifiers, and returns null instead of raising when the string is not a version.

import { valid } from 'fino:semver';

valid('1.2.3+build.5'); // '1.2.3+build.5'
valid('01.2.3');        // null

function compare(a: string, b: string): number

Compare two versions using SemVer precedence.

Returns a negative number when a < b, zero when they are equal, and a positive number when a > b.

Build metadata is ignored by SemVer precedence, so 1.0.0+one and 1.0.0+two compare as equal. Invalid inputs throw.

import { compare } from 'fino:semver';

compare('1.0.0-alpha', '1.0.0'); // negative
compare('2.0.0', '1.9.9');       // positive

function satisfies(version: string, range: string | null | undefined): boolean

Test whether a version satisfies a range expression.

import { satisfies } from 'fino:semver';

satisfies('1.4.2', '^1.2.0'); // true
satisfies('2.0.0', '^1.2.0'); // false

function maxSatisfying(versions: string[], range: string | null | undefined): string | null

Return the highest version in versions that satisfies range.

Invalid versions or ranges throw because this helper delegates to satisfies() and compare(). The returned string is the original matching entry from versions, not a normalized copy.

import { maxSatisfying } from 'fino:semver';

maxSatisfying(['1.0.0', '1.5.0', '2.0.0'], '^1.0.0'); // '1.5.0'

function validRange(range: string | null | undefined): string | null

Validate a range expression and return its trimmed form, or null.

Empty ranges, *, and latest are accepted as wildcard ranges. Other ranges may use comparators, wildcards, tilde, caret, hyphen ranges, and || disjunctions. The return value is suitable for display or reuse.

import { validRange } from 'fino:semver';

validRange(' ^1.2.3 '); // '^1.2.3'
validRange('bad range'); // null