{"id":22305695,"url":"https://github.com/muratgozel/node-calver","last_synced_at":"2025-07-29T04:32:39.182Z","repository":{"id":42582130,"uuid":"264173858","full_name":"muratgozel/node-calver","owner":"muratgozel","description":"Calendar based software versioning library as node.js module and with cli support. 📅","archived":false,"fork":false,"pushed_at":"2024-05-21T12:23:19.000Z","size":332,"stargazers_count":29,"open_issues_count":9,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-11-09T18:08:59.720Z","etag":null,"topics":["calendar-versioning","calver","software-versioning","versioning"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/muratgozel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"patreon":"muratgozel"}},"created_at":"2020-05-15T11:15:47.000Z","updated_at":"2024-10-16T14:11:12.000Z","dependencies_parsed_at":"2024-05-21T12:28:13.321Z","dependency_job_id":"c7d6eb53-c0ad-4f89-8c44-3b7f1fdc204b","html_url":"https://github.com/muratgozel/node-calver","commit_stats":{"total_commits":32,"total_committers":5,"mean_commits":6.4,"dds":0.375,"last_synced_commit":"562ac55ddf1d5f61d7f3b3d3078807fb187e7f9f"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muratgozel%2Fnode-calver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muratgozel%2Fnode-calver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muratgozel%2Fnode-calver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muratgozel%2Fnode-calver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/muratgozel","download_url":"https://codeload.github.com/muratgozel/node-calver/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227981888,"owners_count":17850920,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["calendar-versioning","calver","software-versioning","versioning"],"created_at":"2024-12-03T19:12:48.082Z","updated_at":"2024-12-03T19:12:48.668Z","avatar_url":"https://github.com/muratgozel.png","language":"TypeScript","funding_links":["https://patreon.com/muratgozel","https://patreon.com/muratgozel?utm_medium=organic\u0026utm_source=github_repo\u0026utm_campaign=github\u0026utm_content=join_link"],"categories":[],"sub_categories":[],"readme":"# node-calver\n\nCalendar based software versioning library as node.js module and with cli support. 📅\n\n## What is calendar based versioning?\n\nIt'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](https://git-scm.com/docs/git-diff) for that) but it tells when the next major release will come.\n\nI recommend [this article by Donald Stufft](https://caremad.io/posts/2016/02/versioning-software/) to read more about versioning softwares and [this website by Mahmoud Hashemi](https://calver.org) to learn more about calendar versioning.\n\n## What does it look like?\n\nThe 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:\n\n-   YYYY for yearly release cycle\n-   YYYY-MM for monthly release cycle\n-   YYYY-WW for weekly release cycle\n-   YYYY-MM-DD for daily release cycle\n\nThe releases sent before the next release time period, counts as minor changes and therefore it increments the minor part of the version.\n\n## Prerequisites\n\n-   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.\n\n## Install\n\n```sh\nnpm i -D calver\n# or\npnpm add -D calver\n```\n\n## Usage\n\nThe library can be used both as a node.js module and a cli app. Both usages documented below per feature.\n\n### Library defaults\n\nThere are some defaults to keep in mind while using node-calver.\n\n-   Minor counter is 0 by default and it's hidden from the output if it's zero.\n-   The values of calendar tags computed based on UTC time.\n-   The year always exists in the output and can't be omitted. The other tags is up to a user.\n-   When month, week or day isn't specified, they are considered as zero and this is important when comparing dates.\n\n### Cycles\n\nFinds the next version based on release cycle.\n\n```ts\nimport * as calver from 'calver'\n\ncalver.cycle('2024-4.204')\n```\n\n```sh\ncalver 2024-4.204\n```\n\nDepending on the date the code above executed, the output will be `2024-4.205`, `2024-5` or `2024-[current month]`.\n\nIt's capable to understand the format you chose with one exception.\n\n```ts\ncalver.cycle('2024.204')\n```\n\n```sh\ncalver 2024.204\n```\n\nOutputs `2024.205` or `[current year]`.\n\nThe full year, month and day cycle:\n\n```ts\ncalver.cycle('2024-4-16.204')\n```\n\n```sh\ncalver 2024-4-16.204\n```\n\nOutputs `2024-4-16.205` or `[current date as YYYY-MM-DD]`.\n\nAnd the exception is weeks. A cycle option needs to be passed for weekly release cycles:\n\n```ts\ncalver.cycle('2024-32.204', { cycle: 'week' })\n```\n\n```sh\ncalver 2024-32.204 --cycle week # or -c week\n```\n\nOutputs `2024-32.205` or `2024-[current week of the year]`.\n\n### Minor releases\n\nA minor method just increments the minor portion of the version and leaves the date portion as it is.\n\n```ts\ncalver.minor('2024') // outputs 2024.1\n```\n\n```sh\ncalver 2024 --minor # outputs 2024.1\n```\n\n```ts\ncalver.minor('2024.204') // outputs 2024.205\n```\n\n```sh\ncalver 2024.204 --minor # outputs 2024.205\n```\n\n```ts\ncalver.minor('2024-4-16.204') // outputs 2024-4-16.205\n```\n\n```sh\ncalver 2024-4-16.204 --minor # outputs 2024-4-16.205\n```\n\nand so on.\n\n### Create an initial version\n\n```ts\ncalver.initial({ cycle: 'month' })\n```\n\n```sh\ncalver initial --cycle month\n```\n\nOutputs `[current year]-[current month]`.\n\n### Valid\n\n```ts\ncalver.valid('2024-4.123')\n// provide cycle for more strict check\ncalver.valid('2024-4.123', { cycle: 'month' })\n```\n\nOutputs a `boolean`.\n\n```sh\ncalver valid 2024-4.123\n# or specify --cycle flag for more strict check\ncalver valid --cycle month\n```\n\nOutputs the exact version string or exits with error.\n\n### Comparison\n\n```ts\n// newer than\ncalver.nt('2024-4-20', '2024-4-19') // true\ncalver.nt('2024-4-20', '2024') // true\ncalver.nt('2024', '2024-4-20') // false\n\n// older than\ncalver.ot('2024-4-20', '2024-4-19') // false\ncalver.ot('2024-4-20', '2024') // false\ncalver.ot('2024', '2024-4-20') // true\n\n// speciy cycle if you use weeks\ncalver.nt('2024-32', '2024-30', { cycle: 'week' }) // true\n```\n\nReturns a `boolean`\n\n```sh\ncalver nt 2024-4-20 2024-4-19\ncalver ot 2024-4-20 2024-4-19\ncalver nt 2024-32 2024-30 --cycle week\n```\n\nOutputs the exact version string or exits with error.\n\n### Prefix, suffix and clean\n\nSimple helper methods that might be useful in your versioning processes.\n\n```ts\ncalver.prefix('2024-4.123') // outputs v2024-4.123\ncalver.prefix('2024-4.123', 'v') // outputs v2024-4.123\n\ncalver.suffix('2024-4.123', '-something') // outputs 2024-4.123-something\n\ncalver.clean(' =v2024-4.123-something ') // 2024-4.123\n```\n\nThey work same as in the module api:\n\n```sh\ncalver prefix 2024-4.123\ncalver prefix 2024-4.123 --prefix v\ncalver suffix 2024-4.123 --suffix something\ncalver clean \" =v2024-4.123-something \"\n```\n\n## Contributing\n\nIf you're interested in contributing, read the [CONTRIBUTING.md](https://github.com/muratgozel/muratgozel/blob/main/CONTRIBUTING.md) first, please.\n\n---\n\nVersion management of this repository done by [releaser](https://github.com/muratgozel/node-releaser) 🚀\n\n---\n\nThanks for watching 🐬\n\n[![Support me on Patreon](https://cdn.muratgozel.com.tr/support-me-on-patreon.v1.png)](https://patreon.com/muratgozel?utm_medium=organic\u0026utm_source=github_repo\u0026utm_campaign=github\u0026utm_content=join_link)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmuratgozel%2Fnode-calver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmuratgozel%2Fnode-calver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmuratgozel%2Fnode-calver/lists"}