Fork me on GitHub

11. Node.js модули, о которых вы должны знать: semver

Всем приветы! Это одиннадцатый пост из серии Node.js модули, о которых вы должны знать.

Первый пост был про dnode — фристайл RPC библиотеку для node.js. Второй пост был посвящен optimist — легковесному парсеру командной строки для node.js. Третий был про lazy — ленивые списки для node.js. Четвертый — про request — швецарский нож HTTP стримминга. Пятый был про hashish — библиотеку для работы с хэшами. Шестой пост касался read — обертки для чтения со стандратного потока ввода (stdin). Седьмой был про ntwitter — twitter API для node.js. Восьмой пост был посвящён socket.io, который делает возможным websockets во всех браузерах. Девятый пост касался redis — лучшего redis-клиента для node.js. Десятый пост был про express — небольшой и быстрый веб фреймворк.

Сегодня я хочу представить модуль semver. Semver — это семантический версионер. Автором модуля является TJ Holowaychuk. Semver используется в модуле npm и отвечает за работу с версиями всех модулей для node.js.

Вот пример того, что он умеет:

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

Упорядочивание версий реализуется с помощью следующего алгоритма. Даются две версии и требуется найти большую из них:

  • если главные числа (majors) различаются, то выбирается та версия, у которой главное число больше. Например: 2.3.4 > 1.3.4
  • если второстепенные числа (minors) различаются, то выбирается та версия, у которой второстепенное число больше. Например: 2.3.4 > 2.2.4.
  • если номера патчей различаются, то выбирается та версия, у которой номер патча больше. Например: 2.3.4 > 2.3.3 .
  • если только у одной из версий есть номер сборки (build number), то выбирается версия с номер сборки. Например: 2.3.4-0 > 2.3.4.
  • если обе версии имеют номер сборки и номера сборок отличаются, то выбирается та версия, у которой номер сборки больше. Например: 2.3.4-10 > 2.3.4-9.
  • если у одной из версий есть тэг, то выбирается версия без тэга. Например: 2.3.4 > 2.3.4-beta.
  • если обе версии имеют тэг, то выбирается та версия, у которой тэг лексикографически больше. Например: 2.3.4-beta > 2.3.4-alpha.
  • а вот тут они уже равны.

Semver поддерживает следующие диапазоны и стили:

  • >1.2.3 — отобрать больше, чем указанная версия
  • <1.2.3 — отобрать меньше, чем указанная версия
  • 1.2.3 - 2.3.4 эквивалентно >=1.2.3 <=2.3.4
  • ~1.2.3 эквивалентно >=1.2.3 <1.3.0
  • ~1.2 эквивалентно >=1.2.0 <2.0.0
  • ~1 эквивалентно >=1.0.0 <2.0.0
  • 1.2.x эквивалентно >=1.2.0 <1.3.0
  • 1.x эквивалентно >=1.0.0 <2.0.0

Диапазоны могут быть объединены либо с помощью пробела, что интерпретируется как логическое «И», либо с помощью ||, что интерпретируется как логическое «ИЛИ».

Semver поддерживает следующие функции:

  • valid(v) — возвращает разобранную версию или null, если версия не валидна
  • inc(v, release) — возвращает версию увеличенную на единицу в терминах указанного типа релиза (major, minor, patch, build) или null, если версия не валидна

Semver поддерживает следующие операции сравнения:

  • 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) — в качестве comparator ожидается строка, соответсвующая одной из функций, описанных выше. === и !== выполняют простое сравнение строк, но включены для полноты картины. Если указан не поддерживаемый оператор, то поднимается исключение.
  • compare(v1, v2) — возвращает 0, если v1 == v2; 1, если v1 больше; -1, если v2 больше. Сортирует по возрастанию, если передается в Array.sort().
  • rcompare(v1, v2) — инвариант функции compare. Сортирует массив версий в убывающем порядке, если передать в Array.sort().

Semver поддерживает следующие функции для работы с диапазонами:

  • validRange(range) — возвращает валидный диапазон или null, если не валиден
  • satisfies(version, range) — возвращает true, если версия version соответствует заданному диапазону range
  • maxSatisfying(versions, range) — возвращает наибольшую версию из списка versions, которая соответствует диапазону range, или null

Как всегда, установить semver можно с помощью npm:

npm install semver