IF Commons GitHub

semver

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-formats FR-015

Versions: semantic versions by the rules of semver.org 2.0.0 (parsed, printed, ordered and bumped), and the looser dotted versions that programs print (2.9.8, 1.4.4, 26.13.1), compared part by part (commons 0001-formats FR-015); and npm's ranges, read and satisfied as node-semver reads them (commons 0001-formats FR-014). Taken from erga's kernel (semver.ts) and toolchain (atLeast), Stolos's tools/version.ts and the machine setup.

import { atLeast, compareSemVer, parseSemVer } from "./semver.ts";
atLeast("2.10.0", "2.9.8"); // true
const a = parseSemVer("1.0.0-rc.1"), b = parseSemVer("1.0.0");
if (a.kind === "ok" && b.kind === "ok") compareSemVer(a.value, b.value); // negative: a pre-release comes first

Source: commons/formats/src/semver.ts

14 of 20 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

atLeastfunction
function atLeast(have: string, want: string): boolean

Whether dotted version have is at least want.

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

bumpfunction
function bump(v: SemVer, level: Level): SemVer

The next version at a level: the parts after it reset to zero, and the pre-release and build dropped.

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

bumpSufficesfunction
function bumpSuffices(before: SemVer, after: SemVer, change: Change): boolean

Whether moving from before to after is enough for change; before 1.0 a breaking change needs only the minor raised.

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

compareDottedfunction
function compareDotted(a: string, b: string): number

Negative, zero or positive as dotted version a is below, equal to or above b, part by part; a missing part counts as 0.

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

compareSemVerfunction
function compareSemVer(a: SemVer, b: SemVer): number

Negative where a comes before b, positive where after, zero where they have the same precedence (semver.org 2.0.0 §11): numbers numerically, a pre-release before its release, pre-release identifiers one by one (numeric ones numerically and before the others), and the build ignored.

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

dottedPartsfunction
function dottedParts(version: string): readonly number[]

The numbers of a dotted version: split at ., +, _ and -, each part's leading digits, and 0 where a part has none.

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

formatRangefunction
function formatRange(range: Range): string

A range as text: each set's comparators joined by spaces (= written as the bare version, an empty set as *), the sets by ||.

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

formatSemVerfunction
function formatSemVer(v: SemVer): string

A version as text: 1.2.3, 1.2.3-rc.1 or 1.2.3-rc.1+build.5.

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

maxSatisfyingfunction
function maxSatisfying(versions: readonly SemVer[], range: Range, options?: SatisfiesOptions): SemVer | undefined

The highest of the versions that satisfy the range, or undefined where none does.

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

parseRangefunction
function parseRange(text: string): Result<Range, string>

Text read as an npm range (commons 0001-formats FR-014), by node-semver's grammar and its desugaring: comparators (<, <=, >, >=, =) joined by spaces, sets joined by ||, hyphen ranges (1.2.3 - 2.3.4), x-ranges (*, x, X or a missing part), tilde (~, ~>) and caret (^) ranges, a space allowed after an operator, a leading v and builds ignored. Anything else is an error naming the part.

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

parseSemVerfunction
function parseSemVer(text: string): Result<SemVer, string>

Text read as a semantic version (a leading v allowed, as tags carry it), or why it is not one.

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

satisfiesfunction
function satisfies(version: SemVer, range: Range, options?: SatisfiesOptions): boolean

Whether a version satisfies a range (commons 0001-formats FR-014): every comparator of one of its sets holds. A pre-release version satisfies a set only where one of its comparators is a pre-release of the same major, minor and patch (1.2.3-beta.4 satisfies ^1.2.3-beta.2, 1.2.4-beta does not satisfy ^1.2.3), as node-semver has it, unless includePrerelease is given, when the comparators alone decide.

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

versionInfunction
function versionIn(text: string): string | undefined

The first dotted version in a program's output (bun 1.4.4 (...) gives 1.4.4), or undefined.

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

Changetypeno test imports it
type Change = { readonly kind: "none" } | { readonly kind: "fix" } | { readonly kind: "addition" } | { readonly kind: "breaking" };

The change a surface made, and so the least its version must change by.

Comparatortypeno test imports it
type Comparator = { readonly op: Operator; readonly version: SemVer };

A version compared with one bound: >=1.2.3, <2.0.0-0.

Leveltypeno test imports it
type Level = "major" | "minor" | "patch";

Which part of a version a change raises.

Operatortypeno test imports it
type Operator = "<" | "<=" | ">" | ">=" | "=";

How a comparator compares a version with its bound.

Rangetypeno test imports it
type Range = { readonly kind: "range"; readonly sets: readonly (readonly Comparator[])[] };

A range: sets of comparators joined by ||. A version satisfies it where it satisfies every comparator of one set; an empty set holds every version (*), and no set at all holds none.

SatisfiesOptionstypeno test imports it
type SatisfiesOptions = { readonly includePrerelease?: boolean };

Whether pre-releases are held to the comparators alone (includePrerelease), rather than only where a bound names their release.

SemVertype
type SemVer = {
  readonly major: number;
  readonly minor: number;
  readonly patch: number;
  readonly pre?: string;
  readonly build?: string;
};

A semantic version: major, minor and patch, and an optional pre-release and build, each as its dot-separated text.

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.