@alextheman/utility 4.0.0 → 4.2.0

package/dist/index.cjs

@@ -27,8 +27,8 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 //#endregion
 let zod = require("zod");
 zod = __toESM(zod);
-let path = require("path");
-path = __toESM(path);
+let node_path = require("node:path");
+node_path = __toESM(node_path);
 
 //#region src/constants/NAMESPACE_EXPORT_REGEX.ts
 const NAMESPACE_EXPORT_REGEX = "export\\s+\\*\\s+from";
@@ -163,6 +163,111 @@ var DataError = class extends Error {
 };
 var DataError_default = DataError;
 
+//#endregion
+//#region src/types/VersionType.ts
+const VersionType = {
+	MAJOR: "major",
+	MINOR: "minor",
+	PATCH: "patch"
+};
+
+//#endregion
+//#region src/types/VersionNumber.ts
+/** Represents a software version number, considered to be made up of a major, minor, and patch part. */
+var VersionNumber = class VersionNumber {
+	/** The major number. Increments when a feature is removed or changed in a way that is not backwards-compatible with the previous release. */
+	major = 0;
+	/** The minor number. Increments when a new feature is added/deprecated and is expected to be backwards-compatible with the previous release. */
+	minor = 0;
+	/** The patch number. Increments when the next release is fixing a bug or doing a small refactor that should not be noticeable in practice. */
+	patch = 0;
+	nonNegativeTupleError = "Input array must be a tuple of three non-negative integers.";
+	/**
+	* @param input - The input to create a new instance of `VersionNumber` from.
+	*/
+	constructor(input) {
+		if (input instanceof VersionNumber) {
+			this.major = input.major;
+			this.minor = input.minor;
+			this.patch = input.patch;
+		} else if (typeof input === "string") {
+			if (!RegExp(VERSION_NUMBER_REGEX_default).test(input)) throw new DataError_default(input, "INVALID_VERSION", `"${input}" is not a valid version number. Version numbers must be of the format "X.Y.Z" or "vX.Y.Z", where X, Y, and Z are non-negative integers.`);
+			const [major, minor, patch] = VersionNumber.formatString(input, { omitPrefix: true }).split(".").map((number) => {
+				return parseIntStrict_default(number);
+			});
+			this.major = major;
+			this.minor = minor;
+			this.patch = patch;
+		} else if (Array.isArray(input)) {
+			if (input.length !== 3) throw new DataError_default(input, "INVALID_LENGTH", this.nonNegativeTupleError);
+			const [major, minor, patch] = input.map((number) => {
+				const parsedInteger = parseIntStrict_default(number?.toString());
+				if (parsedInteger < 0) throw new DataError_default(input, "NON_POSITIVE_INPUTS", this.nonNegativeTupleError);
+				return parsedInteger;
+			});
+			this.major = major;
+			this.minor = minor;
+			this.patch = patch;
+		}
+	}
+	static formatString(input, options) {
+		if (options?.omitPrefix) return input.startsWith("v") ? input.slice(1) : input;
+		return input.startsWith("v") ? input : `v${input}`;
+	}
+	/**
+	* Get a string representation of the current version number.
+	*
+	* @param options - Extra additional options to apply.
+	*
+	* @returns A stringified representation of the current version number, leaving out the prefix if `omitPrefix` option was set to true.
+	*/
+	toString(options) {
+		const rawString = `${this.major}.${this.minor}.${this.patch}`;
+		return VersionNumber.formatString(rawString, options);
+	}
+	/**
+	* Gets the current version type of the current instance of `VersionNumber`.
+	*
+	* @returns Either `"major"`, `"minor"`, or `"patch"`, depending on the version type.
+	*/
+	get type() {
+		if (this.minor === 0 && this.patch === 0) return VersionType.MAJOR;
+		if (this.patch === 0) return VersionType.MINOR;
+		return VersionType.PATCH;
+	}
+	/**
+	* Determines whether the current instance of `VersionNumber` is a major, minor, or patch version.
+	*
+	* @param incrementType - The type of increment. Can be one of the following:
+	* - `"major"`: Change the major version `v1.2.3` → `v2.0.0`
+	* - `"minor"`: Change the minor version `v1.2.3` → `v1.3.0`
+	* - `"patch"`: Change the patch version `v1.2.3` → `v1.2.4`
+	*
+	* @returns A new instance of `VersionNumber` with the increment applied.
+	*/
+	increment(incrementType) {
+		const newVersion = {
+			major: [
+				this.major + 1,
+				0,
+				0
+			],
+			minor: [
+				this.major,
+				this.minor + 1,
+				0
+			],
+			patch: [
+				this.major,
+				this.minor,
+				this.patch + 1
+			]
+		}[incrementType];
+		return new VersionNumber(newVersion);
+	}
+};
+var VersionNumber_default = VersionNumber;
+
 //#endregion
 //#region src/functions/parsers/parseIntStrict.ts
 /**
@@ -701,11 +806,6 @@ var parseFormData_default = parseFormData;
 
 //#endregion
 //#region src/functions/parsers/parseVersionType.ts
-const versionTypeSchema = zod.default.enum([
-	"major",
-	"minor",
-	"patch"
-]);
 /**
 * Parses the input and verifies it is a valid software version type (i.e. `"major" | "minor" | "patch"`)
 *
@@ -716,7 +816,7 @@ const versionTypeSchema = zod.default.enum([
 * @returns The given version type if allowed.
 */
 function parseVersionType(data) {
-	return parseZodSchema_default(versionTypeSchema, data, new DataError_default(data, "INVALID_VERSION_TYPE", "The provided version type must be one of `major | minor | patch`"));
+	return parseZodSchema_default(zod.default.enum(VersionType), data, new DataError_default(data, "INVALID_VERSION_TYPE", "The provided version type must be one of `major | minor | patch`"));
 }
 var parseVersionType_default = parseVersionType;
 
