@alextheman/utility 5.15.0 → 5.16.0

package/dist/index.js

@@ -14,6 +14,51 @@ const UUID_REGEX = new RegExp(`^${UUID_PATTERN}$`);
 const VERSION_NUMBER_PATTERN = String.raw`^(?:v)?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$`;
 const VERSION_NUMBER_REGEX = RegExp(`^${VERSION_NUMBER_PATTERN}$`);
 //#endregion
+//#region src/root/deprecated/APIError.ts
+const httpErrorCodeLookup = {
+	400: "BAD_REQUEST",
+	401: "UNAUTHORISED",
+	403: "FORBIDDEN",
+	404: "NOT_FOUND",
+	418: "I_AM_A_TEAPOT",
+	500: "INTERNAL_SERVER_ERROR"
+};
+/**
+* Represents common errors you may get from a HTTP API request.
+*
+* @category Types
+*
+* @deprecated Please use `APIError` from `@alextheman/utility/v6` instead.
+*/
+var APIError = class APIError extends Error {
+	status;
+	/**
+	* @param status - A HTTP status code. Can be any number, but numbers between 400 and 600 are encouraged to fit with HTTP status code conventions.
+	* @param message - An error message to display alongside the status code.
+	* @param options - Extra options to be passed to super Error constructor.
+	*/
+	constructor(status = 500, message, options) {
+		super(message, options);
+		this.status = status;
+		if (message) this.message = message;
+		else this.message = httpErrorCodeLookup[this.status] ?? "API_ERROR";
+		Object.defineProperty(this, "message", { enumerable: true });
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+	/**
+	* Checks whether the given input may have been caused by an APIError.
+	*
+	* @param input - The input to check.
+	*
+	* @returns `true` if the input is an APIError, and `false` otherwise. The type of the input will also be narrowed down to APIError if `true`.
+	*/
+	static check(input) {
+		if (input instanceof APIError) return true;
+		const data = input;
+		return typeof data === "object" && data !== null && typeof data?.status === "number" && typeof data?.message === "string";
+	}
+};
+//#endregion
 //#region src/root/functions/arrayHelpers/fillArray.ts
 /**
 * Creates a new array where each element is the result of the provided callback.
@@ -161,6 +206,17 @@ var CodeError = class CodeError extends Error {
 		}
 		throw new Error(`Expected a ${this.name} to be thrown but none was thrown`);
 	}
+	/**
+	* Converts the `CodeError` instance to a serialised JSON payload.
+	*
+	* @returns A JSON serialised version of the current `CodeError` instance.
+	*/
+	toJSON() {
+		return {
+			code: this.code,
+			message: this.message
+		};
+	}
 };
 //#endregion
 //#region src/v6/DataError.ts
