@alextheman/utility 3.7.0 → 3.8.0

package/dist/index.cjs

@@ -34,6 +34,11 @@ path = __toESM(path);
 const NAMESPACE_EXPORT_REGEX = "export\\s+\\*\\s+from";
 var NAMESPACE_EXPORT_REGEX_default = NAMESPACE_EXPORT_REGEX;
 
+//#endregion
+//#region src/constants/VERSION_NUMBER_REGEX.ts
+const VERSION_NUMBER_REGEX = "^(?:v)?(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$";
+var VERSION_NUMBER_REGEX_default = VERSION_NUMBER_REGEX;
+
 //#endregion
 //#region src/functions/arrayHelpers/fillArray.ts
 /**
@@ -1058,10 +1063,65 @@ function removeIndents(first, ...args) {
 }
 var removeIndents_default = removeIndents;
 
+//#endregion
+//#region src/functions/versioning/parseVersion.ts
+/**
+* Parses a string and verifies it is a valid package version number.
+*
+* Valid formats: `X.Y.Z` or `vX.Y.Z`, where X, Y, and Z are non-negative integers.
+*
+* @param input - The version string to parse.
+* @param options - Extra options to apply.
+*
+* @throws {DataError} If the input is not a valid version number.
+*
+* @returns The validated version number, prefixed with `v` if it was not already.
+*/
+function parseVersion(input, options) {
+	if (!RegExp(VERSION_NUMBER_REGEX_default).test(input)) throw new DataError_default(input, `"${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.`, "INVALID_VERSION");
+	if (options?.omitPrefix) return input.startsWith("v") ? input.slice(1) : input;
+	return input.startsWith("v") ? input : `v${input}`;
+}
+var parseVersion_default = parseVersion;
+
+//#endregion
+//#region src/functions/versioning/getIndividualVersionNumbers.ts
+/**
+* Gets the individual version numbers from a given version number as a tuple of numbers.
+*
+* @param version - The version number.
+*
+* @returns A tuple of three numbers indicating `[major, minor, patch]`.
+*/
+function getIndividualVersionNumbers(version) {
+	return parseVersion_default(version, { omitPrefix: true }).split(".").map((versionNumber) => {
+		return parseIntStrict_default(versionNumber);
+	});
+}
+var getIndividualVersionNumbers_default = getIndividualVersionNumbers;
+
+//#endregion
+//#region src/functions/versioning/determineVersionType.ts
+/**
+* Determines whether the given version is a major, minor, or patch version.
+*
+* @param version - The version number.
+*
+* @returns Either `"major"`, `"minor"`, or `"patch"`, depending on the version type.
+*/
+function determineVersionType(version) {
+	const [_major, minor, patch] = getIndividualVersionNumbers_default(version);
+	if (minor === 0 && patch === 0) return "major";
+	if (patch === 0) return "minor";
+	return "patch";
+}
+var determineVersionType_default = determineVersionType;
+
 //#endregion
 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.addDaysToDate = addDaysToDate_default;
 exports.appendSemicolon = appendSemicolon_default;
 exports.camelToKebab = camelToKebab_default;
@@ -1070,8 +1130,10 @@ exports.createFormData = createFormData_default;
 exports.createTemplateStringsArray = createTemplateStringsArray_default;
 exports.deepCopy = deepCopy_default;
 exports.deepFreeze = deepFreeze_default;
+exports.determineVersionType = determineVersionType_default;
 exports.fillArray = fillArray_default;
 exports.formatDateAndTime = formatDateAndTime_default;
+exports.getIndividualVersionNumbers = getIndividualVersionNumbers_default;
 exports.getRandomNumber = getRandomNumber_default;
 exports.getRecordKeys = getRecordKeys_default;
 exports.httpErrorCodeLookup = httpErrorCodeLookup;
@@ -1095,6 +1157,7 @@ exports.parseEnv = parseEnv_default;
 exports.parseFormData = parseFormData_default;
 exports.parseIntStrict = parseIntStrict_default;
 exports.parseUUID = UUID_default;
+exports.parseVersion = parseVersion_default;
 exports.parseZodSchema = parseZodSchema_default;
 exports.randomiseArray = randomiseArray_default;
 exports.range = range_default;

package/dist/index.d.cts