@@ -795,11 +895,35 @@ var appendSemicolon_default = appendSemicolon;
 * Converts a string from camelCase to kebab-case
 *
 * @param string - The string to convert.
+* @param options - Options to apply to the conversion.
 *
 * @returns The string converted to kebab-case.
 */
-function camelToKebab(string) {
-	return string.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/([A-Z])([A-Z][a-z])/g, "$1-$2").toLowerCase();
+function camelToKebab(string, options = { preserveConsecutiveCapitals: true }) {
+	let result = "";
+	let outerIndex = 0;
+	while (outerIndex < string.length) {
+		const character = string[outerIndex];
+		if (/[A-Z]/.test(character)) {
+			let innerIndex = outerIndex + 1;
+			while (innerIndex < string.length && /[A-Z]/.test(string[innerIndex]) && (options.preserveConsecutiveCapitals ? innerIndex + 1 < string.length && /[a-z]/.test(string[innerIndex + 1]) ? false : true : true)) innerIndex++;
+			const sequenceOfCapitals = string.slice(outerIndex, innerIndex);
+			if (options.preserveConsecutiveCapitals) {
+				if (result) result += "-";
+				result += sequenceOfCapitals.toLowerCase();
+			} else {
+				if (result) result += "-";
+				result += sequenceOfCapitals.split("").map((character$1) => {
+					return character$1.toLowerCase();
+				}).join("-");
+			}
+			outerIndex = innerIndex;
+		} else {
+			result += character;
+			outerIndex++;
+		}
+	}
+	return result;
 }
 var camelToKebab_default = camelToKebab;
 
@@ -857,7 +981,7 @@ var kebabToCamel_default = kebabToCamel;
 * @returns The import path normalized.
 */
 function normalizeImportPath(importPath) {
-	const normalizedPath = path.default.posix.normalize(importPath);
+	const normalizedPath = node_path.default.posix.normalize(importPath);
 	if (importPath.startsWith("./") && !normalizedPath.startsWith("./")) return `./${normalizedPath}`;
 	return normalizedPath;
 }
@@ -1040,6 +1164,8 @@ var normaliseIndents_default = normaliseIndents;
 *
 * Valid formats: `X.Y.Z` or `vX.Y.Z`, where X, Y, and Z are non-negative integers.
 *
+* @deprecated This function does not support the new class-based handling of VersionNumber. Please use `new VersionNumber(input)` instead.
+*
 * @param input - The version string to parse.
 * @param options - Extra options to apply.
 *
@@ -1059,6 +1185,13 @@ var parseVersion_default = parseVersion;
 /**
 * Gets the individual version numbers from a given version number as a tuple of numbers.
 *
+* @deprecated This function does not support the new class-based handling of VersionNumber. Please use one of the following instead:
+*      ```typescript
+*      new VersionNumber(version).major
+*      new VersionNumber(version).minor
+*      new VersionNumber(version).patch
+*      ```
+*
 * @param version - The version number.
 *
 * @returns A tuple of three numbers indicating `[major, minor, patch]`.
@@ -1075,6 +1208,8 @@ var getIndividualVersionNumbers_default = getIndividualVersionNumbers;
 /**
 * Determines whether the given version is a major, minor, or patch version.
 *
+* @deprecated This function does not support the new class-based handling of VersionNumber. Please use `new VersionNumber(version).type` instead.
+*
 * @param version - The version number.
 *
 * @returns Either `"major"`, `"minor"`, or `"patch"`, depending on the version type.
@@ -1092,6 +1227,8 @@ var determineVersionType_default = determineVersionType;
 /**
 * Increments the given input version depending on the given increment type.
 *
+* @deprecated This function does not support the new class-based handling of VersionNumber. Please use `new VersionNumber(version).increment(incrementType)` instead.
+*
 * @param version - The version to increment
 * @param incrementType - The type of increment. Can be one of the following:
 * - `"major"`: Change the major version `v1.2.3` → `v2.0.0`
@@ -1117,6 +1254,8 @@ exports.APIError = APIError_default;
 exports.DataError = DataError_default;
 exports.NAMESPACE_EXPORT_REGEX = NAMESPACE_EXPORT_REGEX_default;
 exports.VERSION_NUMBER_REGEX = VERSION_NUMBER_REGEX_default;
+exports.VersionNumber = VersionNumber_default;
+exports.VersionType = VersionType;
 exports.addDaysToDate = addDaysToDate_default;
 exports.appendSemicolon = appendSemicolon_default;
 exports.camelToKebab = camelToKebab_default;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import z, { ZodType, core, z as z$1 } from "zod";
+import { ZodType, core, z } from "zod";
 
 //#region src/constants/NAMESPACE_EXPORT_REGEX.d.ts
 declare const NAMESPACE_EXPORT_REGEX = "export\\s+\\*\\s+from";
@@ -222,6 +222,71 @@ declare class DataError extends Error {
   static check(input: unknown): input is DataError;
 }
 //#endregion
+//#region src/types/RecordKey.d.ts
+/** Represents the native Record's possible key type. */
+type RecordKey = string | number | symbol;
+//#endregion
+//#region src/types/CreateEnumType.d.ts
+/**
+ * Get the value types from a const object so the object can behave similarly to an enum.
+ *
+ * @template ObjectType - The type of the object to get the value types for.
+ */
+type CreateEnumType<ObjectType extends Record<RecordKey, unknown>> = ObjectType[keyof ObjectType];
+//#endregion
+//#region src/types/VersionType.d.ts
+declare const VersionType: {
+  readonly MAJOR: "major";
+  readonly MINOR: "minor";
+  readonly PATCH: "patch";
+};
+type VersionType = CreateEnumType<typeof VersionType>;
+//#endregion
+//#region src/types/VersionNumber.d.ts
+interface ToStringOptions {
+  omitPrefix?: boolean;
+}
+/** Represents a software version number, considered to be made up of a major, minor, and patch part. */
+declare class VersionNumber {
+  /** The major number. Increments when a feature is removed or changed in a way that is not backwards-compatible with the previous release. */
+  readonly major: number;
+  /** The minor number. Increments when a new feature is added/deprecated and is expected to be backwards-compatible with the previous release. */
+  readonly minor: number;
+  /** The patch number. Increments when the next release is fixing a bug or doing a small refactor that should not be noticeable in practice. */
+  readonly patch: number;
+  private readonly nonNegativeTupleError;
+  /**
+   * @param input - The input to create a new instance of `VersionNumber` from.
+   */
+  constructor(input: string | [number, number, number] | VersionNumber);
+  private static formatString;
+  /**
+   * Get a string representation of the current version number.
+   *
+   * @param options - Extra additional options to apply.
+   *
+   * @returns A stringified representation of the current version number, leaving out the prefix if `omitPrefix` option was set to true.
+   */
+  toString(options?: ToStringOptions): string;
+  /**
+   * Gets the current version type of the current instance of `VersionNumber`.
+   *
+   * @returns Either `"major"`, `"minor"`, or `"patch"`, depending on the version type.
+   */
+  get type(): VersionType;
+  /**
+   * Determines whether the current instance of `VersionNumber` is a major, minor, or patch version.
+   *
+   * @param incrementType - The type of increment. Can be one of the following:
+   * - `"major"`: Change the major version `v1.2.3` → `v2.0.0`
+   * - `"minor"`: Change the minor version `v1.2.3` → `v1.3.0`
+   * - `"patch"`: Change the patch version `v1.2.3` → `v1.2.4`
+   *
+   * @returns A new instance of `VersionNumber` with the increment applied.
+   */
+  increment(incrementType: VersionType): VersionNumber;
+}
+//#endregion
 //#region src/types/ArrayElement.d.ts
 /**
  * Gets the individual element types from an array type.
@@ -263,10 +328,6 @@ type NonUndefined<InputType> = InputType extends undefined ? never : InputType;
  */
 type OptionalOnCondition<Condition extends boolean, ResolvedTypeIfTrue> = Condition extends true ? ResolvedTypeIfTrue : ResolvedTypeIfTrue | undefined;
 //#endregion
