https://github.com/igorskyflyer/npm-keppo

🎡 Parse, manage, compare and output SemVer-compatible version numbers with Keppo. 🧮
https://github.com/igorskyflyer/npm-keppo

back-end compare diff difference igorskyflyer javascript keppo library manage node nodejs npm output parse print semver version

Last synced: about 2 months ago
JSON representation

🎡 Parse, manage, compare and output SemVer-compatible version numbers with Keppo. 🧮

Host: GitHub
URL: https://github.com/igorskyflyer/npm-keppo
Owner: igorskyflyer
License: mit
Created: 2022-07-30T17:20:43.000Z (almost 4 years ago)
Default Branch: main
Last Pushed: 2023-07-03T20:30:20.000Z (about 3 years ago)
Last Synced: 2025-07-05T17:13:40.868Z (about 1 year ago)
Topics: back-end, compare, diff, difference, igorskyflyer, javascript, keppo, library, manage, node, nodejs, npm, output, parse, print, semver, version
Language: JavaScript
Homepage: https://www.npmjs.com/package/@igor.dvlpr/keppo
Size: 35.2 KB
Stars: 1
Watchers: 2
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE.txt

Awesome Lists containing this project

README

Keppo

🎡 A SemVer engine with a fluent API to parse, manage, compare, and output version numbers. 🧮

## 📃 Table of Contents

- [**Features**](#-features)
- [**Usage**](#-usage)
- [**API**](#-api)
- [**Examples**](#️-examples)
- [**Changelog**](#-changelog)
- [**Support**](#-support)
- [**License**](#-license)
- [**Related**](#-related)
- [**Author**](#-author)

## 🤖 Features

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

`keppo.ts`
```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:

```bash
pnpm add @igorskyflyer/keppo
```

```bash
yarn add @igorskyflyer/keppo
```

```bash
npm i @igorskyflyer/keppo
```

## 🤹🏼 API

There are 2 available constructors:

```ts
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.

```ts
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.

```ts
static VERSION: string
```

Returns the internal version of the Keppo engine.

```ts
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.

```ts
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`

```ts
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.

```ts
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.

```ts
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.

```ts
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.

```ts
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.

```ts
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.

```ts
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.

```ts
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.

```ts
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.

```ts
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.

```ts
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.

```ts
clearLabel(): Keppo
```

Clears the label of the current Keppo instance.

```ts
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.

```ts
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.

```ts
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.

```ts
output(): void
```

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

```ts
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.

```ts
reset(): Keppo
```

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

```ts
toString(): string
```

Formats the current `Keppo` object as a String.

```ts
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`.