@@ -3,6 +3,9 @@ import z, { 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";
 //#endregion
+//#region src/constants/VERSION_NUMBER_REGEX.d.ts
+declare const VERSION_NUMBER_REGEX: string;
+//#endregion
 //#region src/functions/arrayHelpers/fillArray.d.ts
 /**
  * Creates a new array where each element is the resolved result of the provided asynchronous callback.
@@ -698,4 +701,43 @@ declare function removeIndents(options: RemoveIndentsOptions): RemoveIndentsFunc
  */
 declare function removeIndents(strings: TemplateStringsArray, ...interpolations: unknown[]): string;
 //#endregion
-export { APIError, ArrayElement, CreateFormDataOptions, CreateFormDataOptionsNullableResolution, CreateFormDataOptionsUndefinedOrNullResolution, DataError, DeepReadonly, DisallowUndefined, Email, Env, FormDataArrayResolutionStrategy, FormDataNullableResolutionStrategy, HTTPErrorCode, IgnoreCase, KebabToCamelOptions, NAMESPACE_EXPORT_REGEX, NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, OptionalOnCondition, RecordKey, RemoveIndentsFunction, RemoveIndentsOptions, StringListToArrayOptions, UUID, addDaysToDate, appendSemicolon, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, kebabToCamel, normaliseImportPath, normaliseIndents, normalizeImportPath, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEmail, parseEnv, parseFormData, parseIntStrict, parseUUID, parseZodSchema, randomiseArray, range, removeDuplicates, removeIndents, stringListToArray, stringToBoolean, truncate, wait };
+//#region src/functions/versioning/determineVersionType.d.ts
+type VersionType = "major" | "minor" | "patch";
+/**
+ * Determines whether the given version is a major, minor, or patch version.
+ *
+ * @param version - The version number.
+ *
+ * @returns Either `"major"`, `"minor"`, or `"patch"`, depending on the version type.
+ */
+declare function determineVersionType(version: string): VersionType;
+//#endregion
+//#region src/functions/versioning/getIndividualVersionNumbers.d.ts
+/**
+ * Gets the individual version numbers from a given version number as a tuple of numbers.
+ *
+ * @param version - The version number.
+ *
+ * @returns A tuple of three numbers indicating `[major, minor, patch]`.
+ */
+declare function getIndividualVersionNumbers(version: string): [number, number, number];
+//#endregion
+//#region src/functions/versioning/parseVersion.d.ts
+interface ParseVersionOptions {
+  omitPrefix?: boolean;
+}
+/**
+ * Parses a string and verifies it is a valid package version number.
+ *
+ * Valid formats: `X.Y.Z` or `vX.Y.Z`, where X, Y, and Z are non-negative integers.
+ *
+ * @param input - The version string to parse.
+ * @param options - Extra options to apply.
+ *
+ * @throws {DataError} If the input is not a valid version number.
+ *
+ * @returns The validated version number, prefixed with `v` if it was not already.
+ */
+declare function parseVersion(input: string, options?: ParseVersionOptions): string;
+//#endregion
+export { APIError, ArrayElement, CreateFormDataOptions, CreateFormDataOptionsNullableResolution, CreateFormDataOptionsUndefinedOrNullResolution, DataError, DeepReadonly, DisallowUndefined, Email, Env, FormDataArrayResolutionStrategy, FormDataNullableResolutionStrategy, HTTPErrorCode, IgnoreCase, KebabToCamelOptions, NAMESPACE_EXPORT_REGEX, NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, OptionalOnCondition, RecordKey, RemoveIndentsFunction, RemoveIndentsOptions, StringListToArrayOptions, UUID, VERSION_NUMBER_REGEX, VersionType, addDaysToDate, appendSemicolon, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, determineVersionType, fillArray, formatDateAndTime, getIndividualVersionNumbers, getRandomNumber, getRecordKeys, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, kebabToCamel, normaliseImportPath, normaliseIndents, normalizeImportPath, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEmail, parseEnv, parseFormData, parseIntStrict, parseUUID, parseVersion, parseZodSchema, randomiseArray, range, removeDuplicates, removeIndents, stringListToArray, stringToBoolean, truncate, wait };

package/dist/index.d.ts

@@ -3,6 +3,9 @@ import z, { 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";
 //#endregion
+//#region src/constants/VERSION_NUMBER_REGEX.d.ts
+declare const VERSION_NUMBER_REGEX: string;
+//#endregion
 //#region src/functions/arrayHelpers/fillArray.d.ts
 /**
  * Creates a new array where each element is the resolved result of the provided asynchronous callback.
@@ -698,4 +701,43 @@ declare function removeIndents(options: RemoveIndentsOptions): RemoveIndentsFunc
  */
 declare function removeIndents(strings: TemplateStringsArray, ...interpolations: unknown[]): string;
 //#endregion
-export { APIError, type ArrayElement, type CreateFormDataOptions, type CreateFormDataOptionsNullableResolution, type CreateFormDataOptionsUndefinedOrNullResolution, DataError, type DeepReadonly, type DisallowUndefined, type Email, type Env, type FormDataArrayResolutionStrategy, type FormDataNullableResolutionStrategy, type HTTPErrorCode, type IgnoreCase, KebabToCamelOptions, NAMESPACE_EXPORT_REGEX, type NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, type OptionalOnCondition, type RecordKey, RemoveIndentsFunction, RemoveIndentsOptions, type StringListToArrayOptions, type UUID, addDaysToDate, appendSemicolon, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, kebabToCamel, normaliseImportPath, normaliseIndents, normalizeImportPath, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEmail, parseEnv, parseFormData, parseIntStrict, parseUUID, parseZodSchema, randomiseArray, range, removeDuplicates, removeIndents, stringListToArray, stringToBoolean, truncate, wait };
+//#region src/functions/versioning/determineVersionType.d.ts
+type VersionType = "major" | "minor" | "patch";
+/**
+ * Determines whether the given version is a major, minor, or patch version.
+ *
+ * @param version - The version number.
+ *
+ * @returns Either `"major"`, `"minor"`, or `"patch"`, depending on the version type.
+ */
+declare function determineVersionType(version: string): VersionType;
+//#endregion
+//#region src/functions/versioning/getIndividualVersionNumbers.d.ts
+/**
+ * Gets the individual version numbers from a given version number as a tuple of numbers.
+ *
+ * @param version - The version number.
+ *
+ * @returns A tuple of three numbers indicating `[major, minor, patch]`.
+ */
+declare function getIndividualVersionNumbers(version: string): [number, number, number];
+//#endregion
+//#region src/functions/versioning/parseVersion.d.ts
+interface ParseVersionOptions {
+  omitPrefix?: boolean;
+}
+/**
+ * Parses a string and verifies it is a valid package version number.
+ *
+ * Valid formats: `X.Y.Z` or `vX.Y.Z`, where X, Y, and Z are non-negative integers.
+ *
+ * @param input - The version string to parse.
+ * @param options - Extra options to apply.
+ *
+ * @throws {DataError} If the input is not a valid version number.
+ *
+ * @returns The validated version number, prefixed with `v` if it was not already.
+ */
+declare function parseVersion(input: string, options?: ParseVersionOptions): string;
+//#endregion
+export { APIError, type ArrayElement, type CreateFormDataOptions, type CreateFormDataOptionsNullableResolution, type CreateFormDataOptionsUndefinedOrNullResolution, DataError, type DeepReadonly, type DisallowUndefined, type Email, type Env, type FormDataArrayResolutionStrategy, type FormDataNullableResolutionStrategy, type HTTPErrorCode, type IgnoreCase, KebabToCamelOptions, NAMESPACE_EXPORT_REGEX, type NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, type OptionalOnCondition, type RecordKey, RemoveIndentsFunction, RemoveIndentsOptions, type StringListToArrayOptions, type UUID, VERSION_NUMBER_REGEX, VersionType, addDaysToDate, appendSemicolon, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, determineVersionType, fillArray, formatDateAndTime, getIndividualVersionNumbers, getRandomNumber, getRecordKeys, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, kebabToCamel, normaliseImportPath, normaliseIndents, normalizeImportPath, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEmail, parseEnv, parseFormData, parseIntStrict, parseUUID, parseVersion, parseZodSchema, randomiseArray, range, removeDuplicates, removeIndents, stringListToArray, stringToBoolean, truncate, wait };

package/dist/index.js

@@ -5,6 +5,11 @@ import path from "path";
 const NAMESPACE_EXPORT_REGEX = "export\\s+\\*\\s+from";
 var NAMESPACE_EXPORT_REGEX_default = NAMESPACE_EXPORT_REGEX;
 
+//#endregion
+//#region src/constants/VERSION_NUMBER_REGEX.ts
+const VERSION_NUMBER_REGEX = "^(?:v)?(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$";
+var VERSION_NUMBER_REGEX_default = VERSION_NUMBER_REGEX;
+
 //#endregion
 //#region src/functions/arrayHelpers/fillArray.ts
 /**
@@ -1030,4 +1035,58 @@ function removeIndents(first, ...args) {
 var removeIndents_default = removeIndents;
 
 //#endregion
-export { APIError_default as APIError, DataError_default as DataError, NAMESPACE_EXPORT_REGEX_default as NAMESPACE_EXPORT_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, fillArray_default as fillArray, formatDateAndTime_default as formatDateAndTime, getRandomNumber_default as getRandomNumber, getRecordKeys_default as getRecordKeys, httpErrorCodeLookup, 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, Email_default as parseEmail, parseEnv_default as parseEnv, parseFormData_default as parseFormData, parseIntStrict_default as parseIntStrict, UUID_default as parseUUID, parseZodSchema_default as parseZodSchema, randomiseArray_default as randomiseArray, range_default as range, removeDuplicates_default as removeDuplicates, removeIndents_default as removeIndents, stringListToArray_default as stringListToArray, stringToBoolean, truncate_default as truncate, wait_default as wait };
+//#region src/functions/versioning/parseVersion.ts
+/**
+* Parses a string and verifies it is a valid package version number.
+*
+* Valid formats: `X.Y.Z` or `vX.Y.Z`, where X, Y, and Z are non-negative integers.
+*
+* @param input - The version string to parse.
+* @param options - Extra options to apply.
+*
+* @throws {DataError} If the input is not a valid version number.
+*
+* @returns The validated version number, prefixed with `v` if it was not already.
+*/
+function parseVersion(input, options) {
+	if (!RegExp(VERSION_NUMBER_REGEX_default).test(input)) throw new DataError_default(input, `"${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.`, "INVALID_VERSION");
+	if (options?.omitPrefix) return input.startsWith("v") ? input.slice(1) : input;
+	return input.startsWith("v") ? input : `v${input}`;
+}
+var parseVersion_default = parseVersion;
+
+//#endregion
+//#region src/functions/versioning/getIndividualVersionNumbers.ts
+/**
+* Gets the individual version numbers from a given version number as a tuple of numbers.
+*
+* @param version - The version number.
+*
+* @returns A tuple of three numbers indicating `[major, minor, patch]`.
+*/
+function getIndividualVersionNumbers(version) {
+	return parseVersion_default(version, { omitPrefix: true }).split(".").map((versionNumber) => {
+		return parseIntStrict_default(versionNumber);
+	});
+}
+var getIndividualVersionNumbers_default = getIndividualVersionNumbers;
+
+//#endregion
+//#region src/functions/versioning/determineVersionType.ts
+/**
+* Determines whether the given version is a major, minor, or patch version.
+*
+* @param version - The version number.
+*
+* @returns Either `"major"`, `"minor"`, or `"patch"`, depending on the version type.
+*/
+function determineVersionType(version) {
+	const [_major, minor, patch] = getIndividualVersionNumbers_default(version);
+	if (minor === 0 && patch === 0) return "major";
+	if (patch === 0) return "minor";
+	return "patch";
+}
+var determineVersionType_default = determineVersionType;
+
+//#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, 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, Email_default as parseEmail, parseEnv_default as parseEnv, parseFormData_default as parseFormData, parseIntStrict_default as parseIntStrict, UUID_default as parseUUID, parseVersion_default as parseVersion, parseZodSchema_default as parseZodSchema, randomiseArray_default as randomiseArray, range_default as range, removeDuplicates_default as removeDuplicates, removeIndents_default as removeIndents, stringListToArray_default as stringListToArray, stringToBoolean, truncate_default as truncate, wait_default as wait };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alextheman/utility",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "description": "Helpful utility functions",
   "repository": {
     "type": "git",
@@ -19,7 +19,7 @@
     "zod": "^4.1.13"
   },
   "devDependencies": {
-    "@alextheman/eslint-plugin": "^4.8.4",
+    "@alextheman/eslint-plugin": "^4.8.6",
     "@types/node": "^25.0.1",
     "dotenv-cli": "^11.0.0",
     "eslint": "^9.39.1",