-//#region src/types/RecordKey.d.ts
-/** Represents the native Record's possible key type. */
-type RecordKey = string | number | symbol;
-//#endregion
 //#region src/functions/miscellaneous/createFormData.d.ts
 type FormDataNullableResolutionStrategy = "stringify" | "empty" | "omit";
 type FormDataArrayResolutionStrategy = "stringify" | "multiple";
@@ -395,13 +456,13 @@ declare function omitProperties<ObjectType extends Record<string, unknown> | Rea
 declare function parseBoolean(inputString: string): boolean;
 //#endregion
 //#region src/functions/parsers/parseEnv.d.ts
-declare const envSchema: z$1.ZodEnum<{
+declare const envSchema: z.ZodEnum<{
   test: "test";
   development: "development";
   production: "production";
 }>;
 /** Represents the most common development environments */
-type Env = z$1.infer<typeof envSchema>;
+type Env = z.infer<typeof envSchema>;
 /**
  * Parses the input and verifies it matches one of the environments allowed by the Env types ("test" | "development" | "production").
  *
@@ -448,12 +509,6 @@ declare function parseFormData(formData: FormData): Record<string, string | Blob
 declare function parseIntStrict(string: string, radix?: number): number;
 //#endregion
 //#region src/functions/parsers/parseVersionType.d.ts
-declare const versionTypeSchema: z.ZodEnum<{
-  major: "major";
-  minor: "minor";
-  patch: "patch";
-}>;
-type VersionType = z.infer<typeof versionTypeSchema>;
 /**
  * Parses the input and verifies it is a valid software version type (i.e. `"major" | "minor" | "patch"`)
  *
@@ -524,14 +579,19 @@ declare function deepFreeze<ObjectType extends object>(object: ObjectType): Read
 declare function appendSemicolon(stringToAppendTo: string): string;
 //#endregion
 //#region src/functions/stringHelpers/camelToKebab.d.ts
+interface CamelToKebabOptions {
+  /** Whether to leave consecutive capitals alone in the conversion or not (e.g. `validateAPIUser` becomes `validate-a-p-i-user` if `false`, and `validate-api-user` if `true`) */
+  preserveConsecutiveCapitals?: boolean;
+}
 /**
  * Converts a string from camelCase to kebab-case
  *
  * @param string - The string to convert.
+ * @param options - Options to apply to the conversion.
  *
  * @returns The string converted to kebab-case.
  */
