node logoHello everyone! This is the eleventh post in the node.js modules you should know about article series.

The first post was about dnode - the freestyle rpc library for node, the second was about optimist - the lightweight options parser for node, the third was about lazy - lazy lists for node, the fourth was about request - the swiss army knife of HTTP streaming, the fifth was about hashish - hash combinators library, the sixth was about read - easy reading from stdin, the seventh was about ntwitter - twitter api for node, the eighth was about socket.io that makes websockets and realtime possible in all browsers, the ninth was about redis - the best redis client API library for node, the tenth was on express - an insanely small and fast web framework for node.

Today I'll introduce you to a module called semver. Semver is the semantic versioner. Semver is written by Isaac Z. Schlueter, the author of npm. Semver is used in npm to handle all the node.js module versioning problems.

Here is an example of what it does:

semver.valid('1.2.3') // true
semver.valid('a.b.c') // false
semver.clean('  =v1.2.3   ') // '1.2.3'
semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true
semver.gt('1.2.3', '9.8.7')  // false
semver.lt('1.2.3', '9.8.7')  // true

The ordering of versions is done using the following algorithm - given two versions and asked to find the greater of the two:

  • If the majors are numerically different, then take the one with a bigger major number. For example, 2.3.4 > 1.3.4.
  • If the minors are numerically different, then take the one with the bigger minor number. For example, 2.3.4 > 2.2.4.
  • If the patches are numerically different, then take the one with the bigger patch number. For example, 2.3.4 > 2.3.3.
  • If only one of them has a build number, then take the one with the build number. For example, 2.3.4-0 > 2.3.4.
  • If they both have build numbers, and the build numbers are numerically different, then take the one with the bigger build number. For example, 2.3.4-10 > 2.3.4-9.
  • If only one of them has a tag, then take the one without the tag. For example, 2.3.4 > 2.3.4-beta.
  • If they both have tags, then take the one with the lexicographically larger tag. For example, 2.3.4-beta > 2.3.4-alpha.
  • At this point, they're equal.

Semver supports the following ranges and styles:

  • >1.2.3 means greater than a specific version.
  • <1.2.3 means less than a specific version.
  • 1.2.3 - 2.3.4 means >=1.2.3 <=2.3.4.
  • ~1.2.3 means >=1.2.3 <1.3.0.
  • ~1.2 means >=1.2.0 <2.0.0.
  • ~1 means >=1.0.0 <2.0.0.
  • 1.2.x means >=1.2.0 <1.3.0.
  • 1.x means >=1.0.0 <2.0.0.

Ranges can be joined with either a space (which implies "and") or a || (which implies "or").

Semver supports the following functions:

  • valid(v) - return the parsed version, or null if it's not valid.
  • inc(v, release) - return the version incremented by the release type (major, minor, patch, or build), or null if it's not valid.

Semver supports the following comparisons:

  • gt(v1, v2) - v1 > v2.
  • gte(v1, v2) - v1 >= v2.
  • lt(v1, v2) - v1 < v2.
  • lte(v1, v2) - v1 <= v2.
  • eq(v1, v2) - v1 == v2.
  • neq(v1, v2) - v1 != v2.
  • cmp(v1, comparator, v2) - pass in a comparison string, and it'll call the corresponding function above. "===" and "!==" do simple string comparison, but are included for completeness. Throws if an invalid comparison string is provided.
  • compare(v1, v2) - return 0 if v1 == v2, or 1 if v1 is greater, or -1 if v2 is greater. Sorts in ascending order if passed to Array.sort().
  • rcompare(v1, v2) - the reverse of compare. Sorts an array of versions in descending order when passed to Array.sort().

Semver supports the following range functions:

  • validRange(range) - Return the valid range or null if it's not valid.
  • satisfies(version, range) - return true if the version satisfies the range.
  • maxSatisfying(versions, range) - return the highest version in the list that satisfies the range, or null if none of them do.

You can install semver through npm as always:

npm install semver

Semver on GitHub: https://github.com/isaacs/node-semver.