Skip to content

Latest commit

 

History

History
230 lines (153 loc) · 5.17 KB

README.md

File metadata and controls

230 lines (153 loc) · 5.17 KB

ChronVer

This repo contains the TypeScript implementation of the Chronologic Versioning specification, as well as a CLI. ChronVer is a temporal-based versioning system that makes version numbers more intuitive and easier to track. Welcome to the future.

Features

  • Full ChronVer specification implementation
  • Command-line interface (CLI)
  • Version validation and comparison
  • Feature branch and breaking change support
  • Deno and Node.js compatibility

Installation

# deno
deno add jsr:@chronver/chronver

# node
npx jsr add @chronver/chronver

Usage

Basic Usage

// deno
import { ChronVer } from "jsr:@chronver/chronver";

// node
import { ChronVer } from "@chronver/chronver";

// create new version
const version = new ChronVer("2024.04.03.1");

// convert to string
console.log(version.toString()); // "2024.04.03.1"

// access version components
console.log(version.year);      // 2024
console.log(version.month);     // 4
console.log(version.day);       // 3
console.log(version.changeset); // 1

Validation

console.log(ChronVer.isValid("2024.04.03")); // true
console.log(ChronVer.isValid("invalid"));    // false
console.log(ChronVer.isValid("2024.13.19")); // false (invalid month)

Comparison

const v1 = "2024.04.03.1";
const v2 = "2024.04.03.2";

console.log(ChronVer.compare(v1, v2)); // -1 (v1 is older than v2)
console.log(ChronVer.compare(v2, v1)); // 1  (v2 is newer than v1)
console.log(ChronVer.compare(v1, v1)); // 0  (versions are equal)

Feature Branches and Breaking Changes

// feature branch
const feature = new ChronVer("2024.04.03-feature");
console.log(feature.feature);    // "feature"
console.log(feature.toString()); // "2024.04.03-feature"

// breaking change
const breaking = new ChronVer("2024.04.03.1-break");
console.log(breaking.isBreaking); // true
console.log(breaking.toString()); // "2024.04.03.1-break"

CLI Usage

# install CLI globally
deno install --allow-read --allow-env --global --name chronver cli.ts

# uninstall CLI globally
deno uninstall chronver --global

The ChronVer CLI provides several commands for working with chronological versions:

# get today's version
chronver today
chronver today --changeset=1 --feature=test
chronver today --breaking

# increment `version` in package.json
chronver -i package

# increment `version` in JSON file
chronver --increment file.json

# validate a version
chronver validate 2024.04.03.1
chronver validate 2024.04.03-feature

# compare versions
chronver compare 2024.04.03.1 2024.04.03.2
chronver is-newer 2024.04.03.2 2024.04.03.1

# parse version details
chronver parse 2024.04.03.1-break

# check for breaking changes
chronver is-breaking 2024.04.03.1-break

# show help
chronver help

CLI Commands

  • compare <v1> <v2> - Compare two versions
  • help - Show help message
  • is-breaking <version> - Check if version is a breaking change
  • is-newer <v1> <v2> - Check if v1 is newer than v2
  • parse <version> - Display detailed version information
  • today - Generate today's version
  • validate <version> - Check if a version string is valid
  • version - Show CLI version

CLI Options

  • --breaking - Mark as breaking change
  • --changeset=<n> - Specify changeset number
  • --feature=<name> - Add feature name
  • --increment - Increment version for the specified target (can be a JSON file path or any value)

Version Format

A valid ChronVer version number follows this format:

  • YYYY.MM.DD[.CHANGESET][-LABEL]

Where:

  • YYYY is the four-digit year
  • MM is the two-digit month (01-12)
  • DD is the two-digit day (01-31)
  • CHANGESET is an optional non-negative integer
  • LABEL can be either "break" for breaking changes or a feature name

Examples:

  • 2024.04.03: basic version
  • 2024.04.03.1: version with changeset
  • 2024.04.03-feature: feature branch
  • 2024.04.03.1-break: breaking change

API Reference

ChronVer Class

Constructor

  • new ChronVer(version: string): creates a new ChronVer instance

Properties

  • changeset: number: changeset number (0 if not specified)
  • day: number: day component (1-31)
  • feature?: string: feature name (if specified)
  • isBreaking: boolean: whether this is a breaking change
  • month: number: month component (1-12)
  • year: number: year component

Methods

  • compare(other: ChronVer): number: compares two versions (-1, 0, 1)
  • toString(): string: converts version to its string representation

Static Methods

  • compare(v1: string, v2: string): number: compares two version strings
  • increment(value: string | undefined): Promise<string>: increments version
  • isValid(version: string): boolean: checks if version string is valid
  • parseVersion(version: string): { changeset: number; date: string; version: string; } | null: parses version

Development

Create executable

deno run --allow-env --allow-read --allow-run --allow-write bundle.ts

Now you can use ./bin/chronver.js in your scripts.

Running Tests

# lint all TypeScript files
deno lint

# type-check file
deno check cli.ts
deno check mod.ts
deno check test.ts

# run the tests in `test.ts`
deno test

License

MIT