Semver4k is a lightweight Kotlin Multiplatform library that helps you handling versions. It follows the rules of the semantic versioning specification and provides several versioning modes: strict, NPM, CocoaPods...

This library is a fork of semver4j completly rewritten in kotlin.

Supported Kotlin Multiplatform targets:

• jvm
• ios
• wasmJs
• (Additional targets can be added as needed)

Add the dependency to your project:

<dependency>
  <groupId>de.voize</groupId>
  <artifactId>semver4k</artifactId>
  <version>4.3.0</version>
</dependency>

implementation("de.voize:semver4k:4.3.0")

In Semver4k, a version looks like: 1.2.3-beta.4+sha899d8g79f87.

• 1 is the major part (required)
• 2 is the minor part (required in strict mode)
• 3 is the patch part (required in strict mode)
• beta and 4 are the version suffixes (optional)
• sha899d8g79f87 is the build information (optional)

You can create a version by using one of the 2 constructors:

val sem1 = Semver("1.2.3-beta.4+sha899d8g79f87") // Defaults to STRICT mode
val sem2 = Semver("1.2.3-beta.4+sha899d8g79f87", SemverType.NPM) // Specify the mode

If the version is invalid, a SemverException will be thrown.
You can access the different parts of the version using getMajor(), getMinor(), getPatch(), getSuffixTokens() or getBuild().

You can check if you're working with a stable version by using Semver#isStable().

A version is stable if its major number is strictly positive and it has no suffix.

Examples:

// TRUE
Semver("1.2.3").isStable()
Semver("1.2.3+sHa.0nSFGKjkjsdf").isStable()

// FALSE
Semver("0.1.2").isStable())
Semver("0.1.2+sHa.0nSFGKjkjsdf").isStable()
Semver("1.2.3-BETA.11+sHa.0nSFGKjkjsdf").isStable()

• isGreaterThan returns true if the version is strictly greater than the other one.

val sem = Semver("1.2.3")
sem.isGreaterThan("1.2.2") // true
sem.isGreaterThan("1.2.4") // false
sem.isGreaterThan("1.2.3") // false

• isLowerThan returns true if the version is strictly lower than the other one.

val sem = Semver("1.2.3")
sem.isLowerThan("1.2.2") // false
sem.isLowerThan("1.2.4") // true
sem.isLowerThan("1.2.3") // false

• isEqualTo returns true if the versions are exactly the same.

val sem = Semver("1.2.3+sha123456789")
sem.isEqualTo("1.2.3+sha123456789") // true
sem.isEqualTo("1.2.3+shaABCDEFGHI") // false

• isEquivalentTo returns true if the versions are the same (does not take the build information into account).

val sem = Semver("1.2.3+sha123456789")
sem.isEquivalentTo("1.2.3+sha123456789") // true
sem.isEquivalentTo("1.2.3+shaABCDEFGHI") // true

If you want to know what is the main difference between 2 versions, use the diff method. It will return a VersionDiff enum value among: NONE, MAJOR, MINOR, PATCH, SUFFIX, BUILD. It will always return the biggest difference.

val sem = Semver("1.2.3-beta.4+sha899d8g79f87")
sem.diff("1.2.3-beta.4+sha899d8g79f87") // NONE
sem.diff("2.3.4-alpha.5+sha32iddfu987") // MAJOR
sem.diff("1.3.4-alpha.5+sha32iddfu987") // MINOR
sem.diff("1.2.4-alpha.5+sha32iddfu987") // PATCH
sem.diff("1.2.3-alpha.5+sha32iddfu987") // SUFFIX
sem.diff("1.2.3-beta.4+sha32iddfu987") // BUILD

If you want to check if a version satisfies a requirement, use the satisfies method.

• In STRICT and LOOSE modes, the requirement can only be another version.
• In NPM mode, the requirement follows NPM versioning rules.

// STRICT mode
val semStrict = Semver("1.2.3", SemverType.STRICT)
semStrict.satisfies("1.2.3") // true
semStrict.satisfies("1.2.2") // false
semStrict.satisfies("1.2.4") // false
semStrict.satisfies(">1.2.2") // SemverException, incompatible requirement for a STRICT mode

// NPM mode (those are just examples, check NPM documentation to see all the cases)
val semNPM =  Semver("1.2.3", SemverType.NPM)
semNPM.satisfies(">1.2.2") // true
semNPM.satisfies("1.1.1 || 1.2.3 - 2.0.0") // true
semNPM.satisfies("1.1.*") // false
semNPM.satisfies("~1.2.1") // true
semNPM.satisfies("^1.1.1") // true

// COCOAPODS mode (those are just examples, check CocoaPods documentation to see all the cases)
val semPOD =  Semver("1.2.3", SemverType.COCOAPODS)
semPOD.satisfies("> 1.2.2") // true
semPOD.satisfies("~> 1.2.1") // true
semPOD.satisfies("<= 1.1.1") // false

// IVY mode (those are just examples, check Ivy/gradle documentation to see all the cases)
val semIVY = Semver("1.2.3", SemverType.IVY)
semIVY.satisfies("1.2.+") // true
semIVY.satisfies("(,1.8.9]") // true
semIVY.satisfies("[0.2,1.4]") // true

The Semver object is immutable. However, it provides a set of methods that will help you create new versions:

• withIncMajor() and withIncMajor(int increment) returns a Semver object with the major part incremented
• withIncMinor() and withIncMinor(int increment) returns a Semver object with the minor part incremented
• withIncPatch() and withIncPatch(int increment) returns a Semver object with the patch part incremented
• withClearedSuffix() returns a Semver object with no suffix
• withClearedBuild() returns a Semver object with no build information

You can also use built-in versioning methods such as:

• nextMajor(): 1.2.3-beta.4+sha32iddfu987 => 2.0.0
• nextMinor(): 1.2.3-beta.4+sha32iddfu987 => 1.3.0
• nextPatch(): 1.2.3-beta.4+sha32iddfu987 => 1.2.4
• nextIncrement(): 1.2.3-beta.4+sha32iddfu987 => 1.2.3-beta.5+sha32iddfu987

Any pull request or bug report is welcome!
If you have any suggestion about new features, you can open an issue.