SemVerRange unstable

npm-style version ranges over SemVer values.

A SemVerRange keeps the syntax it was parsed from, such as ^1.2, ~1.2.3, 1.x, or 1.2.3 - 2.3.4. Matching follows node-semver's pre-release rules, except that wildcard alternatives preserve the union described in matches.

21 exports Since v4.0.6 Source

Constants

any

unstable

Since v4.0.6

The range matching every release, written *.

Gotchas

Like every range, * only matches pre-releases with includePrerelease.

Signature

declare const any: SemVerRange

Constructors

between

unstable

Since v4.0.6

Creates a range matching versions within inclusive bounds, written >=1.2.3 <=2.0.0.

Details

Matches the same versions as SemVer.between, subject to the pre-release rule. Build metadata is dropped. Throws SemVerError for an invalid SemVer.Input.

Signature

declare function between(options: {
  readonly maximum: Input;
  readonly minimum: Input;
}): SemVerRange

caret

unstable

Since v4.0.6

Creates a range matching versions compatible with a version, written ^1.2.3.

Details

Allows changes that do not modify the left-most non-zero component: ^1.2.3 means >=1.2.3 <2.0.0-0 and ^0.2.3 means >=0.2.3 <0.3.0-0. Build metadata is dropped. Throws SemVerError for an invalid SemVer.Input.

Signature

declare function caret(version: Input): SemVerRange

exact

unstable

Since v4.0.6

Creates a range matching exactly one version, written 1.2.3.

Details

Build metadata is dropped because ranges cannot express it and it does not affect matching, so 1.2.3+a and 1.2.3+b both match. Throws SemVerError for an invalid SemVer.Input.

Signature

declare function exact(version: Input): SemVerRange

Example Building ranges from versions

import { SemVer, SemVerRange } from "effect"

const version = SemVer.parseUnsafe("1.2.3+build.5")

SemVerRange.format(SemVerRange.exact(version)) // => "1.2.3"
SemVerRange.format(SemVerRange.greaterThanOrEqualTo(version)) // => ">=1.2.3"
SemVerRange.format(SemVerRange.caret("1.2.3")) // => "^1.2.3"
SemVerRange.matches(SemVerRange.greaterThan(version), "1.2.4") // => true

fromInput

unstable

Since v4.0.6

Converts a range or range string into a SemVerRange.

Details

Ranges are returned unchanged and strings are parsed like parse. Invalid strings fail with SemVer.SemVerError.

See

fromInputUnsafe for throwing on invalid input

Signature

declare function fromInput(input: Input): Result<SemVerRange, SemVerError>

fromInputUnsafe

unstable

Since v4.0.6

Converts a range or range string into a SemVerRange and throws SemVer.SemVerError for invalid input.

See

fromInput for non-throwing conversion

Signature

declare function fromInputUnsafe(input: Input): SemVerRange

greaterThan

unstable

Since v4.0.6

Creates a range matching versions with higher precedence, written >1.2.3.

Details

Build metadata is dropped. Throws SemVerError for an invalid SemVer.Input.

Signature

declare function greaterThan(version: Input): SemVerRange

greaterThanOrEqualTo

unstable

Since v4.0.6

Creates a range matching versions with at least the given precedence, written >=1.2.3.

Details

Build metadata is dropped. Throws SemVerError for an invalid SemVer.Input.

Signature

declare function greaterThanOrEqualTo(version: Input): SemVerRange

lessThan

unstable

Since v4.0.6

Creates a range matching versions with lower precedence, written <1.2.3.

Details

Build metadata is dropped. Throws SemVerError for an invalid SemVer.Input.

Signature

declare function lessThan(version: Input): SemVerRange

lessThanOrEqualTo

unstable

Since v4.0.6

Creates a range matching versions with at most the given precedence, written <=1.2.3.

Details

Build metadata is dropped. Throws SemVerError for an invalid SemVer.Input.

Signature

declare function lessThanOrEqualTo(version: Input): SemVerRange

parse

unstable

Since v4.0.6

Parses an npm-style version range.

Details

Supports:

comparators =, <, <=, >, >=, whitespace-separated as AND;
alternatives separated by ||;
X-ranges such as 1.x, 1.2.*, 1, and *;
tilde (~1.2.3), caret (^1.2.3), and hyphen (1.2.3 - 2.3.4) ranges.

An empty string is equivalent to *. Invalid input fails with SemVer.SemVerError.

Gotchas

Versions must follow the strict SemVer grammar apart from wildcards, so a v prefix, leading zeros, build metadata, and empty || alternatives are rejected.

See

parseUnsafe for throwing on invalid input
format for the inverse operation

Signature

declare function parse(input: string): Result<SemVerRange, SemVerError>

Example Parsing and matching a caret range

import { Result, SemVerRange } from "effect"

const range = SemVerRange.parseUnsafe("^1.2.0 || >=3.0.0-rc.1")

SemVerRange.matches(range, "1.9.0") // => true
SemVerRange.matches(range, "2.0.0") // => false
SemVerRange.matches(range, "3.0.0-rc.2") // => true
Result.isFailure(SemVerRange.parse("^v1.2.0")) // => true

