@alextheman/utility 5.1.4 → 5.3.0

package/dist/index.cjs

@@ -38,6 +38,10 @@ const FILE_PATH_REGEX = String.raw`^(?<directory>.+)[\/\\](?<base>[^\/\\]+)$`;
 //#region src/root/constants/NAMESPACE_EXPORT_REGEX.ts
 const NAMESPACE_EXPORT_REGEX = "export\\s+\\*\\s+from";
 
+//#endregion
+//#region src/root/constants/ONE_DAY_IN_MILLISECONDS.ts
+const ONE_DAY_IN_MILLISECONDS = 1440 * 60 * 1e3;
+
 //#endregion
 //#region src/root/constants/VERSION_NUMBER_REGEX.ts
 const VERSION_NUMBER_REGEX = "^(?:v)?(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$";
@@ -164,6 +168,17 @@ var DataError = class DataError extends Error {
 		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 a DataError.
 	*
@@ -176,6 +191,44 @@ var DataError = class DataError extends Error {
 		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.
+	*
+	* @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`
+	*
+	* @returns The `DataError` that was thrown by the `errorFunction`
+	*/
+	static expectError(errorFunction, options) {
+		try {
+			errorFunction();
+		} catch (error) {
+			return DataError.checkCaughtError(error, options);
+		}
+		throw new Error("Expected a DataError 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.
+	*
+	* @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`
+	*
+	* @returns The `DataError` that was thrown by the `errorFunction`
+	*/
+	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");
+	}
 };
 
 //#endregion
