Calver NPM | npm.io

node-calver | The Calendar Versioner

The calver parser for node. 📆 🚀

NPM npm bundle size npm

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 calver

Usage

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.0

The 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.1

To create an initial version, just leave the version field empty:

const version = calver.inc(format, '', 'calendar') // 2021.1.0.0

To 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.1

Validation

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 = true

Tests

npm run test

Note 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 🐬