@alextheman/utility 3.10.1 → 4.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License Copyright (c) 2025 AlexMan123456
+
+Permission is hereby granted, free
+of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice
+(including the next paragraph) shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/dist/index.cjs

@@ -27,8 +27,8 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 //#endregion
 let zod = require("zod");
 zod = __toESM(zod);
-let path = require("path");
-path = __toESM(path);
+let node_path = require("node:path");
+node_path = __toESM(node_path);
 
 //#region src/constants/NAMESPACE_EXPORT_REGEX.ts
 const NAMESPACE_EXPORT_REGEX = "export\\s+\\*\\s+from";
@@ -88,27 +88,108 @@ function paralleliseArrays(firstArray, secondArray) {
 }
 var paralleliseArrays_default = paralleliseArrays;
 
+//#endregion
+//#region src/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. */
+var APIError = class 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) {
+		const data = input;
+		return typeof data === "object" && data !== null && typeof data?.status === "number" && typeof data?.message === "string";
+	}
+};
+var APIError_default = APIError;
+
+//#endregion
+//#region src/types/DataError.ts
+/** Represents errors you may get that may've been caused by a specific piece of data. */
+var DataError = class extends Error {
+	data;
+	code;
+	/**
+	* @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) {
+		const data = input;
+		return typeof data === "object" && data !== null && typeof data.message === "string" && typeof data.code === "string" && "data" in data;
+	}
+};
+var DataError_default = DataError;
+
 //#endregion
 //#region src/functions/parsers/parseIntStrict.ts
-const IntegerParsingError = /* @__PURE__ */ new TypeError("INTEGER_PARSING_ERROR");
 /**
 * Converts a string to an integer and throws an error if it cannot be converted.
 *
 * @param string - A string to convert into a number.
 * @param radix - A value between 2 and 36 that specifies the base of the number in string. If this argument is not supplied, strings with a prefix of '0x' are considered hexadecimal. All other strings are considered decimal.
 *
-* @throws {TypeError} If the provided string cannot safely be converted to an integer.
+* @throws {DataError} If the provided string cannot safely be converted to an integer.
 *
 * @returns The integer parsed from the input string.
 */
 function parseIntStrict(string, radix) {
 	const trimmedString = string.trim();
-	if (!(radix && radix > 10 && radix <= 36 ? new RegExp(`^[+-]?[0-9a-${String.fromCharCode(87 + radix - 1)}]+$`, "i") : /^[+-]?\d+$/).test(trimmedString)) throw IntegerParsingError;
+	const maxAllowedAlphabeticalCharacter = radix && radix > 10 && radix <= 36 ? String.fromCharCode(87 + radix - 1) : void 0;
+	if (!(radix && radix > 10 && radix <= 36 ? new RegExp(`^[+-]?[0-9a-${maxAllowedAlphabeticalCharacter}]+$`, "i") : /^[+-]?\d+$/).test(trimmedString)) throw new DataError_default(radix ? {
+		string,
+		radix
+	} : string, "INTEGER_PARSING_ERROR", `Only numeric values${radix && radix > 10 && radix <= 36 ? ` or character${radix !== 11 ? "s" : ""} A${radix !== 11 ? `-${maxAllowedAlphabeticalCharacter?.toUpperCase()} ` : " "}` : " "}are allowed.`);
 	if (radix && radix < 10 && [...trimmedString].some((character) => {
 		return parseInt(character) >= radix;
-	})) throw IntegerParsingError;
+	})) throw new DataError_default({
+		string,
+		radix
+	}, "INTEGER_PARSING_ERROR", "Value contains one or more digits outside of the range of the given radix.");
 	const parseIntResult = parseInt(trimmedString, radix);
-	if (isNaN(parseIntResult)) throw IntegerParsingError;
+	if (isNaN(parseIntResult)) throw new DataError_default(string, "INTEGER_PARSING_ERROR", "Value is not a valid integer.");
 	return parseIntResult;
 }
 var parseIntStrict_default = parseIntStrict;
@@ -539,19 +620,42 @@ var omitProperties_default = omitProperties;
 *
 * @param inputString - The string to parse.
 *
-* @throws {TypeError} If the string is not either `true` or `false` (case insensitive).
+* @throws {DataError} If the string is not either `true` or `false` (case insensitive).
 *
 * @returns The string parsed as an actual boolean.
 */
 function parseBoolean(inputString) {
 	const normalisedString = inputString.toLowerCase();
-	if (!["true", "false"].includes(normalisedString)) throw new TypeError("INVALID_BOOLEAN_STRING");
+	if (!["true", "false"].includes(normalisedString)) throw new DataError_default(inputString, "INVALID_BOOLEAN_STRING", "The provided boolean string must be one of `true | false`");
 	return normalisedString === "true";
 }
