📃 Table of Contents

• Features
• Usage
• API
• Examples
• Changelog
• Support
• License
• Related
• Author

🤖 Features

Keppo is a fluent SemVer engine, every method returns the instance, so you can chain mutations like poetry:

keppo.ts

new Keppo('1.2.3-alpha')
  .increaseMajor()
  .setLabel('beta')
  .decreasePatch()
  .toString() // → '2.2.2-beta'

• 🔢 Parses & validates SemVer strings like '1.2.3', 'v2.0.0-alpha'
• 🧠 Strict & loose mode support for flexible parsing
• ⬆️ Increments major, minor, or patch with auto-reset and safety checks for overflows
• ⬇️ Decrements safely, never underflows
• 🏷️ Sets & formats labels like 'alpha', 'beta.1'
• 🔍 Compares versions and returns -1, 0, or 1
• 🧪 Validates version strings before use
• 🧮 Calculates max safe increment for each component
• 🧾 Prints version with optional 'v' prefix
• 🛡️ Guards against unsafe integers and malformed input

🕵🏼 Usage

Install it by executing any of the following, depending on your preferred package manager:

pnpm add @igorskyflyer/keppo

yarn add @igorskyflyer/keppo

npm i @igorskyflyer/keppo

🤹🏼 API

There are 2 available constructors:

constructor(
  major: number,
  minor: number,
  patch: number,
  strict?: boolean,
  label?: string
)

major: number - major version number (default: 0).

minor: number - minor version number (default: 0).

patch: number - patch version number (default: 0).

strict?: boolean = true - enables strict parsing mode (default: true).

label?: string = '' - optional label (e.g. 'alpha', 'beta.1'), no dash prefix needed.

Throws if any component is invalid or violates SemVer rules.

constructor(version: string)

version: string - a valid SemVer string (e.g. '1.2.3', 'v2.0.0-alpha').

Throws if the string is invalid or fails SemVer parsing.

static VERSION: string

Returns the internal version of the Keppo engine.

static from(version: string, strict?: boolean): Keppo

Creates a new Keppo instance from a valid SemVer string.
Equivalent to new Keppo(...).setVersion(version) but more fluent.

version: string - a valid SemVer string (e.g. '1.2.3', 'v2.0.0-alpha').

strict?: boolean - optional flag to enable strict parsing mode.

Throws if the version string is invalid.

Returns a fully initialized Keppo instance.

static isValid(version: string, isStrict: boolean = true): boolean

Checks whether a given string is a valid SemVer version.
Useful for validating a version before calling setVersion() or instantiating a Keppo instance.

version: string - a SemVer string (e.g. '1.2.3', 'v2.0.0-alpha')

isStrict: boolean - whether to enable strict parsing (default: true)

Returns true if the version is valid; otherwise false

setStrict(isStrict: boolean = true): Keppo

Sets the strict mode for SemVer parsing.

When enabled, version strings must follow strict SemVer format (e.g. no v prefix).
When disabled, relaxed formats like v1.0.0 are accepted.

isStrict: boolean - whether to enable strict mode (default: true)

Returns the current Keppo instance.

increaseMajor(major: number = 1): Keppo

Increases the major version number by the specified amount.
Resets the minor and patch components to 0 after incrementing.

major: number = 1 - the amount to increase by (default: 1)

Throws if the value is invalid or exceeds safe integer limits.

increaseMinor(minor?: number = 1): Keppo

Increases the minor version number by the specified amount.
Resets the patch component to 0 after incrementing.

minor: number = 1 - the amount to increase by (default: 1).

Throws if the value is invalid or exceeds safe integer limits.

increasePatch(patch?: number = 1): Keppo

Increases the patch version number by the specified amount.

patch: number = 1 - The amount to increase by (default: 1).

Throws if the value is invalid or exceeds safe integer limits.

decreaseMajor(major?: number = 1): Keppo

Decreases the major version number by the specified amount.
Resets the minor and patch components to 0 after decrementing.

major: number = 1 - the amount to decrease by (default: 1).

Throws if the value is invalid or results in a negative version.

decreaseMinor(minor?: number = 1): Keppo

Decreases the minor version number by the specified amount.
Resets the patch component to 0 after decrementing.

minor: number = 1 - the amount to decrease by (default: 1).

Throws an exception if the passed parameter is not valid.

decreasePatch(patch?: number = 1): Keppo

Decreases the patch version number by the specified amount.

patch: number = 1 - the amount to decrease by (default: 1).

Throws if the value is invalid or results in a negative patch version.

setMajor(major: number): Keppo

Sets the major version number for the current Keppo instance.

major: number - the major version as a number (e.g. 2).

Throws if the value is invalid, non-numeric, or negative.

setMinor(minor: number): Keppo

Sets the minor version number for the current Keppo instance.

minor: number - the minor version, as a number (e.g. 3).

Throws if the value is invalid, non-numeric, or negative.

setPatch(patch: number): Keppo

Sets the patch version number for the current Keppo instance.

patch: number - the patch version, as a number (e.g. 4).

Throws if the value is invalid, non-numeric, or negative.

setLabel(label: string): Keppo

Sets the version label for the current Keppo instance.
The label will be appended to the version string with a dash (e.g. 'alpha' → 0.1.0-alpha).
No need to include the dash manually.

