semver 6.1.2 → 7.0.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # changes log
 
+## 6.3.0
+
+* Expose the token enum on the exports
+
+## 6.2.0
+
+* Coerce numbers to strings when passed to semver.coerce()
+* Add `rtl` option to coerce from right to left
+
+## 6.1.3
+
+* Handle X-ranges properly in includePrerelease mode
+
+## 6.1.2
+
+* Do not throw when testing invalid version strings
+
+## 6.1.1
+
+* Add options support for semver.coerce()
+* Handle undefined version passed to Range.test
+
+## 6.1.0
+
+* Add semver.compareBuild function
+* Support `*` in semver.intersects
+
 ## 6.0
 
 * Fix `intersects` logic.

package/README.md

@@ -60,6 +60,12 @@ Options:
         Coerce a string into SemVer if possible
         (does not imply --loose)
 
+--rtl
+        Coerce version strings right to left
+
+--ltr
+        Coerce version strings left to right (default)
+
 Program exits successfully if any valid version satisfies
 all supplied ranges, and prints all satisfying versions.
 
@@ -399,25 +405,34 @@ range, use the `satisfies(version, range)` function.
 
 ### Coercion
 
-* `coerce(version)`: Coerces a string to semver if possible
-
-This aims to provide a very forgiving translation of a non-semver
-string to semver. It looks for the first digit in a string, and
-consumes all remaining characters which satisfy at least a partial semver
-(e.g., `1`, `1.2`, `1.2.3`) up to the max permitted length (256 characters).
-Longer versions are simply truncated (`4.6.3.9.2-alpha2` becomes `4.6.3`).
-All surrounding text is simply ignored (`v3.4 replaces v3.3.1` becomes `3.4.0`).
-Only text which lacks digits will fail coercion (`version one` is not valid).
-The maximum  length for any semver component considered for coercion is 16 characters;
-longer components will be ignored (`10000000000000000.4.7.4` becomes `4.7.4`).
-The maximum value for any semver component is `Integer.MAX_SAFE_INTEGER || (2**53 - 1)`;
-higher value components are invalid (`9999999999999999.4.7.4` is likely invalid).
+* `coerce(version, options)`: Coerces a string to semver if possible
+
+This aims to provide a very forgiving translation of a non-semver string to
+semver. It looks for the first digit in a string, and consumes all
+remaining characters which satisfy at least a partial semver (e.g., `1`,
+`1.2`, `1.2.3`) up to the max permitted length (256 characters).  Longer
+versions are simply truncated (`4.6.3.9.2-alpha2` becomes `4.6.3`).  All
+surrounding text is simply ignored (`v3.4 replaces v3.3.1` becomes
+`3.4.0`).  Only text which lacks digits will fail coercion (`version one`
+is not valid).  The maximum  length for any semver component considered for
+coercion is 16 characters; longer components will be ignored
+(`10000000000000000.4.7.4` becomes `4.7.4`).  The maximum value for any
+semver component is `Number.MAX_SAFE_INTEGER || (2**53 - 1)`; higher value
+components are invalid (`9999999999999999.4.7.4` is likely invalid).
+
+If the `options.rtl` flag is set, then `coerce` will return the right-most
+coercible tuple that does not share an ending index with a longer coercible
+tuple.  For example, `1.2.3.4` will return `2.3.4` in rtl mode, not
+`4.0.0`.  `1.2.3/4` will return `4.0.0`, because the `4` is not a part of
+any other overlapping SemVer tuple.
 
 ### Clean
 
 * `clean(version)`: Clean a string to be a valid semver if possible
 
-This will return a cleaned and trimmed semver version. If the provided version is not valid a null will be returned. This does not work for ranges. 
+This will return a cleaned and trimmed semver version. If the provided
+version is not valid a null will be returned. This does not work for
+ranges.
 
 ex.
 * `s.clean(' = v 2.1.5foo')`: `null`
@@ -428,3 +443,57 @@ ex.
 * `s.clean('  =v2.1.5')`: `2.1.5`
 * `s.clean('      2.1.5   ')`: `'2.1.5'`
 * `s.clean('~1.0.0')`: `null`