-declare function camelToKebab(string: string): string;
+declare function camelToKebab(string: string, options?: CamelToKebabOptions): string;
 //#endregion
 //#region src/functions/stringHelpers/kebabToCamel.d.ts
 interface KebabToCamelOptions {
@@ -688,6 +748,8 @@ declare const normalizeIndents: typeof normaliseIndents;
 /**
  * Determines whether the given version is a major, minor, or patch version.
  *
+ * @deprecated This function does not support the new class-based handling of VersionNumber. Please use `new VersionNumber(version).type` instead.
+ *
  * @param version - The version number.
  *
  * @returns Either `"major"`, `"minor"`, or `"patch"`, depending on the version type.
@@ -698,6 +760,13 @@ declare function determineVersionType(version: string): VersionType;
 /**
  * Gets the individual version numbers from a given version number as a tuple of numbers.
  *
+ * @deprecated This function does not support the new class-based handling of VersionNumber. Please use one of the following instead:
+ *      ```typescript
+ *      new VersionNumber(version).major
+ *      new VersionNumber(version).minor
+ *      new VersionNumber(version).patch
+ *      ```
+ *
  * @param version - The version number.
  *
  * @returns A tuple of three numbers indicating `[major, minor, patch]`.
@@ -712,6 +781,8 @@ interface IncrementVersionOptions {
 /**
  * Increments the given input version depending on the given increment type.
  *
+ * @deprecated This function does not support the new class-based handling of VersionNumber. Please use `new VersionNumber(version).increment(incrementType)` instead.
+ *
  * @param version - The version to increment
  * @param incrementType - The type of increment. Can be one of the following:
  * - `"major"`: Change the major version `v1.2.3` → `v2.0.0`
@@ -733,6 +804,8 @@ interface ParseVersionOptions {
  *
  * Valid formats: `X.Y.Z` or `vX.Y.Z`, where X, Y, and Z are non-negative integers.
  *
+ * @deprecated This function does not support the new class-based handling of VersionNumber. Please use `new VersionNumber(input)` instead.
+ *
  * @param input - The version string to parse.
  * @param options - Extra options to apply.
  *
@@ -742,4 +815,4 @@ interface ParseVersionOptions {
  */
 declare function parseVersion(input: string, options?: ParseVersionOptions): string;
 //#endregion
-export { APIError, ArrayElement, CreateFormDataOptions, CreateFormDataOptionsNullableResolution, CreateFormDataOptionsUndefinedOrNullResolution, DataError, DisallowUndefined, Env, FormDataArrayResolutionStrategy, FormDataNullableResolutionStrategy, HTTPErrorCode, IgnoreCase, IncrementVersionOptions, KebabToCamelOptions, NAMESPACE_EXPORT_REGEX, NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, OptionalOnCondition, ParseVersionOptions, RecordKey, StringListToArrayOptions, VERSION_NUMBER_REGEX, VersionType, addDaysToDate, appendSemicolon, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, determineVersionType, fillArray, formatDateAndTime, getIndividualVersionNumbers, getRandomNumber, getRecordKeys, httpErrorCodeLookup, incrementVersion, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, kebabToCamel, normaliseImportPath, normaliseIndents, normalizeImportPath, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseVersion, parseVersionType, parseZodSchema, randomiseArray, range, removeDuplicates, stringListToArray, truncate, wait };
+export { APIError, ArrayElement, CamelToKebabOptions, CreateEnumType, CreateFormDataOptions, CreateFormDataOptionsNullableResolution, CreateFormDataOptionsUndefinedOrNullResolution, DataError, DisallowUndefined, Env, FormDataArrayResolutionStrategy, FormDataNullableResolutionStrategy, HTTPErrorCode, IgnoreCase, IncrementVersionOptions, KebabToCamelOptions, NAMESPACE_EXPORT_REGEX, NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, OptionalOnCondition, ParseVersionOptions, RecordKey, StringListToArrayOptions, VERSION_NUMBER_REGEX, VersionNumber, VersionType, addDaysToDate, appendSemicolon, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, determineVersionType, fillArray, formatDateAndTime, getIndividualVersionNumbers, getRandomNumber, getRecordKeys, httpErrorCodeLookup, incrementVersion, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, kebabToCamel, normaliseImportPath, normaliseIndents, normalizeImportPath, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseVersion, parseVersionType, parseZodSchema, randomiseArray, range, removeDuplicates, stringListToArray, truncate, wait };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import z, { ZodType, core, z as z$1 } from "zod";
+import { ZodType, core, z as z$1 } from "zod";
 
 //#region src/constants/NAMESPACE_EXPORT_REGEX.d.ts
 declare const NAMESPACE_EXPORT_REGEX = "export\\s+\\*\\s+from";
@@ -222,6 +222,71 @@ declare class DataError extends Error {
   static check(input: unknown): input is DataError;
 }
 //#endregion
+//#region src/types/RecordKey.d.ts
+/** Represents the native Record's possible key type. */
+type RecordKey = string | number | symbol;
+//#endregion
+//#region src/types/CreateEnumType.d.ts
+/**
+ * Get the value types from a const object so the object can behave similarly to an enum.
+ *
+ * @template ObjectType - The type of the object to get the value types for.
+ */
+type CreateEnumType<ObjectType extends Record<RecordKey, unknown>> = ObjectType[keyof ObjectType];
+//#endregion
+//#region src/types/VersionType.d.ts
+declare const VersionType: {
+  readonly MAJOR: "major";
+  readonly MINOR: "minor";
+  readonly PATCH: "patch";
+};
+type VersionType = CreateEnumType<typeof VersionType>;
+//#endregion
+//#region src/types/VersionNumber.d.ts
+interface ToStringOptions {
+  omitPrefix?: boolean;
+}
+/** Represents a software version number, considered to be made up of a major, minor, and patch part. */
+declare class VersionNumber {
+  /** The major number. Increments when a feature is removed or changed in a way that is not backwards-compatible with the previous release. */
+  readonly major: number;
+  /** The minor number. Increments when a new feature is added/deprecated and is expected to be backwards-compatible with the previous release. */
+  readonly minor: number;
+  /** The patch number. Increments when the next release is fixing a bug or doing a small refactor that should not be noticeable in practice. */
+  readonly patch: number;
+  private readonly nonNegativeTupleError;
+  /**
+   * @param input - The input to create a new instance of `VersionNumber` from.
+   */
+  constructor(input: string | [number, number, number] | VersionNumber);
+  private static formatString;
+  /**
+   * Get a string representation of the current version number.
+   *
+   * @param options - Extra additional options to apply.
+   *
+   * @returns A stringified representation of the current version number, leaving out the prefix if `omitPrefix` option was set to true.
+   */
+  toString(options?: ToStringOptions): string;
+  /**
+   * Gets the current version type of the current instance of `VersionNumber`.
+   *
+   * @returns Either `"major"`, `"minor"`, or `"patch"`, depending on the version type.
+   */
+  get type(): VersionType;
+  /**
+   * Determines whether the current instance of `VersionNumber` is a major, minor, or patch version.
+   *
+   * @param incrementType - The type of increment. Can be one of the following:
+   * - `"major"`: Change the major version `v1.2.3` → `v2.0.0`
+   * - `"minor"`: Change the minor version `v1.2.3` → `v1.3.0`
+   * - `"patch"`: Change the patch version `v1.2.3` → `v1.2.4`
+   *
+   * @returns A new instance of `VersionNumber` with the increment applied.
+   */
+  increment(incrementType: VersionType): VersionNumber;
+}
+//#endregion
 //#region src/types/ArrayElement.d.ts
 /**
  * Gets the individual element types from an array type.
@@ -263,10 +328,6 @@ type NonUndefined<InputType> = InputType extends undefined ? never : InputType;
  */
 type OptionalOnCondition<Condition extends boolean, ResolvedTypeIfTrue> = Condition extends true ? ResolvedTypeIfTrue : ResolvedTypeIfTrue | undefined;
 //#endregion
-//#region src/types/RecordKey.d.ts
-/** Represents the native Record's possible key type. */
-type RecordKey = string | number | symbol;
-//#endregion
 //#region src/functions/miscellaneous/createFormData.d.ts
 type FormDataNullableResolutionStrategy = "stringify" | "empty" | "omit";
 type FormDataArrayResolutionStrategy = "stringify" | "multiple";
@@ -448,12 +509,6 @@ declare function parseFormData(formData: FormData): Record<string, string | Blob
 declare function parseIntStrict(string: string, radix?: number): number;
 //#endregion
 //#region src/functions/parsers/parseVersionType.d.ts
-declare const versionTypeSchema: z.ZodEnum<{
-  major: "major";
-  minor: "minor";
-  patch: "patch";
-}>;
-type VersionType = z.infer<typeof versionTypeSchema>;
 /**
  * Parses the input and verifies it is a valid software version type (i.e. `"major" | "minor" | "patch"`)
  *
@@ -524,14 +579,19 @@ declare function deepFreeze<ObjectType extends object>(object: ObjectType): Read
 declare function appendSemicolon(stringToAppendTo: string): string;
 //#endregion
 //#region src/functions/stringHelpers/camelToKebab.d.ts
+interface CamelToKebabOptions {
+  /** Whether to leave consecutive capitals alone in the conversion or not (e.g. `validateAPIUser` becomes `validate-a-p-i-user` if `false`, and `validate-api-user` if `true`) */
+  preserveConsecutiveCapitals?: boolean;
+}
 /**
  * Converts a string from camelCase to kebab-case
  *
  * @param string - The string to convert.
+ * @param options - Options to apply to the conversion.
  *
  * @returns The string converted to kebab-case.
  */
