effect 4.0.5 → 4.0.6

package/src/SemVerRange.ts

@@ -0,0 +1,883 @@
+/**
+ * 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 {@link matches}.
+ *
+ * @stability unstable
+ * @since 4.0.6
+ */
+import * as Equal from "./Equal.ts"
+import { dual } from "./Function.ts"
+import * as Hash from "./Hash.ts"
+import { type Inspectable, NodeInspectSymbol } from "./Inspectable.ts"
+import * as Option from "./Option.ts"
+import { type Pipeable, pipeArguments } from "./Pipeable.ts"
+import { hasProperty } from "./Predicate.ts"
+import * as Result from "./Result.ts"
+import {
+  compareCore,
+  type Core,
+  fromInputUnsafe as versionFromInputUnsafe,
+  type Input as VersionInput,
+  invalid,
+  parseComponent,
+  prereleaseIdentifier,
+  sameCore,
+  type SemVer,
+  type SemVerError,
+  tryParse
+} from "./SemVer.ts"
+
+const TypeId = "~effect/SemVerRange"
+
+/**
+ * Represents an npm-style version range.
+ *
+ * **Details**
+ *
+ * Ranges are opaque. {@link format} preserves parsed operators such as `^1.2`
+ * rather than expanding them into bounds.
+ *
+ * @see {@link parse} for decoding range strings
+ * @see {@link matches} for matching versions
+ * @stability unstable
+ * @category models
+ * @since 4.0.6
+ */
+export interface SemVerRange extends Pipeable, Equal.Equal, Inspectable {
+  readonly [TypeId]: typeof TypeId
+}
+
+interface PartialVersion {
+  // The components given before the first wildcard; empty for `*`.
+  readonly components: ReadonlyArray<number>
+  // Only a full MAJOR.MINOR.PATCH may carry a pre-release.
+  readonly prerelease: ReadonlyArray<string | number>
+}
+
+type Operator = "=" | "<" | "<=" | ">" | ">=" | "~" | "^"
+
+type Comparator =
+  | {
+    readonly _tag: "Comparator"
+    readonly operator: Operator
+    readonly version: PartialVersion
+  }
+  | {
+    readonly _tag: "Hyphen"
+    readonly from: PartialVersion
+    readonly to: PartialVersion
+  }
+
+interface SemVerRangeImpl extends SemVerRange {
+  // Alternatives separated by `||`, each a set of comparators that must all match.
+  readonly sets: ReadonlyArray<ReadonlyArray<Comparator>>
+  matcher?: (version: SemVer) => boolean
+  prereleaseMatcher?: (version: SemVer) => boolean
+}
+
+/**
+ * Options controlling how pre-release versions match a range.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.6
+ */
+export interface MatchOptions {
+  /**
+   * Lets pre-release versions match any comparator set whose bounds contain
+   * them, and lowers wildcard lower bounds to include pre-releases.
+   *
+   * @default false
+   */
+  readonly includePrerelease?: boolean | undefined
+}
+
+const SemVerRangeProto: SemVerRange = {
+  [TypeId]: TypeId,
+  [Equal.symbol](this: SemVerRange, that: unknown): boolean {
+    return isSemVerRange(that) && format(this) === format(that)
+  },
+  [Hash.symbol](this: SemVerRange): number {
+    return Hash.string(format(this))
+  },
+  toString(this: SemVerRange) {
+    return `SemVerRange(${format(this)})`
+  },
+  toJSON(this: SemVerRange) {
+    return { _id: "SemVerRange", value: format(this) }
+  },
+  [NodeInspectSymbol](this: SemVerRange) {
+    return this.toJSON()
+  },
+  pipe() {
+    return pipeArguments(this, arguments)
+  }
+}
+
+/**
+ * Checks whether a value is a `SemVerRange`.
+ *
+ * @stability unstable
+ * @category guards
+ * @since 4.0.6
+ */
+export const isSemVerRange = (u: unknown): u is SemVerRange => hasProperty(u, TypeId)
+
+const isRangeArgs = (args: IArguments) => isSemVerRange(args[0])
+
+const wildcard: PartialVersion = { components: [], prerelease: [] }
+const operatorPattern = /^(<=|>=|<|>|=|~|\^)?(.*)$/
+const isWildcard = (part: string): boolean => part === "x" || part === "X" || part === "*"
+
+const componentLabels = ["major", "minor", "patch"] as const
+
+const parsePartial = (input: string): PartialVersion => {
+  if (input.length === 0) return invalid("expected a version after the operator")
+  if (input.includes("+")) {
+    return invalid(`build metadata is not allowed in ranges, received ${JSON.stringify(input)}`)
+  }
+  const dash = input.indexOf("-")
+  const parts = (dash === -1 ? input : input.slice(0, dash)).split(".")
+  if (parts.length > 3) return invalid(`expected at most MAJOR.MINOR.PATCH, received ${JSON.stringify(input)}`)
+  const components: Array<number> = []
+  for (let i = 0; i < parts.length; i++) {
+    if (isWildcard(parts[i])) continue
+    // A skipped wildcard leaves `components` shorter than the position reached.
+    if (components.length < i) {
+      return invalid(`a version component cannot follow a wildcard, received ${JSON.stringify(input)}`)
+    }
+    components.push(parseComponent(parts[i], componentLabels[i]))
+  }
+  if (dash === -1) return { components, prerelease: [] }
+  if (components.length < 3) {
+    return invalid(`a pre-release requires MAJOR.MINOR.PATCH, received ${JSON.stringify(input)}`)
+  }
+  return { components, prerelease: input.slice(dash + 1).split(".").map(prereleaseIdentifier) }
+}
+
+const parseComparatorSet = (input: string): ReadonlyArray<Comparator> => {
+  const tokens = input.split(/\s+/).filter((token) => token.length > 0)
+  if (tokens.length === 0) return invalid("expected a comparator")
+  if (tokens.length === 3 && tokens[1] === "-") {
+    return [{ _tag: "Hyphen", from: parsePartial(tokens[0]), to: parsePartial(tokens[2]) }]
+  }
+  const comparators: Array<Comparator> = []
+  for (let i = 0; i < tokens.length; i++) {
+    const [, operator, rest] = operatorPattern.exec(tokens[i])!
+    // Allow whitespace between an operator and its version, as in `>= 1.2.3`.
+    const version = rest.length === 0 && operator !== undefined && i + 1 < tokens.length ? tokens[++i] : rest
+    comparators.push({ _tag: "Comparator", operator: (operator ?? "=") as Operator, version: parsePartial(version) })
+  }
+  return comparators
+}
+
+const makeRange = (sets: ReadonlyArray<ReadonlyArray<Comparator>>): SemVerRange => {
+  const self = Object.create(SemVerRangeProto)
+  self.sets = sets
+  return self
+}
+
+const parseOrThrow = (input: string): SemVerRange => {
+  if (input.trim().length === 0) return any
+  return makeRange(input.split("||").map(parseComparatorSet))
+}
+
+/**
+ * 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.
+ *
+ * **Example** (Parsing and matching a caret range)
+ *
+ * ```ts import.meta.vitest
+ * 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
+ * ```
+ *
+ * @see {@link parseUnsafe} for throwing on invalid input
+ * @see {@link format} for the inverse operation
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.6
+ */
+export const parse = (input: string): Result.Result<SemVerRange, SemVerError> =>
+  tryParse("SemVer range", input, parseOrThrow)
+
+/**
+ * Parses an npm-style version range and throws `SemVer.SemVerError` for
+ * invalid input.
+ *
+ * @see {@link parse} for non-throwing parsing
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.6
+ */
+export const parseUnsafe = (input: string): SemVerRange => Result.getOrThrow(parse(input))
+
+/**
+ * Values accepted by `fromInput`: a range or a range string.
+ *
+ * @see {@link fromInput} for converting inputs
+ * @stability unstable
+ * @category models
+ * @since 4.0.6
+ */
+export type Input = SemVerRange | string
+
+/**
+ * Converts a range or range string into a `SemVerRange`.
+ *
+ * **Details**
+ *
+ * Ranges are returned unchanged and strings are parsed like {@link parse}.
+ * Invalid strings fail with `SemVer.SemVerError`.
+ *
+ * @see {@link fromInputUnsafe} for throwing on invalid input
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.6
+ */
+export const fromInput = (input: Input): Result.Result<SemVerRange, SemVerError> =>
+  isSemVerRange(input) ? Result.succeed(input) : parse(input)
+
+/**
+ * Converts a range or range string into a `SemVerRange` and throws
+ * `SemVer.SemVerError` for invalid input.
+ *
+ * @see {@link fromInput} for non-throwing conversion
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.6
+ */
+export const fromInputUnsafe = (input: Input): SemVerRange => Result.getOrThrow(fromInput(input))
+
+const toPartial = (version: SemVer): PartialVersion => ({
+  components: [version.major, version.minor, version.patch],
+  prerelease: version.prerelease
+})
+
+const comparator = (operator: Operator, version: VersionInput): Comparator => ({
+  _tag: "Comparator",
+  operator,
+  version: toPartial(versionFromInputUnsafe(version))
+})
+
+const fromComparator = (operator: Operator, version: VersionInput): SemVerRange =>
+  makeRange([[comparator(operator, version)]])
+
+/**
+ * The range matching every release, written `*`.
+ *
+ * **Gotchas**
+ *
+ * Like every range, `*` only matches pre-releases with `includePrerelease`.
+ *
+ * @stability unstable
+ * @category constants
+ * @since 4.0.6
+ */
+export const any: SemVerRange = makeRange([[{ _tag: "Comparator", operator: "=", version: wildcard }]])
+
+/**
+ * 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`.
+ *
+ * **Example** (Building ranges from versions)
+ *
+ * ```ts import.meta.vitest
+ * 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
+ * ```
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.6
+ */
+export const exact = (version: VersionInput): SemVerRange => fromComparator("=", version)
+
+/**
+ * Creates a range matching versions with higher precedence, written `>1.2.3`.
+ *
+ * **Details**
+ *
+ * Build metadata is dropped. Throws `SemVerError` for an invalid `SemVer.Input`.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.6
+ */
+export const greaterThan = (version: VersionInput): SemVerRange => fromComparator(">", version)
+
+/**
+ * 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`.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.6
+ */
+export const greaterThanOrEqualTo = (version: VersionInput): SemVerRange => fromComparator(">=", version)
+
+/**
+ * Creates a range matching versions with lower precedence, written `<1.2.3`.
+ *
+ * **Details**
+ *
+ * Build metadata is dropped. Throws `SemVerError` for an invalid `SemVer.Input`.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.6
+ */
+export const lessThan = (version: VersionInput): SemVerRange => fromComparator("<", version)
+
+/**
+ * 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`.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.6
+ */
+export const lessThanOrEqualTo = (version: VersionInput): SemVerRange => fromComparator("<=", version)
+
+/**
+ * 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`.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.6
+ */
+export const caret = (version: VersionInput): SemVerRange => fromComparator("^", version)
+
+/**
+ * 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`.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.6
+ */
+export const tilde = (version: VersionInput): SemVerRange => fromComparator("~", version)
+
+/**
+ * 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`.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.6
+ */
+export const between = (options: { readonly minimum: VersionInput; readonly maximum: VersionInput }): SemVerRange =>
+  makeRange([[comparator(">=", options.minimum), comparator("<=", options.maximum)]])
+
+const formatPartial = (self: PartialVersion): string => {
+  if (self.components.length === 0) return "*"
+  const core = self.components.join(".")
+  return self.prerelease.length === 0 ? core : `${core}-${self.prerelease.join(".")}`
+}
+
+const formatComparator = (self: Comparator): string =>
+  self._tag === "Hyphen"
+    ? `${formatPartial(self.from)} - ${formatPartial(self.to)}`
+    : `${self.operator === "=" ? "" : self.operator}${formatPartial(self.version)}`
+
+/**
+ * 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 {@link parse} for the inverse operation
+ * @stability unstable
+ * @category converting
+ * @since 4.0.6
+ */
+export const format = (self: SemVerRange): string =>
+  (self as SemVerRangeImpl).sets.map((set) => set.map(formatComparator).join(" ")).join(" || ")
+
+interface Bound extends Core {
+  readonly operator: "=" | "<" | "<=" | ">" | ">="
+}
+
+const bound = (
+  operator: Bound["operator"],
+  [major = 0, minor = 0, patch = 0]: ReadonlyArray<number>,
+  prerelease: ReadonlyArray<string | number>
+): Bound => ({ operator, major, minor, patch, prerelease })
+
+// The expansions below follow node-semver's `Range` desugaring. `z` is the
+// pre-release a wildcard lower bound carries: `[0]` when pre-releases are
+// included, so `>=1.2` admits `1.2.0-alpha`, and empty otherwise.
+
+// Exclusive upper bound at the first pre-release of `core`, node-semver's `<X.Y.Z-0`.
+const below = (core: ReadonlyArray<number>): Bound => bound("<", core, [0])
+
+// The lowest version a partial covers.
+const floor = (self: PartialVersion, z: ReadonlyArray<number>): Bound =>
+  bound(">=", self.components, self.components.length === 3 ? self.prerelease : z)
+
+// The first core above every version the first `precision` components cover.
+const after = (components: ReadonlyArray<number>, precision: number): ReadonlyArray<number> => {
+  const next = components.slice(0, precision)
+  next[precision - 1]++
+  return next
+}
+
+const expandCaret = (self: PartialVersion, z: ReadonlyArray<number>): ReadonlyArray<Bound> => {
+  const n = self.components.length
+  if (n === 0) return []
+  // The first non-zero component may not change; `^0.0.x` pins the patch.
+  const precision = self.components.findIndex((component) => component !== 0) + 1 || n
+  return [floor(self, z), below(after(self.components, precision))]
+}
+
+const expandTilde = (self: PartialVersion, z: ReadonlyArray<number>): ReadonlyArray<Bound> => {
+  const n = self.components.length
+  if (n === 0) return []
+  return [floor(self, z), below(after(self.components, Math.min(n, 2)))]
+}
+
+const expandXRange = (
+  operator: Bound["operator"],
+  self: PartialVersion,
+  z: ReadonlyArray<number>
+): ReadonlyArray<Bound> => {
+  const n = self.components.length
+  if (n === 3) return [bound(operator, self.components, self.prerelease)]
+  if (n === 0) return operator === "<" || operator === ">" ? [below([0, 0, 0])] : []
+  switch (operator) {
+    case "=":
+      return [floor(self, z), below(after(self.components, n))]
+    case ">":
+      return [bound(">=", after(self.components, n), z)]
+    case ">=":
+      return [floor(self, z)]
+    case "<=":
+      return [below(after(self.components, n))]
+    case "<":
+      return [below(self.components)]
+  }
+}
+
+const expand = (self: Comparator, includePrerelease: boolean): ReadonlyArray<Bound> => {
+  const z = includePrerelease ? [0] : []
+  if (self._tag === "Hyphen") {
+    const { from, to } = self
+    // Unlike `>=`, a full hyphen lower bound without a pre-release also takes `z`.
+    const lower = from.components.length === 0
+      ? []
+      : [bound(">=", from.components, from.prerelease.length > 0 ? from.prerelease : z)]
+    return [...lower, ...expandXRange("<=", to, z)]
+  }
+  switch (self.operator) {
+    case "^":
+      return expandCaret(self.version, z)
+    case "~":
+      return expandTilde(self.version, z)
+    default:
+      return expandXRange(self.operator, self.version, z)
+  }
+}
+
+const testBound = (self: Bound, version: SemVer): boolean => {
+  const result = compareCore(version, self)
+  switch (self.operator) {
+    case "=":
+      return result === 0
+    case "<":
+      return result < 0
+    case "<=":
+      return result <= 0
+    case ">":
+      return result > 0
+    case ">=":
+      return result >= 0
+  }
+}
+
+const compile = (self: SemVerRangeImpl, includePrerelease: boolean): (version: SemVer) => boolean => {
+  const sets = self.sets.map((set) => set.flatMap((comparator) => expand(comparator, includePrerelease)))
+  return (version) =>
+    sets.some((bounds) =>
+      bounds.every((bound) => testBound(bound, version)) &&
+      (includePrerelease || version.prerelease.length === 0 ||
+        bounds.some((bound) => bound.prerelease.length > 0 && sameCore(bound, version)))
+    )
+}
+
+const matcher = (range: SemVerRange, options: MatchOptions | undefined): (version: SemVer) => boolean => {
+  const self = range as SemVerRangeImpl
+  return options?.includePrerelease === true
+    ? (self.prereleaseMatcher ??= compile(self, true))
+    : (self.matcher ??= compile(self, false))
+}
+
+/**
+ * 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.
+ *
+ * **Example** (Matching pre-releases)
+ *
+ * ```ts import.meta.vitest
+ * 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)
+ *
+ * ```ts import.meta.vitest
+ * 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"]
+ * ```
+ *
+ * @see {@link maxSatisfying} for selecting the highest matching version
+ * @stability unstable
+ * @category predicates
+ * @since 4.0.6
+ */
+export const matches: {
+  /**
+   * 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.
+   *
+   * **Example** (Matching pre-releases)
+   *
+   * ```ts import.meta.vitest
+   * 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)
+   *
+   * ```ts import.meta.vitest
+   * 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"]
+   * ```
+   *
+   * @see {@link maxSatisfying} for selecting the highest matching version
+   * @stability unstable
+   * @category predicates
+   * @since 4.0.6
+   */
+  (version: VersionInput, options?: MatchOptions): (self: SemVerRange) => boolean
+  /**
+   * 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.
+   *
+   * **Example** (Matching pre-releases)
+   *
+   * ```ts import.meta.vitest
+   * 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)
+   *
+   * ```ts import.meta.vitest
+   * 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"]
+   * ```
+   *
+   * @see {@link maxSatisfying} for selecting the highest matching version
+   * @stability unstable
+   * @category predicates
+   * @since 4.0.6
+   */
+  (self: SemVerRange, version: VersionInput, options?: MatchOptions): boolean
+} = dual(
+  isRangeArgs,
+  (self: SemVerRange, version: VersionInput, options?: MatchOptions): boolean =>
+    matcher(self, options)(versionFromInputUnsafe(version))
+)
+
+const select = (
+  self: SemVerRange,
+  versions: Iterable<VersionInput>,
+  options: MatchOptions | undefined,
+  better: -1 | 1
+): Option.Option<SemVer> => {
+  const test = matcher(self, options)
+  let selected: SemVer | undefined
+  for (const input of versions) {
+    const version = versionFromInputUnsafe(input)
+    if (test(version) && (selected === undefined || compareCore(version, selected) === better)) {
+      selected = version
+    }
+  }
+  return Option.fromUndefinedOr(selected)
+}
+
+/**
+ * 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`.
+ *
+ * **Example** (Selecting the newest compatible version)
+ *
+ * ```ts import.meta.vitest
+ * 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")
+ * ```
+ *
+ * @see {@link minSatisfying} for the lowest matching version
+ * @stability unstable
+ * @category filtering
+ * @since 4.0.6
+ */
+export const maxSatisfying: {
+  /**
+   * 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`.
+   *
+   * **Example** (Selecting the newest compatible version)
+   *
+   * ```ts import.meta.vitest
+   * 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")
+   * ```
+   *
+   * @see {@link minSatisfying} for the lowest matching version
+   * @stability unstable
+   * @category filtering
+   * @since 4.0.6
+   */
+  (versions: Iterable<VersionInput>, options?: MatchOptions): (self: SemVerRange) => Option.Option<SemVer>
+  /**
+   * 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`.
+   *
+   * **Example** (Selecting the newest compatible version)
+   *
+   * ```ts import.meta.vitest
+   * 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")
+   * ```
+   *
+   * @see {@link minSatisfying} for the lowest matching version
+   * @stability unstable
+   * @category filtering
+   * @since 4.0.6
+   */
+  (
+    self: SemVerRange,
+    versions: Iterable<VersionInput>,
+    options?: MatchOptions
+  ): Option.Option<SemVer>
+} = dual(
+  isRangeArgs,
+  (self: SemVerRange, versions: Iterable<VersionInput>, options?: MatchOptions): Option.Option<SemVer> =>
+    select(self, versions, options, 1)
+)
+
+/**
+ * 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 {@link maxSatisfying} for the highest matching version
+ * @stability unstable
+ * @category filtering
+ * @since 4.0.6
+ */
+export const minSatisfying: {
+  /**
+   * 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 {@link maxSatisfying} for the highest matching version
+   * @stability unstable
+   * @category filtering
+   * @since 4.0.6
+   */
+  (versions: Iterable<VersionInput>, options?: MatchOptions): (self: SemVerRange) => Option.Option<SemVer>
+  /**
+   * 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 {@link maxSatisfying} for the highest matching version
+   * @stability unstable
+   * @category filtering
+   * @since 4.0.6
+   */
+  (
+    self: SemVerRange,
+    versions: Iterable<VersionInput>,
+    options?: MatchOptions
+  ): Option.Option<SemVer>
+} = dual(
+  isRangeArgs,
+  (self: SemVerRange, versions: Iterable<VersionInput>, options?: MatchOptions): Option.Option<SemVer> =>
+    select(self, versions, options, -1)
+)