+
+## Exported Modules
+
+<!--
+TODO: Make sure that all of these items are documented (classes aren't,
+eg), and then pull the module name into the documentation for that specific
+thing.
+-->
+
+You may pull in just the part of this semver utility that you need, if you
+are sensitive to packing and tree-shaking concerns.  The main
+`require('semver')` export uses getter functions to lazily load the parts
+of the API that are used.
+
+The following modules are available:
+
+* `require('semver')`
+* `require('semver/classes')`
+* `require('semver/classes/comparator')`
+* `require('semver/classes/range')`
+* `require('semver/classes/semver')`
+* `require('semver/functions/clean')`
+* `require('semver/functions/cmp')`
+* `require('semver/functions/coerce')`
+* `require('semver/functions/compare')`
+* `require('semver/functions/compare-build')`
+* `require('semver/functions/compare-loose')`
+* `require('semver/functions/diff')`
+* `require('semver/functions/eq')`
+* `require('semver/functions/gt')`
+* `require('semver/functions/gte')`
+* `require('semver/functions/inc')`
+* `require('semver/functions/lt')`
+* `require('semver/functions/lte')`
+* `require('semver/functions/major')`
+* `require('semver/functions/minor')`
+* `require('semver/functions/neq')`
+* `require('semver/functions/parse')`
+* `require('semver/functions/patch')`
+* `require('semver/functions/prerelease')`
+* `require('semver/functions/rcompare')`
+* `require('semver/functions/rsort')`
+* `require('semver/functions/satisfies')`
+* `require('semver/functions/sort')`
+* `require('semver/functions/valid')`
+* `require('semver/ranges/gtr')`
+* `require('semver/ranges/intersects')`
+* `require('semver/ranges/ltr')`
+* `require('semver/ranges/max-satisfying')`
+* `require('semver/ranges/min-satisfying')`
+* `require('semver/ranges/min-version')`
+* `require('semver/ranges/outside')`
+* `require('semver/ranges/to-comparators')`
+* `require('semver/ranges/valid')`

package/bin/semver.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+// Standalone semver comparison program.
+// Exits successfully and prints matching version(s) if
+// any supplied version is valid and passes all tests.
+
+const argv = process.argv.slice(2)
+
+let versions = []
+
+const range = []
+
+let inc = null
+
+const version = require('../package.json').version
+
+let loose = false
+
+let includePrerelease = false
+
+let coerce = false
+
+let rtl = false
+
+let identifier
+
+const semver = require('../')
+
+let reverse = false
+
+const options = {}
+
+const main = () => {
+  if (!argv.length) return help()
+  while (argv.length) {
+    let a = argv.shift()
+    const indexOfEqualSign = a.indexOf('=')
+    if (indexOfEqualSign !== -1) {
+      a = a.slice(0, indexOfEqualSign)
+      argv.unshift(a.slice(indexOfEqualSign + 1))
+    }
+    switch (a) {
+      case '-rv': case '-rev': case '--rev': case '--reverse':
+        reverse = true
+        break
+      case '-l': case '--loose':
+        loose = true
+        break
+      case '-p': case '--include-prerelease':
+        includePrerelease = true
+        break
+      case '-v': case '--version':
+        versions.push(argv.shift())
+        break
+      case '-i': case '--inc': case '--increment':
+        switch (argv[0]) {
+          case 'major': case 'minor': case 'patch': case 'prerelease':
+          case 'premajor': case 'preminor': case 'prepatch':
+            inc = argv.shift()
+            break
+          default:
+            inc = 'patch'
+            break
+        }
+        break
+      case '--preid':
+        identifier = argv.shift()
+        break
+      case '-r': case '--range':
+        range.push(argv.shift())
+        break
+      case '-c': case '--coerce':
+        coerce = true
+        break
+      case '--rtl':
+        rtl = true
+        break
+      case '--ltr':
+        rtl = false
+        break
+      case '-h': case '--help': case '-?':
+        return help()
+      default:
+        versions.push(a)
+        break
+    }
+  }
+
+  const options = { loose: loose, includePrerelease: includePrerelease, rtl: rtl }
+
+  versions = versions.map((v) => {
+    return coerce ? (semver.coerce(v, options) || { version: v }).version : v
+  }).filter((v) => {
+    return semver.valid(v)
+  })
+  if (!versions.length) return fail()
+  if (inc && (versions.length !== 1 || range.length)) { return failInc() }
+
+  for (let i = 0, l = range.length; i < l; i++) {
+    versions = versions.filter((v) => {
+      return semver.satisfies(v, range[i], options)
+    })
+    if (!versions.length) return fail()
+  }
+  return success(versions)
+}
+
+
+const failInc = () => {
+  console.error('--inc can only be used on a single version with no range')
+  fail()
+}
+
+const fail = () => process.exit(1)
+
+const success = () => {
+  const compare = reverse ? 'rcompare' : 'compare'
+  versions.sort((a, b) => {
+    return semver[compare](a, b, options)
+  }).map((v) => {
+    return semver.clean(v, options)
+  }).map((v) => {
+    return inc ? semver.inc(v, inc, options, identifier) : v
+  }).forEach((v, i, _) => { console.log(v) })
+}
+
+const help = () => console.log(
+`SemVer ${version}
+
+A JavaScript implementation of the https://semver.org/ specification
+Copyright Isaac Z. Schlueter
+
+Usage: semver [options] <version> [<version> [...]]
+Prints valid versions sorted by SemVer precedence
+
+Options:
+-r --range <range>
+        Print versions that match the specified range.
+
+-i --increment [<level>]
+        Increment a version by the specified level.  Level can
+        be one of: major, minor, patch, premajor, preminor,
+        prepatch, or prerelease.  Default level is 'patch'.
+        Only one version may be specified.
+
+--preid <identifier>
+        Identifier to be used to prefix premajor, preminor,
+        prepatch or prerelease version increments.
+
+-l --loose
+        Interpret versions and ranges loosely
+
+-p --include-prerelease
+        Always include prerelease versions in range matching
+
+-c --coerce
+        Coerce a string into SemVer if possible
+        (does not imply --loose)
+
+--rtl
+        Coerce version strings right to left
+
+--ltr
+        Coerce version strings left to right (default)
+
+Program exits successfully if any valid version satisfies
+all supplied ranges, and prints all satisfying versions.
+
+If no satisfying versions are found, then exits failure.
+
+Versions are printed in ascending order, so supplying
+multiple versions to the utility will just sort them.`)
+
+main()

