@hashgraph/solo
Version:
An opinionated CLI tool to deploy and manage private Hedera Networks.
381 lines • 19.6 kB
JavaScript
// SPDX-License-Identifier: Apache-2.0
import { SoloError } from '../../core/errors/solo-error.js';
import { IllegalArgumentError } from '../../core/errors/illegal-argument-error.js';
import { Numbers } from './numbers.js';
/**
* A class representing a semantic version, which can be initialized with either a string or a number.
* The class provides methods for comparing semantic versions, as well as validating and formatting them.
* It supports both standard semantic versioning (e.g., "1.0.0", "2.1.3-alpha+001") and a simplified numeric versioning (e.g., 1, 2).
* The class also includes a static method for validating and formatting semantic version strings with optional 'v' prefix handling.
*
* @template T - The type of the original value used to create the semantic version, either string or number
*/
export class SemanticVersion {
originalValue;
/**
* Constant value representing a zero version number.
*/
static ZERO = new SemanticVersion('0');
/**
* The major version number, which is incremented for incompatible API changes.
* Initialized to 0 by default.
*
* @readonly
*/
major = 0;
/**
* The minor version number, which is incremented for added functionality in a backwards-compatible manner.
* Initialized to 0 by default.
*
* @readonly
*/
minor = 0;
/**
* The patch version number, which is incremented for backwards-compatible bug fixes.
* Initialized to 0 by default.
*
* @readonly
*/
patch = 0;
/**
* The pre-release version, which is denoted by a hyphen and can contain alphanumeric identifiers separated by dots.
* It indicates that the version is unstable and may not satisfy the intended compatibility requirements as denoted by
* its associated normal version.
* Initialized to null by default.
*
* @readonly
*/
preRelease = undefined;
/**
* The build metadata, which is denoted by a plus sign and can contain alphanumeric identifiers separated by dots.
* It is ignored when determining version precedence but can be used to provide additional build information.
* Initialized to null by default.
*
* @readonly
*/
buildMetadata = undefined;
/**
* The type of the original value used to create the semantic version, either 'string' or 'number'.
* This is used to determine how to format the version when converting it back to a string.
*
* @readonly
*/
tType = 'string';
/**
* Creates a new SemanticVersion instance from a string or number. The constructor validates the input and parses it
* into its components (major, minor, patch, pre-release, build metadata) based on the type of the original value.
* @param originalValue - The original value used to create the semantic version, which can be a string
* (e.g., "1.0.0", "2.1.3-alpha+001") or a number (e.g., 1, 2)
* @throws IllegalArgumentError if the original value is not a valid semantic version string or a non-negative integer
*/
constructor(originalValue) {
this.originalValue = originalValue;
if (!SemanticVersion.isSemanticVersion(this.originalValue)) {
throw new IllegalArgumentError(`Invalid semantic version: ${this.originalValue}`, this.originalValue);
}
if (this.originalValue instanceof SemanticVersion) {
this.major = this.originalValue.major;
this.minor = this.originalValue.minor;
this.patch = this.originalValue.patch;
this.preRelease = this.originalValue.preRelease;
this.buildMetadata = this.originalValue.buildMetadata;
this.tType = this.originalValue.tType;
}
else if (Numbers.isNumeric(`${this.originalValue}`) &&
Number.isSafeInteger(this.originalValue) &&
this.originalValue >= 0) {
this.major = this.originalValue;
this.tType = 'number';
}
else if (SemanticVersion.isSemanticVersion(this.originalValue) && typeof this.originalValue === 'string') {
this.tType = 'string';
// @ts-expect-error - This is safe because the constructor will throw if the type is not correct
this.originalValue = originalValue.trim();
const versionParts = this.originalValue.split('.');
this.major = Number.parseInt(versionParts[0].replace(/^v/, ''), 10);
if (versionParts.length > 1) {
this.minor = Number.parseInt(versionParts[1], 10);
if (versionParts.length > 2) {
this.patch = Number.parseInt(versionParts[2].split('-')[0].split('+')[0], 10);
}
}
const preReleaseMatch = this.originalValue.match(/-(.+?)(?:\+|$)/);
if (preReleaseMatch) {
this.preRelease = preReleaseMatch[1];
}
const buildMetadataMatch = this.originalValue.match(/\+(.+)$/);
if (buildMetadataMatch) {
this.buildMetadata = buildMetadataMatch[1];
}
}
}
/**
* Checks if this semantic version is equal to another semantic version or a valid string/number representation of a semantic version.
* @param other - The other semantic version or a valid string/number to compare against
* @returns true if they are equal, false otherwise
*/
equals(other) {
// other must be a valid semantic version (either an instance of SemanticVersion or a valid string/number)
if (!SemanticVersion.isSemanticVersion(other)) {
return false;
}
// if both are the same instance, they are equal
if (this === other) {
return true;
}
const otherValue = new SemanticVersion(other);
return (this.tType === otherValue.tType &&
this.major === otherValue.major &&
this.minor === otherValue.minor &&
this.patch === otherValue.patch &&
this.preRelease === otherValue.preRelease &&
(this.buildMetadata === otherValue.buildMetadata || !this.buildMetadata || !otherValue.buildMetadata));
}
/**
* Compares this semantic version to another semantic version or a valid string/number representation of a semantic version.
* @returns 0 if they are equal, 1 if this version is greater, -1 if this version is less, or NaN if the other value is not a valid semantic version
* @param other - The other semantic version or a valid string/number to compare against
* @throws IllegalArgumentError if the other value is not a valid semantic version
* @remarks The comparison is based on the precedence rules defined in the Semantic Versioning specification, which
* considers major, minor, patch, pre-release, and build metadata components. Pre-release versions are considered
* less than their associated normal versions, and build metadata does not affect precedence.
*/
compare(other) {
// throw an error if the other value is not a valid semantic version
if (!SemanticVersion.isSemanticVersion(other)) {
throw new IllegalArgumentError(`Cannot compare with non-semantic version: ${other}`, other);
}
if (this.equals(other)) {
return 0;
}
if (this.greaterThan(other)) {
return 1;
}
if (this.lessThan(other)) {
return -1;
}
return Number.NaN; // This should never happen if the above conditions are exhaustive
}
/**
* Determines if this semantic version is greater than another semantic version or a valid string/number representation of a semantic version.
* @returns true if this version is greater, false otherwise
* @param other - The other semantic version or a valid string/number to compare against
* @remarks The comparison is based on the precedence rules defined in the Semantic Versioning specification, which
* considers major, minor, patch, pre-release, and build metadata components. Pre-release versions are considered
* less than their associated normal versions, and build metadata does not affect precedence.
*/
greaterThan(other) {
const otherValue = new SemanticVersion(other);
if (this.major > otherValue.major) {
return true;
}
if (this.major < otherValue.major) {
return false;
}
if (this.minor > otherValue.minor) {
return true;
}
if (this.minor < otherValue.minor) {
return false;
}
if (this.patch > otherValue.patch) {
return true;
}
if (this.patch < otherValue.patch) {
return false;
}
// Handle pre-release comparison
if (this.preRelease && !otherValue.preRelease) {
return false;
} // Pre-release is less than no pre-release
if (!this.preRelease && otherValue.preRelease) {
return true;
} // No pre-release is greater than pre-release
if (this.preRelease && otherValue.preRelease) {
const thisPreReleaseParts = this.preRelease.split('.');
const otherPreReleaseParts = otherValue.preRelease.split('.');
for (let index = 0; index < Math.max(thisPreReleaseParts.length, otherPreReleaseParts.length); index++) {
const thisPart = thisPreReleaseParts[index];
const otherPart = otherPreReleaseParts[index];
if (thisPart === undefined) {
return false;
} // shorter pre-release is less
if (otherPart === undefined) {
return true;
} // shorter pre-release is less
const thisPartIsNumeric = Numbers.isNumeric(thisPart);
const otherPartIsNumeric = Numbers.isNumeric(otherPart);
if (thisPartIsNumeric && otherPartIsNumeric) {
const thisNumber = Number.parseInt(thisPart, 10);
const otherNumber = Number.parseInt(otherPart, 10);
if (thisNumber > otherNumber) {
return true;
}
if (thisNumber < otherNumber) {
return false;
}
}
else if (thisPartIsNumeric) {
return false; // Numeric identifiers have lower precedence than non-numeric (semver §11.4.4)
}
else if (otherPartIsNumeric) {
return true; // Numeric identifiers have lower precedence than non-numeric (semver §11.4.4)
}
else {
if (thisPart > otherPart) {
return true;
}
if (thisPart < otherPart) {
return false;
}
}
}
}
// Build metadata does not affect precedence
return false;
}
/**
* Determines if this semantic version is less than another semantic version or a valid string/number representation of a semantic version.
* @returns true if this version is less, false otherwise
* @param other - The other semantic version or a valid string/number to compare against
* @remarks The comparison is based on the precedence rules defined in the Semantic Versioning specification, which
* considers major, minor, patch, pre-release, and build metadata components. Pre-release versions are considered
* less than their associated normal versions, and build metadata does not affect precedence.
*/
lessThan(other) {
return !this.equals(other) && !this.greaterThan(other);
}
/**
* Determines if this semantic version is greater than or equal to another semantic version or a valid string/number representation of a semantic version.
* @returns true if this version is greater than or equal, false otherwise
* @param other - The other semantic version or a valid string/number to compare against
* @remarks The comparison is based on the precedence rules defined in the Semantic Versioning specification, which
* considers major, minor, patch, pre-release, and build metadata components. Pre-release versions are considered
* less than their associated normal versions, and build metadata does not affect precedence.
*/
greaterThanOrEqual(other) {
return this.equals(other) || this.greaterThan(other);
}
/**
* Determines if this semantic version is less than or equal to another semantic version or a valid string/number
* representation of a semantic version.
* @returns true if this version is less than or equal, false otherwise
* @param other - The other semantic version or a valid string/number to compare against
* @remarks The comparison is based on the precedence rules defined in the Semantic Versioning specification, which
* considers major, minor, patch, pre-release, and build metadata components. Pre-release versions are considered
* less than their associated normal versions, and build metadata does not affect precedence.
*/
lessThanOrEqual(other) {
return this.equals(other) || this.lessThan(other);
}
/**
* Converts this semantic version to a string representation. If the original type was a number, it returns just the
* major version as a string.
* If the original type was a string, it returns the full semantic version string, including pre-release and build
* metadata if present.
* @returns The string representation of this semantic version
*/
toString() {
if (this.tType === 'number') {
return `${this.major}`;
}
return `${this.major}.${this.minor}.${this.patch}${this.preRelease ? `-${this.preRelease}` : ''}${this.buildMetadata ? `+${this.buildMetadata}` : ''}`;
}
/**
* Converts this semantic version to a string representation with a 'v' prefix. If the original type was a number, it
* returns just the major version with a 'v' prefix.
* If the original type was a string, it returns the full semantic version string with a 'v' prefix, including
* pre-release and build metadata if present.
* @returns The string representation of this semantic version with a 'v' prefix
*/
toPrefixedString() {
return `v${this.toString()}`;
}
/**
* Validates if a value is a valid semantic version, which can be an instance of SemanticVersion, a numeric value, or a
* string that matches the semantic version pattern.
* The validation allows for an optional 'v' prefix in string representations and ensures that numeric values are
* non-negative safe integers.
* @returns true if the value is a valid semantic version, false otherwise
* @param value - The value to validate, which can be an instance of SemanticVersion, a numeric value, or a string
* @private
*/
static isSemanticVersion(value) {
// if it's an instance of SemanticVersion it must be valid
if (value instanceof SemanticVersion) {
return true;
}
if (typeof value === 'string') {
value = value.trim().replace(/^v/, ''); // Remove 'v' prefix if present for validation
}
// if it's numeric, a safe integer, and non-negative, it's valid
if (Numbers.isNumeric(`${value}`) && Number.isSafeInteger(value) && value >= 0) {
return true;
}
// if it's a string and matches a semantic version regex pattern,
// it's valid,
// allows for an optional 'v' prefix,
// '0',
// '0.1',
// '0.0.1',
// as well as acceptable pre-release and build metadata formats
if (typeof value === 'string') {
return /^v?(0|[1-9]\d*)(\.(0|[1-9]\d*)(\.(0|[1-9]\d*)(?:-[\da-zA-Z-]+(?:\.[\da-zA-Z-]+)*)?(?:\+[\da-zA-Z-]+(?:\.[\da-zA-Z-]+)*)?)?)?$/.test(value.trim());
}
return false;
}
/**
* Validates if a string is a valid semantic version and handles the 'v' prefix
*
* @param versionString - The version string to validate
* @param isNeedPrefix - If true, adds 'v' prefix if missing; if false, removes 'v' prefix if present
* @param label - Label to use in error messages (e.g., 'Release tag', 'SemanticVersion')
* @returns The processed version string with proper prefix handling
* @throws SoloError or IllegalArgumentError if the version string is invalid
*/
static getValidSemanticVersion(versionString, isNeedPrefix = false, label = 'SemanticVersion') {
if (!versionString) {
throw new SoloError(`${label} cannot be empty`);
}
// Validate the version string
if (!SemanticVersion.isSemanticVersion(versionString)) {
throw new IllegalArgumentError(`Invalid ${label.toLowerCase()}: ${versionString}`, versionString);
}
const value = new SemanticVersion(versionString);
return isNeedPrefix ? value.toPrefixedString() : value.toString();
}
/**
* Returns a new SemanticVersion instance with the minor version incremented by 1 and major versions unchanged.
* The patch version is reset to 0, and pre-release and build metadata are cleared.
* The returned instance is always of type SemanticVersion<string> to ensure that the version is represented in a
* standard semantic version format.
* @returns A new SemanticVersion instance with the minor version incremented by 1
* @remarks This method is useful for automatically generating the next minor version based on the current version,
* following semantic versioning rules.
* For example, if the current version is "1.2.3", calling bumpMinor() will return a new SemanticVersion instance
* representing "1.3.0".
* If the current version is "1.2.3-alpha+001", calling bumpMinor() will return a new SemanticVersion instance
* representing "1.3.0" (pre-release and build metadata are cleared).
*/
bumpMinor() {
return new SemanticVersion(`${this.major}.${this.minor + 1}.${0}`);
}
/**
* Returns a new SemanticVersion instance with the major version incremented by 1 and minor and patch versions reset to 0.
* Pre-release and build metadata are cleared.
* The returned instance is of the same type as the original (string or number) to maintain consistency in version representation.
* @returns A new SemanticVersion instance with the major version incremented by 1
* @remarks This method is useful for automatically generating the next major version based on the current version,
* following semantic versioning rules.
* For example, if the current version is "1.2.3", calling bumpMajor() will return a new SemanticVersion instance
* representing "2.0.0".
*/
bumpMajor() {
return this.tType === 'number'
? // @ts-expect-error - This is safe because the constructor will throw if the type is not correct
new SemanticVersion(this.major + 1)
: // @ts-expect-error - This is safe because the constructor will throw if the type is not correct
new SemanticVersion(`${this.major + 1}.0.0`);
}
}
//# sourceMappingURL=semantic-version.js.map