@alextheman/utility 3.6.0 → 3.8.0

package/dist/index.js

@@ -1,19 +1,14 @@
-import path from "path";
 import z, { z as z$1 } from "zod";
+import path from "path";
 
 //#region src/constants/NAMESPACE_EXPORT_REGEX.ts
 const NAMESPACE_EXPORT_REGEX = "export\\s+\\*\\s+from";
 var NAMESPACE_EXPORT_REGEX_default = NAMESPACE_EXPORT_REGEX;
 
 //#endregion
-//#region src/functions/appendSemicolon.ts
-function appendSemicolon(stringToAppendTo) {
-	if (stringToAppendTo.includes("\n")) throw new Error("MULTIPLE_LINE_ERROR");
-	const stringWithNoTrailingWhitespace = stringToAppendTo.trimEnd();
-	if (stringWithNoTrailingWhitespace === "") return "";
-	return stringWithNoTrailingWhitespace[stringWithNoTrailingWhitespace.length - 1] === ";" ? stringWithNoTrailingWhitespace : `${stringWithNoTrailingWhitespace};`;
-}
-var appendSemicolon_default = appendSemicolon;
+//#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
@@ -67,7 +62,17 @@ var paralleliseArrays_default = paralleliseArrays;
 //#endregion
 //#region src/functions/parsers/parseIntStrict.ts
 const IntegerParsingError = /* @__PURE__ */ new TypeError("INTEGER_PARSING_ERROR");
