node-calver | The Calendar Versioner
The calver parser for node.
Why
Yes, semantic versioning isn't the only versioning scheme. Software developers are versioning their software for decades and there are various schemes. Calendar versioning is one of them. It has a bit more flexible when compared to semver. It's based on dates and more human-readable. Personally, using it in my frontend projects and it's working pretty well.
Implementation
There is no standart (as much in semver) about the implementation of calendar versioning. The introduction in calver.org inspired me a lot and I build the API flexible enough for user to create versions in various formats.
Install
This is node.js module and compiled for cjs and es module environments. There is no dependency and it can be installed via npm:
npm i calverUsage
Require or import:
const calver = require('calver')
// or
import calver from 'calver'If your node < 14 then:
const calver = require('calver/node/lts')
// or
import calver from 'calver/node/lts'Unlike semver, calver needs a format to deal with version strings.
Choose Format
A format is a recipe for calver to decide what will the next version be. In semver, format is fixed (MAJOR.MINOR.PATCH.MODIFIER) but in calver you create your own version format by using available tags.
| Tag | Type | Description |
|---|---|---|
| YYYY | calendar | Zero based year with max 4 digit. |
| YY | calendar | Zero based year with max 2 digit. |
| 0Y | calendar | Zero padded 2 digit year. |
| MM | calendar | Zero based month with max 2 digit. |
| 0M | calendar | Zero padded 2 digit month. |
| WW | calendar | Zero based week of the year with max 2 digit. |
| 0W | calendar | Zero padded 2 digit week of the year. |
| DD | calendar | Zero based day of the month with max 2 digit. |
| 0D | calendar | Zero padded 2 digit day of the month. |
| MAJOR | semantic | Auto-increment number for breaking changes. |
| MINOR | semantic | Auto-increment number for new features. |
| PATCH | semantic | Auto-increment number for bug fixes. |
| DEV | modifier | Auto-increment number for dev updates. |
| ALPHA | modifier | Auto-increment number for alpha updates. |
| BETA | modifier | Auto-increment number for beta updates. |
| RC | modifier | Auto-increment number for release candidate updates. |
You can combine any of these tags while choosing a format except modifiers. Let's say we choose:
const format = 'yyyy.mm.minor.patch'and create an initial release:
// assuming current date is 2021.01
const version = calver.inc(format, '', 'calendar')
// version = 2021.1.0.0The second argument is previous version string that we would like to increment but left empty to show to create an initial version.
The third argument is the level of the increment operation. level might be one of the following:
| Level | Type | Description |
|---|---|---|
| calendar | calendar | Updates calendar tags to the current date and removes modifier if it exist. |
| major | semantic | Increments the major tag, resets minor, patch tags and removes modifier if it exist. |
| minor | semantic | Increments the minor tag, resets the patch tag and removes modifier if it exist. |
| patch | semantic | Increments tha patch tag and removes modifier if it exist. |
| dev | modifier | Increments the dev tag. |
| alpha | modifier | Increments the alpha tag. |
| beta | modifier | Increments the beta tag. |
| rc | modifier | Increments the rc tag. |
| calendar.[dev,alpha,beta,rc] | composite | Updates calendar tags and adds specified modifier tag. |
| major.[dev,alpha,beta,rc] | composite | Increments the major tag and adds specified modifier tag. |
| minor.[dev,alpha,beta,rc] | composite | Increments the minor tag and adds specified modifier tag. |
| patch.[dev,alpha,beta,rc] | composite | Increments the patch tag and adds specified modifier tag. |
Increment
Let's make some more updates:
// assuming current date is 2021.01
const version = calver.inc(format, '2021.1.0.0', 'minor.dev')
// version = 2021.1.1.0-dev.0
const version = calver.inc(format, '2021.1.1.0-dev.0', 'dev')
// version = 2021.1.1.0-dev.1
const version = calver.inc(format, '2021.1.1.0-dev.1', 'dev')
// version = 2021.1.1.0-dev.2
const version = calver.inc(format, '2021.1.1.0-dev.2', 'alpha')
// version = 2021.1.1.0-alpha.0
const version = calver.inc(format, '2021.1.1.0-alpha.0', 'alpha')
// version = 2021.1.1.0-alpha.1
const version = calver.inc(format, '2021.1.1.0-alpha.1', 'minor')
// version = 2021.1.1.0
const version = calver.inc(format, '2021.1.1.0', 'minor')
// version = 2021.1.2.0
const version = calver.inc(format, '2021.1.2.0', 'patch')
// version = 2021.1.2.1To create an initial version, just leave the version field empty:
const version = calver.inc(format, '', 'calendar') // 2021.1.0.0To increment based on both calendar and semantic tags:
const version = calver.inc('yy.mm.minor', '', 'calendar.minor') // 2021.1.0
const version = calver.inc('yy.mm.minor', '2021.1.0', 'calendar.minor') // 2021.1.1Validation
Test the input if it is valid against a format:
calver.isValid('yyyy.mm.0w', '2020.6.1') === false // because 0W can't be "1", it should be "01"
calver.isValid('yyyy.mm.minor.patch', '0.0.0.1') === false // because YYYY and MM can't be "0"Timezone
calver's default timezone is UTC. If you want to use local timezone, set useLocalTime.
calver.useLocalTime = trueTests
npm run testNote that the Date.now() function replaced with a fixed value in tests so we can reliably run tests whenever we want.
Note
Software versioning is hard. None of the schemes are working perfectly and currently it highly depends on the how you are going to use. See this article written by donald stufft.
Version management of this repository done by releaser
Thanks for watching