-declare function camelToKebab(string: string): string;
+declare function camelToKebab(string: string, options?: CamelToKebabOptions): string;
 //#endregion
 //#region src/functions/stringHelpers/kebabToCamel.d.ts
 interface KebabToCamelOptions {
@@ -688,6 +748,8 @@ declare const normalizeIndents: typeof normaliseIndents;
 /**
  * Determines whether the given version is a major, minor, or patch version.
  *
+ * @deprecated This function does not support the new class-based handling of VersionNumber. Please use `new VersionNumber(version).type` instead.
+ *
  * @param version - The version number.
  *
  * @returns Either `"major"`, `"minor"`, or `"patch"`, depending on the version type.
@@ -698,6 +760,13 @@ declare function determineVersionType(version: string): VersionType;
 /**
  * Gets the individual version numbers from a given version number as a tuple of numbers.
  *
+ * @deprecated This function does not support the new class-based handling of VersionNumber. Please use one of the following instead:
+ *      ```typescript
+ *      new VersionNumber(version).major
+ *      new VersionNumber(version).minor
+ *      new VersionNumber(version).patch
+ *      ```
+ *
  * @param version - The version number.
  *
  * @returns A tuple of three numbers indicating `[major, minor, patch]`.
@@ -712,6 +781,8 @@ interface IncrementVersionOptions {
 /**
  * Increments the given input version depending on the given increment type.
  *
+ * @deprecated This function does not support the new class-based handling of VersionNumber. Please use `new VersionNumber(version).increment(incrementType)` instead.
+ *
  * @param version - The version to increment
  * @param incrementType - The type of increment. Can be one of the following:
  * - `"major"`: Change the major version `v1.2.3` → `v2.0.0`
@@ -733,6 +804,8 @@ interface ParseVersionOptions {
  *
  * Valid formats: `X.Y.Z` or `vX.Y.Z`, where X, Y, and Z are non-negative integers.
  *
+ * @deprecated This function does not support the new class-based handling of VersionNumber. Please use `new VersionNumber(input)` instead.
+ *
  * @param input - The version string to parse.
  * @param options - Extra options to apply.
  *
@@ -742,4 +815,4 @@ interface ParseVersionOptions {
  */
 declare function parseVersion(input: string, options?: ParseVersionOptions): string;
 //#endregion
-export { APIError, ArrayElement, CreateFormDataOptions, CreateFormDataOptionsNullableResolution, CreateFormDataOptionsUndefinedOrNullResolution, DataError, DisallowUndefined, type Env, FormDataArrayResolutionStrategy, FormDataNullableResolutionStrategy, HTTPErrorCode, IgnoreCase, type IncrementVersionOptions, KebabToCamelOptions, NAMESPACE_EXPORT_REGEX, NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, OptionalOnCondition, type ParseVersionOptions, RecordKey, StringListToArrayOptions, VERSION_NUMBER_REGEX, type VersionType, addDaysToDate, appendSemicolon, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, determineVersionType, fillArray, formatDateAndTime, getIndividualVersionNumbers, getRandomNumber, getRecordKeys, httpErrorCodeLookup, incrementVersion, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, kebabToCamel, normaliseImportPath, normaliseIndents, normalizeImportPath, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseVersion, parseVersionType, parseZodSchema, randomiseArray, range, removeDuplicates, stringListToArray, truncate, wait };
+export { APIError, ArrayElement, CamelToKebabOptions, CreateEnumType, CreateFormDataOptions, CreateFormDataOptionsNullableResolution, CreateFormDataOptionsUndefinedOrNullResolution, DataError, DisallowUndefined, type Env, FormDataArrayResolutionStrategy, FormDataNullableResolutionStrategy, HTTPErrorCode, IgnoreCase, IncrementVersionOptions, KebabToCamelOptions, NAMESPACE_EXPORT_REGEX, NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, OptionalOnCondition, ParseVersionOptions, RecordKey, StringListToArrayOptions, VERSION_NUMBER_REGEX, VersionNumber, VersionType, addDaysToDate, appendSemicolon, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, determineVersionType, fillArray, formatDateAndTime, getIndividualVersionNumbers, getRandomNumber, getRecordKeys, httpErrorCodeLookup, incrementVersion, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, kebabToCamel, normaliseImportPath, normaliseIndents, normalizeImportPath, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseVersion, parseVersionType, parseZodSchema, randomiseArray, range, removeDuplicates, stringListToArray, truncate, wait };

package/dist/index.js

@@ -1,5 +1,5 @@
 import z, { z as z$1 } from "zod";
-import path from "path";
+import path from "node:path";
 
 //#region src/constants/NAMESPACE_EXPORT_REGEX.ts
 const NAMESPACE_EXPORT_REGEX = "export\\s+\\*\\s+from";
@@ -134,6 +134,111 @@ var DataError = class extends Error {
 };
 var DataError_default = DataError;
 
+//#endregion
+//#region src/types/VersionType.ts
+const VersionType = {
+	MAJOR: "major",
+	MINOR: "minor",
+	PATCH: "patch"
+};
+
+//#endregion
+//#region src/types/VersionNumber.ts
+/** Represents a software version number, considered to be made up of a major, minor, and patch part. */
+var VersionNumber = class VersionNumber {
+	/** The major number. Increments when a feature is removed or changed in a way that is not backwards-compatible with the previous release. */
+	major = 0;
+	/** The minor number. Increments when a new feature is added/deprecated and is expected to be backwards-compatible with the previous release. */
+	minor = 0;
+	/** The patch number. Increments when the next release is fixing a bug or doing a small refactor that should not be noticeable in practice. */
+	patch = 0;
+	nonNegativeTupleError = "Input array must be a tuple of three non-negative integers.";
+	/**
+	* @param input - The input to create a new instance of `VersionNumber` from.
+	*/
+	constructor(input) {
+		if (input instanceof VersionNumber) {
+			this.major = input.major;
+			this.minor = input.minor;
+			this.patch = input.patch;
+		} else if (typeof input === "string") {
+			if (!RegExp(VERSION_NUMBER_REGEX_default).test(input)) throw new DataError_default(input, "INVALID_VERSION", `"${input}" is not a valid version number. Version numbers must be of the format "X.Y.Z" or "vX.Y.Z", where X, Y, and Z are non-negative integers.`);
+			const [major, minor, patch] = VersionNumber.formatString(input, { omitPrefix: true }).split(".").map((number) => {
+				return parseIntStrict_default(number);
+			});
+			this.major = major;
+			this.minor = minor;
+			this.patch = patch;
+		} else if (Array.isArray(input)) {
+			if (input.length !== 3) throw new DataError_default(input, "INVALID_LENGTH", this.nonNegativeTupleError);
+			const [major, minor, patch] = input.map((number) => {
+				const parsedInteger = parseIntStrict_default(number?.toString());
+				if (parsedInteger < 0) throw new DataError_default(input, "NON_POSITIVE_INPUTS", this.nonNegativeTupleError);
+				return parsedInteger;
+			});
+			this.major = major;
+			this.minor = minor;
+			this.patch = patch;
+		}
+	}
+	static formatString(input, options) {
+		if (options?.omitPrefix) return input.startsWith("v") ? input.slice(1) : input;
+		return input.startsWith("v") ? input : `v${input}`;
+	}
+	/**
+	* Get a string representation of the current version number.
+	*
+	* @param options - Extra additional options to apply.
+	*
+	* @returns A stringified representation of the current version number, leaving out the prefix if `omitPrefix` option was set to true.
+	*/
+	toString(options) {
+		const rawString = `${this.major}.${this.minor}.${this.patch}`;
+		return VersionNumber.formatString(rawString, options);
+	}
+	/**
+	* Gets the current version type of the current instance of `VersionNumber`.
+	*
+	* @returns Either `"major"`, `"minor"`, or `"patch"`, depending on the version type.
+	*/
+	get type() {
+		if (this.minor === 0 && this.patch === 0) return VersionType.MAJOR;
+		if (this.patch === 0) return VersionType.MINOR;
+		return VersionType.PATCH;
+	}
+	/**
+	* Determines whether the current instance of `VersionNumber` is a major, minor, or patch version.
+	*
+	* @param incrementType - The type of increment. Can be one of the following:
+	* - `"major"`: Change the major version `v1.2.3` → `v2.0.0`
+	* - `"minor"`: Change the minor version `v1.2.3` → `v1.3.0`
+	* - `"patch"`: Change the patch version `v1.2.3` → `v1.2.4`
+	*
+	* @returns A new instance of `VersionNumber` with the increment applied.
+	*/
+	increment(incrementType) {
+		const newVersion = {
+			major: [
+				this.major + 1,
+				0,
+				0
+			],
+			minor: [
+				this.major,
+				this.minor + 1,
+				0
+			],
+			patch: [
+				this.major,
+				this.minor,
+				this.patch + 1
+			]
+		}[incrementType];
+		return new VersionNumber(newVersion);
+	}
+};
+var VersionNumber_default = VersionNumber;
+
 //#endregion
 //#region src/functions/parsers/parseIntStrict.ts
 /**
@@ -672,11 +777,6 @@ var parseFormData_default = parseFormData;
 
 //#endregion
 //#region src/functions/parsers/parseVersionType.ts
-const versionTypeSchema = z.enum([
-	"major",
-	"minor",
-	"patch"
-]);
 /**
 * Parses the input and verifies it is a valid software version type (i.e. `"major" | "minor" | "patch"`)
 *
@@ -687,7 +787,7 @@ const versionTypeSchema = z.enum([
 * @returns The given version type if allowed.
 */
 function parseVersionType(data) {
-	return parseZodSchema_default(versionTypeSchema, data, new DataError_default(data, "INVALID_VERSION_TYPE", "The provided version type must be one of `major | minor | patch`"));
+	return parseZodSchema_default(z.enum(VersionType), data, new DataError_default(data, "INVALID_VERSION_TYPE", "The provided version type must be one of `major | minor | patch`"));
 }
 var parseVersionType_default = parseVersionType;
 
@@ -766,11 +866,35 @@ var appendSemicolon_default = appendSemicolon;
 * Converts a string from camelCase to kebab-case
 *
 * @param string - The string to convert.
+* @param options - Options to apply to the conversion.
 *
 * @returns The string converted to kebab-case.
 */
-function camelToKebab(string) {
-	return string.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/([A-Z])([A-Z][a-z])/g, "$1-$2").toLowerCase();
+function camelToKebab(string, options = { preserveConsecutiveCapitals: true }) {
+	let result = "";
+	let outerIndex = 0;
+	while (outerIndex < string.length) {
+		const character = string[outerIndex];
+		if (/[A-Z]/.test(character)) {
+			let innerIndex = outerIndex + 1;
+			while (innerIndex < string.length && /[A-Z]/.test(string[innerIndex]) && (options.preserveConsecutiveCapitals ? innerIndex + 1 < string.length && /[a-z]/.test(string[innerIndex + 1]) ? false : true : true)) innerIndex++;
+			const sequenceOfCapitals = string.slice(outerIndex, innerIndex);
+			if (options.preserveConsecutiveCapitals) {
+				if (result) result += "-";
+				result += sequenceOfCapitals.toLowerCase();
+			} else {
+				if (result) result += "-";
+				result += sequenceOfCapitals.split("").map((character$1) => {
+					return character$1.toLowerCase();
+				}).join("-");
+			}
+			outerIndex = innerIndex;
+		} else {
+			result += character;
+			outerIndex++;
+		}
+	}
+	return result;
 }
 var camelToKebab_default = camelToKebab;
 
@@ -1011,6 +1135,8 @@ var normaliseIndents_default = normaliseIndents;
 *
 * Valid formats: `X.Y.Z` or `vX.Y.Z`, where X, Y, and Z are non-negative integers.
 *
+* @deprecated This function does not support the new class-based handling of VersionNumber. Please use `new VersionNumber(input)` instead.
+*
 * @param input - The version string to parse.
 * @param options - Extra options to apply.
 *
@@ -1030,6 +1156,13 @@ var parseVersion_default = parseVersion;
 /**
 * Gets the individual version numbers from a given version number as a tuple of numbers.
 *
+* @deprecated This function does not support the new class-based handling of VersionNumber. Please use one of the following instead:
+*      ```typescript
+*      new VersionNumber(version).major
+*      new VersionNumber(version).minor
+*      new VersionNumber(version).patch
+*      ```
+*
 * @param version - The version number.
 *
 * @returns A tuple of three numbers indicating `[major, minor, patch]`.
@@ -1046,6 +1179,8 @@ var getIndividualVersionNumbers_default = getIndividualVersionNumbers;
 /**
 * Determines whether the given version is a major, minor, or patch version.
 *
+* @deprecated This function does not support the new class-based handling of VersionNumber. Please use `new VersionNumber(version).type` instead.
+*
 * @param version - The version number.
 *
 * @returns Either `"major"`, `"minor"`, or `"patch"`, depending on the version type.
@@ -1063,6 +1198,8 @@ var determineVersionType_default = determineVersionType;
 /**
 * Increments the given input version depending on the given increment type.
 *
+* @deprecated This function does not support the new class-based handling of VersionNumber. Please use `new VersionNumber(version).increment(incrementType)` instead.
+*
 * @param version - The version to increment
 * @param incrementType - The type of increment. Can be one of the following:
 * - `"major"`: Change the major version `v1.2.3` → `v2.0.0`
@@ -1084,4 +1221,4 @@ function incrementVersion(version, incrementType, options) {
 var incrementVersion_default = incrementVersion;
 
 //#endregion
-export { APIError_default as APIError, DataError_default as DataError, NAMESPACE_EXPORT_REGEX_default as NAMESPACE_EXPORT_REGEX, VERSION_NUMBER_REGEX_default as VERSION_NUMBER_REGEX, addDaysToDate_default as addDaysToDate, appendSemicolon_default as appendSemicolon, camelToKebab_default as camelToKebab, convertFileToBase64_default as convertFileToBase64, createFormData_default as createFormData, createTemplateStringsArray_default as createTemplateStringsArray, deepCopy_default as deepCopy, deepFreeze_default as deepFreeze, determineVersionType_default as determineVersionType, fillArray_default as fillArray, formatDateAndTime_default as formatDateAndTime, getIndividualVersionNumbers_default as getIndividualVersionNumbers, getRandomNumber_default as getRandomNumber, getRecordKeys_default as getRecordKeys, httpErrorCodeLookup, incrementVersion_default as incrementVersion, interpolate_default as interpolate, interpolateObjects_default as interpolateObjects, isAnniversary_default as isAnniversary, isLeapYear_default as isLeapYear, isMonthlyMultiple_default as isMonthlyMultiple, isOrdered_default as isOrdered, isSameDate_default as isSameDate, kebabToCamel_default as kebabToCamel, normaliseImportPath, normaliseIndents_default as normaliseIndents, normalizeImportPath_default as normalizeImportPath, normalizeIndents, omitProperties_default as omitProperties, paralleliseArrays_default as paralleliseArrays, parseBoolean_default as parseBoolean, parseEnv_default as parseEnv, parseFormData_default as parseFormData, parseIntStrict_default as parseIntStrict, parseVersion_default as parseVersion, parseVersionType_default as parseVersionType, parseZodSchema_default as parseZodSchema, randomiseArray_default as randomiseArray, range_default as range, removeDuplicates_default as removeDuplicates, stringListToArray_default as stringListToArray, truncate_default as truncate, wait_default as wait };
+export { APIError_default as APIError, DataError_default as DataError, NAMESPACE_EXPORT_REGEX_default as NAMESPACE_EXPORT_REGEX, VERSION_NUMBER_REGEX_default as VERSION_NUMBER_REGEX, VersionNumber_default as VersionNumber, VersionType, addDaysToDate_default as addDaysToDate, appendSemicolon_default as appendSemicolon, camelToKebab_default as camelToKebab, convertFileToBase64_default as convertFileToBase64, createFormData_default as createFormData, createTemplateStringsArray_default as createTemplateStringsArray, deepCopy_default as deepCopy, deepFreeze_default as deepFreeze, determineVersionType_default as determineVersionType, fillArray_default as fillArray, formatDateAndTime_default as formatDateAndTime, getIndividualVersionNumbers_default as getIndividualVersionNumbers, getRandomNumber_default as getRandomNumber, getRecordKeys_default as getRecordKeys, httpErrorCodeLookup, incrementVersion_default as incrementVersion, interpolate_default as interpolate, interpolateObjects_default as interpolateObjects, isAnniversary_default as isAnniversary, isLeapYear_default as isLeapYear, isMonthlyMultiple_default as isMonthlyMultiple, isOrdered_default as isOrdered, isSameDate_default as isSameDate, kebabToCamel_default as kebabToCamel, normaliseImportPath, normaliseIndents_default as normaliseIndents, normalizeImportPath_default as normalizeImportPath, normalizeIndents, omitProperties_default as omitProperties, paralleliseArrays_default as paralleliseArrays, parseBoolean_default as parseBoolean, parseEnv_default as parseEnv, parseFormData_default as parseFormData, parseIntStrict_default as parseIntStrict, parseVersion_default as parseVersion, parseVersionType_default as parseVersionType, parseZodSchema_default as parseZodSchema, randomiseArray_default as randomiseArray, range_default as range, removeDuplicates_default as removeDuplicates, stringListToArray_default as stringListToArray, truncate_default as truncate, wait_default as wait };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alextheman/utility",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "description": "Helpful utility functions",
   "repository": {
     "type": "git",
@@ -19,9 +19,9 @@
     "zod": "^4.2.1"
   },
   "devDependencies": {
-    "@alextheman/eslint-plugin": "^4.9.0",
+    "@alextheman/eslint-plugin": "^5.0.1",
     "@types/node": "^25.0.3",
-    "alex-c-line": "^1.9.0",
+    "alex-c-line": "^1.10.0",
     "dotenv-cli": "^11.0.0",
     "eslint": "^9.39.2",
     "eslint-plugin-perfectionist": "^5.0.0",
@@ -34,6 +34,9 @@
     "vite-tsconfig-paths": "^6.0.3",
     "vitest": "^4.0.16"
   },
+  "engines": {
+    "node": ">=22.0.0"
+  },
   "scripts": {
     "build": "tsdown",
     "create-local-package": "pnpm run build && rm -f alextheman-utility-*.tgz && pnpm pack",