-function parseIntStrict(...[string, radix]) {
+/**
+* Converts a string to an integer and throws an error if it cannot be converted.
+*
+* @param string — A string to convert into a number.
+* @param radix - A value between 2 and 36 that specifies the base of the number in string. If this argument is not supplied, strings with a prefix of '0x' are considered hexadecimal. All other strings are considered decimal.
+*
+* @throws {TypeError} If the provided string cannot safely be converted to an integer.
+*
+* @returns The integer parsed from the input string.
+*/
+function parseIntStrict(string, radix) {
 	const trimmedString = string.trim();
 	if (!(radix && radix > 10 && radix <= 36 ? new RegExp(`^[+-]?[0-9a-${String.fromCharCode(87 + radix - 1)}]+$`, "i") : /^[+-]?\d+$/).test(trimmedString)) throw IntegerParsingError;
 	if (radix && radix < 10 && [...trimmedString].some((character) => {
@@ -80,7 +85,15 @@ function parseIntStrict(...[string, radix]) {
 var parseIntStrict_default = parseIntStrict;
 
 //#endregion
-//#region src/functions/getRandomNumber.ts
+//#region src/functions/miscellaneous/getRandomNumber.ts
+/**
+* Gets a random number between the given bounds.
+*
+* @param lowerBound - The lowest number that can be chosen.
+* @param upperBound - The highest number that can be chosen.
+*
+* @returns A random number between the provided lower bound and upper bound.
+*/
 function getRandomNumber(lowerBound, upperBound) {
 	const parsedLowerBound = parseIntStrict_default(`${lowerBound}`);
 	const parsedUpperBound = parseIntStrict_default(`${upperBound}`);
@@ -115,8 +128,8 @@ var randomiseArray_default = randomiseArray;
 /**
 * Creates an array of numbers within a given range.
 *
-* The range is inclusive of `start` and exclusive of `stop`.
-* The sign of `step` must match the direction of the range.
+* - The range is inclusive of `start` and exclusive of `stop`.
+* - The sign of `step` must match the direction of the range.
 *
 * @param start - The number to start at (inclusive).
 * @param stop - The number to stop at (exclusive).
@@ -142,96 +155,22 @@ function range(start, stop, step = 1) {
 var range_default = range;
 
 //#endregion
-//#region src/functions/camelToKebab.ts
-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();
-}
-var camelToKebab_default = camelToKebab;
-
-//#endregion
-//#region src/functions/convertFileToBase64.ts
-function convertFileToBase64(file) {
-	return new Promise((resolve, reject) => {
-		const reader = new FileReader();
-		reader.readAsDataURL(file);
-		reader.onload = () => {
-			if (reader.result === null) {
-				reject(/* @__PURE__ */ new Error("FILE_CONVERSION_ERROR"));
-				return;
-			}
-			resolve(reader.result);
-		};
-		reader.onerror = () => {
-			reject(/* @__PURE__ */ new Error("FILE_READER_ERROR"));
-		};
-	});
-}
-var convertFileToBase64_default = convertFileToBase64;
-
-//#endregion
-//#region src/functions/createFormData.ts
-function getNullableResolutionStrategy(key, strategy) {
-	return (typeof strategy === "object" ? strategy[key] : strategy) ?? "empty";
-}
-function createFormData(data, options = {
-	arrayResolution: "stringify",
-	nullableResolution: "empty"
-}) {
-	const formData = new FormData();
-	function resolveNullablesByStrategy(key, value, resolutionStrategy) {
-		switch (resolutionStrategy) {
-			case "empty":
-				formData.append(String(key), "");
-				break;
-			case "stringify":
-				formData.append(String(key), JSON.stringify(value));
-				break;
-			case "omit": break;
-			default: throw new TypeError("SLOPPY_PURE_JAVASCRIPT_USER_ERROR");
-		}
-	}
-	function resolveNullables(key, value, options$1) {
-		if (options$1.nullableResolution) {
-			resolveNullablesByStrategy(key, value, getNullableResolutionStrategy(key, options$1.nullableResolution));
-			return;
-		}
-		if (options$1.undefinedResolution || options$1.nullResolution) {
-			if (data[key] === void 0 && options$1.undefinedResolution) {
-				resolveNullablesByStrategy(key, value, getNullableResolutionStrategy(key, options$1.undefinedResolution));
-				return;
-			}
-			if (data[key] === null && options$1.nullResolution) resolveNullablesByStrategy(key, value, getNullableResolutionStrategy(key, options$1.nullResolution));
-		}
-	}
-	const entries = Object.entries(data);
-	for (const [key, value] of entries) if (value instanceof Blob) formData.append(String(key), value);
-	else if (value === void 0 || value === null) resolveNullables(key, value, options);
-	else if (typeof value === "object") {
-		if (Array.isArray(value)) {
-			if (value.some((item) => {
-				return item instanceof Blob;
-			}) && (options.arrayResolution === "stringify" || typeof options.arrayResolution === "object" && options.arrayResolution[key] === "stringify")) throw new TypeError("CANNOT_STRINGIFY_BLOB");
-			if (options.arrayResolution === "multiple" || typeof options.arrayResolution === "object" && options.arrayResolution[key] === "multiple") {
-				for (const item of value) {
-					if ((typeof item === "object" || !item) && !(item instanceof Blob)) throw new TypeError("NON_PRIMITIVE_ARRAY_ITEMS_FOUND");
-					if (item instanceof Blob) formData.append(String(key), item);
-					else formData.append(String(key), String(item));
-				}
-				continue;
-			}
-		}
-		formData.append(String(key), JSON.stringify(value));
-	} else formData.append(String(key), String(value));
-	return formData;
-}
-var createFormData_default = createFormData;
-
-//#endregion
-//#region src/functions/createTemplateStringsArray.ts
-function createTemplateStringsArray(strings) {
-	return Object.assign([...strings], { raw: [...strings] });
+//#region src/functions/arrayHelpers/removeDuplicates.ts
+/**
+* Removes duplicate values from an array.
+*
+* @template ItemType - The type of the array items.
+*
+* @param array - The array to remove duplicates from.
+*
+* @returns A new array with a different reference in memory, with the duplicates removed.
+*/
+function removeDuplicates(array) {
+	const outputArray = [];
+	for (const item of array) if (!outputArray.includes(item)) outputArray.push(item);
+	return outputArray;
 }
-var createTemplateStringsArray_default = createTemplateStringsArray;
+var removeDuplicates_default = removeDuplicates;
 
 //#endregion
 //#region src/functions/date/addDaysToDate.ts
@@ -374,43 +313,111 @@ function isMonthlyMultiple(firstDate, secondDate) {
 var isMonthlyMultiple_default = isMonthlyMultiple;
 
 //#endregion
-//#region src/functions/deepCopy.ts
-function callDeepCopy(input) {
-	return typeof input === "object" && input !== null ? deepCopy(input) : input;
-}
-function deepCopy(object) {
-	if (Array.isArray(object)) return object.map((item) => {
-		return callDeepCopy(item);
+//#region src/functions/miscellaneous/convertFileToBase64.ts
+/**
+* Asynchronously converts a file to a base 64 string
+*
+* @param file - The file to convert.
+*
+* @throws {Error} If the file reader gives an error.
+*
+* @returns A promise that resolves to the encoded base 64 string.
+*/
+function convertFileToBase64(file) {
+	return new Promise((resolve, reject) => {
+		const reader = new FileReader();
+		reader.readAsDataURL(file);
+		reader.onload = () => {
+			if (reader.result === null) {
+				reject(/* @__PURE__ */ new Error("FILE_CONVERSION_ERROR"));
+				return;
+			}
+			resolve(reader.result);
+		};
+		reader.onerror = () => {
+			reject(/* @__PURE__ */ new Error("FILE_READER_ERROR"));
+		};
 	});
-	const clonedObject = { ...object };
-	for (const key in clonedObject) {
-		const value = clonedObject[key];
-		clonedObject[key] = callDeepCopy(value);
-	}
-	return clonedObject;
 }
-var deepCopy_default = deepCopy;
+var convertFileToBase64_default = convertFileToBase64;
 
 //#endregion
-//#region src/functions/deepFreeze.ts
-function deepFreeze(object) {
-	for (const value of Object.values(object)) {
-		if (typeof value === "function") continue;
-		if (value && typeof value === "object") deepFreeze(value);
-	}
-	return Object.freeze(object);
+//#region src/functions/miscellaneous/createFormData.ts
+function getNullableResolutionStrategy(key, strategy) {
+	return (typeof strategy === "object" ? strategy[key] : strategy) ?? "empty";
 }
-var deepFreeze_default = deepFreeze;
-
-//#endregion
-//#region src/functions/getRecordKeys.ts
-function getRecordKeys(record) {
-	return Object.keys(record);
+/**
+* Creates FormData from a given object, resolving non-string types as appropriate.
+*
+* @template DataType - The type of the given data.
+*
+* @param data - The data to create FormData from.
+* @param options - Options to apply to the conversion.
+*
+* @returns A FormData object with the data applied.
+*/
+function createFormData(data, options = {
+	arrayResolution: "stringify",
+	nullableResolution: "empty"
+}) {
+	const formData = new FormData();
+	function resolveNullablesByStrategy(key, value, resolutionStrategy) {
+		switch (resolutionStrategy) {
+			case "empty":
+				formData.append(String(key), "");
+				break;
+			case "stringify":
+				formData.append(String(key), JSON.stringify(value));
+				break;
+			case "omit": break;
+			default: throw new TypeError("SLOPPY_PURE_JAVASCRIPT_USER_ERROR");
+		}
+	}
+	function resolveNullables(key, value, options$1) {
+		if (options$1.nullableResolution) {
+			resolveNullablesByStrategy(key, value, getNullableResolutionStrategy(key, options$1.nullableResolution));
+			return;
+		}
+		if (options$1.undefinedResolution || options$1.nullResolution) {
+			if (data[key] === void 0 && options$1.undefinedResolution) {
+				resolveNullablesByStrategy(key, value, getNullableResolutionStrategy(key, options$1.undefinedResolution));
+				return;
+			}
+			if (data[key] === null && options$1.nullResolution) resolveNullablesByStrategy(key, value, getNullableResolutionStrategy(key, options$1.nullResolution));
+		}
+	}
+	const entries = Object.entries(data);
+	for (const [key, value] of entries) if (value instanceof Blob) formData.append(String(key), value);
+	else if (value === void 0 || value === null) resolveNullables(key, value, options);
+	else if (typeof value === "object") {
+		if (Array.isArray(value)) {
+			if (value.some((item) => {
+				return item instanceof Blob;
+			}) && (options.arrayResolution === "stringify" || typeof options.arrayResolution === "object" && options.arrayResolution[key] === "stringify")) throw new TypeError("CANNOT_STRINGIFY_BLOB");
+			if (options.arrayResolution === "multiple" || typeof options.arrayResolution === "object" && options.arrayResolution[key] === "multiple") {
+				for (const item of value) {
+					if ((typeof item === "object" || !item) && !(item instanceof Blob)) throw new TypeError("NON_PRIMITIVE_ARRAY_ITEMS_FOUND");
+					if (item instanceof Blob) formData.append(String(key), item);
+					else formData.append(String(key), String(item));
+				}
+				continue;
+			}
+		}
+		formData.append(String(key), JSON.stringify(value));
+	} else formData.append(String(key), String(value));
+	return formData;
 }
-var getRecordKeys_default = getRecordKeys;
+var createFormData_default = createFormData;
 
 //#endregion
-//#region src/functions/isOrdered.ts
+//#region src/functions/miscellaneous/isOrdered.ts
+/**
+* Checks to see if the given array is sorted in ascending order.
+*
+* @param array - The array to check.
+*
+* @returns `true` if the array is sorted in ascending order, and `false` otherwise.
+*/
 function isOrdered(array) {
 	const newArray = [...array];
 	newArray.sort();
@@ -420,47 +427,73 @@ function isOrdered(array) {
 var isOrdered_default = isOrdered;
 
 //#endregion
-//#region src/functions/kebabToCamel.ts
-function kebabToCamel(string, options) {
-	if (string !== string.toLowerCase()) throw new Error("INVALID_KEBAB_CASE_INPUT");
-	if (string.startsWith("-") || string.endsWith("-") || string.includes("--")) throw new Error("INVALID_KEBAB_CASE_INPUT");
-	let outputString = "";
-	let skip = false;
-	for (const stringIndex in [...string]) {
-		if (skip) {
-			skip = false;
-			continue;
-		}
-		const index = parseIntStrict_default(stringIndex);
-		if (index === 0 && options?.startWithUpper) {
-			outputString += string[index].toUpperCase();
-			continue;
-		}
-		if (index === string.length - 1) {
-			outputString += string[index];
-			break;
-		}
-		if (string[index] === "-" && /^[a-zA-Z]+$/.test(string[index + 1])) {
-			outputString += string[index + 1].toUpperCase();
-			skip = true;
-		} else outputString += string[index];
-	}
-	return outputString;
+//#region src/functions/miscellaneous/stringListToArray.ts
+/**
+* Converts a stringly-typed list to a proper array.
+*
+* @param stringList - The stringly-typed list to convert.
+* @param options - The options to apply to the conversion.
+* @param options.separator - What each item in the list is separated by.
+* @param options.trimWhitespace - An option to trim any extra whitespace.
+*
+* @returns A new array with each item being an item from the given list.
+*/
+function stringListToArray(stringList, { separator = ",", trimWhitespace = true } = {}) {
+	if (trimWhitespace && stringList.trim() === "") return [];
+	const arrayList = stringList.split(separator ?? "");
+	return trimWhitespace ? arrayList.map((item) => {
+		return item.trim();
+	}) : arrayList;
 }
-var kebabToCamel_default = kebabToCamel;
+var stringListToArray_default = stringListToArray;
 
 //#endregion
-//#region src/functions/normalizeImportPath.ts
-function normalizeImportPath(importPath) {
-	const normalizedPath = path.posix.normalize(importPath);
-	if (importPath.startsWith("./") && !normalizedPath.startsWith("./")) return `./${normalizedPath}`;
-	return normalizedPath;
+//#region src/functions/miscellaneous/wait.ts
+/**
+* Waits for the given number of seconds
+*
+* @param seconds - The number of seconds to wait.
+*
+* @returns A Promise that resolves after the given number of seconds.
+*/
+function wait(seconds) {
+	return new Promise((resolve, _) => {
+		setTimeout(() => {
+			resolve();
+		}, seconds * 1e3);
+	});
 }
-const normaliseImportPath = normalizeImportPath;
-var normalizeImportPath_default = normalizeImportPath;
+var wait_default = wait;
+
+//#endregion
+//#region src/functions/objectHelpers/getRecordKeys.ts
+/**
+* Gets the keys from a given record object, properly typed to be an array of the key of the input object's type.
+*
+* @template InputRecordType - The type of the input object.
+*
+* @param record - The record to get the keys from.
+*
+* @returns An array with all the keys of the input object in string form, but properly typed as `keyof InputRecordType`.
+*/
+function getRecordKeys(record) {
+	return Object.keys(record);
+}
+var getRecordKeys_default = getRecordKeys;
 
 //#endregion
-//#region src/functions/omitProperties.ts
+//#region src/functions/objectHelpers/omitProperties.ts
+/**
+* Omits properties from a given object.
+*
+* @template ObjectType - The type of the input object.
+* @template KeysToOmit - A type representing the keys to omit from the object.
+*
+* @param object - The object to omit properties from.
+* @param keysToOmit - The keys to omit from the object. Can either be a single string to omit one, or an array to omit multiple.
+*
+* @returns An object with a new reference in memory, with the properties omitted.
+*/
 function omitProperties(object, keysToOmit) {
 	const outputObject = { ...object };
 	(Array.isArray(keysToOmit) ? keysToOmit : [keysToOmit]).forEach((key) => {
@@ -472,6 +505,15 @@ var omitProperties_default = omitProperties;
 
 //#endregion
 //#region src/functions/parsers/parseBoolean.ts
+/**
+* Takes a stringly-typed boolean and converts it to an actual boolean type.
+*
+* @param inputString - The string to parse.
+*
+* @throws {TypeError} If the string is not either `true` or `false` (case insensitive).
+*
+* @returns The string parsed as an actual boolean.
+*/
 function parseBoolean(inputString) {
 	const normalisedString = inputString.toLowerCase();
 	if (!["true", "false"].includes(normalisedString)) throw new TypeError("INVALID_BOOLEAN_STRING");
@@ -488,6 +530,15 @@ const envSchema = z$1.enum([
 	"development",
 	"production"
 ]);
+/**
+* Parses the input and verifies it matches one of the environments allowed by the Env types ("test" | "development" | "production").
+*
+* @param data - The data to parse.
+*
+* @throws {ZodError} If the data does not match one of the environments allowed by the Env types ("test" | "development" | "production").
+*
+* @returns The specified environment if allowed.
+*/
 function parseEnv(data) {
 	return envSchema.parse(data);
 }
@@ -495,6 +546,16 @@ var parseEnv_default = parseEnv;
 
 //#endregion
 //#region src/functions/parsers/parseFormData.ts
+/**
+* Returns an object given FormData and an optional data parser function to call on the resulting object.
+*
+* @template DataType - The type of the resulting object when called from the dataParser.
+*
+* @param formData - The FormData to parse.
+* @param dataParser - An optional parser to call on the object before it gets returned.
+*
+* @returns A parsed object based on the contents of the input formData and the result of parsing with the data parser if provided.
+*/
 function parseFormData(formData, dataParser) {
 	const object = {};
 	formData.forEach((value, key) => {
@@ -515,8 +576,14 @@ const httpErrorCodeLookup = {
 	418: "I_AM_A_TEAPOT",
 	500: "INTERNAL_SERVER_ERROR"
 };
+/** Represents common errors you may get from a HTTP API request. */
 var APIError = class extends Error {
 	status;
+	/**
+	* @param status - A HTTP status code. Can be any number, but numbers between 400 and 600 are encouraged to fit with HTTP status code conventions.
+	* @param message - An error message to display alongside the status code.
+	* @param options - Extra options to be passed to super Error constructor.
+	*/
 	constructor(status = 500, message, options) {
 		super(message, options);
 		this.status = status;
@@ -525,6 +592,13 @@ var APIError = class extends Error {
 		Object.defineProperty(this, "message", { enumerable: true });
 		Object.setPrototypeOf(this, new.target.prototype);
 	}
+	/**
+	* Checks whether the given input may have been caused by an APIError.
+	*
+	* @param input - The input to check.
+	*
+	* @returns `true` if the input is an APIError, and `false` otherwise. The type of the input will also be narrowed down to APIError if `true`.
+	*/
 	static check(input) {
 		const data = input;
 		return typeof data === "object" && data !== null && typeof data?.status === "number" && typeof data?.message === "string";
@@ -534,6 +608,7 @@ var APIError_default = APIError;
 
 //#endregion
 //#region src/types/DataError.ts
+/** Represents errors you may get that may've been caused by a specific piece of data. */
 var DataError = class extends Error {
 	data;
 	code;
@@ -552,6 +627,13 @@ var DataError = class extends Error {
 		Object.defineProperty(this, "message", { enumerable: true });
 		Object.setPrototypeOf(this, new.target.prototype);
 	}
+	/**
+	* Checks whether the given input may have been caused by a DataError.
+	*
+	* @param input - The input to check.
+	*
+	* @returns `true` if the input is a DataError, and `false` otherwise. The type of the input will also be narrowed down to DataError if `true`.
+	*/
 	static check(input) {
 		const data = input;
 		return typeof data === "object" && data !== null && typeof data.message === "string" && typeof data.code === "string" && "data" in data;
@@ -579,6 +661,20 @@ var UUID_default = parseUUID;
 
 //#endregion
 //#region src/functions/parsers/parseZodSchema.ts
+/**
+* An alternative function to zodSchema.parse() that can be used to strictly parse Zod schemas.
+*
+* @template Output - The Zod output type.
+* @template Input - The Zod input type.
+* @template Internals - The Zod internal types based on the output and input types.
+*
+* @param schema - The Zod schema to use in parsing.
+* @param data - The data to parse.
+*
+* @throws {DataError} If the given data cannot be parsed according to the schema.
+*
+* @returns The parsed data from the Zod schema.
+*/
 function parseZodSchema(schema, data) {
 	const parsedResult = schema.safeParse(data);
 	if (!parsedResult.success) throw new DataError_default(data);
@@ -587,27 +683,207 @@ function parseZodSchema(schema, data) {
 var parseZodSchema_default = parseZodSchema;
 
 //#endregion
-//#region src/functions/removeDuplicates.ts
-function removeDuplicates(array) {
-	const outputArray = [];
-	for (const item of array) if (!outputArray.includes(item)) outputArray.push(item);
-	return outputArray;
+//#region src/functions/recursive/deepCopy.ts
+function callDeepCopy(input) {
+	return typeof input === "object" && input !== null ? deepCopy(input) : input;
 }
-var removeDuplicates_default = removeDuplicates;
+/**
+* Deeply copies an object or array such that all child objects/arrays are also copied.
+*
+* @template ObjectType - The type of the input object.
+*
+* @param object - The object to copy. May also be an array.
+*
+* @returns An identical object with a new reference in memory.
+*/
+function deepCopy(object) {
+	if (Array.isArray(object)) return object.map((item) => {
+		return callDeepCopy(item);
+	});
+	const clonedObject = { ...object };
+	for (const key in clonedObject) {
+		const value = clonedObject[key];
+		clonedObject[key] = callDeepCopy(value);
+	}
+	return clonedObject;
+}
+var deepCopy_default = deepCopy;
 
 //#endregion
-//#region src/functions/stringListToArray.ts
-function stringListToArray(stringList, { separator = ",", trimWhitespace = true } = {}) {
-	if (trimWhitespace && stringList.trim() === "") return [];
-	const arrayList = stringList.split(separator ?? "");
-	return trimWhitespace ? arrayList.map((item) => {
-		return item.trim();
-	}) : arrayList;
+//#region src/functions/recursive/deepFreeze.ts
+/**
+* Deeply freezes an object or array such that all child objects/arrays are also frozen.
+*
+* Note that this will also freeze the input itself as well.
+* If the intent is to create a newly frozen object with a different reference in memory, pass your object through deepCopy first before passing to deepFreeze.
+*
+* @template ObjectType - The type of the input object.
+*
+* @param object - The object to freeze. May also be an array.
+*
+* @returns The input object completely frozen.
+*/
+function deepFreeze(object) {
+	for (const value of Object.values(object)) {
+		if (typeof value === "function") continue;
+		if (value && typeof value === "object") deepFreeze(value);
+	}
+	return Object.freeze(object);
 }
-var stringListToArray_default = stringListToArray;
+var deepFreeze_default = deepFreeze;
+
+//#endregion
+//#region src/functions/stringHelpers/appendSemicolon.ts
+/**
+* Appends a semicolon to the end of a string, trimming where necessary first.
+*
+* @param stringToAppendTo - The string to append a semicolon to.
+*
+* @throws {Error} If the string contains multiple lines.
+*
+* @returns A string with the semicolon appended.
+*/
+function appendSemicolon(stringToAppendTo) {
+	if (stringToAppendTo.includes("\n")) throw new Error("MULTIPLE_LINE_ERROR");
+	const stringWithNoTrailingWhitespace = stringToAppendTo.trimEnd();
+	if (stringWithNoTrailingWhitespace === "") return "";
+	return stringWithNoTrailingWhitespace[stringWithNoTrailingWhitespace.length - 1] === ";" ? stringWithNoTrailingWhitespace : `${stringWithNoTrailingWhitespace};`;
+}
+var appendSemicolon_default = appendSemicolon;
+
+//#endregion
+//#region src/functions/stringHelpers/camelToKebab.ts
+/**
+* Converts a string from camelCase to kebab-case
+*
+* @param string - The string to convert.
+*
+* @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();
+}
+var camelToKebab_default = camelToKebab;
+
+//#endregion
+//#region src/functions/stringHelpers/kebabToCamel.ts
+/**
+* Converts a string from kebab-case to camelCase
+*
+* @param string - The string to convert.
+* @param options - Options to apply to the conversion.
+*
+* @returns The string converted to camelCase.
+*/
+function kebabToCamel(string, options) {
+	if (string !== string.toLowerCase()) throw new Error("INVALID_KEBAB_CASE_INPUT");
+	if (string.startsWith("-") || string.endsWith("-") || string.includes("--")) throw new Error("INVALID_KEBAB_CASE_INPUT");
+	let outputString = "";
+	let skip = false;
+	for (const stringIndex in [...string]) {
+		if (skip) {
+			skip = false;
+			continue;
+		}
+		const index = parseIntStrict_default(stringIndex);
+		if (index === 0 && options?.startWithUpper) {
+			outputString += string[index].toUpperCase();
+			continue;
+		}
+		if (index === string.length - 1) {
+			outputString += string[index];
+			break;
+		}
+		if (string[index] === "-" && /^[a-zA-Z]+$/.test(string[index + 1])) {
+			outputString += string[index + 1].toUpperCase();
+			skip = true;
+		} else outputString += string[index];
+	}
+	return outputString;
+}
+var kebabToCamel_default = kebabToCamel;
+
+//#endregion
+//#region src/functions/stringHelpers/normalizeImportPath.ts
+/**
+* Normalizes an import path meant for use in an import statement in JavaScript.
+*
+* When multiple slashes are found, they're replaced by a single one; when the path contains a trailing slash, it is preserved. On Windows backslashes are used. If the path is a zero-length string, '.' is returned, representing the current working directory.
+*
+* If the path starts with ./, it is preserved (unlike what would happen with path.posix.normalize() normally).
+*
+* Helpful for custom linter rules that need to check (or fix) import paths.
+*
+* @param importPath - The import path to normalize.
+*
+* @returns The import path normalized.
+*/
+function normalizeImportPath(importPath) {
+	const normalizedPath = path.posix.normalize(importPath);
+	if (importPath.startsWith("./") && !normalizedPath.startsWith("./")) return `./${normalizedPath}`;
+	return normalizedPath;
+}
+/**
+* Normalises an import path meant for use in an import statement in JavaScript.
+*
+* When multiple slashes are found, they're replaced by a single one; when the path contains a trailing slash, it is preserved. On Windows backslashes are used. If the path is a zero-length string, '.' is returned, representing the current working directory.
+*
+* If the path starts with ./, it is preserved (unlike what would happen with path.posix.normalize() normally).
+*
+* Helpful for custom linter rules that need to check (or fix) import paths.
+*
+* @param importPath - The import path to normalise.
+*
+* @returns The import path normalised.
+*/
+const normaliseImportPath = normalizeImportPath;
+var normalizeImportPath_default = normalizeImportPath;
+
+//#endregion
+//#region src/functions/stringHelpers/truncate.ts
+/**
+* Truncates a string and appends `...` to the end of it
+*
+* @param stringToTruncate - The string to truncate.
+* @param maxLength - The length at which to start truncating. Note that this does not include the `...` part that would be appended.
+*
+* @returns A new string that has been truncated based on the length provided.
+*/
+function truncate(stringToTruncate, maxLength = 5) {
+	return stringToTruncate.length > maxLength ? `${stringToTruncate.slice(0, maxLength)}...` : stringToTruncate;
+}
+var truncate_default = truncate;
+
+//#endregion
+//#region src/functions/taggedTemplate/createTemplateStringsArray.ts
+/**
+* Creates a template strings array given a regular array of strings
+*
+* @param strings - The array of strings.
+*
+* @returns A template strings array that can be passed as the first argument of any tagged template function.
+*/
+function createTemplateStringsArray(strings) {
+	return deepFreeze_default(Object.assign([...strings], { raw: [...strings] }));
+}
+var createTemplateStringsArray_default = createTemplateStringsArray;
 
 //#endregion
 //#region src/functions/taggedTemplate/interpolate.ts
+/**
+* Returns the result of interpolating a template string when given the strings and interpolations separately.
+*
+* You can pass a template string directly by doing:
+*
+*      interpolate`Template string here`.
+*
+* In this case, it will be functionally the same as if you just wrote the template string by itself.
+*
+* @param strings - The strings from the template to process.
+* @param interpolations - An array of all interpolations from the template.
+*
+* @returns A new string with the strings and interpolations from the template applied.
+*/
 function interpolate(strings, ...interpolations) {
 	let result = "";
 	for (const [string, interpolation = ""] of paralleliseArrays_default(strings, interpolations)) result += string + interpolation;
@@ -617,11 +893,23 @@ var interpolate_default = interpolate;
 
 //#endregion
 //#region src/functions/taggedTemplate/interpolateObjects.ts
-function interpolateObjects(strings, ...values) {
+/**
+* Returns the result of interpolating a template string, also stringifying objects.
+*
+* You can pass a template string directly by doing:
+*
+*      interpolateObjects`Template string here ${{ my: "object" }}`.
+*
+* @param strings - The strings from the template to process.
+* @param interpolations - An array of all interpolations from the template.
+*
+* @returns A new string with the strings and interpolations from the template applied, with objects stringified.
+*/
+function interpolateObjects(strings, ...interpolations) {
 	let result = "";
 	for (let i = 0; i < strings.length; i++) {
 		result += strings[i];
-		if (i !== strings.length - 1) result += values[i] && typeof values[i] === "object" ? JSON.stringify(values[i]) : values[i];
+		if (i !== strings.length - 1) result += interpolations[i] && typeof interpolations[i] === "object" ? JSON.stringify(interpolations[i]) : interpolations[i];
 	}
 	return result;
 }
@@ -653,6 +941,26 @@ function reduceLines$1(lines, { preserveTabs = true }) {
 		}, tabSize).join("") : "") + line.trimStart();
 	}).join("\n");
 }
+/**
+* Applies any options if provided, then removes any extraneous indents from a multi-line template string.
+*
+* You can pass a template string directly by doing:
+*
+*      normaliseIndents`Template string here
+*          with a new line
+*          and another new line`.
+*
+* You may also pass the options first, then invoke the resulting function with a template string:
+*
+*      normaliseIndents({ preserveTabs: false })`Template string here
+*          with a new line
+*          and another new line`.
+*
+* @param first - The strings from the template to process, or the options to apply.
+* @param args - An array of all interpolations from the template.
+*
+* @returns An additional function to invoke, or a new string with the strings and interpolations from the template applied, and extraneous indents removed.
+*/
 function normaliseIndents(first, ...args) {
 	if (typeof first === "object" && first !== null && !Array.isArray(first)) {
 		const options$1 = first;
@@ -664,6 +972,26 @@ function normaliseIndents(first, ...args) {
 	const options = typeof args[args.length - 1] === "object" && !Array.isArray(args[args.length - 1]) ? args.pop() : {};
 	return reduceLines$1(interpolate_default(strings, ...[...args]).split("\n"), options);
 }
+/**
+* Applies any options if provided, then removes any extraneous indents from a multi-line template string.
+*
+* You can pass a template string directly by doing:
+*
+*      normalizeIndents`Template string here
+*          with a new line
+*          and another new line`.
+*
+* You may also pass the options first, then invoke the resulting function with a template string:
+*
+*      normalizeIndents({ preserveTabs: false })`Template string here
+*          with a new line
+*          and another new line`.
+*
+* @param first - The strings from the template to process, or the options to apply.
+* @param args - An array of all interpolations from the template.
+*
+* @returns An additional function to invoke, or a new string with the strings and interpolations from the template applied, and extraneous indents removed.
+*/
 const normalizeIndents = normaliseIndents;
 var normaliseIndents_default = normaliseIndents;
 
@@ -707,22 +1035,58 @@ function removeIndents(first, ...args) {
 var removeIndents_default = removeIndents;
 
 //#endregion
-//#region src/functions/truncate.ts
-function truncate(stringToTruncate, maxLength = 5) {
-	return stringToTruncate.length > maxLength ? `${stringToTruncate.slice(0, maxLength)}...` : stringToTruncate;
+//#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 truncate_default = truncate;
+var parseVersion_default = parseVersion;
 
 //#endregion
-//#region src/functions/wait.ts
-function wait(seconds) {
-	return new Promise((resolve, _) => {
-		setTimeout(() => {
-			resolve();
-		}, seconds * 1e3);
+//#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 wait_default = wait;
+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, 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 };
+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 };