package/classes/comparator.js

@@ -0,0 +1,139 @@
+const ANY = Symbol('SemVer ANY')
+// hoisted class for cyclic dependency
+class Comparator {
+  static get ANY () {
+    return ANY
+  }
+  constructor (comp, options) {
+    if (!options || typeof options !== 'object') {
+      options = {
+        loose: !!options,
+        includePrerelease: false
+      }
+    }
+
+    if (comp instanceof Comparator) {
+      if (comp.loose === !!options.loose) {
+        return comp
+      } else {
+        comp = comp.value
+      }
+    }
+
+    debug('comparator', comp, options)
+    this.options = options
+    this.loose = !!options.loose
+    this.parse(comp)
+
+    if (this.semver === ANY) {
+      this.value = ''
+    } else {
+      this.value = this.operator + this.semver.version
+    }
+
+    debug('comp', this)
+  }
+
+  parse (comp) {
+    const r = this.options.loose ? re[t.COMPARATORLOOSE] : re[t.COMPARATOR]
+    const m = comp.match(r)
+
+    if (!m) {
+      throw new TypeError(`Invalid comparator: ${comp}`)
+    }
+
+    this.operator = m[1] !== undefined ? m[1] : ''
+    if (this.operator === '=') {
+      this.operator = ''
+    }
+
+    // if it literally is just '>' or '' then allow anything.
+    if (!m[2]) {
+      this.semver = ANY
+    } else {
+      this.semver = new SemVer(m[2], this.options.loose)
+    }
+  }
+
+  toString () {
+    return this.value
+  }
+
+  test (version) {
+    debug('Comparator.test', version, this.options.loose)
+
+    if (this.semver === ANY || version === ANY) {
+      return true
+    }
+
+    if (typeof version === 'string') {
+      try {
+        version = new SemVer(version, this.options)
+      } catch (er) {
+        return false
+      }
+    }
+
+    return cmp(version, this.operator, this.semver, this.options)
+  }
+
+  intersects (comp, options) {
+    if (!(comp instanceof Comparator)) {
+      throw new TypeError('a Comparator is required')
+    }
+
+    if (!options || typeof options !== 'object') {
+      options = {
+        loose: !!options,
+        includePrerelease: false
+      }
+    }
+
+    if (this.operator === '') {
+      if (this.value === '') {
+        return true
+      }
+      return new Range(comp.value, options).test(this.value)
+    } else if (comp.operator === '') {
+      if (comp.value === '') {
+        return true
+      }
+      return new Range(this.value, options).test(comp.semver)
+    }
+
+    const sameDirectionIncreasing =
+      (this.operator === '>=' || this.operator === '>') &&
+      (comp.operator === '>=' || comp.operator === '>')
+    const sameDirectionDecreasing =
+      (this.operator === '<=' || this.operator === '<') &&
+      (comp.operator === '<=' || comp.operator === '<')
+    const sameSemVer = this.semver.version === comp.semver.version
+    const differentDirectionsInclusive =
+      (this.operator === '>=' || this.operator === '<=') &&
+      (comp.operator === '>=' || comp.operator === '<=')
+    const oppositeDirectionsLessThan =
+      cmp(this.semver, '<', comp.semver, options) &&
+      (this.operator === '>=' || this.operator === '>') &&
+        (comp.operator === '<=' || comp.operator === '<')
+    const oppositeDirectionsGreaterThan =
+      cmp(this.semver, '>', comp.semver, options) &&
+      (this.operator === '<=' || this.operator === '<') &&
+        (comp.operator === '>=' || comp.operator === '>')
+
+    return (
+      sameDirectionIncreasing ||
+      sameDirectionDecreasing ||
+      (sameSemVer && differentDirectionsInclusive) ||
+      oppositeDirectionsLessThan ||
+      oppositeDirectionsGreaterThan
+    )
+  }
+}
+
+module.exports = Comparator
+
+const {re, t} = require('../internal/re')
+const cmp = require('../functions/cmp')
+const debug = require('../internal/debug')
+const SemVer = require('./semver')
+const Range = require('./range')

package/classes/index.js

@@ -0,0 +1,5 @@
+module.exports = {
+  SemVer: require('./semver.js'),
+  Range: require('./range.js'),
+  Comparator: require('./comparator.js')
+}