parseUnsafe

unstable

Since v4.0.6

Parses an npm-style version range and throws SemVer.SemVerError for invalid input.

See

parse for non-throwing parsing

Signature

declare function parseUnsafe(input: string): SemVerRange

tilde

unstable

Since v4.0.6

Creates a range matching patch-level changes of a version, written ~1.2.3.

Details

~1.2.3 means >=1.2.3 <1.3.0-0. Build metadata is dropped. Throws SemVerError for an invalid SemVer.Input.

Signature

declare function tilde(version: Input): SemVerRange

Converting

format

unstable

Since v4.0.6

Formats a range in canonical form.

Details

Operators and comparators are kept as parsed. Wildcard spellings are normalized by dropping trailing wildcard components (1.x and 1.*.* format as 1, and x as *), and an explicit = operator is omitted.

See

parse for the inverse operation

Signature

declare function format(self: SemVerRange): string

Filtering

maxSatisfying

unstable

Since v4.0.6

Returns the version with the highest precedence that a range matches.

Details

Returns None when no version matches. When several versions share the highest precedence, the first one is returned. Throws SemVerError when a version is an invalid SemVer.Input.

See

minSatisfying for the lowest matching version

Signature

declare const maxSatisfying: {
  (versions: Iterable<Input>, options?: MatchOptions): (self: SemVerRange) => Option<SemVer>;
  (self: SemVerRange, versions: Iterable<Input>, options?: MatchOptions): Option<SemVer>;
}

Example Selecting the newest compatible version

import { Option, SemVer, SemVerRange } from "effect"

const range = SemVerRange.parseUnsafe("^1.2.0")

SemVerRange.maxSatisfying(range, ["1.2.0", "1.4.1", "2.0.0", "1.5.0-rc.1"]).pipe(Option.map(SemVer.format)) // => Option.some("1.4.1")

minSatisfying

unstable

Since v4.0.6

Returns the version with the lowest precedence that a range matches.

Details

Returns None when no version matches. When several versions share the lowest precedence, the first one is returned. Throws SemVerError when a version is an invalid SemVer.Input.

See

maxSatisfying for the highest matching version

Signature

declare const minSatisfying: {
  (versions: Iterable<Input>, options?: MatchOptions): (self: SemVerRange) => Option<SemVer>;
  (self: SemVerRange, versions: Iterable<Input>, options?: MatchOptions): Option<SemVer>;
}

Guards

isSemVerRange

unstable

Since v4.0.6

Checks whether a value is a SemVerRange.

Signature

declare function isSemVerRange(u: unknown): u is SemVerRange

Models

Input

type unstable

Since v4.0.6

Values accepted by fromInput: a range or a range string.

See

fromInput for converting inputs

Signature

type Input = SemVerRange | string

MatchOptions

interface unstable

Since v4.0.6

Options controlling how pre-release versions match a range.

Signature

interface MatchOptions {
  readonly includePrerelease?: boolean;
}

SemVerRange

interface unstable

Since v4.0.6

Represents an npm-style version range.

Details

Ranges are opaque. format preserves parsed operators such as ^1.2 rather than expanding them into bounds.

See

parse for decoding range strings
matches for matching versions

Signature

interface SemVerRange extends Pipeable, Equal, Inspectable {
  readonly "~effect/SemVerRange": "~effect/SemVerRange";
}

Predicates

matches

unstable

Since v4.0.6

Checks whether a range matches a version.

Details

Partial versions, tilde, caret, and hyphen ranges expand to bounds following node-semver. For example, ^1.2.3 means >=1.2.3 <2.0.0-0, ~1.2 means >=1.2.0 <1.3.0-0, and <=1.2 means <1.3.0-0. Throws SemVerError when version is an invalid SemVer.Input.

Gotchas

A pre-release version only matches a comparator set that contains a comparator with a pre-release on the same major, minor, and patch. So ^1.2.3-beta.1 matches 1.2.3-beta.2 but not 1.3.0-rc.1, and * does not match any pre-release. Set includePrerelease to disable this rule.

Alternatives separated by || always form a union. Unlike node-semver, a * alternative does not discard pre-releases admitted by another alternative.

See

maxSatisfying for selecting the highest matching version

Signature

declare const matches: {
  (version: Input, options?: MatchOptions): (self: SemVerRange) => boolean;
  (self: SemVerRange, version: Input, options?: MatchOptions): boolean;
}

Example Matching pre-releases

import { SemVerRange } from "effect"

const range = SemVerRange.parseUnsafe("^1.2.3-beta.1")

SemVerRange.matches(range, "1.2.3-beta.2") // => true
SemVerRange.matches(range, "1.3.0-rc.1") // => false
SemVerRange.matches(range, "1.3.0-rc.1", { includePrerelease: true }) // => true

Example Filtering versions

import { SemVer, SemVerRange } from "effect"

const range = SemVerRange.parseUnsafe("~1.2")
const versions = ["1.1.0", "1.2.0", "1.2.7", "1.3.0"].map(SemVer.parseUnsafe)

versions.filter((version) => SemVerRange.matches(range, version)).map(SemVer.format) // => ["1.2.0", "1.2.7"]