@alextheman/utility 5.13.0 → 5.14.0

package/dist/index.cjs

@@ -180,7 +180,7 @@ var CodeError = class CodeError extends Error {
 *
 * @template DataType - The type of the data that caused the error.
 */
-var DataError = class DataError extends CodeError {
+var DataError$1 = class DataError$1 extends CodeError {
 	data;
 	/**
 	* @param data - The data that caused the error.
@@ -205,7 +205,7 @@ var DataError = class DataError extends CodeError {
 	* @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) {
-		if (input instanceof DataError) return true;
+		if (input instanceof DataError$1) return true;
 		return typeof input === "object" && input !== null && "message" in input && typeof input.message === "string" && "code" in input && typeof input.code === "string" && "data" in input;
 	}
 	/**
@@ -254,18 +254,18 @@ var DataError = class DataError extends CodeError {
 function parseIntStrict(string, radix) {
 	const trimmedString = string.trim();
 	const maxAllowedAlphabeticalCharacter = radix && radix > 10 && radix <= 36 ? String.fromCharCode(87 + radix - 1) : void 0;
-	if (!(radix && radix > 10 && radix <= 36 ? new RegExp(`^[+-]?[0-9a-${maxAllowedAlphabeticalCharacter}]+$`, "i") : /^[+-]?\d+$/).test(trimmedString)) throw new DataError(radix ? {
+	if (!(radix && radix > 10 && radix <= 36 ? new RegExp(`^[+-]?[0-9a-${maxAllowedAlphabeticalCharacter}]+$`, "i") : /^[+-]?\d+$/).test(trimmedString)) throw new DataError$1(radix ? {
 		string,
 		radix
 	} : { string }, "INTEGER_PARSING_ERROR", `Only numeric values${radix && radix > 10 && radix <= 36 ? ` or character${radix !== 11 ? "s" : ""} A${radix !== 11 ? `-${maxAllowedAlphabeticalCharacter?.toUpperCase()} ` : " "}` : " "}are allowed.`);
 	if (radix && radix < 10 && [...trimmedString.replace(/^[+-]/, "")].some((character) => {
 		return parseInt(character) >= radix;
-	})) throw new DataError({
+	})) throw new DataError$1({
 		string,
 		radix
 	}, "INTEGER_PARSING_ERROR", "Value contains one or more digits outside of the range of the given radix.");
 	const parseIntResult = parseInt(trimmedString, radix);
-	if (isNaN(parseIntResult)) throw new DataError({ string }, "INTEGER_PARSING_ERROR", "Value is not a valid integer.");
+	if (isNaN(parseIntResult)) throw new DataError$1({ string }, "INTEGER_PARSING_ERROR", "Value is not a valid integer.");
 	return parseIntResult;
 }
 //#endregion
@@ -328,16 +328,16 @@ function randomiseArray(array) {
 */
 function range(start, stop, step = 1) {
 	const numbers = [];
-	if (step === 0) throw new DataError({ step }, "ZERO_STEP_SIZE", "Step size cannot be zero.");
+	if (step === 0) throw new DataError$1({ step }, "ZERO_STEP_SIZE", "Step size cannot be zero.");
 	else if (step > 0) {
-		if (start > stop) throw new DataError({
+		if (start > stop) throw new DataError$1({
 			start,
 			stop,
 			step
 		}, "INVALID_BOUNDARIES", "The starting value cannot be bigger than the final value if step is positive");
 		for (let i = start; i < stop; i += step) numbers.push(i);
 	} else if (step < 0) {
-		if (start < stop) throw new DataError({
+		if (start < stop) throw new DataError$1({
 			start,
 			stop,
 			step
@@ -537,7 +537,7 @@ function convertFileToBase64(file) {
 		reader.readAsDataURL(file);
 		reader.onload = () => {
 			if (reader.result === null) {
-				reject(new DataError({ result: reader.result }, "FILE_CONVERSION_ERROR", "Could not convert the given file."));
+				reject(new DataError$1({ result: reader.result }, "FILE_CONVERSION_ERROR", "Could not convert the given file."));
 				return;
 			}
 			resolve(reader.result);
@@ -604,10 +604,10 @@ function createFormData(data, options = {
 		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 DataError({ value }, "CANNOT_STRINGIFY_BLOB", "Files/blobs cannot be stringified. Please change the resolution option for this item to \"multiple\" instead.");
+			}) && (options.arrayResolution === "stringify" || typeof options.arrayResolution === "object" && options.arrayResolution[key] === "stringify")) throw new DataError$1({ value }, "CANNOT_STRINGIFY_BLOB", "Files/blobs cannot be stringified. Please change the resolution option for this item to \"multiple\" instead.");
 			if (options.arrayResolution === "multiple" || typeof options.arrayResolution === "object" && options.arrayResolution[key] === "multiple") {
 				for (const item of value) {
-					if (!isPrimitive(item) && !(item instanceof Blob)) throw new DataError({ item }, "NON_PRIMITIVE_ARRAY_ITEMS_FOUND", "Cannot directly add non-primitive data to FormData. Please change the resolution option for this item to \"stringify\" instead.");
+					if (!isPrimitive(item) && !(item instanceof Blob)) throw new DataError$1({ item }, "NON_PRIMITIVE_ARRAY_ITEMS_FOUND", "Cannot directly add non-primitive data to FormData. Please change the resolution option for this item to \"stringify\" instead.");
 					if (item instanceof Blob) formData.append(String(key), item);
 					else formData.append(String(key), String(item));
 				}
@@ -763,8 +763,8 @@ function stringifyDotenv(contents, options) {
 	const { quoteStyle = "double" } = options ?? {};
 	let result = "";
 	for (const key in contentsCopy) {
-		if (/[ \t\r\n]/.test(key)) throw new DataError({ [key]: contentsCopy[key] }, "INVALID_KEY", "Environment variables are not allowed to have whitespace.");
-		if (quoteStyle === "none") if (/[ \t\r\n]/.test(contentsCopy[key]) || contentsCopy[key].includes("#") || contentsCopy[key].includes("=") || contentsCopy[key].includes("\\")) throw new DataError({ [key]: contentsCopy[key] }, "INCOMPATIBLE_QUOTE_STYLE", "Cannot use `{ quoteStyle: \"none\" }` when value has whitespace, #, =, or \\");
+		if (/[ \t\r\n]/.test(key)) throw new DataError$1({ [key]: contentsCopy[key] }, "INVALID_KEY", "Environment variables are not allowed to have whitespace.");
+		if (quoteStyle === "none") if (/[ \t\r\n]/.test(contentsCopy[key]) || contentsCopy[key].includes("#") || contentsCopy[key].includes("=") || contentsCopy[key].includes("\\")) throw new DataError$1({ [key]: contentsCopy[key] }, "INCOMPATIBLE_QUOTE_STYLE", "Cannot use `{ quoteStyle: \"none\" }` when value has whitespace, #, =, or \\");
 		else {
 			result += `${key}=${contentsCopy[key]}\n`;
 			continue;
@@ -889,11 +889,221 @@ function removeUndefinedFromObject(object) {
 */
 function parseBoolean(inputString) {
 	const normalisedString = inputString.toLowerCase();
-	if (!["true", "false"].includes(normalisedString)) throw new DataError({ inputString }, "INVALID_BOOLEAN_STRING", "The provided boolean string must be one of `true | false`");
+	if (!["true", "false"].includes(normalisedString)) throw new DataError$1({ inputString }, "INVALID_BOOLEAN_STRING", "The provided boolean string must be one of `true | false`");
 	return normalisedString === "true";
 }
 //#endregion
-//#region src/root/functions/parsers/zod/_parseZodSchema.ts
+//#region src/root/types/APIError.ts
+const httpErrorCodeLookup = {
+	400: "BAD_REQUEST",
+	401: "UNAUTHORISED",
+	403: "FORBIDDEN",
+	404: "NOT_FOUND",
+	418: "I_AM_A_TEAPOT",
+	500: "INTERNAL_SERVER_ERROR"
+};
+/**
+* Represents common errors you may get from a HTTP API request.
+*
+* @category Types
+*/
+var APIError = class APIError 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;
+		if (message) this.message = message;
+		else this.message = httpErrorCodeLookup[this.status] ?? "API_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) {
+		if (input instanceof APIError) return true;
+		const data = input;
+		return typeof data === "object" && data !== null && typeof data?.status === "number" && typeof data?.message === "string";
+	}
+};
+//#endregion
+//#region src/root/types/VersionNumber.ts
+/**
+* Represents a software version number, considered to be made up of a major, minor, and patch part.
+*
+* @category Types
+*/
+var VersionNumber = class VersionNumber {
+	static NON_NEGATIVE_TUPLE_ERROR = "Input array must be a tuple of three non-negative integers.";
+	/** 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;
+	/**
+	* @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 (!VERSION_NUMBER_REGEX.test(input)) throw new DataError$1({ 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(number);
+			});
+			this.major = major;
+			this.minor = minor;
+			this.patch = patch;
+		} else if (Array.isArray(input)) {
+			if (input.length !== 3) throw new DataError$1({ input }, "INVALID_LENGTH", VersionNumber.NON_NEGATIVE_TUPLE_ERROR);
+			const [major, minor, patch] = input.map((number) => {
+				const parsedInteger = parseIntStrict(number?.toString());
+				if (parsedInteger < 0) throw new DataError$1({ input }, "NEGATIVE_INPUTS", VersionNumber.NON_NEGATIVE_TUPLE_ERROR);
+				return parsedInteger;
+			});
+			this.major = major;
+			this.minor = minor;
+			this.patch = patch;
+		} else throw new DataError$1({ input }, "INVALID_INPUT", normaliseIndents`
+        The provided input can not be parsed into a valid version number.
+        Expected either a string of format X.Y.Z or vX.Y.Z, a tuple of three numbers, or another \`VersionNumber\` instance.
+      `);
+	}
+	/**
+	* 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;
+	}
+	static formatString(input, options) {
+		if (options?.omitPrefix) return input.startsWith("v") ? input.slice(1) : input;
+		return input.startsWith("v") ? input : `v${input}`;
+	}
+	/**
+	* Checks if the provided version numbers have the exact same major, minor, and patch numbers.
+	*
+	* @param firstVersion - The first version number to compare.
+	* @param secondVersion - The second version number to compare.
+	*
+	* @returns `true` if the provided version numbers have exactly the same major, minor, and patch numbers, and returns `false` otherwise.
+	*/
+	static isEqual(firstVersion, secondVersion) {
+		return firstVersion.major === secondVersion.major && firstVersion.minor === secondVersion.minor && firstVersion.patch === secondVersion.patch;
+	}
+	/**
+	* Get a formatted string representation of the current version number
+	*
+	* @param options - Options to apply to the string formatting.
+	*
+	* @returns A formatted string representation of the current version number with the options applied.
+	*/
+	format(options) {
+		let baseOutput = `${this.major}`;
+		if (!options?.omitMinor) {
+			baseOutput += `.${this.minor}`;
+			if (!options?.omitPatch) baseOutput += `.${this.patch}`;
+		}
+		return VersionNumber.formatString(baseOutput, { omitPrefix: options?.omitPrefix });
+	}
+	/**
+	* Increments the current version number by the given increment type, returning the result as a new reference in memory.
+	*
+	* @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`
+	* @param incrementAmount - The amount to increment by (defaults to 1).
+	*
+	* @returns A new instance of `VersionNumber` with the increment applied.
+	*/
+	increment(incrementType, incrementAmount = 1) {
+		const incrementBy = parseIntStrict(String(incrementAmount));
+		const calculatedRawVersion = {
+			major: [
+				this.major + incrementBy,
+				0,
+				0
+			],
+			minor: [
+				this.major,
+				this.minor + incrementBy,
+				0
+			],
+			patch: [
+				this.major,
+				this.minor,
+				this.patch + incrementBy
+			]
+		}[incrementType];
+		try {
+			return new VersionNumber(calculatedRawVersion);
+		} catch (error) {
+			if (DataError$1.check(error) && error.code === "NEGATIVE_INPUTS") throw new DataError$1({
+				currentVersion: this.toString(),
+				calculatedRawVersion: `v${calculatedRawVersion.join(".")}`,
+				incrementAmount
+			}, "NEGATIVE_VERSION", "Cannot apply this increment amount as it would lead to a negative version number.");
+			else throw error;
+		}
+	}
+	/**
+	* Ensures that the VersionNumber behaves correctly when attempted to be coerced to a string.
+	*
+	* @param hint - Not used as of now, but generally used to help with numeric coercion, I think (which we most likely do not need for version numbers).
+	*
+	* @returns A stringified representation of the current version number, prefixed with `v`.
+	*/
+	[Symbol.toPrimitive](hint) {
+		if (hint === "number") throw new DataError$1({ thisVersion: this.toString() }, "INVALID_COERCION", "VersionNumber cannot be coerced to a number type.");
+		return this.toString();
+	}
+	/**
+	* Ensures that the VersionNumber behaves correctly when attempted to be converted to JSON.
+	*
+	* @returns A stringified representation of the current version number, prefixed with `v`.
+	*/
+	toJSON() {
+		return this.toString();
+	}
+	/**
+	* Get a string representation of the current version number.
+	*
+	* @returns A stringified representation of the current version number with the prefix.
+	*/
+	toString() {
+		const rawString = `${this.major}.${this.minor}.${this.patch}`;
+		return VersionNumber.formatString(rawString, { omitPrefix: false });
+	}
+};
+const zodVersionNumber = zod.default.union([
+	zod.default.string(),
+	zod.default.tuple([
+		zod.default.number(),
+		zod.default.number(),
+		zod.default.number()
+	]),
+	zod.default.instanceof(VersionNumber)
+]).transform((rawVersionNumber) => {
+	return new VersionNumber(rawVersionNumber);
+});
+//#endregion
+//#region src/root/zod/_parseZodSchema.ts
 function _parseZodSchema(parsedResult, input, onError) {
 	if (!parsedResult.success) {
 		if (onError) {
@@ -908,7 +1118,7 @@ function _parseZodSchema(parsedResult, input, onError) {
 			const code = issue.code.toUpperCase();
 			allErrorCodes[code] = (allErrorCodes[code] ?? 0) + 1;
 		}
-		throw new DataError({ input }, Object.entries(allErrorCodes).toSorted(([_, firstCount], [__, secondCount]) => {
+		throw new DataError$1({ input }, Object.entries(allErrorCodes).toSorted(([_, firstCount], [__, secondCount]) => {
 			return secondCount - firstCount;
 		}).map(([code, count], _, allErrorCodes) => {
 			return allErrorCodes.length === 1 && count === 1 ? code : `${code}×${count}`;
@@ -917,7 +1127,7 @@ function _parseZodSchema(parsedResult, input, onError) {
 	return parsedResult.data;
 }
 //#endregion
-//#region src/root/functions/parsers/zod/parseZodSchema.ts
+//#region src/root/zod/parseZodSchema.ts
 /**
 * An alternative function to zodSchema.parse() that can be used to strictly parse Zod schemas.
 *
@@ -925,6 +1135,8 @@ function _parseZodSchema(parsedResult, input, onError) {
 *
 * @category Parsers
 *
+* @deprecated Please use `az.with(schema).parse(input)` instead.
+*
 * @template SchemaType - The Zod schema type.
 * @template ErrorType - The type of error to throw on invalid data.
 *
@@ -940,6 +1152,60 @@ function parseZodSchema(schema, input, onError) {
 	return _parseZodSchema(schema.safeParse(input), input, onError);
 }
 //#endregion
+//#region src/root/zod/parseZodSchemaAsync.ts
+/**
+* An alternative function to zodSchema.parseAsync() that can be used to strictly parse asynchronous Zod schemas.
+*
+* @category Parsers
+*
+* @deprecated Please use `az.with(schema).parseAsync(input)` instead.
+*
+* @template SchemaType - The Zod schema type.
+* @template ErrorType - The type of error to throw on invalid data.
+*
+* @param schema - The Zod schema to use in parsing.
+* @param input - The data to parse.
+* @param onError - A custom error to throw on invalid data (defaults to `DataError`). May either be the error itself, or a function that returns the error or nothing. If nothing is returned, the default error is thrown instead.
+*
+* @throws {DataError} If the given data cannot be parsed according to the schema.
+*
+* @returns The parsed data from the Zod schema.
+*/
+async function parseZodSchemaAsync(schema, input, onError) {
+	return _parseZodSchema(await schema.safeParseAsync(input), input, onError);
+}
+//#endregion
+//#region src/root/zod/zodFieldWrapper.ts
+function zodFieldWrapper(schema) {
+	return zod.default.string().trim().transform((value) => {
+		return value === "" ? null : value;
+	}).pipe(schema);
+}
+//#endregion
+//#region src/root/zod/az.ts
+const az = {
+	field: zodFieldWrapper,
+	fieldNumber: () => {
+		return zod.default.coerce.number();
+	},
+	versionNumber: () => {
+		return zodVersionNumber;
+	},
+	fieldDate: () => {
+		return zod.default.coerce.date();
+	},
+	with: (schema) => {
+		return {
+			parse: (input, error) => {
+				return parseZodSchema(schema, input, error);
+			},
+			parseAsync: async (input, error) => {
+				return await parseZodSchemaAsync(schema, input, error);
+			}
+		};
+	}
+};
+//#endregion
 //#region src/root/functions/parsers/parseEnv.ts
 /**
 * Represents the three common development environments.
@@ -963,7 +1229,7 @@ const Env = {
 * @returns The specified environment if allowed.
 */
 function parseEnv(input) {
-	return parseZodSchema(zod.z.enum(Env), input, new DataError({ input }, "INVALID_ENV", "The provided environment type must be one of `test | development | production`"));
+	return az.with(zod.z.enum(Env)).parse(input, new DataError$1({ input }, "INVALID_ENV", "The provided environment type must be one of `test | development | production`"));
 }
 //#endregion
 //#region src/root/functions/parsers/parseFormData.ts
@@ -1001,8 +1267,8 @@ function parseFormData(formData, dataParser) {
 * @returns The UUID again if successful.
 */
 function parseUUID(input) {
-	if (!(typeof input === "string")) throw new DataError({ input }, "INVALID_TYPE", "Invalid type - expected string.");
-	if (!UUID_REGEX.test(input)) throw new DataError({ input }, "INVALID_UUID", "The provided input does not match the expected shape for a UUID.");
+	if (!(typeof input === "string")) throw new DataError$1({ input }, "INVALID_TYPE", "Invalid type - expected string.");
+	if (!UUID_REGEX.test(input)) throw new DataError$1({ input }, "INVALID_UUID", "The provided input does not match the expected shape for a UUID.");
 	return input;
 }
 //#endregion
@@ -1029,28 +1295,7 @@ const VersionType = {
 * @returns The given version type if allowed.
 */
 function parseVersionType(input) {
-	return parseZodSchema(zod.default.enum(VersionType), input, new DataError({ input }, "INVALID_VERSION_TYPE", "The provided version type must be one of `major | minor | patch`"));
-}
-//#endregion
-//#region src/root/functions/parsers/zod/parseZodSchemaAsync.ts
-/**
-* An alternative function to zodSchema.parseAsync() that can be used to strictly parse asynchronous Zod schemas.
-*
-* @category Parsers
-*
-* @template SchemaType - The Zod schema type.
-* @template ErrorType - The type of error to throw on invalid data.
-*
-* @param schema - The Zod schema to use in parsing.
-* @param input - The data to parse.
-* @param onError - A custom error to throw on invalid data (defaults to `DataError`). May either be the error itself, or a function that returns the error or nothing. If nothing is returned, the default error is thrown instead.
-*
-* @throws {DataError} If the given data cannot be parsed according to the schema.
-*
-* @returns The parsed data from the Zod schema.
-*/
-async function parseZodSchemaAsync(schema, input, onError) {
-	return _parseZodSchema(await schema.safeParseAsync(input), input, onError);
+	return az.with(zod.default.enum(VersionType)).parse(input, new DataError$1({ input }, "INVALID_VERSION_TYPE", "The provided version type must be one of `major | minor | patch`"));
 }
 //#endregion
 //#region src/root/functions/recursive/deepCopy.ts
@@ -1116,7 +1361,7 @@ function deepFreeze(object) {
 * @returns A string with the semicolon appended.
 */
 function appendSemicolon(stringToAppendTo) {
-	if (stringToAppendTo.includes("\n")) throw new DataError({ stringToAppendTo }, "MULTIPLE_LINE_ERROR", "Cannot append semicolon to multi-line string.");
+	if (stringToAppendTo.includes("\n")) throw new DataError$1({ stringToAppendTo }, "MULTIPLE_LINE_ERROR", "Cannot append semicolon to multi-line string.");
 	const stringWithNoTrailingWhitespace = stringToAppendTo.trimEnd();
 	if (stringWithNoTrailingWhitespace === "") return "";
 	return stringWithNoTrailingWhitespace[stringWithNoTrailingWhitespace.length - 1] === ";" ? stringWithNoTrailingWhitespace : `${stringWithNoTrailingWhitespace};`;
@@ -1184,9 +1429,9 @@ function escapeRegexPattern(regexPattern) {
 * @returns The string converted to camelCase.
 */
 function kebabToCamel(input, options) {
-	if (input !== input.toLowerCase()) throw new DataError({ input }, "UPPERCASE_INPUT", "Kebab-case must be purely lowercase.");
-	if (input.startsWith("-") || input.endsWith("-")) throw new DataError({ input }, "TRAILING_DASHES", "Dashes at the start and/or end are not allowed.");
-	if (input.includes("--")) throw new DataError({ input }, "CONSECUTIVE_DASHES", "Consecutive dashes are not allowed.");
+	if (input !== input.toLowerCase()) throw new DataError$1({ input }, "UPPERCASE_INPUT", "Kebab-case must be purely lowercase.");
+	if (input.startsWith("-") || input.endsWith("-")) throw new DataError$1({ input }, "TRAILING_DASHES", "Dashes at the start and/or end are not allowed.");
+	if (input.includes("--")) throw new DataError$1({ input }, "CONSECUTIVE_DASHES", "Consecutive dashes are not allowed.");
 	let outputString = "";
 	let skip = false;
 	for (const stringIndex in [...input]) {
@@ -1299,7 +1544,7 @@ function createTemplateStringsArray(strings) {
 * ```
 */
 function getStringsAndInterpolations(strings, ...interpolations) {
-	if (strings.length !== interpolations.length + 1) throw new DataError({
+	if (strings.length !== interpolations.length + 1) throw new DataError$1({
 		stringsLength: strings.length,
 		interpolationsLength: interpolations.length,
 		strings,
@@ -1465,217 +1710,99 @@ function normaliseIndents(first, ...args) {
 */
 const normalizeIndents = normaliseIndents;
 //#endregion
-//#region src/root/types/APIError.ts
-const httpErrorCodeLookup = {
-	400: "BAD_REQUEST",
-	401: "UNAUTHORISED",
-	403: "FORBIDDEN",
-	404: "NOT_FOUND",
-	418: "I_AM_A_TEAPOT",
-	500: "INTERNAL_SERVER_ERROR"
-};
+//#region src/root/deprecated/DataError.ts
 /**
-* Represents common errors you may get from a HTTP API request.
+* Represents errors you may get that may've been caused by a specific piece of data.
 *
 * @category Types
+*
+* @deprecated Please use `DataError` from `@alextheman/utility/v6` instead.
+*
+* @template DataType - The type of the data that caused the error.
 */
-var APIError = class APIError extends Error {
-	status;
+var DataError = class DataError extends Error {
+	code;
+	data;
 	/**
-	* @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.
+	* @param data - The data that caused the error.
+	* @param code - A standardised code (e.g. UNEXPECTED_DATA).
+	* @param message  - A human-readable error message (e.g. The data provided is invalid).
+	* @param options - Extra options to pass to super Error constructor.
 	*/
-	constructor(status = 500, message, options) {
+	constructor(data, code = "INVALID_DATA", message = "The data provided is invalid", options) {
 		super(message, options);
-		this.status = status;
-		if (message) this.message = message;
-		else this.message = httpErrorCodeLookup[this.status] ?? "API_ERROR";
+		if (Error.captureStackTrace) Error.captureStackTrace(this, new.target);
+		this.name = new.target.name;
+		this.code = code;
+		this.data = data;
 		Object.defineProperty(this, "message", { enumerable: true });
 		Object.setPrototypeOf(this, new.target.prototype);
 	}
+	static checkCaughtError(error, options) {
+		if (DataError.check(error)) {
+			if (options?.expectedCode && error.code !== options.expectedCode) throw new Error(normaliseIndents`The error code on the thrown error does not match the expected error code.
+            
+            Expected: ${options.expectedCode}
+            Received: ${error.code}
+            `, { cause: error });
+			return error;
+		}
+		throw error;
+	}
 	/**
-	* Checks whether the given input may have been caused by an APIError.
+	* Checks whether the given input may have been caused by a DataError.
 	*
 	* @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`.
+	* @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) {
-		if (input instanceof APIError) return true;
+		if (input instanceof DataError) return true;
 		const data = input;
-		return typeof data === "object" && data !== null && typeof data?.status === "number" && typeof data?.message === "string";
+		return typeof data === "object" && data !== null && typeof data.message === "string" && typeof data.code === "string" && "data" in data;
 	}
-};
-//#endregion
-//#region src/root/types/VersionNumber.ts
-/**
-* Represents a software version number, considered to be made up of a major, minor, and patch part.
-*
-* @category Types
-*/
-var VersionNumber = class VersionNumber {
-	static NON_NEGATIVE_TUPLE_ERROR = "Input array must be a tuple of three non-negative integers.";
-	/** 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;
 	/**
-	* @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 (!VERSION_NUMBER_REGEX.test(input)) throw new DataError({ 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(number);
-			});
-			this.major = major;
-			this.minor = minor;
-			this.patch = patch;
-		} else if (Array.isArray(input)) {
-			if (input.length !== 3) throw new DataError({ input }, "INVALID_LENGTH", VersionNumber.NON_NEGATIVE_TUPLE_ERROR);
-			const [major, minor, patch] = input.map((number) => {
-				const parsedInteger = parseIntStrict(number?.toString());
-				if (parsedInteger < 0) throw new DataError({ input }, "NEGATIVE_INPUTS", VersionNumber.NON_NEGATIVE_TUPLE_ERROR);
-				return parsedInteger;
-			});
-			this.major = major;
-			this.minor = minor;
-			this.patch = patch;
-		} else throw new DataError({ input }, "INVALID_INPUT", normaliseIndents`
-        The provided input can not be parsed into a valid version number.
-        Expected either a string of format X.Y.Z or vX.Y.Z, a tuple of three numbers, or another \`VersionNumber\` instance.
-      `);
-	}
-	/**
-	* 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;
-	}
-	static formatString(input, options) {
-		if (options?.omitPrefix) return input.startsWith("v") ? input.slice(1) : input;
-		return input.startsWith("v") ? input : `v${input}`;
-	}
-	/**
-	* Checks if the provided version numbers have the exact same major, minor, and patch numbers.
-	*
-	* @param firstVersion - The first version number to compare.
-	* @param secondVersion - The second version number to compare.
-	*
-	* @returns `true` if the provided version numbers have exactly the same major, minor, and patch numbers, and returns `false` otherwise.
-	*/
-	static isEqual(firstVersion, secondVersion) {
-		return firstVersion.major === secondVersion.major && firstVersion.minor === secondVersion.minor && firstVersion.patch === secondVersion.patch;
-	}
-	/**
-	* Get a formatted string representation of the current version number
-	*
-	* @param options - Options to apply to the string formatting.
+	* Gets the thrown `DataError` from a given function if one was thrown, and re-throws any other errors, or throws a default `DataError` if no error thrown.
 	*
-	* @returns A formatted string representation of the current version number with the options applied.
-	*/
-	format(options) {
-		let baseOutput = `${this.major}`;
-		if (!options?.omitMinor) {
-			baseOutput += `.${this.minor}`;
-			if (!options?.omitPatch) baseOutput += `.${this.patch}`;
-		}
-		return VersionNumber.formatString(baseOutput, { omitPrefix: options?.omitPrefix });
-	}
-	/**
-	* Increments the current version number by the given increment type, returning the result as a new reference in memory.
+	* @param errorFunction - The function expected to throw the error.
+	* @param options - Extra options to apply.
 	*
-	* @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`
-	* @param incrementAmount - The amount to increment by (defaults to 1).
+	* @throws {Error} Any other errors thrown by the `errorFunction` that are not a `DataError`.
+	* @throws {Error} If no `DataError` was thrown by the `errorFunction`
 	*
-	* @returns A new instance of `VersionNumber` with the increment applied.
+	* @returns The `DataError` that was thrown by the `errorFunction`
 	*/
-	increment(incrementType, incrementAmount = 1) {
-		const incrementBy = parseIntStrict(String(incrementAmount));
-		const calculatedRawVersion = {
-			major: [
-				this.major + incrementBy,
-				0,
-				0
-			],
-			minor: [
-				this.major,
-				this.minor + incrementBy,
-				0
-			],
-			patch: [
-				this.major,
-				this.minor,
-				this.patch + incrementBy
-			]
-		}[incrementType];
+	static expectError(errorFunction, options) {
 		try {
-			return new VersionNumber(calculatedRawVersion);
+			errorFunction();
 		} catch (error) {
-			if (DataError.check(error) && error.code === "NEGATIVE_INPUTS") throw new DataError({
-				currentVersion: this.toString(),
-				calculatedRawVersion: `v${calculatedRawVersion.join(".")}`,
-				incrementAmount
-			}, "NEGATIVE_VERSION", "Cannot apply this increment amount as it would lead to a negative version number.");
-			else throw error;
+			return DataError.checkCaughtError(error, options);
 		}
+		throw new Error("Expected a DataError to be thrown but none was thrown");
 	}
 	/**
-	* Ensures that the VersionNumber behaves correctly when attempted to be coerced to a string.
-	*
-	* @param hint - Not used as of now, but generally used to help with numeric coercion, I think (which we most likely do not need for version numbers).
+	* Gets the thrown `DataError` from a given asynchronous function if one was thrown, and re-throws any other errors, or throws a default `DataError` if no error thrown.
 	*
-	* @returns A stringified representation of the current version number, prefixed with `v`.
-	*/
-	[Symbol.toPrimitive](hint) {
-		if (hint === "number") throw new DataError({ thisVersion: this.toString() }, "INVALID_COERCION", "VersionNumber cannot be coerced to a number type.");
-		return this.toString();
-	}
-	/**
-	* Ensures that the VersionNumber behaves correctly when attempted to be converted to JSON.
+	* @param errorFunction - The function expected to throw the error.
+	* @param options - Extra options to apply.
 	*
-	* @returns A stringified representation of the current version number, prefixed with `v`.
-	*/
-	toJSON() {
-		return this.toString();
-	}
-	/**
-	* Get a string representation of the current version number.
+	* @throws {Error} Any other errors thrown by the `errorFunction` that are not a `DataError`.
+	* @throws {Error} If no `DataError` was thrown by the `errorFunction`
 	*
-	* @returns A stringified representation of the current version number with the prefix.
+	* @returns The `DataError` that was thrown by the `errorFunction`
 	*/
-	toString() {
-		const rawString = `${this.major}.${this.minor}.${this.patch}`;
-		return VersionNumber.formatString(rawString, { omitPrefix: false });
+	static async expectErrorAsync(errorFunction, options) {
+		try {
+			await errorFunction();
+		} catch (error) {
+			return DataError.checkCaughtError(error, options);
+		}
+		throw new Error("Expected a DataError to be thrown but none was thrown");
 	}
 };
-const zodVersionNumber = zod.default.union([
-	zod.default.string(),
-	zod.default.tuple([
-		zod.default.number(),
-		zod.default.number(),
-		zod.default.number()
-	]),
-	zod.default.instanceof(VersionNumber)
-]).transform((rawVersionNumber) => {
-	return new VersionNumber(rawVersionNumber);
-});
 //#endregion
 exports.APIError = APIError;
+exports.DataError = DataError;
 exports.Env = Env;
 exports.FILE_PATH_PATTERN = FILE_PATH_PATTERN;
 exports.FILE_PATH_REGEX = FILE_PATH_REGEX;
@@ -1688,6 +1815,7 @@ exports.VersionNumber = VersionNumber;
 exports.VersionType = VersionType;
 exports.addDaysToDate = addDaysToDate;
 exports.appendSemicolon = appendSemicolon;
+exports.az = az;
 exports.calculateMonthlyDifference = calculateMonthlyDifference;
 exports.camelToKebab = camelToKebab;
 exports.convertFileToBase64 = convertFileToBase64;