label: string - a valid label string (e.g. 'alpha', 'beta.1').

Throws if the label is invalid or fails pattern validation.

clearLabel(): Keppo

Clears the label of the current Keppo instance.

compareWith(version: Keppo): KeppoComparison

Compares the current Keppo version against another Keppo instance.

For improved readability, use the KeppoComparison enum.

version: Keppo - another Keppo instance to compare against.

Throws if the input is invalid.

Returns a value of KeppoComparison defined as:

• -1 if the current version is older
• 0 if both versions are equal,
• 1 if the current version is newer.

enum KeppoComparison {
  Older = -1, // the current version is less than the compared version
  Current = 0, // both versions are equal
  Newer = 1 // the current version is greater than the compared version
}

Enum representing the result of a version comparison.
Used by compareWith() to indicate whether the current version is older, equal to, or newer than the target version.

compareWith(version: string): KeppoComparison

Compares the current Keppo version against a SemVer string.

For improved readability, use the KeppoComparison enum.

version: string - a valid SemVer string (e.g. '1.2.3-beta.1') to compare against.

Throws if the input is not a valid SemVer string.

Returns a value of KeppoComparison defined as:

• -1 if the current version is older
• 0 if both versions are equal,
• 1 if the current version is newer.

output(): void

Prints to console the String representation of the current Keppo object.

setVersion(version: string): Keppo

Sets the current version for the Keppo instance.
Replaces all existing version components and label with values parsed from the provided SemVer string.

Throws an exception if the passed parameter is not valid or the passed parameter is not a valid SemVer version.

version: string - a valid SemVer string (e.g. '1.2.3', 'v2.0.0-beta.1').

Throws if the string is invalid or fails SemVer parsing.

reset(): Keppo

Resets the current Keppo instance's SemVer version to 0.0.0 and label to an empty string.

toString(): string

Formats the current Keppo object as a String.

canIncreaseMajor(major: number = 1): boolean

Checks whether the major version can be safely increased by the given amount.
Uses Number.isSafeInteger() to ensure the result stays within JavaScript's safe integer range.

major: number = 1 - the amount to increase by (default: 1).

Returns true if the increment is safe; otherwise false.

Read more about Integer safety on MDN.

canIncreaseMinor(minor: number = 1): boolean

Checks whether the minor version can be safely increased by the given amount.
Uses Number.isSafeInteger() to ensure the result remains within JavaScript's safe integer range.

minor: number = 1 - the amount to increase by (default: 1).

Returns true if the increment is safe; otherwise false.

Read more about Integer safety on MDN.

canIncreasePatch(patch: number = 1): boolean

Checks whether the patch version can be safely increased by the given amount.
Uses Number.isSafeInteger() to ensure the result remains within JavaScript's safe integer range.

patch: number = 1 - the amount to increase by (default: 1).

Returns true if the increment is safe; otherwise false.

Read more about Integer safety on MDN.

maxIncreaseMajor(): number

Returns the maximum safe value that can be used to increase the major version number.
Based on JavaScript's Number.MAX_SAFE_INTEGER, which ensures arithmetic remains precise.

Read more about Integer safety on MDN.

maxIncreaseMinor(): number

Returns the maximum safe value that can be used to increase the minor version number.
Based on JavaScript’s Number.MAX_SAFE_INTEGER, ensuring arithmetic remains precise.

Read more about Integer safety on MDN.

maxIncreasePatch(): number

Returns the maximum safe value that can be used to increase the patch version number.
Based on JavaScript’s Number.MAX_SAFE_INTEGER, ensuring arithmetic remains precise.

🗒️ Examples

import { Keppo } from '@igorskyflyer/keppo'

new Keppo(1, 0, 0).toString() // returns '1.0.0'
new Keppo(1, 0, 0, true, 'alpha').toString() // returns '1.0.0-alpha'
new Keppo('1.0.0').increaseMajor(2).toString() // returns '3.0.0'
new Keppo(1, 0, 0).compareWith('2.0.0') // returns  -1
new Keppo('1.0.32').maxIncreasePatch() // returns 9007199254740959
new Keppo('1.0.1').canIncreasePatch(1) // returns true
// static method
Keppo.isValid('v1.0.0', false) //returns true
Keppo.isValid('v1.0.0') // returns false

📝 Changelog

📑 The changelog is available here, CHANGELOG.

🪪 License

Licensed under the MIT license.

💖 Support

🧬 Related

@igorskyflyer/common-color

🎨 Provides common Color-related TypeScript types. 🌈

@igorskyflyer/rawelement

🐯 A utility that lets you manipulate HTML elements, their attributes and innerHTML as strings, on the go and then render the modified HTML. Very useful in SSG projects. 💤

@igorskyflyer/str-is-in

🧵 Provides ways of checking whether a String is present in an Array of Strings using custom Comparators. 🔍

@igorskyflyer/recursive-readdir

📖 Provides recursive readdir() and readdirSync() functions. 📁

@igorskyflyer/clone

🧬 A lightweight JavaScript utility allowing deep copy-by-value of nested objects, arrays and arrays of objects. 🪁

👨🏻‍💻 Author

Created by Igor Dimitrijević (@igorskyflyer).