-/** @deprecated This function has been renamed to parseBoolean. */
-const stringToBoolean = parseBoolean;
 var parseBoolean_default = parseBoolean;
 
+//#endregion
+//#region src/functions/parsers/parseZodSchema.ts
+/**
+* An alternative function to zodSchema.parse() that can be used to strictly parse Zod schemas.
+*
+* @template Output - The Zod output type.
+* @template Input - The Zod input type.
+* @template Internals - The Zod internal types based on the output and input types.
+* @template ErrorType - The type of error to throw on invalid data.
+*
+* @param schema - The Zod schema to use in parsing.
+* @param data - The data to parse.
+* @param error - A custom error to throw on invalid data (defaults to `DataError`).
+*
+* @throws {DataError} If the given data cannot be parsed according to the schema.
+*
+* @returns The parsed data from the Zod schema.
+*/
+function parseZodSchema(schema, data, error) {
+	const parsedResult = schema.safeParse(data);
+	if (!parsedResult.success) throw error ?? new DataError_default(data);
+	return parsedResult.data;
+}
+var parseZodSchema_default = parseZodSchema;
+
 //#endregion
 //#region src/functions/parsers/parseEnv.ts
 const envSchema = zod.z.enum([
@@ -564,12 +668,12 @@ const envSchema = zod.z.enum([
 *
 * @param data - The data to parse.
 *
-* @throws {ZodError} If the data does not match one of the environments allowed by the Env types ("test" | "development" | "production").
+* @throws {DataError} If the data does not match one of the environments allowed by the Env types ("test" | "development" | "production").
 *
 * @returns The specified environment if allowed.
 */
 function parseEnv(data) {
-	return envSchema.parse(data);
+	return parseZodSchema_default(envSchema, data, new DataError_default(data, "INVALID_ENV", "The provided environment type must be one of `test | development | production`"));
 }
 var parseEnv_default = parseEnv;
 
@@ -595,122 +699,6 @@ function parseFormData(formData, dataParser) {
 }
 var parseFormData_default = parseFormData;
 
-//#endregion
-//#region src/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. */
-var APIError = class 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) {
-		const data = input;
-		return typeof data === "object" && data !== null && typeof data?.status === "number" && typeof data?.message === "string";
-	}
-};
-var APIError_default = APIError;
-
-//#endregion
-//#region src/types/DataError.ts
-/** Represents errors you may get that may've been caused by a specific piece of data. */
-var DataError = class extends Error {
-	data;
-	code;
-	/**
-	* @param data - The data that caused the error.
-	* @param message  - A human-readable error message (e.g. The data provided is invalid).
-	* @param code - A standardised code (e.g. UNEXPECTED_DATA).
-	* @param options - Extra options to pass to super Error constructor.
-	*/
-	constructor(data, message = "The data provided is invalid", code = "INVALID_DATA", 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) {
-		const data = input;
-		return typeof data === "object" && data !== null && typeof data.message === "string" && typeof data.code === "string" && "data" in data;
-	}
-};
-var DataError_default = DataError;
-
-//#endregion
-//#region src/types/Email.ts
-const emailSchema = zod.default.email().brand();
-/** @deprecated Please use `z.email().parse() from Zod instead.`*/
-function parseEmail(data) {
-	return emailSchema.parse(data);
-}
-var Email_default = parseEmail;
-
-//#endregion
-//#region src/types/UUID.ts
-const uuidSchema = zod.default.uuid().brand();
-/** @deprecated Please use `z.uuid().parse() from Zod instead.`*/
-function parseUUID(UUID) {
-	return uuidSchema.parse(UUID);
-}
-var UUID_default = parseUUID;
-
-//#endregion
-//#region src/functions/parsers/parseZodSchema.ts
-/**
-* An alternative function to zodSchema.parse() that can be used to strictly parse Zod schemas.
-*
-* @template Output - The Zod output type.
-* @template Input - The Zod input type.
-* @template Internals - The Zod internal types based on the output and input types.
-*
-* @param schema - The Zod schema to use in parsing.
-* @param data - The data to parse.
-*
-* @throws {DataError} If the given data cannot be parsed according to the schema.
-*
-* @returns The parsed data from the Zod schema.
-*/
-function parseZodSchema(schema, data) {
-	const parsedResult = schema.safeParse(data);
-	if (!parsedResult.success) throw new DataError_default(data);
-	return parsedResult.data;
-}
-var parseZodSchema_default = parseZodSchema;
-
 //#endregion
 //#region src/functions/parsers/parseVersionType.ts
 const versionTypeSchema = zod.default.enum([
@@ -728,7 +716,7 @@ const versionTypeSchema = zod.default.enum([
 * @returns The given version type if allowed.
 */
 function parseVersionType(data) {
-	return parseZodSchema_default(versionTypeSchema, data);
+	return parseZodSchema_default(versionTypeSchema, data, new DataError_default(data, "INVALID_VERSION_TYPE", "The provided version type must be one of `major | minor | patch`"));
 }
 var parseVersionType_default = parseVersionType;
 
@@ -807,11 +795,35 @@ var appendSemicolon_default = appendSemicolon;
 * Converts a string from camelCase to kebab-case
 *
 * @param string - The string to convert.
+* @param options - Options to apply to the conversion.
 *
 * @returns The string converted to kebab-case.
 */
-function camelToKebab(string) {
-	return string.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/([A-Z])([A-Z][a-z])/g, "$1-$2").toLowerCase();
+function camelToKebab(string, options = { preserveConsecutiveCapitals: true }) {
+	let result = "";
+	let outerIndex = 0;
+	while (outerIndex < string.length) {
+		const character = string[outerIndex];
+		if (/[A-Z]/.test(character)) {
+			let innerIndex = outerIndex + 1;
+			while (innerIndex < string.length && /[A-Z]/.test(string[innerIndex]) && (options.preserveConsecutiveCapitals ? innerIndex + 1 < string.length && /[a-z]/.test(string[innerIndex + 1]) ? false : true : true)) innerIndex++;
+			const sequenceOfCapitals = string.slice(outerIndex, innerIndex);
+			if (options.preserveConsecutiveCapitals) {
+				if (result) result += "-";
+				result += sequenceOfCapitals.toLowerCase();
+			} else {
+				if (result) result += "-";
+				result += sequenceOfCapitals.split("").map((character$1) => {
+					return character$1.toLowerCase();
+				}).join("-");
+			}
+			outerIndex = innerIndex;
+		} else {
+			result += character;
+			outerIndex++;
+		}
+	}
+	return result;
 }
 var camelToKebab_default = camelToKebab;
 
@@ -869,7 +881,7 @@ var kebabToCamel_default = kebabToCamel;
 * @returns The import path normalized.
 */
 function normalizeImportPath(importPath) {
-	const normalizedPath = path.default.posix.normalize(importPath);
+	const normalizedPath = node_path.default.posix.normalize(importPath);
 	if (importPath.startsWith("./") && !normalizedPath.startsWith("./")) return `./${normalizedPath}`;
 	return normalizedPath;
 }
@@ -967,25 +979,25 @@ var interpolateObjects_default = interpolateObjects;
 
 //#endregion
 //#region src/functions/taggedTemplate/normaliseIndents.ts
-function calculateTabSize$1(line, whitespaceLength) {
+function calculateTabSize(line, whitespaceLength) {
 	const potentialWhitespacePart = line.slice(0, whitespaceLength);
 	const trimmedString = line.trimStart();
 	if (potentialWhitespacePart.trim() !== "") return 0;
 	const tabSize = line.length - (trimmedString.length + whitespaceLength);
 	return tabSize < 0 ? 0 : tabSize;
 }
-function getWhitespaceLength$1(lines) {
+function getWhitespaceLength(lines) {
 	const [firstNonEmptyLine] = lines.filter((line) => {
 		return line.trim() !== "";
 	});
 	return firstNonEmptyLine.length - firstNonEmptyLine.trimStart().length;
 }
-function reduceLines$1(lines, { preserveTabs = true }) {
+function reduceLines(lines, { preserveTabs = true }) {
 	const slicedLines = lines.slice(1);
 	const isFirstLineEmpty = lines[0].trim() === "";
-	const whitespaceLength = getWhitespaceLength$1(isFirstLineEmpty ? lines : slicedLines);
+	const whitespaceLength = getWhitespaceLength(isFirstLineEmpty ? lines : slicedLines);
 	return (isFirstLineEmpty ? slicedLines : lines).map((line) => {
-		const tabSize = calculateTabSize$1(line, whitespaceLength);
+		const tabSize = calculateTabSize(line, whitespaceLength);
 		return (preserveTabs ? fillArray_default(() => {
 			return " ";
 		}, tabSize).join("") : "") + line.trimStart();
@@ -1020,7 +1032,7 @@ function normaliseIndents(first, ...args) {
 	}
 	const strings = first;
 	const options = typeof args[args.length - 1] === "object" && !Array.isArray(args[args.length - 1]) ? args.pop() : {};
-	return reduceLines$1(interpolate_default(strings, ...[...args]).split("\n"), options);
+	return reduceLines(interpolate_default(strings, ...[...args]).split("\n"), options);
 }
 /**
 * Applies any options if provided, then removes any extraneous indents from a multi-line template string.
@@ -1045,45 +1057,6 @@ function normaliseIndents(first, ...args) {
 const normalizeIndents = normaliseIndents;
 var normaliseIndents_default = normaliseIndents;
 
-//#endregion
-//#region src/functions/taggedTemplate/removeIndents.ts
-function calculateTabSize(line, whitespaceLength) {
-	const potentialWhitespacePart = line.slice(0, whitespaceLength);
-	const trimmedString = line.trimStart();
-	if (potentialWhitespacePart.trim() !== "") return 0;
-	const tabSize = line.length - (trimmedString.length + whitespaceLength);
-	return tabSize < 0 ? 0 : tabSize;
-}
-function getWhitespaceLength(lines) {
-	const [firstNonEmptyLine] = lines.filter((line) => {
-		return line.trim() !== "";
-	});
-	return firstNonEmptyLine.length - firstNonEmptyLine.trimStart().length;
-}
-function reduceLines(lines, { preserveTabs = true }) {
-	const slicedLines = lines.slice(1);
-	const isFirstLineEmpty = lines[0].trim() === "";
-	const whitespaceLength = getWhitespaceLength(isFirstLineEmpty ? lines : slicedLines);
-	return (isFirstLineEmpty ? slicedLines : lines).map((line) => {
-		const tabSize = calculateTabSize(line, whitespaceLength);
-		return (preserveTabs ? fillArray_default(() => {
-			return " ";
-		}, tabSize).join("") : "") + line.trimStart();
-	}).join("\n");
-}
-function removeIndents(first, ...args) {
-	if (typeof first === "object" && first !== null && !Array.isArray(first)) {
-		const options$1 = first;
-		return (strings$1, ...interpolations) => {
-			return removeIndents(strings$1, ...interpolations, options$1);
-		};
-	}
-	const strings = first;
-	const options = typeof args[args.length - 1] === "object" && !Array.isArray(args[args.length - 1]) ? args.pop() : {};
-	return reduceLines(interpolate_default(strings, ...[...args]).split("\n"), options);
-}
-var removeIndents_default = removeIndents;
-
 //#endregion
 //#region src/functions/versioning/parseVersion.ts
 /**
@@ -1099,7 +1072,7 @@ var removeIndents_default = removeIndents;
 * @returns The validated version number, prefixed with `v` if it was not already.
 */
 function parseVersion(input, options) {
-	if (!RegExp(VERSION_NUMBER_REGEX_default).test(input)) throw new DataError_default(input, `"${input}" is not a valid version number. Version numbers must be of the format "X.Y.Z" or "vX.Y.Z", where X, Y, and Z are non-negative integers.`, "INVALID_VERSION");
+	if (!RegExp(VERSION_NUMBER_REGEX_default).test(input)) throw new DataError_default(input, "INVALID_VERSION", `"${input}" is not a valid version number. Version numbers must be of the format "X.Y.Z" or "vX.Y.Z", where X, Y, and Z are non-negative integers.`);
 	if (options?.omitPrefix) return input.startsWith("v") ? input.slice(1) : input;
 	return input.startsWith("v") ? input : `v${input}`;
 }
@@ -1199,19 +1172,15 @@ exports.normalizeIndents = normalizeIndents;
 exports.omitProperties = omitProperties_default;
 exports.paralleliseArrays = paralleliseArrays_default;
 exports.parseBoolean = parseBoolean_default;
-exports.parseEmail = Email_default;
 exports.parseEnv = parseEnv_default;
 exports.parseFormData = parseFormData_default;
 exports.parseIntStrict = parseIntStrict_default;
-exports.parseUUID = UUID_default;
 exports.parseVersion = parseVersion_default;
 exports.parseVersionType = parseVersionType_default;
 exports.parseZodSchema = parseZodSchema_default;
 exports.randomiseArray = randomiseArray_default;
 exports.range = range_default;
 exports.removeDuplicates = removeDuplicates_default;
-exports.removeIndents = removeIndents_default;
 exports.stringListToArray = stringListToArray_default;
-exports.stringToBoolean = stringToBoolean;
 exports.truncate = truncate_default;
 exports.wait = wait_default;