node-calver

Calendar based software versioning library as node.js module and with cli support. 📅

What is calendar based versioning?

It's a way of tagging software state based on in combination of a chosen calendar tags such as YYYY, MM, DD. The chosen tags convey the message of how frequently the software gets major updates, to the user. It doesn't tell anything about breaking changes (there is git-diff for that) but it tells when the next major release will come.

I recommend this article by Donald Stufft to read more about versioning softwares and this website by Mahmoud Hashemi to learn more about calendar versioning.

What does it look like?

The format consist of two parts. The calendar part and the minor changes counter. The calendar part describes software's release cycle. The minor part is just a counter over the main release. Take 2024-4.104 for example; the year and the month separated by a dash and the minor counter separated by a dot. So the general template for the format is YYYY-MM-DD.MINOR. One might choose:

• YYYY for yearly release cycle
• YYYY-MM for monthly release cycle
• YYYY-WW for weekly release cycle
• YYYY-MM-DD for daily release cycle

The releases sent before the next release time period, counts as minor changes and therefore it increments the minor part of the version.

Prerequisites

• What is your release cycle? Decide how frequently you will release your software. Excluding minor changes such as security fixes or other kind of features and fixes.

Install

npm i -D calver
# or
pnpm add -D calver

Usage

The library can be used both as a node.js module and a cli app. Both usages documented below per feature.

Library defaults

There are some defaults to keep in mind while using node-calver.

• Minor counter is 0 by default and it's hidden from the output if it's zero.
• The values of calendar tags computed based on UTC time.
• The year always exists in the output and can't be omitted. The other tags is up to a user.
• When month, week or day isn't specified, they are considered as zero and this is important when comparing dates.

Cycles

Finds the next version based on release cycle.

import * as calver from 'calver'

calver.cycle('2024-4.204')

calver 2024-4.204

Depending on the date the code above executed, the output will be 2024-4.205, 2024-5 or 2024-[current month].

It's capable to understand the format you chose with one exception.

calver.cycle('2024.204')

calver 2024.204

Outputs 2024.205 or [current year].

The full year, month and day cycle:

calver.cycle('2024-4-16.204')

calver 2024-4-16.204

Outputs 2024-4-16.205 or [current date as YYYY-MM-DD].

And the exception is weeks. A cycle option needs to be passed for weekly release cycles:

calver.cycle('2024-32.204', { cycle: 'week' })

calver 2024-32.204 --cycle week # or -c week

Outputs 2024-32.205 or 2024-[current week of the year].

Minor releases

A minor method just increments the minor portion of the version and leaves the date portion as it is.

calver.minor('2024') // outputs 2024.1

calver 2024 --minor # outputs 2024.1

calver.minor('2024.204') // outputs 2024.205

calver 2024.204 --minor # outputs 2024.205

calver.minor('2024-4-16.204') // outputs 2024-4-16.205

calver 2024-4-16.204 --minor # outputs 2024-4-16.205

and so on.

Create an initial version

calver.initial({ cycle: 'month' })

calver initial --cycle month

Outputs [current year]-[current month].

Valid

calver.valid('2024-4.123')
// provide cycle for more strict check
calver.valid('2024-4.123', { cycle: 'month' })

Outputs a boolean.

calver valid 2024-4.123
# or specify --cycle flag for more strict check
calver valid --cycle month

Outputs the exact version string or exits with error.

Comparison

// newer than
calver.nt('2024-4-20', '2024-4-19') // true
calver.nt('2024-4-20', '2024') // true
calver.nt('2024', '2024-4-20') // false

// older than
calver.ot('2024-4-20', '2024-4-19') // false
calver.ot('2024-4-20', '2024') // false
calver.ot('2024', '2024-4-20') // true

// speciy cycle if you use weeks
calver.nt('2024-32', '2024-30', { cycle: 'week' }) // true

Returns a boolean

calver nt 2024-4-20 2024-4-19
calver ot 2024-4-20 2024-4-19
calver nt 2024-32 2024-30 --cycle week

Outputs the exact version string or exits with error.

Prefix, suffix and clean

Simple helper methods that might be useful in your versioning processes.

calver.prefix('2024-4.123') // outputs v2024-4.123
calver.prefix('2024-4.123', 'v') // outputs v2024-4.123

calver.suffix('2024-4.123', '-something') // outputs 2024-4.123-something

calver.clean(' =v2024-4.123-something ') // 2024-4.123

They work same as in the module api:

calver prefix 2024-4.123
calver prefix 2024-4.123 --prefix v
calver suffix 2024-4.123 --suffix something
calver clean " =v2024-4.123-something "

Contributing

If you're interested in contributing, read the CONTRIBUTING.md first, please.

Version management of this repository done by releaser 🚀

Thanks for watching 🐬