semver 0.0.1-preview.1

Semantic versions and npm's version ranges

Readme Files Dependencies Versions

semver#

Semantic versions (https://semver.org) and npm's version ranges (https://github.com/npm/node-semver#ranges), for Zena.

import {Range, Version} from 'zena-lang:semver';

let range = Range.parse('^1.4.2 || ^2.0.0');
range.includes(Version.parse('1.7.0')); // true
range.includes(Version.parse('3.0.0')); // false
range.toString(); // '>=1.4.2 <2.0.0-0 || >=2.0.0 <3.0.0-0'
Range Means
^1.4.2 >=1.4.2 <2.0.0-0
^0.3.1 >=0.3.1 <0.4.0-0
~1.4.2 >=1.4.2 <1.5.0-0
1.4.2 exactly 1.4.2
1.x, 1 >=1.0.0 <2.0.0-0
1.2.3 - 2.3 >=1.2.3 <2.4.0-0
>=1.4.2 <1.7.0 both comparators
a || b either range

A pre-release is in a range only when the range names a pre-release of the same major.minor.patch, as in npm: ^2.0.0 does not include 2.1.0-rc.1. Pass includePrerelease to includes to include them.

highest and lowest pick from a list of versions, and intervals gives each comparator set as a pair of bounds.

21.9 KiB Raw
/**
 * Version ranges in npm's syntax
 * (https://github.com/npm/node-semver#ranges): `^1.4.2`, `~1.4.2`,
 * `1.4.2`, `>=1.4.2 <1.7.0`, `1.x`, `1.2.3 - 2.3`, and any of them joined
 * by `||`.
 *
 * A range is read into comparator sets, as node-semver reads it: a
 * version is in the range when it meets every comparator of one of the
 * sets. `^1.4.2` is the set `>=1.4.2 <2.0.0-0`. The `-0` on an upper bound
 * is the lowest pre-release of that version, so `<2.0.0-0` excludes
 * `2.0.0-rc.1` along with `2.0.0`.
 *
 * A pre-release is in a range only when one comparator of the set it
 * meets names a pre-release of the same `major.minor.patch`: `^2.0.0`
 * does not take `2.1.0-rc.1`, and `>=2.1.0-rc.1 <3.0.0-0` does. A caller
 * that wants every pre-release passes `includePrerelease`.
 */

import {HashSet} from 'zena:collections';
import {Version, VersionError, parseBuild, parsePrerelease, parseVersionNumber} from './version.zena';

/** How a comparator compares a version with its own. */
export enum Relation {
  Less,
  LessOrEqual,
  Greater,
  GreaterOrEqual,
  Equal
}

/** A version and how a version must compare with it: `>=1.4.2`. */
export final class Comparator {
  relation: Relation;
  version: Version;

  new(relation: Relation, version: Version) : relation = relation, version = version;

  /** Whether `version` meets this comparator, by precedence alone. */
  test(version: Version): boolean {
    let order = version.compareTo(this.version);
    return match (this.relation) {
      case Relation.Less: order < 0
      case Relation.LessOrEqual: order <= 0
      case Relation.Greater: order > 0
      case Relation.GreaterOrEqual: order >= 0
      case Relation.Equal: order == 0
    };
  }

  toString(): String {
    let prefix = match (this.relation) {
      case Relation.Less: '<'
      case Relation.LessOrEqual: '<='
      case Relation.Greater: '>'
      case Relation.GreaterOrEqual: '>='
      case Relation.Equal: ''
    };
    return `${prefix}${this.version.toString()}`;
  }
}

/** One end of an interval of versions. */
export final class Bound {
  version: Version;
  inclusive: boolean;

  new(version: Version, inclusive: boolean) : version = version, inclusive = inclusive;
}

/**
 * The versions between two bounds, by precedence: what one comparator set
 * allows, before the pre-release rule. A missing bound is unbounded.
 */
export final class Interval {
  lower: Bound | null;
  upper: Bound | null;

  new(lower: Bound | null, upper: Bound | null) : lower = lower, upper = upper;

  /** Whether `version` is between the bounds, by precedence alone. */
  contains(version: Version): boolean {
    let lower = this.lower;
    if (lower != null) {
      let order = version.compareTo(lower.version);
      if (order < 0 || (order == 0 && !lower.inclusive)) {
        return false;
      }
    }
    let upper = this.upper;
    if (upper != null) {
      let order = version.compareTo(upper.version);
      if (order > 0 || (order == 0 && !upper.inclusive)) {
        return false;
      }
    }
    return true;
  }

  /** Whether no version is between the bounds. */
  isEmpty: boolean {
    get {
      let lower = this.lower;
      let upper = this.upper;
      if (lower == null || upper == null) {
        return false;
      }
      let order = lower.version.compareTo(upper.version);
      return order > 0 || (order == 0 && !(lower.inclusive && upper.inclusive));
    }
  }
}

/** A version range: comparator sets, any one of which a version may meet. */
export final class Range {
  /**
   * The comparator sets. A version must meet every comparator of one set.
   * A set with no comparators, from `*` or an empty range, is met by every
   * version.
   */
  sets: GrowableArray<GrowableArray<Comparator>>;
  /** The text the range was read from, as written: `^1.4.2`. */
  text: String;

  new(sets: GrowableArray<GrowableArray<Comparator>>, text: String) : sets = sets, text = text;

  /** Reads a range in npm's syntax. Throws `VersionError` for anything else. */
  static parse(text: String): Range {
    let parsed = new GrowableArray<GrowableArray<Comparator>>();
    for (let part in text.split('||')) {
      parsed.push(parseSet(part.trim(), text));
    }
    // As node-semver does: a set met by everything makes the range met by
    // everything, and a set met by nothing is dropped beside others.
    let sets = new GrowableArray<GrowableArray<Comparator>>();
    for (let set in parsed) {
      if (set.length == 0) {
        let any = new GrowableArray<GrowableArray<Comparator>>();
        any.push(set);
        return new Range(any, text);
      }
      if (!isNothing(set)) {
        sets.push(set);
      }
    }
    if (sets.length == 0) {
      sets.push(parsed[0]);
    }
    return new Range(sets, text);
  }

  /**
   * Whether `version` is in the range. A pre-release is in it only when a
   * comparator of the set it meets names a pre-release of the same
   * `major.minor.patch`, unless `includePrerelease` is true.
   */
  includes(version: Version, includePrerelease: boolean = false): boolean {
    for (let set in this.sets) {
      if (inSet(set, version, includePrerelease)) {
        return true;
      }
    }
    return false;
  }

  /**
   * The lowest version in the range, whether or not it is published, or
   * null when no version is in it: `1.4.2` for `^1.4.2`, `1.2.4` for
   * `>1.2.3`, `0.0.0` for `<2.0.0`. node-semver calls it `minVersion`.
   */
  minimum(): Version | null {
    var found: Version | null = null;
    for (let set in this.sets) {
      // The highest lower bound of the set, or the lowest version of all.
      var lowest = new Version(0 as i64, 0 as i64, 0 as i64, none());
      for (let comparator in set) {
        let v = comparator.version;
        let candidate = match (comparator.relation) {
          case Relation.Greater: justAbove(v)
          case Relation.GreaterOrEqual: v
          case Relation.Equal: v
          case Relation.Less: null
          case Relation.LessOrEqual: null
        };
        if (candidate != null && candidate.compareTo(lowest) > 0) {
          lowest = candidate;
        }
      }
      if (inSet(set, lowest, false)) {
        let current = found;
        if (current == null || lowest.compareTo(current) < 0) {
          found = lowest;
        }
      }
    }
    return found;
  }

  /** The highest of `versions` in the range, or null when none is. */
  highest(versions: GrowableArray<Version>, includePrerelease: boolean = false): Version | null {
    var found: Version | null = null;
    for (let version in versions) {
      if (this.includes(version, includePrerelease)) {
        let current = found;
        if (current == null || version.compareTo(current) > 0) {
          found = version;
        }
      }
    }
    return found;
  }

  /** The lowest of `versions` in the range, or null when none is. */
  lowest(versions: GrowableArray<Version>, includePrerelease: boolean = false): Version | null {
    var found: Version | null = null;
    for (let version in versions) {
      if (this.includes(version, includePrerelease)) {
        let current = found;
        if (current == null || version.compareTo(current) < 0) {
          found = version;
        }
      }
    }
    return found;
  }

  /**
   * Each comparator set as an interval of versions, by precedence: the
   * highest of its lower bounds and the lowest of its upper bounds. The
   * pre-release rule of `includes` is not part of it.
   */
  intervals(): GrowableArray<Interval> {
    let out = new GrowableArray<Interval>();
    for (let set in this.sets) {
      var lower: Bound | null = null;
      var upper: Bound | null = null;
      for (let comparator in set) {
        let version = comparator.version;
        match (comparator.relation) {
          case Relation.Greater: { lower = tighterLower(lower, new Bound(version, false)); }
          case Relation.GreaterOrEqual: { lower = tighterLower(lower, new Bound(version, true)); }
          case Relation.Less: { upper = tighterUpper(upper, new Bound(version, false)); }
          case Relation.LessOrEqual: { upper = tighterUpper(upper, new Bound(version, true)); }
          case Relation.Equal: {
            lower = tighterLower(lower, new Bound(version, true));
            upper = tighterUpper(upper, new Bound(version, true));
          }
        }
      }
      out.push(new Interval(lower, upper));
    }
    return out;
  }

  /** The range's comparator sets, as `>=1.4.2 <2.0.0-0 || >=3.0.0`; `*` for a set met by everything. */
  toString(): String {
    var text = '';
    for (var i = 0; i < this.sets.length; i += 1) {
      let set = this.sets[i];
      var part = '';
      for (let comparator in set) {
        part = if (part == '') comparator.toString() else `${part} ${comparator.toString()}`;
      }
      if (part == '') {
        part = '*';
      }
      text = if (i == 0) part else `${text} || ${part}`;
    }
    return text;
  }
}

/**
 * The lowest version above `v`: its next pre-release when it is one
 * (`1.2.3-rc` becomes `1.2.3-rc.0`), and otherwise its next patch.
 */
function justAbove(v: Version): Version {
  if (v.isPrerelease) {
    let prerelease = new FixedArray<String>(v.prerelease.length + 1, '0');
    for (var i = 0; i < v.prerelease.length; i += 1) {
      prerelease[i] = v.prerelease[i];
    }
    return new Version(v.major, v.minor, v.patch, prerelease);
  }
  return new Version(v.major, v.minor, v.patch + (1 as i64), none());
}

/** Whether `version` is in `set`, with the pre-release rule unless `includePrerelease`. */
function inSet(set: GrowableArray<Comparator>, version: Version, includePrerelease: boolean): boolean {
  if (!meetsAll(set, version)) {
    return false;
  }
  if (!version.isPrerelease || includePrerelease) {
    return true;
  }
  for (let comparator in set) {
    if (comparator.version.isPrerelease && comparator.version.hasSameCore(version)) {
      return true;
    }
  }
  return false;
}

/** Whether `version` meets every comparator of `set`. */
function meetsAll(set: GrowableArray<Comparator>, version: Version): boolean {
  for (let comparator in set) {
    if (!comparator.test(version)) {
      return false;
    }
  }
  return true;
}

/** The higher of two lower bounds; at one version, the exclusive one. */
function tighterLower(current: Bound | null, next: Bound): Bound {
  if (current == null) {
    return next;
  }
  let order = next.version.compareTo(current.version);
  return if (order > 0 || (order == 0 && !next.inclusive)) next else current;
}

/** The lower of two upper bounds; at one version, the exclusive one. */
function tighterUpper(current: Bound | null, next: Bound): Bound {
  if (current == null) {
    return next;
  }
  let order = next.version.compareTo(current.version);
  return if (order < 0 || (order == 0 && !next.inclusive)) next else current;
}

/** A missing or wildcard (`x`, `X`, `*`) part of a partial version. */
let WILD: i64 = -1;

/**
 * A version that may stop early or have wildcards: `1`, `1.2`, `1.x`,
 * `1.2.3-rc.1`. Missing and wildcard parts are `WILD`, and a pre-release
 * is allowed only after three numbers.
 */
final class Partial {
  major: i64;
  minor: i64;
  patch: i64;
  prerelease: FixedArray<String>;

  new(major: i64, minor: i64, patch: i64, prerelease: FixedArray<String>)
      : major = major, minor = minor, patch = patch, prerelease = prerelease;

  majorWild: boolean {
    get { return this.major == WILD; }
  }

  minorWild: boolean {
    get { return this.majorWild || this.minor == WILD; }
  }

  patchWild: boolean {
    get { return this.minorWild || this.patch == WILD; }
  }
}

/** The pre-release `-0`, the lowest a version can have. */
function lowestPrerelease() {
  return new FixedArray<String>(1, '0');
}

function none() {
  return new FixedArray<String>(0, '');
}

function version(major: i64, minor: i64, patch: i64) {
  return new Version(major, minor, patch, none());
}

/** `<major.minor.patch-0`: below every pre-release of the version. */
function below(major: i64, minor: i64, patch: i64) {
  return new Comparator(Relation.Less, new Version(major, minor, patch, lowestPrerelease()));
}

function atLeast(v: Version) {
  return new Comparator(Relation.GreaterOrEqual, v);
}

/**
 * Reads one comparator set of `text`: the text between two `||`s. As
 * node-semver does, it drops `>=0.0.0`, which every release meets, and
 * repeated comparators, and a comparator met by nothing makes the set
 * met by nothing.
 */
function parseSet(part: String, text: String): GrowableArray<Comparator> {
  let read = new GrowableArray<Comparator>();
  let tokens = tokenize(part);
  if (tokens.length == 3 && tokens[1] == '-') {
    hyphen(parsePartial(tokens[0], text), parsePartial(tokens[2], text), read);
  } else {
    for (let token in tokens) {
      simple(token, text, read);
    }
  }
  let set = new GrowableArray<Comparator>();
  let seen = new HashSet<String>();
  for (let comparator in read) {
    if (isNothingComparator(comparator)) {
      let nothing = new GrowableArray<Comparator>();
      nothing.push(comparator);
      return nothing;
    }
    let key = comparator.toString();
    if (key != '>=0.0.0' && !seen.has(key)) {
      seen.add(key);
      set.push(comparator);
    }
  }
  return set;
}

/** Whether `comparator` is `<0.0.0-0`, which no version meets. */
function isNothingComparator(comparator: Comparator): boolean {
  return comparator.relation == Relation.Less && comparator.toString() == '<0.0.0-0';
}

/** Whether `set` is the set no version meets. */
function isNothing(set: GrowableArray<Comparator>): boolean {
  return set.length == 1 && isNothingComparator(set[0]);
}

/**
 * The words of a comparator set, split at whitespace, with an relation
 * written apart from its version joined to it: `>= 1.2.3` is one word.
 */
function tokenize(part: String): GrowableArray<String> {
  let words = new GrowableArray<String>();
  var start = -1;
  for (var i = 0; i <= part.length; i += 1) {
    let space = i == part.length || part.getByteAt(i) == 32 || part.getByteAt(i) == 9;
    if (space && start >= 0) {
      words.push(part.sliceBytes(start, i));
      start = -1;
    } else if (!space && start < 0) {
      start = i;
    }
  }
  let tokens = new GrowableArray<String>();
  var pending = '';
  for (let word in words) {
    if (isOperator(word)) {
      pending = `${pending}${word}`;
    } else {
      tokens.push(`${pending}${word}`);
      pending = '';
    }
  }
  if (pending != '') {
    tokens.push(pending);
  }
  return tokens;
}

function isOperator(word: String): boolean {
  return word == '<' || word == '<=' || word == '>' || word == '>=' || word == '=' ||
      word == '~' || word == '~>' || word == '^';
}

/** Adds the comparators of one word of a set, `^1.4.2` or `>=1.2`, to `set`. */
function simple(token: String, text: String, set: GrowableArray<Comparator>): void {
  if (token.startsWith('~>')) {
    tilde(parsePartial(token.sliceBytes(2, token.length), text), set);
  } else if (token.startsWith('~')) {
    tilde(parsePartial(token.sliceBytes(1, token.length), text), set);
  } else if (token.startsWith('^')) {
    caret(parsePartial(token.sliceBytes(1, token.length), text), set);
  } else if (token.startsWith('>=')) {
    primitive(Relation.GreaterOrEqual, parsePartial(token.sliceBytes(2, token.length), text), set);
  } else if (token.startsWith('<=')) {
    primitive(Relation.LessOrEqual, parsePartial(token.sliceBytes(2, token.length), text), set);
  } else if (token.startsWith('>')) {
    primitive(Relation.Greater, parsePartial(token.sliceBytes(1, token.length), text), set);
  } else if (token.startsWith('<')) {
    primitive(Relation.Less, parsePartial(token.sliceBytes(1, token.length), text), set);
  } else if (token.startsWith('=')) {
    primitive(Relation.Equal, parsePartial(token.sliceBytes(1, token.length), text), set);
  } else {
    primitive(Relation.Equal, parsePartial(token, text), set);
  }
}

/**
 * `~1.2.3` is `>=1.2.3 <1.3.0-0`: patches. `~1.2` is the same from 1.2.0,
 * and `~1` is `>=1.0.0 <2.0.0-0`.
 */
function tilde(p: Partial, set: GrowableArray<Comparator>): void {
  if (p.majorWild) {
    return;
  }
  if (p.minorWild) {
    set.push(atLeast(version(p.major, 0 as i64, 0 as i64)));
    set.push(below(p.major + (1 as i64), 0 as i64, 0 as i64));
    return;
  }
  let patch = if (p.patchWild) 0 as i64 else p.patch;
  set.push(atLeast(new Version(p.major, p.minor, patch, p.prerelease)));
  set.push(below(p.major, p.minor + (1 as i64), 0 as i64));
}

/**
 * `^1.2.3` is `>=1.2.3 <2.0.0-0`: everything up to the next major
 * version. Before 1.0, the first number that is not zero is the one that
 * may not change: `^0.2.3` is `<0.3.0-0`, and `^0.0.3` is `<0.0.4-0`.
 */
function caret(p: Partial, set: GrowableArray<Comparator>): void {
  if (p.majorWild) {
    return;
  }
  let zero = 0 as i64;
  let one = 1 as i64;
  if (p.minorWild) {
    set.push(atLeast(version(p.major, zero, zero)));
    set.push(below(p.major + one, zero, zero));
    return;
  }
  if (p.patchWild) {
    set.push(atLeast(version(p.major, p.minor, zero)));
    if (p.major == zero) {
      set.push(below(zero, p.minor + one, zero));
    } else {
      set.push(below(p.major + one, zero, zero));
    }
    return;
  }
  set.push(atLeast(new Version(p.major, p.minor, p.patch, p.prerelease)));
  if (p.major != zero) {
    set.push(below(p.major + one, zero, zero));
  } else if (p.minor != zero) {
    set.push(below(zero, p.minor + one, zero));
  } else {
    set.push(below(zero, zero, p.patch + one));
  }
}

/**
 * A comparator, or a version alone (`relation` is `Equal`), whose version
 * may have wildcards. `1.x` and `1` are `>=1.0.0 <2.0.0-0`; `>1.2` is
 * `>=1.3.0`; `<=1.2` is `<1.3.0-0`; `*` is every version.
 */
function primitive(relation: Relation, p: Partial, set: GrowableArray<Comparator>): void {
  let zero = 0 as i64;
  let one = 1 as i64;
  if (!p.patchWild) {
    set.push(new Comparator(relation, new Version(p.major, p.minor, p.patch, p.prerelease)));
    return;
  }
  if (p.majorWild) {
    // `>*` and `<*` are met by nothing, and the rest by everything.
    if (relation == Relation.Greater || relation == Relation.Less) {
      set.push(below(zero, zero, zero));
    }
    return;
  }
  if (relation == Relation.Equal) {
    if (p.minorWild) {
      set.push(atLeast(version(p.major, zero, zero)));
      set.push(below(p.major + one, zero, zero));
    } else {
      set.push(atLeast(version(p.major, p.minor, zero)));
      set.push(below(p.major, p.minor + one, zero));
    }
    return;
  }
  var major = p.major;
  var minor = if (p.minorWild) zero else p.minor;
  match (relation) {
    case Relation.Greater: {
      // Above every version the wildcard covers.
      if (p.minorWild) {
        major = major + one;
        minor = zero;
      } else {
        minor = minor + one;
      }
      set.push(atLeast(version(major, minor, zero)));
    }
    case Relation.GreaterOrEqual: {
      set.push(atLeast(version(major, minor, zero)));
    }
    case Relation.LessOrEqual: {
      // Up to and with every version the wildcard covers.
      if (p.minorWild) {
        major = major + one;
      } else {
        minor = minor + one;
      }
      set.push(below(major, minor, zero));
    }
    case Relation.Less: {
      set.push(below(major, minor, zero));
    }
    case Relation.Equal: {}
  }
}

/**
 * `1.2.3 - 2.3.4` is `>=1.2.3 <=2.3.4`. A partial version on the left
 * starts at its lowest version, and one on the right ends before the next
 * one it does not cover: `1.2.3 - 2.3` is `>=1.2.3 <2.4.0-0`.
 */
function hyphen(from: Partial, to: Partial, set: GrowableArray<Comparator>): void {
  let zero = 0 as i64;
  let one = 1 as i64;
  if (!from.majorWild) {
    if (from.minorWild) {
      set.push(atLeast(version(from.major, zero, zero)));
    } else if (from.patchWild) {
      set.push(atLeast(version(from.major, from.minor, zero)));
    } else {
      set.push(atLeast(new Version(from.major, from.minor, from.patch, from.prerelease)));
    }
  }
  if (!to.majorWild) {
    if (to.minorWild) {
      set.push(below(to.major + one, zero, zero));
    } else if (to.patchWild) {
      set.push(below(to.major, to.minor + one, zero));
    } else {
      set.push(new Comparator(Relation.LessOrEqual, new Version(to.major, to.minor, to.patch, to.prerelease)));
    }
  }
}

/**
 * Reads a partial version of `text`, after an optional `v` or `=`: one to
 * three numbers or wildcards, and after three numbers a pre-release and
 * build metadata, which a range ignores.
 */
function parsePartial(word: String, text: String): Partial {
  var start = 0;
  while (start < word.length && (word.getByteAt(start) == 118 || word.getByteAt(start) == 61)) { // 'v', '='
    start += 1;
  }
  var coreEnd = word.length;
  var buildStart = word.length;
  for (var i = start; i < word.length; i += 1) {
    let b = word.getByteAt(i);
    if (b == 43 && buildStart == word.length) { // '+'
      buildStart = i;
      if (coreEnd == word.length) {
        coreEnd = i;
      }
    }
    if (b == 45 && coreEnd == word.length) { // '-'
      coreEnd = i;
    }
  }
  let core = word.sliceBytes(start, coreEnd);
  if (core.length == 0) {
    throw new VersionError(`'${text}' is not a range: '${word}' has no version`);
  }
  let parts = core.split('.');
  if (parts.length > 3) {
    throw new VersionError(`'${text}' is not a range: '${word}' has more than three numbers`);
  }
  let numbers = new FixedArray<i64>(3, WILD);
  var sawWild = false;
  for (var i = 0; i < parts.length; i += 1) {
    let part = parts[i];
    if (part == 'x' || part == 'X' || part == '*') {
      sawWild = true;
    } else if (sawWild) {
      throw new VersionError(`'${text}' is not a range: '${word}' has a number after a wildcard`);
    } else {
      numbers[i] = parseVersionNumber(part, text);
    }
  }
  var prerelease = none();
  if (coreEnd < word.length) {
    if (parts.length != 3 || sawWild) {
      throw new VersionError(`'${text}' is not a range: '${word}' has a pre-release or build without three numbers`);
    }
    if (coreEnd < buildStart) {
      prerelease = parsePrerelease(word.sliceBytes(coreEnd + 1, buildStart), text);
    }
    if (buildStart < word.length) {
      parseBuild(word.sliceBytes(buildStart + 1, word.length), text);
    }
  }
  return new Partial(numbers[0], numbers[1], numbers[2], prerelease);
}
none
VersionPublishedDependenciesApproved by
0.0.1-preview.1 2026-11-19 none