@@ -169,14 +225,15 @@ var CodeError = class CodeError extends Error {
 *
 * @category Types
 *
-* @template DataType - The type of the data that caused the error.
+* @template DataType The type of the data that caused the error.
+* @template ErrorCode The type of the standardised error code.
 */
 var DataError$1 = class DataError$1 extends CodeError {
 	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 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, message = "The data provided is invalid", options) {
@@ -196,7 +253,7 @@ var DataError$1 = class DataError$1 extends CodeError {
 	*/
 	static check(input) {
 		if (input instanceof DataError$1) return true;
-		return typeof input === "object" && input !== null && "message" in input && typeof input.message === "string" && "code" in input && typeof input.code === "string" && "data" in input;
+		return typeof input === "object" && input !== null && "message" in input && typeof input.message === "string" && "code" in input && typeof input.code === "string" && "data" in input && typeof input.data === "object" && input.data !== null;
 	}
 	/**
 	* Check a `DataError` against its error code
@@ -241,6 +298,17 @@ var DataError$1 = class DataError$1 extends CodeError {
 	static async expectErrorAsync(errorFunction, options) {
 		return await super.expectErrorAsync(errorFunction, options);
 	}
+	/**
+	* Converts the `DataError` instance to a serialised JSON payload.
+	*
+	* @returns A JSON serialised version of the current `DataError` instance.
+	*/
+	toJSON() {
+		return {
+			...super.toJSON(),
+			data: this.data
+		};
+	}
 };
 //#endregion
 //#region src/root/functions/parsers/parseIntStrict.ts
@@ -898,49 +966,6 @@ function parseBoolean(inputString) {
 	return normalisedString === "true";
 }
 //#endregion
-//#region src/root/types/APIError.ts
-const httpErrorCodeLookup = {
-	400: "BAD_REQUEST",
-	401: "UNAUTHORISED",
-	403: "FORBIDDEN",
-	404: "NOT_FOUND",
-	418: "I_AM_A_TEAPOT",
-	500: "INTERNAL_SERVER_ERROR"
-};
-/**
-* Represents common errors you may get from a HTTP API request.
-*
-* @category Types
-*/
-var APIError = class APIError extends Error {
-	status;
-	/**
-	* @param status - A HTTP status code. Can be any number, but numbers between 400 and 600 are encouraged to fit with HTTP status code conventions.
-	* @param message - An error message to display alongside the status code.
-	* @param options - Extra options to be passed to super Error constructor.
-	*/
-	constructor(status = 500, message, options) {
-		super(message, options);
-		this.status = status;
-		if (message) this.message = message;
-		else this.message = httpErrorCodeLookup[this.status] ?? "API_ERROR";
-		Object.defineProperty(this, "message", { enumerable: true });
-		Object.setPrototypeOf(this, new.target.prototype);
-	}
-	/**
-	* Checks whether the given input may have been caused by an APIError.
-	*
-	* @param input - The input to check.
-	*
-	* @returns `true` if the input is an APIError, and `false` otherwise. The type of the input will also be narrowed down to APIError if `true`.
-	*/
-	static check(input) {
-		if (input instanceof APIError) return true;
-		const data = input;
-		return typeof data === "object" && data !== null && typeof data?.status === "number" && typeof data?.message === "string";
-	}
-};
-//#endregion
 //#region src/root/types/VersionNumber.ts
 /**
 * Represents a software version number, considered to be made up of a major, minor, and patch part.
@@ -1806,4 +1831,20 @@ var DataError = class DataError extends Error {
 	}
 };
 //#endregion
-export { APIError, DataError, Env, FILE_PATH_PATTERN, FILE_PATH_REGEX, ONE_DAY_IN_MILLISECONDS, UUID_PATTERN, UUID_REGEX, VERSION_NUMBER_PATTERN, VERSION_NUMBER_REGEX, VersionNumber, VersionType, addDaysToDate, appendSemicolon, az, calculateMonthlyDifference, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, escapeRegexPattern, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, getStringsAndInterpolations, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, isTemplateStringsArray, kebabToCamel, normaliseIndents, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseUUID, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, sayHello, stringListToArray, stringifyDotenv, toTitleCase, truncate, wait, zodVersionNumber };
+//#region src/root/errors/assertNotNull.ts
+/**
+* Asserts that a given input is not `null`, and throws a DataError if it does.
+*
+* If no error is thrown from this, the input type gets narrowed down to not include `null`.
+*
+* @template InputType The type of the input.
+*
+* @param input - The input to assert against
+*
+* @throws {DataError} If the input is `null`.
+*/
+function assertNotNull(input) {
+	if (input === null) throw new DataError$1({ input }, "NULL_INPUT", "Expected the input not to be null");
+}
+//#endregion
+export { APIError, DataError, Env, FILE_PATH_PATTERN, FILE_PATH_REGEX, ONE_DAY_IN_MILLISECONDS, UUID_PATTERN, UUID_REGEX, VERSION_NUMBER_PATTERN, VERSION_NUMBER_REGEX, VersionNumber, VersionType, addDaysToDate, appendSemicolon, assertNotNull, az, calculateMonthlyDifference, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, escapeRegexPattern, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, getStringsAndInterpolations, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, isTemplateStringsArray, kebabToCamel, normaliseIndents, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseUUID, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, sayHello, stringListToArray, stringifyDotenv, toTitleCase, truncate, wait, zodVersionNumber };

package/dist/internal/index.cjs

@@ -184,6 +184,17 @@ var CodeError = class CodeError extends Error {
 		}
 		throw new Error(`Expected a ${this.name} to be thrown but none was thrown`);
 	}
+	/**
+	* Converts the `CodeError` instance to a serialised JSON payload.
+	*
+	* @returns A JSON serialised version of the current `CodeError` instance.
+	*/
+	toJSON() {
+		return {
+			code: this.code,
+			message: this.message
+		};
+	}
 };
 //#endregion
 //#region src/v6/DataError.ts
