@alextheman/utility 5.11.3 → 5.13.0

package/dist/index.cjs

@@ -87,77 +87,42 @@ function paralleliseArrays(firstArray, secondArray) {
 	return outputArray;
 }
 //#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"
-};
-/**
-* 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/DataError.ts
+//#region src/v6/CodeError.ts
 /**
-* Represents errors you may get that may've been caused by a specific piece of data.
+* Represents errors that can be described using a standardised error code, and a human-readable error message.
 *
 * @category Types
 *
-* @template DataType - The type of the data that caused the error.
+* @template ErrorCode The type of the standardised error code.
 */
-var DataError = class DataError extends Error {
+var CodeError = class CodeError extends Error {
 	code;
-	data;
 	/**
-	* @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(data, code = "INVALID_DATA", message = "The data provided is invalid", options) {
+	constructor(code, message = "Something went wrong.", options) {
 		super(message, options);
 		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);
 	}
+	/**
+	* Checks whether the given input may have been caused by a CodeError.
+	*
+	* @param input - The input to check.
+	*
+	* @returns `true` if the input is a CodeError, and `false` otherwise. The type of the input will also be narrowed down to CodeError if `true`.
+	*/
+	static check(input) {
+		if (input instanceof CodeError) return true;
+		return typeof input === "object" && input !== null && "message" in input && typeof input.message === "string" && "code" in input && typeof input.code === "string";
+	}
 	static checkCaughtError(error, options) {
-		if (DataError.check(error)) {
+		if (this.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}
@@ -168,223 +133,110 @@ var DataError = class DataError extends Error {
 		throw error;
 	}
 	/**
-	* 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) {
-		if (input instanceof DataError) return true;
-		const data = input;
-		return typeof data === "object" && data !== null && typeof data.message === "string" && typeof data.code === "string" && "data" in data;
-	}
-	/**
-	* 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.
+	* Gets the thrown `CodeError` from a given function if one was thrown, and re-throws any other errors, or throws a default `CodeError` if no error thrown.
 	*
 	* @param errorFunction - The function expected to throw the error.
 	* @param options - Extra options to apply.
 	*
-	* @throws {Error} Any other errors thrown by the `errorFunction` that are not a `DataError`.
-	* @throws {Error} If no `DataError` was thrown by the `errorFunction`
+	* @throws {Error} Any other errors thrown by the `errorFunction` that are not a `CodeError`.
+	* @throws {Error} If no `CodeError` was thrown by the `errorFunction`
 	*
-	* @returns The `DataError` that was thrown by the `errorFunction`
+	* @returns The `CodeError` that was thrown by the `errorFunction`
 	*/
 	static expectError(errorFunction, options) {
 		try {
 			errorFunction();
 		} catch (error) {
-			return DataError.checkCaughtError(error, options);
+			return this.checkCaughtError(error, options);
 		}
-		throw new Error("Expected a DataError to be thrown but none was thrown");
+		throw new Error(`Expected a ${this.name} to be thrown but none was thrown`);
 	}
 	/**
-	* 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.
+	* Gets the thrown `CodeError` from a given asynchronous function if one was thrown, and re-throws any other errors, or throws a default `CodeError` if no error thrown.
 	*
 	* @param errorFunction - The function expected to throw the error.
 	* @param options - Extra options to apply.
 	*
-	* @throws {Error} Any other errors thrown by the `errorFunction` that are not a `DataError`.
-	* @throws {Error} If no `DataError` was thrown by the `errorFunction`
+	* @throws {Error} Any other errors thrown by the `errorFunction` that are not a `CodeError`.
+	* @throws {Error} If no `CodeError` was thrown by the `errorFunction`
 	*
-	* @returns The `DataError` that was thrown by the `errorFunction`
+	* @returns The `CodeError` that was thrown by the `errorFunction`
 	*/
 	static async expectErrorAsync(errorFunction, options) {
 		try {
 			await errorFunction();
 		} catch (error) {
-			return DataError.checkCaughtError(error, options);
+			return this.checkCaughtError(error, options);
 		}
-		throw new Error("Expected a DataError to be thrown but none was thrown");
+		throw new Error(`Expected a ${this.name} to be thrown but none was thrown`);
 	}
 };
 //#endregion
-//#region src/root/types/VersionNumber.ts
+//#region src/v6/DataError.ts
 /**
-* Represents a software version number, considered to be made up of a major, minor, and patch part.
+* Represents errors you may get that may've been caused by a specific piece of data.
 *
 * @category Types
+*
+* @template DataType - The type of the data that caused the error.
 */
-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.
-      `);
-	}
+var DataError = class DataError extends CodeError {
+	data;
 	/**
-	* Gets the current version type of the current instance of `VersionNumber`.
-	*
-	* @returns Either `"major"`, `"minor"`, or `"patch"`, depending on the version type.
+	* @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.
 	*/
-	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}`;
+	constructor(data, code = "INVALID_DATA", message = "The data provided is invalid", options) {
+		super(code, message, options);
+		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);
 	}
 	/**
-	* Checks if the provided version numbers have the exact same major, minor, and patch numbers.
+	* Checks whether the given input may have been caused by a DataError.
 	*
-	* @param firstVersion - The first version number to compare.
-	* @param secondVersion - The second version number to compare.
+	* @param input - The input to check.
 	*
-	* @returns `true` if the provided version numbers have exactly the same major, minor, and patch numbers, and returns `false` otherwise.
+	* @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 isEqual(firstVersion, secondVersion) {
-		return firstVersion.major === secondVersion.major && firstVersion.minor === secondVersion.minor && firstVersion.patch === secondVersion.patch;
+	static check(input) {
+		if (input instanceof DataError) 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;
 	}
 	/**
-	* 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];
-		try {
-			return new VersionNumber(calculatedRawVersion);
-		} 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;
-		}
+	static expectError(errorFunction, options) {
+		return super.expectError(errorFunction, options);
 	}
 	/**
-	* 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) {
+		return await super.expectErrorAsync(errorFunction, options);
 	}
 };
-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/functions/parsers/parseIntStrict.ts
 /**
@@ -784,350 +636,116 @@ function isOrdered(array) {
 	return true;
 }
 //#endregion
-//#region src/root/functions/recursive/deepFreeze.ts
+//#region src/root/functions/miscellaneous/sayHello.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.
-*
-* @category Recursive
-*
-* @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);
-}
-//#endregion
-//#region src/root/functions/taggedTemplate/createTemplateStringsArray.ts
-/**
-* Creates a template strings array given a regular array of strings
-*
-* @category Tagged Template
-*
-* @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(Object.assign([...strings], { raw: [...strings] }));
-}
-//#endregion
-//#region src/root/functions/taggedTemplate/getStringsAndInterpolations.ts
-/**
-*
-* Gets the strings and interpolations separately from a template string.
-* You can pass a template string directly by doing:
-*
-* ```typescript
-* getStringsAndInterpolations`Template string here`;
-* ```
-*
-* @category Tagged Template
-*
-* @template InterpolationsType - The type of the interpolations.
-*
-* @param strings - The strings from the template to process.
-* @param interpolations - An array of all interpolations from the template.
-*
-* @returns A tuple where the first item is the strings from the template, and the remaining items are the interpolations.
-*
-* The return of this function may also be spread into any other tagged template function in the following way:
-*
-* ```typescript
-* import { interpolate } from "@alextheman/utility"; // Example function
-*
-* const packageName = "@alextheman/utility";
-* const packageManager = getPackageManager(packageName);
-*
-* interpolate(...getStringsAndInterpolations`The package ${packageName} uses the ${packageManager} package manager.`);
-* ```
-*/
-function getStringsAndInterpolations(strings, ...interpolations) {
-	if (strings.length !== interpolations.length + 1) throw new DataError({
-		stringsLength: strings.length,
-		interpolationsLength: interpolations.length,
-		strings,
-		interpolations
-	}, "INVALID_STRINGS_AND_INTERPOLATIONS_LENGTH", "The length of the strings must be exactly one more than the length of the interpolations.");
-	return [createTemplateStringsArray(strings), ...interpolations];
-}
-//#endregion
-//#region src/root/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.
-*
-* @category Tagged Template
-*
-* @template InterpolationsType - The type of the interpolations.
-*
-* @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(strings, interpolations)) result += string + interpolation;
-	return result;
-}
-//#endregion
-//#region src/root/functions/taggedTemplate/interpolateObjects.ts
-/**
-* Returns the result of interpolating a template string, also stringifying objects.
-*
-* You can pass a template string directly by doing:
-*
-* ```typescript
-* interpolateObjects`Template string here ${{ my: "object" }}`;
-* ```
-*
-* @category Tagged Template
-*
-* @template InterpolationsType - The type of the interpolations.
-*
-* @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 += interpolations[i] && typeof interpolations[i] === "object" ? JSON.stringify(interpolations[i]) : interpolations[i];
-	}
-	return result;
-}
-//#endregion
-//#region src/root/functions/taggedTemplate/isTemplateStringsArray.ts
-/**
-* Determines whether or not the input is a valid `TemplateStringsArray`.
-*
-* @category Tagged Template
-*
-* @param input - The input to check
-*
-* @returns `true` if the input is a valid `TemplateStringsArray`, and false otherwise. The type of the input will also be narrowed down to `TemplateStringsArray` if `true`.
-*/
-function isTemplateStringsArray(input) {
-	return typeof input === "object" && input !== null && "raw" in input;
-}
-//#endregion
-//#region src/root/functions/taggedTemplate/normaliseIndents.ts
-function calculateTabSize(line, whitespaceLength) {
-	const potentialWhitespacePart = line.slice(0, whitespaceLength);
-	const trimmedString = line.trimStart();
-	if (potentialWhitespacePart.trim() !== "") return 0;
-	const tabSize = line.length - (trimmedString.length + whitespaceLength);
-	return tabSize < 0 ? 0 : tabSize;
-}
-function getWhitespaceLength(lines) {
-	const [firstNonEmptyLine] = lines.filter((line) => {
-		return line.trim() !== "";
-	});
-	return firstNonEmptyLine.length - firstNonEmptyLine.trimStart().length;
-}
-function reduceLines(lines, { preserveTabs = true }) {
-	const slicedLines = lines.slice(1);
-	const isFirstLineEmpty = lines[0].trim() === "";
-	const whitespaceLength = getWhitespaceLength(isFirstLineEmpty ? lines : slicedLines);
-	return (isFirstLineEmpty ? slicedLines : lines).map((line) => {
-		const tabSize = calculateTabSize(line, whitespaceLength);
-		return (preserveTabs ? fillArray(() => {
-			return " ";
-		}, 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:
-*
-* ```typescript
-* 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:
-*
-* ```typescript
-* normaliseIndents({ preserveTabs: false })`Template string here
-*     with a new line
-*     and another new line`;
-* ```
-*
-* @category Tagged Template
-*
-* @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 = first;
-		return (strings, ...interpolations) => {
-			return normaliseIndents(strings, ...interpolations, options);
-		};
-	}
-	const strings = first;
-	const options = typeof args[args.length - 1] === "object" && !Array.isArray(args[args.length - 1]) ? args.pop() : {};
-	return reduceLines(interpolate(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:
-*
-* ```typescript
-* 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:
-*
-* ```typescript
-* 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;
-//#endregion
-//#region src/root/functions/miscellaneous/sayHello.ts
-/**
-* Returns a string representing the lyrics to the package's theme song, Commit To You
+* Returns a string representing the lyrics to the package's theme song, Commit To You
 *
 * [Pls listen!](https://www.youtube.com/watch?v=mH-Sg-8EnxM)
 *
 * @returns The lyrics string in markdown format.
 */
 function sayHello() {
-	return normaliseIndents`
-    # Commit To You
+	return `
+# Commit To You
 
-    ### Verse 1
+### Verse 1
 
-    I know you've been checking me out,  
-    Shall we take it to the next level now?  
-    'Cause I really wanna be there all for you,  
-    All for you!  
-    Come on now, let's make a fresh start!  
-    Pin my number, then you can take me out!  
-    Can't you see I really do care about you,  
-    About you!
+I know you've been checking me out,  
+Shall we take it to the next level now?  
+'Cause I really wanna be there all for you,  
+All for you!  
+Come on now, let's make a fresh start!  
+Pin my number, then you can take me out!  
+Can't you see I really do care about you,  
+About you!
 
-    ### Pre-chorus 1
-    Although our calendars are imperfect, at best,  
-    I'd like to organise time with you! (with you!).  
-    Just tell me when and I'll make it clear,  
-    All clear for you,  
-    All clear for you!  
-    (One, two, three, go!)
+### Pre-chorus 1
+Although our calendars are imperfect, at best,  
+I'd like to organise time with you! (with you!).  
+Just tell me when and I'll make it clear,  
+All clear for you,  
+All clear for you!  
+(One, two, three, go!)
 
-    ### Chorus
-    I wanna be of utility, I'll help you on the run!  
-    I'll be the one here in the back, while you go have some fun!  
-    Looking out for you tonight, I'll be the one you can rely on!  
-    Watch you go and watch me pass by,  
-    I'll be here!  
-    I'll commit to you!
+### Chorus
+I wanna be of utility, I'll help you on the run!  
+I'll be the one here in the back, while you go have some fun!  
+Looking out for you tonight, I'll be the one you can rely on!  
+Watch you go and watch me pass by,  
+I'll be here!  
+I'll commit to you!
 
-    ### Verse 2
-    Though sometimes it won't be easy,  
-    You'll be here to bring out the best in me,  
-    And I'll hold myself to high standards for you!  
-    All for you!  
-    We'll grow as a pair, you and me,  
-    We'll build up a healthy dependency,  
-    You can build with me and I'll develop with you!  
-    I'm with you!
+### Verse 2
+Though sometimes it won't be easy,  
+You'll be here to bring out the best in me,  
+And I'll hold myself to high standards for you!  
+All for you!  
+We'll grow as a pair, you and me,  
+We'll build up a healthy dependency,  
+You can build with me and I'll develop with you!  
+I'm with you!
 
-    ### Pre-chorus 2
-    I'll be with you when you're up or you're down,  
-    We'll deal with all our problems together (together!)  
-    Just tell me what you want, I'll make it clear,  
-    All clear for you,  
-    All clear for you!  
-    (One, three, one, go!)
+### Pre-chorus 2
+I'll be with you when you're up or you're down,  
+We'll deal with all our problems together (together!)  
+Just tell me what you want, I'll make it clear,  
+All clear for you,  
+All clear for you!  
+(One, three, one, go!)
 
-    ### Chorus
-    I wanna be of utility, I'll help you on the run!  
-    (help you on the run!)  
-    I'll be the one here in the back, while you go have some fun!  
-    (you go have some fun!)  
-    Looking out for you tonight, I'll be the one you can rely on!  
-    Watch you go and watch me pass by,  
-    I'll be here!  
-    I'll commit to you!
+### Chorus
+I wanna be of utility, I'll help you on the run!  
+(help you on the run!)  
+I'll be the one here in the back, while you go have some fun!  
+(you go have some fun!)  
+Looking out for you tonight, I'll be the one you can rely on!  
+Watch you go and watch me pass by,  
+I'll be here!  
+I'll commit to you!
 
-    ### Bridge
-    Looking into our stack!  
-    I'll commit to you!  
-    We've got a lot to unpack!  
-    I'll commit to you!  
-    The environment that we're in!  
-    I'll commit to you!  
-    Delicate as a string!  
-    I'll commit to you!
+### Bridge
+Looking into our stack!  
+I'll commit to you!  
+We've got a lot to unpack!  
+I'll commit to you!  
+The environment that we're in!  
+I'll commit to you!  
+Delicate as a string!  
+I'll commit to you!
 
-    But I think you're my type!  
-    I'll commit to you!  
-    Oh, this feels all so right!  
-    I'll commit to you!  
-    Nothing stopping us now!  
-    I'll commit to you!  
-    Let's show them what we're about!  
-    Two, three, four, go!
+But I think you're my type!  
+I'll commit to you!  
+Oh, this feels all so right!  
+I'll commit to you!  
+Nothing stopping us now!  
+I'll commit to you!  
+Let's show them what we're about!  
+Two, three, four, go!
 
-    ### Final Chorus
-    I wanna be of utility, I'll help you on the run!  
-    (help you on the run!)  
-    I'll be the one here in the back, while you go have some fun!  
-    (you go have some fun!)  
-    Looking out for you tonight, I'll be the one you can rely on!  
-    Watch you go and watch me pass by,  
-    I'll be here!  
-    I'll commit to you!
+### Final Chorus
+I wanna be of utility, I'll help you on the run!  
+(help you on the run!)  
+I'll be the one here in the back, while you go have some fun!  
+(you go have some fun!)  
+Looking out for you tonight, I'll be the one you can rely on!  
+Watch you go and watch me pass by,  
+I'll be here!  
+I'll commit to you!
 
-    I wanna be of utility, I'll help you on the run!  
-    (I'll commit to you!)  
-    I'll be the one here in the back, while you go have some fun!  
-    (I'll commit to you!)  
-    Looking out for you tonight, I'll be the one you can rely on!  
-    (I'll commit to you!)  
-    Watch you go and watch me pass by,  
-    (I'll commit to you!)  
-    I'll be here!  
+I wanna be of utility, I'll help you on the run!  
+(I'll commit to you!)  
+I'll be the one here in the back, while you go have some fun!  
+(I'll commit to you!)  
+Looking out for you tonight, I'll be the one you can rely on!  
+(I'll commit to you!)  
+Watch you go and watch me pass by,  
+(I'll commit to you!)  
+I'll be here!  
 
-    ### Outro
-    I'll commit to you!  
-    I'll commit to you!  
-    I'll commit to you!
+### Outro
+I'll commit to you!  
+I'll commit to you!  
+I'll commit to you!
     `;
 }
 //#endregion
@@ -1314,7 +932,7 @@ function _parseZodSchema(parsedResult, input, onError) {
 * @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.
+* @throws {DataErrorCode} If the given data cannot be parsed according to the schema.
 *
 * @returns The parsed data from the Zod schema.
 */
@@ -1462,6 +1080,29 @@ function deepCopy(object) {
 	return clonedObject;
 }
 //#endregion
+//#region src/root/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.
+*
+* @category Recursive
+*
+* @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);
+}
+//#endregion
 //#region src/root/functions/stringHelpers/appendSemicolon.ts
 /**
 * Appends a semicolon to the end of a string, trimming where necessary first.
@@ -1613,8 +1254,428 @@ function truncate(stringToTruncate, maxLength = 5) {
 	return stringToTruncate.length > maxLength ? `${stringToTruncate.slice(0, maxLength)}...` : stringToTruncate;
 }
 //#endregion
+//#region src/root/functions/taggedTemplate/createTemplateStringsArray.ts
+/**
+* Creates a template strings array given a regular array of strings
+*
+* @category Tagged Template
+*
+* @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(Object.assign([...strings], { raw: [...strings] }));
+}
+//#endregion
+//#region src/root/functions/taggedTemplate/getStringsAndInterpolations.ts
+/**
+*
+* Gets the strings and interpolations separately from a template string.
+* You can pass a template string directly by doing:
+*
+* ```typescript
+* getStringsAndInterpolations`Template string here`;
+* ```
+*
+* @category Tagged Template
+*
+* @template InterpolationsType - The type of the interpolations.
+*
+* @param strings - The strings from the template to process.
+* @param interpolations - An array of all interpolations from the template.
+*
+* @returns A tuple where the first item is the strings from the template, and the remaining items are the interpolations.
+*
+* The return of this function may also be spread into any other tagged template function in the following way:
+*
+* ```typescript
+* import { interpolate } from "@alextheman/utility"; // Example function
+*
+* const packageName = "@alextheman/utility";
+* const packageManager = getPackageManager(packageName);
+*
+* interpolate(...getStringsAndInterpolations`The package ${packageName} uses the ${packageManager} package manager.`);
+* ```
+*/
+function getStringsAndInterpolations(strings, ...interpolations) {
+	if (strings.length !== interpolations.length + 1) throw new DataError({
+		stringsLength: strings.length,
+		interpolationsLength: interpolations.length,
+		strings,
+		interpolations
+	}, "INVALID_STRINGS_AND_INTERPOLATIONS_LENGTH", "The length of the strings must be exactly one more than the length of the interpolations.");
+	return [createTemplateStringsArray(strings), ...interpolations];
+}
+//#endregion
+//#region src/root/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.
+*
+* @category Tagged Template
+*
+* @template InterpolationsType - The type of the interpolations.
+*
+* @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(strings, interpolations)) result += string + interpolation;
+	return result;
+}
+//#endregion
+//#region src/root/functions/taggedTemplate/interpolateObjects.ts
+/**
+* Returns the result of interpolating a template string, also stringifying objects.
+*
+* You can pass a template string directly by doing:
+*
+* ```typescript
+* interpolateObjects`Template string here ${{ my: "object" }}`;
+* ```
+*
+* @category Tagged Template
+*
+* @template InterpolationsType - The type of the interpolations.
+*
+* @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 += interpolations[i] && typeof interpolations[i] === "object" ? JSON.stringify(interpolations[i]) : interpolations[i];
+	}
+	return result;
+}
+//#endregion
+//#region src/root/functions/taggedTemplate/isTemplateStringsArray.ts
+/**
+* Determines whether or not the input is a valid `TemplateStringsArray`.
+*
+* @category Tagged Template
+*
+* @param input - The input to check
+*
+* @returns `true` if the input is a valid `TemplateStringsArray`, and false otherwise. The type of the input will also be narrowed down to `TemplateStringsArray` if `true`.
+*/
+function isTemplateStringsArray(input) {
+	return typeof input === "object" && input !== null && "raw" in input;
+}
+//#endregion
+//#region src/root/functions/taggedTemplate/normaliseIndents.ts
+function calculateTabSize(line, whitespaceLength) {
+	const potentialWhitespacePart = line.slice(0, whitespaceLength);
+	const trimmedString = line.trimStart();
+	if (potentialWhitespacePart.trim() !== "") return 0;
+	const tabSize = line.length - (trimmedString.length + whitespaceLength);
+	return tabSize < 0 ? 0 : tabSize;
+}
+function getWhitespaceLength(lines) {
+	const [firstNonEmptyLine] = lines.filter((line) => {
+		return line.trim() !== "";
+	});
+	return firstNonEmptyLine.length - firstNonEmptyLine.trimStart().length;
+}
+function reduceLines(lines, { preserveTabs = true }) {
+	const slicedLines = lines.slice(1);
+	const isFirstLineEmpty = lines[0].trim() === "";
+	const whitespaceLength = getWhitespaceLength(isFirstLineEmpty ? lines : slicedLines);
+	return (isFirstLineEmpty ? slicedLines : lines).map((line) => {
+		const tabSize = calculateTabSize(line, whitespaceLength);
+		return (preserveTabs ? fillArray(() => {
+			return " ";
+		}, 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:
+*
+* ```typescript
+* 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:
+*
+* ```typescript
+* normaliseIndents({ preserveTabs: false })`Template string here
+*     with a new line
+*     and another new line`;
+* ```
+*
+* @category Tagged Template
+*
+* @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 = first;
+		return (strings, ...interpolations) => {
+			return normaliseIndents(strings, ...interpolations, options);
+		};
+	}
+	const strings = first;
+	const options = typeof args[args.length - 1] === "object" && !Array.isArray(args[args.length - 1]) ? args.pop() : {};
+	return reduceLines(interpolate(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:
+*
+* ```typescript
+* 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:
+*
+* ```typescript
+* 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;
+//#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"
+};
+/**
+* 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({ 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.
+	*
+	* @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.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;
+		}
+	}
+	/**
+	* 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({ 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
 exports.APIError = APIError;
-exports.DataError = DataError;
 exports.Env = Env;
 exports.FILE_PATH_PATTERN = FILE_PATH_PATTERN;
 exports.FILE_PATH_REGEX = FILE_PATH_REGEX;