@alextheman/utility 5.1.4 → 5.2.0

package/dist/index.cjs

@@ -164,6 +164,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 +187,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 +479,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 +679,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 +689,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 +705,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 +734,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 +757,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 +1502,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 +1559,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;
 }

package/dist/index.d.cts

@@ -87,8 +87,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 +198,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 +239,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 +259,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 +268,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 +849,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 +892,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
 /**

package/dist/index.d.ts

@@ -87,8 +87,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 +198,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 +239,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 +259,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 +268,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 +849,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 +892,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
 /**

package/dist/index.js

@@ -134,6 +134,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 +157,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 +449,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 +649,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 +659,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 +675,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 +704,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 +727,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 +1472,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 +1529,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;
 }

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,6 +141,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

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,6 +111,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

package/dist/node/index.cjs

@@ -76,47 +76,6 @@ const FILE_PATH_REGEX = String.raw`^(?<directory>.+)[\/\\](?<base>[^\/\\]+)$`;
 //#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/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;
-	}
-};
-
 //#endregion
 //#region src/root/functions/arrayHelpers/fillArray.ts
 /**
@@ -419,6 +378,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

@@ -46,47 +46,6 @@ const FILE_PATH_REGEX = String.raw`^(?<directory>.+)[\/\\](?<base>[^\/\\]+)$`;
 //#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/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;
-	}
-};
-
 //#endregion
 //#region src/root/functions/arrayHelpers/fillArray.ts
 /**
@@ -389,6 +348,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.2.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",