@@ -430,19 +483,27 @@ function randomiseArray(array) {
 * @param stop - The number to stop at (exclusive).
 * @param step - The step size between numbers, defaulting to 1.
 *
-* @throws {Error} If `step` is `0`.
-* @throws {Error} If `step` direction does not match the order of `start` and `stop`.
+* @throws {DataError} If `step` is `0`.
+* @throws {DataError} If `step` direction does not match the order of `start` and `stop`.
 *
 * @returns An array of numbers satisfying the range provided.
 */
 function range(start, stop, step = 1) {
 	const numbers = [];
-	if (step === 0) throw new Error("ZERO_STEP_SIZE_NOT_ALLOWED");
+	if (step === 0) throw new DataError({ step }, "ZERO_STEP_SIZE", "Step size cannot be zero.");
 	else if (step > 0) {
-		if (start > stop) throw new Error("INVALID_BOUNDARIES");
+		if (start > stop) throw new DataError({
+			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 Error("INVALID_BOUNDARIES");
+		if (start < stop) throw new DataError({
+			start,
+			stop,
+			step
+		}, "INVALID_BOUNDARIES", "The final value cannot be bigger than the starting value if step is negative");
 		for (let i = start; i > stop; i += step) numbers.push(i);
 	}
 	return numbers;
@@ -622,7 +683,7 @@ function isMonthlyMultiple(firstDate, secondDate) {
 *
 * @param file - The file to convert.
 *
-* @throws {Error} If the file reader gives an error.
+* @throws {Error | DataError} If the file reader gives an error.
 *
 * @returns A promise that resolves to the encoded base 64 string.
 */
@@ -632,7 +693,7 @@ function convertFileToBase64(file) {
 		reader.readAsDataURL(file);
 		reader.onload = () => {
 			if (reader.result === null) {
-				reject(/* @__PURE__ */ new Error("FILE_CONVERSION_ERROR"));
+				reject(new DataError({ result: reader.result }, "FILE_CONVERSION_ERROR", "Could not convert the given file."));
 				return;
 			}
 			resolve(reader.result);
@@ -648,6 +709,9 @@ function convertFileToBase64(file) {
 function getNullableResolutionStrategy(key, strategy) {
 	return (typeof strategy === "object" ? strategy[key] : strategy) ?? "empty";
 }
+function isPrimitive(item) {
+	return typeof item === "string" || typeof item === "number" || typeof item === "boolean";
+}
 /**
 * Creates FormData from a given object, resolving non-string types as appropriate.
 *
@@ -674,7 +738,7 @@ function createFormData(data, options = {
 				formData.append(String(key), JSON.stringify(value));
 				break;
 			case "omit": break;
-			default: throw new TypeError("SLOPPY_PURE_JAVASCRIPT_USER_ERROR");
+			default: throw resolutionStrategy;
 		}
 	}
 	function resolveNullables(key, value, options) {
@@ -697,10 +761,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 TypeError("CANNOT_STRINGIFY_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.");
 			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 (!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 (item instanceof Blob) formData.append(String(key), item);
 					else formData.append(String(key), String(item));
 				}
@@ -1442,12 +1506,12 @@ async function encryptWithKey(publicKey, plaintextValue) {
 *
 * @param stringToAppendTo - The string to append a semicolon to.
 *
-* @throws {Error} If the string contains multiple lines.
+* @throws {DataError} 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");
+	if (stringToAppendTo.includes("\n")) throw new DataError({ 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};`;
@@ -1499,34 +1563,35 @@ function camelToKebab(string, options = { preserveConsecutiveCapitals: true }) {
 *
 * @category String Helpers
 *
-* @param string - The string to convert.
+* @param input - 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");
+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.");
 	let outputString = "";
 	let skip = false;
-	for (const stringIndex in [...string]) {
+	for (const stringIndex in [...input]) {
 		if (skip) {
 			skip = false;
 			continue;
 		}
 		const index = parseIntStrict(stringIndex);
 		if (index === 0 && options?.startWithUpper) {
-			outputString += string[index].toUpperCase();
+			outputString += input[index].toUpperCase();
 			continue;
 		}
-		if (index === string.length - 1) {
-			outputString += string[index];
+		if (index === input.length - 1) {
+			outputString += input[index];
 			break;
 		}
-		if (string[index] === "-" && /^[a-zA-Z]+$/.test(string[index + 1])) {
-			outputString += string[index + 1].toUpperCase();
+		if (input[index] === "-" && /^[a-zA-Z]+$/.test(input[index + 1])) {
+			outputString += input[index + 1].toUpperCase();
 			skip = true;
-		} else outputString += string[index];
+		} else outputString += input[index];
 	}
 	return outputString;
 }
@@ -1553,6 +1618,7 @@ exports.DataError = DataError;
 exports.Env = Env;
 exports.FILE_PATH_REGEX = FILE_PATH_REGEX;
 exports.NAMESPACE_EXPORT_REGEX = NAMESPACE_EXPORT_REGEX;
+exports.ONE_DAY_IN_MILLISECONDS = ONE_DAY_IN_MILLISECONDS;
 exports.VERSION_NUMBER_REGEX = VERSION_NUMBER_REGEX;
 exports.VersionNumber = VersionNumber;
 exports.VersionType = VersionType;

package/dist/index.d.cts

@@ -7,6 +7,9 @@ declare const FILE_PATH_REGEX: string;
 //#region src/root/constants/NAMESPACE_EXPORT_REGEX.d.ts
 declare const NAMESPACE_EXPORT_REGEX = "export\\s+\\*\\s+from";
 //#endregion
+//#region src/root/constants/ONE_DAY_IN_MILLISECONDS.d.ts
+declare const ONE_DAY_IN_MILLISECONDS: number;
+//#endregion
 //#region src/root/constants/VERSION_NUMBER_REGEX.d.ts
 declare const VERSION_NUMBER_REGEX: string;
 //#endregion
@@ -87,8 +90,8 @@ declare function randomiseArray<ItemType>(array: ItemType[]): ItemType[];
  * @param stop - The number to stop at (exclusive).
  * @param step - The step size between numbers, defaulting to 1.
  *
- * @throws {Error} If `step` is `0`.
- * @throws {Error} If `step` direction does not match the order of `start` and `stop`.
+ * @throws {DataError} If `step` is `0`.
+ * @throws {DataError} If `step` direction does not match the order of `start` and `stop`.
  *
  * @returns An array of numbers satisfying the range provided.
  */
@@ -198,7 +201,7 @@ declare function isSameDate(firstDate: Date, secondDate: Date): boolean;
  *
  * @param file - The file to convert.
  *
- * @throws {Error} If the file reader gives an error.
+ * @throws {Error | DataError} If the file reader gives an error.
  *
  * @returns A promise that resolves to the encoded base 64 string.
  */
@@ -239,6 +242,9 @@ declare class APIError extends Error {
 type RecordKey = string | number | symbol;
 //#endregion
 //#region src/root/types/DataError.d.ts
+interface ExpectErrorOptions {
+  expectedCode?: string;
+}
 /**
  * Represents errors you may get that may've been caused by a specific piece of data.
  *
@@ -256,6 +262,7 @@ declare class DataError<DataType extends Record<RecordKey, unknown> = Record<Rec
    * @param options - Extra options to pass to super Error constructor.
    */
   constructor(data: DataType, code?: string, message?: string, options?: ErrorOptions);
+  private static checkCaughtError;
   /**
    * Checks whether the given input may have been caused by a DataError.
    *
@@ -264,6 +271,30 @@ declare class DataError<DataType extends Record<RecordKey, unknown> = Record<Rec
    * @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<DataType extends Record<RecordKey, unknown> = Record<RecordKey, unknown>>(input: unknown): input is DataError<DataType>;
+  /**
+   * 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.
+   *
+   * @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`
+   *
+   * @returns The `DataError` that was thrown by the `errorFunction`
+   */
+  static expectError(errorFunction: () => unknown, options?: ExpectErrorOptions): DataError;
+  /**
+   * 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.
+   *
+   * @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`
+   *
+   * @returns The `DataError` that was thrown by the `errorFunction`
+   */
+  static expectErrorAsync(errorFunction: () => Promise<unknown>, options?: ExpectErrorOptions): Promise<DataError>;
 }
 //#endregion
 //#region src/root/types/VersionNumber.d.ts
@@ -821,7 +852,7 @@ declare function encryptWithKey(publicKey: string, plaintextValue: string): Prom
  *
  * @param stringToAppendTo - The string to append a semicolon to.
  *
- * @throws {Error} If the string contains multiple lines.
+ * @throws {DataError} If the string contains multiple lines.
  *
  * @returns A string with the semicolon appended.
  */
@@ -864,12 +895,12 @@ interface KebabToCamelOptions {
  *
  * @category String Helpers
  *
- * @param string - The string to convert.
+ * @param input - The string to convert.
  * @param options - Options to apply to the conversion.
  *
  * @returns The string converted to camelCase.
  */
-declare function kebabToCamel(string: string, options?: KebabToCamelOptions): string;
+declare function kebabToCamel(input: string, options?: KebabToCamelOptions): string;
 //#endregion
 //#region src/root/functions/stringHelpers/truncate.d.ts
 /**
@@ -1052,4 +1083,4 @@ declare function normaliseIndents(strings: TemplateStringsArray, ...interpolatio
  */
 declare const normalizeIndents: typeof normaliseIndents;
 //#endregion
-export { APIError, ArrayElement, CallReturnType, CamelToKebabOptions, CreateEnumType, CreateFormDataOptions, CreateFormDataOptionsNullableResolution, CreateFormDataOptionsUndefinedOrNullResolution, DataError, DisallowUndefined, Env, FILE_PATH_REGEX, FormDataArrayResolutionStrategy, FormDataNullableResolutionStrategy, HTTPErrorCode, IgnoreCase, IsTypeArgumentString, KebabToCamelOptions, NAMESPACE_EXPORT_REGEX, NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, OptionalOnCondition, ParallelTuple, RecordKey, RemoveUndefined, StringListToArrayOptions, VERSION_NUMBER_REGEX, VersionNumber, FormatOptionsBase as VersionNumberToStringOptions, VersionType, addDaysToDate, appendSemicolon, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, encryptWithKey, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, getStringsAndInterpolations, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, isTemplateStringsArray, kebabToCamel, normaliseIndents, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, sayHello, stringListToArray, stringifyDotenv, truncate, wait, zodVersionNumber };
+export { APIError, ArrayElement, CallReturnType, CamelToKebabOptions, CreateEnumType, CreateFormDataOptions, CreateFormDataOptionsNullableResolution, CreateFormDataOptionsUndefinedOrNullResolution, DataError, DisallowUndefined, Env, FILE_PATH_REGEX, FormDataArrayResolutionStrategy, FormDataNullableResolutionStrategy, HTTPErrorCode, IgnoreCase, IsTypeArgumentString, KebabToCamelOptions, NAMESPACE_EXPORT_REGEX, NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, ONE_DAY_IN_MILLISECONDS, OptionalOnCondition, ParallelTuple, RecordKey, RemoveUndefined, StringListToArrayOptions, VERSION_NUMBER_REGEX, VersionNumber, FormatOptionsBase as VersionNumberToStringOptions, VersionType, addDaysToDate, appendSemicolon, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, encryptWithKey, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, getStringsAndInterpolations, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, isTemplateStringsArray, kebabToCamel, normaliseIndents, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, sayHello, stringListToArray, stringifyDotenv, truncate, wait, zodVersionNumber };

package/dist/index.d.ts

@@ -7,6 +7,9 @@ declare const FILE_PATH_REGEX: string;
 //#region src/root/constants/NAMESPACE_EXPORT_REGEX.d.ts
 declare const NAMESPACE_EXPORT_REGEX = "export\\s+\\*\\s+from";
 //#endregion
+//#region src/root/constants/ONE_DAY_IN_MILLISECONDS.d.ts
+declare const ONE_DAY_IN_MILLISECONDS: number;
+//#endregion
 //#region src/root/constants/VERSION_NUMBER_REGEX.d.ts
 declare const VERSION_NUMBER_REGEX: string;
 //#endregion
@@ -87,8 +90,8 @@ declare function randomiseArray<ItemType>(array: ItemType[]): ItemType[];
  * @param stop - The number to stop at (exclusive).
  * @param step - The step size between numbers, defaulting to 1.
  *
- * @throws {Error} If `step` is `0`.
- * @throws {Error} If `step` direction does not match the order of `start` and `stop`.
+ * @throws {DataError} If `step` is `0`.
+ * @throws {DataError} If `step` direction does not match the order of `start` and `stop`.
  *
  * @returns An array of numbers satisfying the range provided.
  */
@@ -198,7 +201,7 @@ declare function isSameDate(firstDate: Date, secondDate: Date): boolean;
  *
  * @param file - The file to convert.
  *
- * @throws {Error} If the file reader gives an error.
+ * @throws {Error | DataError} If the file reader gives an error.
  *
  * @returns A promise that resolves to the encoded base 64 string.
  */
@@ -239,6 +242,9 @@ declare class APIError extends Error {
 type RecordKey = string | number | symbol;
 //#endregion
 //#region src/root/types/DataError.d.ts
+interface ExpectErrorOptions {
+  expectedCode?: string;
+}
 /**
  * Represents errors you may get that may've been caused by a specific piece of data.
  *
@@ -256,6 +262,7 @@ declare class DataError<DataType extends Record<RecordKey, unknown> = Record<Rec
    * @param options - Extra options to pass to super Error constructor.
    */
   constructor(data: DataType, code?: string, message?: string, options?: ErrorOptions);
+  private static checkCaughtError;
   /**
    * Checks whether the given input may have been caused by a DataError.
    *
@@ -264,6 +271,30 @@ declare class DataError<DataType extends Record<RecordKey, unknown> = Record<Rec
    * @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<DataType extends Record<RecordKey, unknown> = Record<RecordKey, unknown>>(input: unknown): input is DataError<DataType>;
+  /**
+   * 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.
+   *
+   * @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`
+   *
+   * @returns The `DataError` that was thrown by the `errorFunction`
+   */
+  static expectError(errorFunction: () => unknown, options?: ExpectErrorOptions): DataError;
+  /**
+   * 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.
+   *
+   * @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`
+   *
+   * @returns The `DataError` that was thrown by the `errorFunction`
+   */
+  static expectErrorAsync(errorFunction: () => Promise<unknown>, options?: ExpectErrorOptions): Promise<DataError>;
 }
 //#endregion
 //#region src/root/types/VersionNumber.d.ts
@@ -821,7 +852,7 @@ declare function encryptWithKey(publicKey: string, plaintextValue: string): Prom
  *
  * @param stringToAppendTo - The string to append a semicolon to.
  *
- * @throws {Error} If the string contains multiple lines.
+ * @throws {DataError} If the string contains multiple lines.
  *
  * @returns A string with the semicolon appended.
  */
@@ -864,12 +895,12 @@ interface KebabToCamelOptions {
  *
  * @category String Helpers
  *
- * @param string - The string to convert.
+ * @param input - The string to convert.
  * @param options - Options to apply to the conversion.
  *
  * @returns The string converted to camelCase.
  */
-declare function kebabToCamel(string: string, options?: KebabToCamelOptions): string;
+declare function kebabToCamel(input: string, options?: KebabToCamelOptions): string;
 //#endregion
 //#region src/root/functions/stringHelpers/truncate.d.ts
 /**
@@ -1052,4 +1083,4 @@ declare function normaliseIndents(strings: TemplateStringsArray, ...interpolatio
  */
 declare const normalizeIndents: typeof normaliseIndents;
 //#endregion
-export { APIError, type ArrayElement, type CallReturnType, CamelToKebabOptions, type CreateEnumType, type CreateFormDataOptions, type CreateFormDataOptionsNullableResolution, type CreateFormDataOptionsUndefinedOrNullResolution, DataError, type DisallowUndefined, Env, FILE_PATH_REGEX, type FormDataArrayResolutionStrategy, type FormDataNullableResolutionStrategy, type HTTPErrorCode, type IgnoreCase, type IsTypeArgumentString, KebabToCamelOptions, NAMESPACE_EXPORT_REGEX, type NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, type OptionalOnCondition, ParallelTuple, type RecordKey, type RemoveUndefined, type StringListToArrayOptions, VERSION_NUMBER_REGEX, VersionNumber, type FormatOptionsBase as VersionNumberToStringOptions, VersionType, addDaysToDate, appendSemicolon, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, encryptWithKey, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, getStringsAndInterpolations, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, isTemplateStringsArray, kebabToCamel, normaliseIndents, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, sayHello, stringListToArray, stringifyDotenv, truncate, wait, zodVersionNumber };
+export { APIError, type ArrayElement, type CallReturnType, CamelToKebabOptions, type CreateEnumType, type CreateFormDataOptions, type CreateFormDataOptionsNullableResolution, type CreateFormDataOptionsUndefinedOrNullResolution, DataError, type DisallowUndefined, Env, FILE_PATH_REGEX, type FormDataArrayResolutionStrategy, type FormDataNullableResolutionStrategy, type HTTPErrorCode, type IgnoreCase, type IsTypeArgumentString, KebabToCamelOptions, NAMESPACE_EXPORT_REGEX, type NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, ONE_DAY_IN_MILLISECONDS, type OptionalOnCondition, ParallelTuple, type RecordKey, type RemoveUndefined, type StringListToArrayOptions, VERSION_NUMBER_REGEX, VersionNumber, type FormatOptionsBase as VersionNumberToStringOptions, VersionType, addDaysToDate, appendSemicolon, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, encryptWithKey, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, getStringsAndInterpolations, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, isTemplateStringsArray, kebabToCamel, normaliseIndents, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, sayHello, stringListToArray, stringifyDotenv, truncate, wait, zodVersionNumber };

package/dist/index.js

@@ -8,6 +8,10 @@ const FILE_PATH_REGEX = String.raw`^(?<directory>.+)[\/\\](?<base>[^\/\\]+)$`;
 //#region src/root/constants/NAMESPACE_EXPORT_REGEX.ts
 const NAMESPACE_EXPORT_REGEX = "export\\s+\\*\\s+from";
 
+//#endregion
+//#region src/root/constants/ONE_DAY_IN_MILLISECONDS.ts
+const ONE_DAY_IN_MILLISECONDS = 1440 * 60 * 1e3;
+
 //#endregion
 //#region src/root/constants/VERSION_NUMBER_REGEX.ts
 const VERSION_NUMBER_REGEX = "^(?:v)?(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$";
@@ -134,6 +138,17 @@ var DataError = class DataError extends Error {
 		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 a DataError.
 	*
@@ -146,6 +161,44 @@ var DataError = class DataError extends Error {
 		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.
+	*
+	* @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`
+	*
+	* @returns The `DataError` that was thrown by the `errorFunction`
+	*/
+	static expectError(errorFunction, options) {
+		try {
+			errorFunction();
+		} catch (error) {
+			return DataError.checkCaughtError(error, options);
+		}
+		throw new Error("Expected a DataError 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.
+	*
+	* @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`
+	*
+	* @returns The `DataError` that was thrown by the `errorFunction`
+	*/
+	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");
+	}
 };
 
 //#endregion
@@ -400,19 +453,27 @@ function randomiseArray(array) {
 * @param stop - The number to stop at (exclusive).
 * @param step - The step size between numbers, defaulting to 1.
 *
-* @throws {Error} If `step` is `0`.
-* @throws {Error} If `step` direction does not match the order of `start` and `stop`.
+* @throws {DataError} If `step` is `0`.
+* @throws {DataError} If `step` direction does not match the order of `start` and `stop`.
 *
 * @returns An array of numbers satisfying the range provided.
 */
 function range(start, stop, step = 1) {
 	const numbers = [];
-	if (step === 0) throw new Error("ZERO_STEP_SIZE_NOT_ALLOWED");
+	if (step === 0) throw new DataError({ step }, "ZERO_STEP_SIZE", "Step size cannot be zero.");
 	else if (step > 0) {
-		if (start > stop) throw new Error("INVALID_BOUNDARIES");
+		if (start > stop) throw new DataError({
+			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 Error("INVALID_BOUNDARIES");
+		if (start < stop) throw new DataError({
+			start,
+			stop,
+			step
+		}, "INVALID_BOUNDARIES", "The final value cannot be bigger than the starting value if step is negative");
 		for (let i = start; i > stop; i += step) numbers.push(i);
 	}
 	return numbers;
@@ -592,7 +653,7 @@ function isMonthlyMultiple(firstDate, secondDate) {
 *
 * @param file - The file to convert.
 *
-* @throws {Error} If the file reader gives an error.
+* @throws {Error | DataError} If the file reader gives an error.
 *
 * @returns A promise that resolves to the encoded base 64 string.
 */
@@ -602,7 +663,7 @@ function convertFileToBase64(file) {
 		reader.readAsDataURL(file);
 		reader.onload = () => {
 			if (reader.result === null) {
-				reject(/* @__PURE__ */ new Error("FILE_CONVERSION_ERROR"));
+				reject(new DataError({ result: reader.result }, "FILE_CONVERSION_ERROR", "Could not convert the given file."));
 				return;
 			}
 			resolve(reader.result);
@@ -618,6 +679,9 @@ function convertFileToBase64(file) {
 function getNullableResolutionStrategy(key, strategy) {
 	return (typeof strategy === "object" ? strategy[key] : strategy) ?? "empty";
 }
+function isPrimitive(item) {
+	return typeof item === "string" || typeof item === "number" || typeof item === "boolean";
+}
 /**
 * Creates FormData from a given object, resolving non-string types as appropriate.
 *
@@ -644,7 +708,7 @@ function createFormData(data, options = {
 				formData.append(String(key), JSON.stringify(value));
 				break;
 			case "omit": break;
-			default: throw new TypeError("SLOPPY_PURE_JAVASCRIPT_USER_ERROR");
+			default: throw resolutionStrategy;
 		}
 	}
 	function resolveNullables(key, value, options) {
@@ -667,10 +731,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 TypeError("CANNOT_STRINGIFY_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.");
 			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 (!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 (item instanceof Blob) formData.append(String(key), item);
 					else formData.append(String(key), String(item));
 				}
@@ -1412,12 +1476,12 @@ async function encryptWithKey(publicKey, plaintextValue) {
 *
 * @param stringToAppendTo - The string to append a semicolon to.
 *
-* @throws {Error} If the string contains multiple lines.
+* @throws {DataError} 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");
+	if (stringToAppendTo.includes("\n")) throw new DataError({ 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};`;
@@ -1469,34 +1533,35 @@ function camelToKebab(string, options = { preserveConsecutiveCapitals: true }) {
 *
 * @category String Helpers
 *
-* @param string - The string to convert.
+* @param input - 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");
+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.");
 	let outputString = "";
 	let skip = false;
-	for (const stringIndex in [...string]) {
+	for (const stringIndex in [...input]) {
 		if (skip) {
 			skip = false;
 			continue;
 		}
 		const index = parseIntStrict(stringIndex);
 		if (index === 0 && options?.startWithUpper) {
-			outputString += string[index].toUpperCase();
+			outputString += input[index].toUpperCase();
 			continue;
 		}
-		if (index === string.length - 1) {
-			outputString += string[index];
+		if (index === input.length - 1) {
+			outputString += input[index];
 			break;
 		}
-		if (string[index] === "-" && /^[a-zA-Z]+$/.test(string[index + 1])) {
-			outputString += string[index + 1].toUpperCase();
+		if (input[index] === "-" && /^[a-zA-Z]+$/.test(input[index + 1])) {
+			outputString += input[index + 1].toUpperCase();
 			skip = true;
-		} else outputString += string[index];
+		} else outputString += input[index];
 	}
 	return outputString;
 }
@@ -1518,4 +1583,4 @@ function truncate(stringToTruncate, maxLength = 5) {
 }
 
 //#endregion
-export { APIError, DataError, Env, FILE_PATH_REGEX, NAMESPACE_EXPORT_REGEX, VERSION_NUMBER_REGEX, VersionNumber, VersionType, addDaysToDate, appendSemicolon, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, encryptWithKey, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, getStringsAndInterpolations, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, isTemplateStringsArray, kebabToCamel, normaliseIndents, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, sayHello, stringListToArray, stringifyDotenv, truncate, wait, zodVersionNumber };
+export { APIError, DataError, Env, FILE_PATH_REGEX, NAMESPACE_EXPORT_REGEX, ONE_DAY_IN_MILLISECONDS, VERSION_NUMBER_REGEX, VersionNumber, VersionType, addDaysToDate, appendSemicolon, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, encryptWithKey, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, getStringsAndInterpolations, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, isTemplateStringsArray, kebabToCamel, normaliseIndents, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, sayHello, stringListToArray, stringifyDotenv, truncate, wait, zodVersionNumber };

package/dist/internal/index.cjs

@@ -118,6 +118,17 @@ var DataError = class DataError extends Error {
 		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 a DataError.
 	*
@@ -130,12 +141,54 @@ var DataError = class DataError extends Error {
 		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.
+	*
+	* @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`
+	*
+	* @returns The `DataError` that was thrown by the `errorFunction`
+	*/
+	static expectError(errorFunction, options) {
+		try {
+			errorFunction();
+		} catch (error) {
+			return DataError.checkCaughtError(error, options);
+		}
+		throw new Error("Expected a DataError 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.
+	*
+	* @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`
+	*
+	* @returns The `DataError` that was thrown by the `errorFunction`
+	*/
+	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");
+	}
 };
 
 //#endregion
 //#region src/root/constants/FILE_PATH_REGEX.ts
 const FILE_PATH_REGEX = String.raw`^(?<directory>.+)[\/\\](?<base>[^\/\\]+)$`;
 
+//#endregion
+//#region src/root/constants/ONE_DAY_IN_MILLISECONDS.ts
+const ONE_DAY_IN_MILLISECONDS = 1440 * 60 * 1e3;
+
 //#endregion
 //#region src/root/constants/VERSION_NUMBER_REGEX.ts
 const VERSION_NUMBER_REGEX = "^(?:v)?(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$";

package/dist/internal/index.d.cts

@@ -9,6 +9,9 @@ import { ExecaMethod } from "execa";
 type RecordKey = string | number | symbol;
 //#endregion
 //#region src/root/types/DataError.d.ts
+interface ExpectErrorOptions {
+  expectedCode?: string;
+}
 /**
  * Represents errors you may get that may've been caused by a specific piece of data.
  *
@@ -26,6 +29,7 @@ declare class DataError<DataType extends Record<RecordKey, unknown> = Record<Rec
    * @param options - Extra options to pass to super Error constructor.
    */
   constructor(data: DataType, code?: string, message?: string, options?: ErrorOptions);
+  private static checkCaughtError;
   /**
    * Checks whether the given input may have been caused by a DataError.
    *
@@ -34,6 +38,30 @@ declare class DataError<DataType extends Record<RecordKey, unknown> = Record<Rec
    * @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<DataType extends Record<RecordKey, unknown> = Record<RecordKey, unknown>>(input: unknown): input is DataError<DataType>;
+  /**
+   * 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.
+   *
+   * @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`
+   *
+   * @returns The `DataError` that was thrown by the `errorFunction`
+   */
+  static expectError(errorFunction: () => unknown, options?: ExpectErrorOptions): DataError;
+  /**
+   * 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.
+   *
+   * @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`
+   *
+   * @returns The `DataError` that was thrown by the `errorFunction`
+   */
+  static expectErrorAsync(errorFunction: () => Promise<unknown>, options?: ExpectErrorOptions): Promise<DataError>;
 }
 //#endregion
 //#region src/root/types/CreateEnumType.d.ts

package/dist/internal/index.d.ts

@@ -10,6 +10,9 @@ import { ExecaMethod } from "execa";
 type RecordKey = string | number | symbol;
 //#endregion
 //#region src/root/types/DataError.d.ts
+interface ExpectErrorOptions {
+  expectedCode?: string;
+}
 /**
  * Represents errors you may get that may've been caused by a specific piece of data.
  *
@@ -27,6 +30,7 @@ declare class DataError<DataType extends Record<RecordKey, unknown> = Record<Rec
    * @param options - Extra options to pass to super Error constructor.
    */
   constructor(data: DataType, code?: string, message?: string, options?: ErrorOptions);
+  private static checkCaughtError;
   /**
    * Checks whether the given input may have been caused by a DataError.
    *
@@ -35,6 +39,30 @@ declare class DataError<DataType extends Record<RecordKey, unknown> = Record<Rec
    * @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<DataType extends Record<RecordKey, unknown> = Record<RecordKey, unknown>>(input: unknown): input is DataError<DataType>;
+  /**
+   * 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.
+   *
+   * @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`
+   *
+   * @returns The `DataError` that was thrown by the `errorFunction`
+   */
+  static expectError(errorFunction: () => unknown, options?: ExpectErrorOptions): DataError;
+  /**
+   * 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.
+   *
+   * @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`
+   *
+   * @returns The `DataError` that was thrown by the `errorFunction`
+   */
+  static expectErrorAsync(errorFunction: () => Promise<unknown>, options?: ExpectErrorOptions): Promise<DataError>;
 }
 //#endregion
 //#region src/root/types/CreateEnumType.d.ts

package/dist/internal/index.js

@@ -88,6 +88,17 @@ var DataError = class DataError extends Error {
 		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 a DataError.
 	*
@@ -100,12 +111,54 @@ var DataError = class DataError extends Error {
 		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.
+	*
+	* @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`
+	*
+	* @returns The `DataError` that was thrown by the `errorFunction`
+	*/
+	static expectError(errorFunction, options) {
+		try {
+			errorFunction();
+		} catch (error) {
+			return DataError.checkCaughtError(error, options);
+		}
+		throw new Error("Expected a DataError 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.
+	*
+	* @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`
+	*
+	* @returns The `DataError` that was thrown by the `errorFunction`
+	*/
+	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");
+	}
 };
 
 //#endregion
 //#region src/root/constants/FILE_PATH_REGEX.ts
 const FILE_PATH_REGEX = String.raw`^(?<directory>.+)[\/\\](?<base>[^\/\\]+)$`;
 
+//#endregion
+//#region src/root/constants/ONE_DAY_IN_MILLISECONDS.ts
+const ONE_DAY_IN_MILLISECONDS = 1440 * 60 * 1e3;
+
 //#endregion
 //#region src/root/constants/VERSION_NUMBER_REGEX.ts
 const VERSION_NUMBER_REGEX = "^(?:v)?(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$";

package/dist/node/index.cjs

@@ -73,49 +73,12 @@ const normaliseImportPath = normalizeImportPath;
 const FILE_PATH_REGEX = String.raw`^(?<directory>.+)[\/\\](?<base>[^\/\\]+)$`;
 
 //#endregion
-//#region src/root/constants/VERSION_NUMBER_REGEX.ts
-const VERSION_NUMBER_REGEX = "^(?:v)?(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$";
+//#region src/root/constants/ONE_DAY_IN_MILLISECONDS.ts
+const ONE_DAY_IN_MILLISECONDS = 1440 * 60 * 1e3;
 
 //#endregion
-//#region src/root/types/DataError.ts
-/**
-* 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 DataError = class DataError 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) {
-		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 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;
-	}
-};
+//#region src/root/constants/VERSION_NUMBER_REGEX.ts
+const VERSION_NUMBER_REGEX = "^(?:v)?(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$";
 
 //#endregion
 //#region src/root/functions/arrayHelpers/fillArray.ts
@@ -419,6 +382,96 @@ const VersionType = {
 	PATCH: "patch"
 };
 
+//#endregion
+//#region src/root/types/DataError.ts
+/**
+* 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 DataError = class DataError 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) {
+		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);
+	}
+	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 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.
+	*
+	* @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`
+	*
+	* @returns The `DataError` that was thrown by the `errorFunction`
+	*/
+	static expectError(errorFunction, options) {
+		try {
+			errorFunction();
+		} catch (error) {
+			return DataError.checkCaughtError(error, options);
+		}
+		throw new Error("Expected a DataError 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.
+	*
+	* @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`
+	*
+	* @returns The `DataError` that was thrown by the `errorFunction`
+	*/
+	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");
+	}
+};
+
 //#endregion
 //#region src/root/types/VersionNumber.ts
 /**

package/dist/node/index.js

@@ -43,49 +43,12 @@ const normaliseImportPath = normalizeImportPath;
 const FILE_PATH_REGEX = String.raw`^(?<directory>.+)[\/\\](?<base>[^\/\\]+)$`;
 
 //#endregion
-//#region src/root/constants/VERSION_NUMBER_REGEX.ts
-const VERSION_NUMBER_REGEX = "^(?:v)?(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$";
+//#region src/root/constants/ONE_DAY_IN_MILLISECONDS.ts
+const ONE_DAY_IN_MILLISECONDS = 1440 * 60 * 1e3;
 
 //#endregion
-//#region src/root/types/DataError.ts
-/**
-* 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 DataError = class DataError 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) {
-		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 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;
-	}
-};
+//#region src/root/constants/VERSION_NUMBER_REGEX.ts
+const VERSION_NUMBER_REGEX = "^(?:v)?(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$";
 
 //#endregion
 //#region src/root/functions/arrayHelpers/fillArray.ts
@@ -389,6 +352,96 @@ const VersionType = {
 	PATCH: "patch"
 };
 
+//#endregion
+//#region src/root/types/DataError.ts
+/**
+* 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 DataError = class DataError 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) {
+		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);
+	}
+	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 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.
+	*
+	* @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`
+	*
+	* @returns The `DataError` that was thrown by the `errorFunction`
+	*/
+	static expectError(errorFunction, options) {
+		try {
+			errorFunction();
+		} catch (error) {
+			return DataError.checkCaughtError(error, options);
+		}
+		throw new Error("Expected a DataError 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.
+	*
+	* @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`
+	*
+	* @returns The `DataError` that was thrown by the `errorFunction`
+	*/
+	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");
+	}
+};
+
 //#endregion
 //#region src/root/types/VersionNumber.ts
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alextheman/utility",
-  "version": "5.1.4",
+  "version": "5.3.0",
   "description": "Helpful utility functions.",
   "repository": {
     "type": "git",
@@ -36,7 +36,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@alextheman/eslint-plugin": "^5.7.1",
+    "@alextheman/eslint-plugin": "^5.8.2",
     "@types/node": "^25.3.0",
     "alex-c-line": "^1.28.0",
     "dotenv-cli": "^11.0.0",