@@ -192,14 +203,15 @@ var CodeError = class CodeError extends Error {
 *
 * @category Types
 *
-* @template DataType - The type of the data that caused the error.
+* @template DataType The type of the data that caused the error.
+* @template ErrorCode The type of the standardised error code.
 */
 var DataError = class DataError extends CodeError {
 	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 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, message = "The data provided is invalid", options) {
@@ -219,7 +231,7 @@ var DataError = class DataError extends CodeError {
 	*/
 	static check(input) {
 		if (input instanceof DataError) return true;
-		return typeof input === "object" && input !== null && "message" in input && typeof input.message === "string" && "code" in input && typeof input.code === "string" && "data" in input;
+		return typeof input === "object" && input !== null && "message" in input && typeof input.message === "string" && "code" in input && typeof input.code === "string" && "data" in input && typeof input.data === "object" && input.data !== null;
 	}
 	/**
 	* Check a `DataError` against its error code
@@ -264,6 +276,17 @@ var DataError = class DataError extends CodeError {
 	static async expectErrorAsync(errorFunction, options) {
 		return await super.expectErrorAsync(errorFunction, options);
 	}
+	/**
+	* Converts the `DataError` instance to a serialised JSON payload.
+	*
+	* @returns A JSON serialised version of the current `DataError` instance.
+	*/
+	toJSON() {
+		return {
+			...super.toJSON(),
+			data: this.data
+		};
+	}
 };
 //#endregion
 //#region src/root/functions/parsers/parseIntStrict.ts

package/dist/internal/index.d.cts

@@ -89,6 +89,12 @@ declare class CodeError<ErrorCode extends string = string> extends Error {
    * @returns The `CodeError` that was thrown by the `errorFunction`
    */
   static expectErrorAsync<ErrorCode extends string = string>(this: typeof CodeError, errorFunction: () => Promise<unknown>, options?: ExpectErrorOptions<ErrorCode>): Promise<CodeError>;
+  /**
+   * Converts the `CodeError` instance to a serialised JSON payload.
+   *
+   * @returns A JSON serialised version of the current `CodeError` instance.
+   */
+  toJSON(): Omit<CodeError<ErrorCode>, "toJSON" | "name">;
 }
 //#endregion
 //#region src/v6/DataError.d.ts
@@ -97,14 +103,15 @@ declare class CodeError<ErrorCode extends string = string> extends Error {
  *
  * @category Types
  *
- * @template DataType - The type of the data that caused the error.
+ * @template DataType The type of the data that caused the error.
+ * @template ErrorCode The type of the standardised error code.
  */
 declare class DataError<DataType extends object = Record<PropertyKey, unknown>, ErrorCode extends string = string> extends CodeError<ErrorCode> {
   data: DataType;
   /**
    * @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 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: DataType, code: ErrorCode, message?: string, options?: ErrorOptions);
@@ -153,6 +160,12 @@ declare class DataError<DataType extends object = Record<PropertyKey, unknown>,
    * @returns The `DataError` that was thrown by the `errorFunction`
    */
   static expectErrorAsync<DataType extends Record<PropertyKey, unknown>, ErrorCode extends string = string>(errorFunction: () => Promise<unknown>, options?: ExpectErrorOptions<ErrorCode>): Promise<DataError<DataType, ErrorCode>>;
+  /**
+   * Converts the `DataError` instance to a serialised JSON payload.
+   *
+   * @returns A JSON serialised version of the current `DataError` instance.
+   */
+  toJSON(): Omit<DataError<DataType, ErrorCode>, "toJSON" | "name">;
 }
 //#endregion
 //#region src/internal/DependencyGroup.d.ts

package/dist/internal/index.d.ts

@@ -89,6 +89,12 @@ declare class CodeError<ErrorCode extends string = string> extends Error {
    * @returns The `CodeError` that was thrown by the `errorFunction`
    */
   static expectErrorAsync<ErrorCode extends string = string>(this: typeof CodeError, errorFunction: () => Promise<unknown>, options?: ExpectErrorOptions<ErrorCode>): Promise<CodeError>;
+  /**
+   * Converts the `CodeError` instance to a serialised JSON payload.
+   *
+   * @returns A JSON serialised version of the current `CodeError` instance.
+   */
+  toJSON(): Omit<CodeError<ErrorCode>, "toJSON" | "name">;
 }
 //#endregion
 //#region src/v6/DataError.d.ts
@@ -97,14 +103,15 @@ declare class CodeError<ErrorCode extends string = string> extends Error {
  *
  * @category Types
  *
- * @template DataType - The type of the data that caused the error.
+ * @template DataType The type of the data that caused the error.
+ * @template ErrorCode The type of the standardised error code.
  */
 declare class DataError<DataType extends object = Record<PropertyKey, unknown>, ErrorCode extends string = string> extends CodeError<ErrorCode> {
   data: DataType;
   /**
    * @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 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: DataType, code: ErrorCode, message?: string, options?: ErrorOptions);
@@ -153,6 +160,12 @@ declare class DataError<DataType extends object = Record<PropertyKey, unknown>,
    * @returns The `DataError` that was thrown by the `errorFunction`
    */
   static expectErrorAsync<DataType extends Record<PropertyKey, unknown>, ErrorCode extends string = string>(errorFunction: () => Promise<unknown>, options?: ExpectErrorOptions<ErrorCode>): Promise<DataError<DataType, ErrorCode>>;
+  /**
+   * Converts the `DataError` instance to a serialised JSON payload.
+   *
+   * @returns A JSON serialised version of the current `DataError` instance.
+   */
+  toJSON(): Omit<DataError<DataType, ErrorCode>, "toJSON" | "name">;
 }
 //#endregion
 //#region src/internal/DependencyGroup.d.ts

package/dist/internal/index.js

@@ -159,6 +159,17 @@ var CodeError = class CodeError extends Error {
 		}
 		throw new Error(`Expected a ${this.name} to be thrown but none was thrown`);
 	}
+	/**
+	* Converts the `CodeError` instance to a serialised JSON payload.
+	*
+	* @returns A JSON serialised version of the current `CodeError` instance.
+	*/
+	toJSON() {
+		return {
+			code: this.code,
+			message: this.message
+		};
+	}
 };
 //#endregion
 //#region src/v6/DataError.ts
@@ -167,14 +178,15 @@ var CodeError = class CodeError extends Error {
 *
 * @category Types
 *
-* @template DataType - The type of the data that caused the error.
+* @template DataType The type of the data that caused the error.
+* @template ErrorCode The type of the standardised error code.
 */
 var DataError = class DataError extends CodeError {
 	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 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, message = "The data provided is invalid", options) {
@@ -194,7 +206,7 @@ var DataError = class DataError extends CodeError {
 	*/
 	static check(input) {
 		if (input instanceof DataError) return true;
-		return typeof input === "object" && input !== null && "message" in input && typeof input.message === "string" && "code" in input && typeof input.code === "string" && "data" in input;
+		return typeof input === "object" && input !== null && "message" in input && typeof input.message === "string" && "code" in input && typeof input.code === "string" && "data" in input && typeof input.data === "object" && input.data !== null;
 	}
 	/**
 	* Check a `DataError` against its error code
@@ -239,6 +251,17 @@ var DataError = class DataError extends CodeError {
 	static async expectErrorAsync(errorFunction, options) {
 		return await super.expectErrorAsync(errorFunction, options);
 	}
+	/**
+	* Converts the `DataError` instance to a serialised JSON payload.
+	*
+	* @returns A JSON serialised version of the current `DataError` instance.
+	*/
+	toJSON() {
+		return {
+			...super.toJSON(),
+			data: this.data
+		};
+	}
 };
 //#endregion
 //#region src/root/functions/parsers/parseIntStrict.ts

package/dist/node/index.cjs

@@ -300,6 +300,17 @@ var CodeError = class CodeError extends Error {
 		}
 		throw new Error(`Expected a ${this.name} to be thrown but none was thrown`);
 	}
+	/**
+	* Converts the `CodeError` instance to a serialised JSON payload.
+	*
+	* @returns A JSON serialised version of the current `CodeError` instance.
+	*/
+	toJSON() {
+		return {
+			code: this.code,
+			message: this.message
+		};
+	}
 };
 //#endregion
 //#region src/v6/DataError.ts
@@ -308,14 +319,15 @@ var CodeError = class CodeError extends Error {
 *
 * @category Types
 *
-* @template DataType - The type of the data that caused the error.
+* @template DataType The type of the data that caused the error.
+* @template ErrorCode The type of the standardised error code.
 */
 var DataError = class DataError extends CodeError {
 	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 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, message = "The data provided is invalid", options) {
@@ -335,7 +347,7 @@ var DataError = class DataError extends CodeError {
 	*/
 	static check(input) {
 		if (input instanceof DataError) return true;
-		return typeof input === "object" && input !== null && "message" in input && typeof input.message === "string" && "code" in input && typeof input.code === "string" && "data" in input;
+		return typeof input === "object" && input !== null && "message" in input && typeof input.message === "string" && "code" in input && typeof input.code === "string" && "data" in input && typeof input.data === "object" && input.data !== null;
 	}
 	/**
 	* Check a `DataError` against its error code
@@ -380,6 +392,17 @@ var DataError = class DataError extends CodeError {
 	static async expectErrorAsync(errorFunction, options) {
 		return await super.expectErrorAsync(errorFunction, options);
 	}
+	/**
+	* Converts the `DataError` instance to a serialised JSON payload.
+	*
+	* @returns A JSON serialised version of the current `DataError` instance.
+	*/
+	toJSON() {
+		return {
+			...super.toJSON(),
+			data: this.data
+		};
+	}
 };
 //#endregion
 //#region src/node/functions/parseFilePath.ts

package/dist/node/index.js

@@ -276,6 +276,17 @@ var CodeError = class CodeError extends Error {
 		}
 		throw new Error(`Expected a ${this.name} to be thrown but none was thrown`);
 	}
+	/**
+	* Converts the `CodeError` instance to a serialised JSON payload.
+	*
+	* @returns A JSON serialised version of the current `CodeError` instance.
+	*/
+	toJSON() {
+		return {
+			code: this.code,
+			message: this.message
+		};
+	}
 };
 //#endregion
 //#region src/v6/DataError.ts
@@ -284,14 +295,15 @@ var CodeError = class CodeError extends Error {
 *
 * @category Types
 *
-* @template DataType - The type of the data that caused the error.
+* @template DataType The type of the data that caused the error.
+* @template ErrorCode The type of the standardised error code.
 */
 var DataError = class DataError extends CodeError {
 	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 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, message = "The data provided is invalid", options) {
@@ -311,7 +323,7 @@ var DataError = class DataError extends CodeError {
 	*/
 	static check(input) {
 		if (input instanceof DataError) return true;
-		return typeof input === "object" && input !== null && "message" in input && typeof input.message === "string" && "code" in input && typeof input.code === "string" && "data" in input;
+		return typeof input === "object" && input !== null && "message" in input && typeof input.message === "string" && "code" in input && typeof input.code === "string" && "data" in input && typeof input.data === "object" && input.data !== null;
 	}
 	/**
 	* Check a `DataError` against its error code
@@ -356,6 +368,17 @@ var DataError = class DataError extends CodeError {
 	static async expectErrorAsync(errorFunction, options) {
 		return await super.expectErrorAsync(errorFunction, options);
 	}
+	/**
+	* Converts the `DataError` instance to a serialised JSON payload.
+	*
+	* @returns A JSON serialised version of the current `DataError` instance.
+	*/
+	toJSON() {
+		return {
+			...super.toJSON(),
+			data: this.data
+		};
+	}
 };
 //#endregion
 //#region src/node/functions/parseFilePath.ts