This article is part of the article series "Node.JS Modules You Should Know About."
<- previous article next article ->
node logo

Hello 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 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'1.2.3', '9.8.7')  // false'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:

Sponsor this blog series!

Doing a node.js company and want your ad to appear in the series? The ad will go out to 14,000 rss subscribers, 7,000 email subscribers, and it will get viewed by thousands of my blog visitors! Email me and we'll set it up!


If you love these articles, subscribe to my blog for more, follow me on Twitter to find about my adventures, and watch me produce code on GitHub!

This article is part of the article series "Node.JS Modules You Should Know About."
<- previous article next article ->


Aaron Lampros Permalink
December 15, 2011, 18:11

Thanks - really great writeup!

Just a heads up - you have Isaac's name misspelled. Should be Isaac Z. Schlueter. (I'm totally used to seeing "isaacs" too, I know)

December 18, 2011, 14:08

Thanks for reporting the misspelling. I corrected it.

Leave a new comment

(why do I need your e-mail?)

(Your twitter handle, if you have one.)

Type the word "server_295": (just to make sure you're a human)

Please preview the comment before submitting to make sure it's OK.