@alextheman/utility 4.2.1 → 4.3.1

package/dist/index.cjs

@@ -47,6 +47,8 @@ var VERSION_NUMBER_REGEX_default = VERSION_NUMBER_REGEX;
 * If the callback returns at least one Promise, the entire result will be wrapped
 * in a `Promise` and resolved with `Promise.all`. Otherwise, a plain array is returned.
 *
+* @category Array Helpers
+*
 * @template ItemType
 *
 * @param callback - A function invoked with the current index. May return a value or a Promise.
@@ -73,6 +75,8 @@ var fillArray_default = fillArray;
 * If `secondArray` is shorter than `firstArray`, the second position in the tuple
 * will be `undefined`. Iteration always uses the length of the first array.
 *
+* @category Array Helpers
+*
 * @template FirstArrayItem
 * @template SecondArrayItem
 *
@@ -98,7 +102,11 @@ const httpErrorCodeLookup = {
 	418: "I_AM_A_TEAPOT",
 	500: "INTERNAL_SERVER_ERROR"
 };
-/** Represents common errors you may get from a HTTP API request. */
+/**
+* Represents common errors you may get from a HTTP API request.
+*
+* @category Types
+*/
 var APIError = class extends Error {
 	status;
 	/**
@@ -130,10 +138,14 @@ 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. */
+/**
+* Represents errors you may get that may've been caused by a specific piece of data.
+*
+* @category Types
+*/
 var DataError = class extends Error {
-	data;
 	code;
+	data;
 	/**
 	* @param data - The data that caused the error.
 	* @param code - A standardised code (e.g. UNEXPECTED_DATA).
@@ -165,6 +177,11 @@ var DataError_default = DataError;
 
 //#endregion
 //#region src/types/VersionType.ts
+/**
+* Represents the three common software version types.
+*
+* @category Types
+*/
 const VersionType = {
 	MAJOR: "major",
 	MINOR: "minor",
@@ -173,15 +190,19 @@ const VersionType = {
 
 //#endregion
 //#region src/types/VersionNumber.ts
-/** Represents a software version number, considered to be made up of a major, minor, and patch part. */
+/**
+* Represents a software version number, considered to be made up of a major, minor, and patch part.
+*
+* @category Types
+*/
 var VersionNumber = class VersionNumber {
+	static NON_NEGATIVE_TUPLE_ERROR = "Input array must be a tuple of three non-negative integers.";
 	/** The major number. Increments when a feature is removed or changed in a way that is not backwards-compatible with the previous release. */
 	major = 0;
 	/** The minor number. Increments when a new feature is added/deprecated and is expected to be backwards-compatible with the previous release. */
 	minor = 0;
 	/** The patch number. Increments when the next release is fixing a bug or doing a small refactor that should not be noticeable in practice. */
 	patch = 0;
-	static NON_NEGATIVE_TUPLE_ERROR = "Input array must be a tuple of three non-negative integers.";
 	/**
 	* @param input - The input to create a new instance of `VersionNumber` from.
 	*/
@@ -202,7 +223,7 @@ var VersionNumber = class VersionNumber {
 			if (input.length !== 3) throw new DataError_default(input, "INVALID_LENGTH", VersionNumber.NON_NEGATIVE_TUPLE_ERROR);
 			const [major, minor, patch] = input.map((number) => {
 				const parsedInteger = parseIntStrict_default(number?.toString());
-				if (parsedInteger < 0) throw new DataError_default(input, "NON_POSITIVE_INPUTS", VersionNumber.NON_NEGATIVE_TUPLE_ERROR);
+				if (parsedInteger < 0) throw new DataError_default(input, "NEGATIVE_INPUTS", VersionNumber.NON_NEGATIVE_TUPLE_ERROR);
 				return parsedInteger;
 			});
 			this.major = major;
@@ -210,21 +231,6 @@ var VersionNumber = class VersionNumber {
 			this.patch = patch;
 		}
 	}
-	static formatString(input, options) {
-		if (options?.omitPrefix) return input.startsWith("v") ? input.slice(1) : input;
-		return input.startsWith("v") ? input : `v${input}`;
-	}
-	/**
-	* Get a string representation of the current version number.
-	*
-	* @param options - Extra additional options to apply.
-	*
-	* @returns A stringified representation of the current version number, leaving out the prefix if `omitPrefix` option was set to true.
-	*/
-	toString(options) {
-		const rawString = `${this.major}.${this.minor}.${this.patch}`;
-		return VersionNumber.formatString(rawString, options);
-	}
 	/**
 	* Gets the current version type of the current instance of `VersionNumber`.
 	*
@@ -235,6 +241,21 @@ var VersionNumber = class VersionNumber {
 		if (this.patch === 0) return VersionType.MINOR;
 		return VersionType.PATCH;
 	}
+	static formatString(input, options) {
+		if (options?.omitPrefix) return input.startsWith("v") ? input.slice(1) : input;
+		return input.startsWith("v") ? input : `v${input}`;
+	}
+	/**
+	* Checks if the provided version numbers have the exact same major, minor, and patch numbers.
+	*
+	* @param firstVersion - The first version number to compare.
+	* @param secondVersion - The second version number to compare.
+	*
+	* @returns `true` if the provided version numbers have exactly the same major, minor, and patch numbers, and returns `false` otherwise.
+	*/
+	static isEqual(firstVersion, secondVersion) {
+		return firstVersion.major === secondVersion.major && firstVersion.minor === secondVersion.minor && firstVersion.patch === secondVersion.patch;
+	}
 	/**
 	* Determines whether the current instance of `VersionNumber` is a major, minor, or patch version.
 	*
@@ -246,24 +267,34 @@ var VersionNumber = class VersionNumber {
 	* @returns A new instance of `VersionNumber` with the increment applied.
 	*/
 	increment(incrementType) {
-		const newVersion = {
-			major: [
+		return {
+			major: new VersionNumber([
 				this.major + 1,
 				0,
 				0
-			],
-			minor: [
+			]),
+			minor: new VersionNumber([
 				this.major,
 				this.minor + 1,
 				0
-			],
-			patch: [
+			]),
+			patch: new VersionNumber([
 				this.major,
 				this.minor,
 				this.patch + 1
-			]
+			])
 		}[incrementType];
-		return new VersionNumber(newVersion);
+	}
+	/**
+	* Get a string representation of the current version number.
+	*
+	* @param options - Extra additional options to apply.
+	*
+	* @returns A stringified representation of the current version number, leaving out the prefix if `omitPrefix` option was set to true.
+	*/
+	toString(options) {
+		const rawString = `${this.major}.${this.minor}.${this.patch}`;
+		return VersionNumber.formatString(rawString, options);
 	}
 };
 var VersionNumber_default = VersionNumber;
@@ -273,6 +304,8 @@ var VersionNumber_default = VersionNumber;
 /**
 * Converts a string to an integer and throws an error if it cannot be converted.
 *
+* @category Parsers
+*
 * @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.
 *
@@ -304,6 +337,8 @@ var parseIntStrict_default = parseIntStrict;
 /**
 * Gets a random number between the given bounds.
 *
+* @category Miscellaneous
+*
 * @param lowerBound - The lowest number that can be chosen.
 * @param upperBound - The highest number that can be chosen.
 *
@@ -321,6 +356,8 @@ var getRandomNumber_default = getRandomNumber;
 /**
 * Randomises the order of a given array and returns the result in a new array without mutating the original.
 *
+* @category Array Helpers
+*
 * @template ItemType - The type of the array items.
 *
 * @param array - The array to randomise.
@@ -346,6 +383,8 @@ var randomiseArray_default = randomiseArray;
 * - The range is inclusive of `start` and exclusive of `stop`.
 * - The sign of `step` must match the direction of the range.
 *
+* @category Array Helpers
+*
 * @param start - The number to start at (inclusive).
 * @param stop - The number to stop at (exclusive).
 * @param step - The step size between numbers, defaulting to 1.
@@ -374,6 +413,8 @@ var range_default = range;
 /**
 * Removes duplicate values from an array.
 *
+* @category Array Helpers
+*
 * @template ItemType - The type of the array items.
 *
 * @param array - The array to remove duplicates from.
@@ -392,6 +433,8 @@ var removeDuplicates_default = removeDuplicates;
 /**
 * Adds a given number of days to the provided date, returning the result as a new instance of Date.
 *
+* @category Date
+*
 * @param currentDate - The starting date (defaults to today).
 * @param dayIncrement - The amount of days you want to add (defaults to 1)
 *
@@ -409,6 +452,8 @@ var addDaysToDate_default = addDaysToDate;
 /**
 * Checks if the provided dates happen on the exact same day, month, and year.
 *
+* @category Date
+*
 * @param firstDate - The first date to compare.
 * @param secondDate - The second date to compare.
 *
@@ -424,6 +469,8 @@ var isSameDate_default = isSameDate;
 /**
 * Creates a human-readable string with information about the input date.
 *
+* @category Date
+*
 * @param inputDate - The date to base the string on.
 *
 * @returns A new string with information about the given date.
@@ -447,6 +494,8 @@ var formatDateAndTime_default = formatDateAndTime;
 /**
 * Checks if the provided year is a leap year.
 *
+* @category Date
+*
 * @param year - The year to check as a number.
 *
 * @throws {TypeError} If the year provided is not an integer.
@@ -468,6 +517,8 @@ function checkLeapYear(firstDate, secondDate) {
 /**
 * Checks if the provided dates are exactly a whole number of years apart.
 *
+* @category Date
+*
 * @param firstDate - The first date to compare.
 * @param secondDate - The second date to compare.
 *
@@ -514,6 +565,8 @@ function leapYearFebruaryChecks(firstDate, secondDate) {
 /**
 * Checks if the provided dates are exactly a whole number of months apart.
 *
+* @category Date
+*
 * @param firstDate - The first date to compare.
 * @param secondDate - The second date to compare.
 *
@@ -532,6 +585,8 @@ var isMonthlyMultiple_default = isMonthlyMultiple;
 /**
 * Asynchronously converts a file to a base 64 string
 *
+* @category Miscellaneous
+*
 * @param file - The file to convert.
 *
 * @throws {Error} If the file reader gives an error.
@@ -564,6 +619,8 @@ function getNullableResolutionStrategy(key, strategy) {
 /**
 * Creates FormData from a given object, resolving non-string types as appropriate.
 *
+* @category Miscellaneous
+*
 * @template DataType - The type of the given data.
 *
 * @param data - The data to create FormData from.
@@ -629,6 +686,8 @@ var createFormData_default = createFormData;
 /**
 * Checks to see if the given array is sorted in ascending order.
 *
+* @category Miscellaneous
+*
 * @param array - The array to check.
 *
 * @returns `true` if the array is sorted in ascending order, and `false` otherwise.
@@ -646,6 +705,8 @@ var isOrdered_default = isOrdered;
 /**
 * Converts a stringly-typed list to a proper array.
 *
+* @category Miscellaneous
+*
 * @param stringList - The stringly-typed list to convert.
 * @param options - The options to apply to the conversion.
 * @param options.separator - What each item in the list is separated by.
@@ -667,6 +728,8 @@ var stringListToArray_default = stringListToArray;
 /**
 * Waits for the given number of seconds
 *
+* @category Miscellaneous
+*
 * @param seconds - The number of seconds to wait.
 *
 * @returns A Promise that resolves after the given number of seconds.
@@ -685,6 +748,8 @@ var wait_default = wait;
 /**
 * Gets the keys from a given record object, properly typed to be an array of the key of the input object's type.
 *
+* @category Object Helpers
+*
 * @template InputRecordType - The type of the input object.
 *
 * @param record - The record to get the keys from.
@@ -701,6 +766,8 @@ var getRecordKeys_default = getRecordKeys;
 /**
 * Omits properties from a given object.
 *
+* @category Object Helpers
+*
 * @template ObjectType - The type of the input object.
 * @template KeysToOmit - A type representing the keys to omit from the object.
 *
@@ -723,6 +790,8 @@ var omitProperties_default = omitProperties;
 /**
 * Takes a stringly-typed boolean and converts it to an actual boolean type.
 *
+* @category Parsers
+*
 * @param inputString - The string to parse.
 *
 * @throws {DataError} If the string is not either `true` or `false` (case insensitive).
@@ -741,6 +810,8 @@ var parseBoolean_default = parseBoolean;
 /**
 * An alternative function to zodSchema.parse() that can be used to strictly parse Zod schemas.
 *
+* @category Parsers
+*
 * @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.
@@ -771,6 +842,8 @@ const envSchema = zod.z.enum([
 /**
 * Parses the input and verifies it matches one of the environments allowed by the Env types ("test" | "development" | "production").
 *
+* @category Parsers
+*
 * @param data - The data to parse.
 *
 * @throws {DataError} If the data does not match one of the environments allowed by the Env types ("test" | "development" | "production").
@@ -787,6 +860,8 @@ var parseEnv_default = parseEnv;
 /**
 * Returns an object given FormData and an optional data parser function to call on the resulting object.
 *
+* @category Parsers
+*
 * @template DataType - The type of the resulting object when called from the dataParser.
 *
 * @param formData - The FormData to parse.
@@ -809,6 +884,8 @@ var parseFormData_default = parseFormData;
 /**
 * Parses the input and verifies it is a valid software version type (i.e. `"major" | "minor" | "patch"`)
 *
+* @category Parsers
+*
 * @param data - The data to parse.
 *
 * @throws {DataError} If the data does not match one of the allowed version types (`"major" | "minor" | "patch"`).
@@ -828,6 +905,8 @@ function callDeepCopy(input) {
 /**
 * Deeply copies an object or array such that all child objects/arrays are also copied.
 *
+* @category Recursive
+*
 * @template ObjectType - The type of the input object.
 *
 * @param object - The object to copy. May also be an array.
@@ -855,6 +934,8 @@ var deepCopy_default = deepCopy;
 * Note that this will also freeze the input itself as well.
 * If the intent is to create a newly frozen object with a different reference in memory, pass your object through deepCopy first before passing to deepFreeze.
 *
+* @category Recursive
+*
 * @template ObjectType - The type of the input object.
 *
 * @param object - The object to freeze. May also be an array.
@@ -875,6 +956,8 @@ var deepFreeze_default = deepFreeze;
 /**
 * Appends a semicolon to the end of a string, trimming where necessary first.
 *
+* @category String Helpers
+*
 * @param stringToAppendTo - The string to append a semicolon to.
 *
 * @throws {Error} If the string contains multiple lines.
@@ -894,6 +977,8 @@ var appendSemicolon_default = appendSemicolon;
 /**
 * Converts a string from camelCase to kebab-case
 *
+* @category String Helpers
+*
 * @param string - The string to convert.
 * @param options - Options to apply to the conversion.
 *
@@ -932,6 +1017,8 @@ var camelToKebab_default = camelToKebab;
 /**
 * Converts a string from kebab-case to camelCase
 *
+* @category String Helpers
+*
 * @param string - The string to convert.
 * @param options - Options to apply to the conversion.
 *
@@ -969,13 +1056,14 @@ var kebabToCamel_default = kebabToCamel;
 //#region src/functions/stringHelpers/normalizeImportPath.ts
 /**
 * Normalizes an import path meant for use in an import statement in JavaScript.
-*
 * When multiple slashes are found, they're replaced by a single one; when the path contains a trailing slash, it is preserved. On Windows backslashes are used. If the path is a zero-length string, '.' is returned, representing the current working directory.
 *
 * If the path starts with ./, it is preserved (unlike what would happen with path.posix.normalize() normally).
 *
 * Helpful for custom linter rules that need to check (or fix) import paths.
 *
+* @category String Helpers
+*
 * @param importPath - The import path to normalize.
 *
 * @returns The import path normalized.
@@ -987,13 +1075,14 @@ function normalizeImportPath(importPath) {
 }
 /**
 * Normalises an import path meant for use in an import statement in JavaScript.
-*
 * When multiple slashes are found, they're replaced by a single one; when the path contains a trailing slash, it is preserved. On Windows backslashes are used. If the path is a zero-length string, '.' is returned, representing the current working directory.
 *
 * If the path starts with ./, it is preserved (unlike what would happen with path.posix.normalize() normally).
 *
 * Helpful for custom linter rules that need to check (or fix) import paths.
 *
+* @category String Helpers
+*
 * @param importPath - The import path to normalise.
 *
 * @returns The import path normalised.
@@ -1006,6 +1095,8 @@ var normalizeImportPath_default = normalizeImportPath;
 /**
 * Truncates a string and appends `...` to the end of it
 *
+* @category String Helpers
+*
 * @param stringToTruncate - The string to truncate.
 * @param maxLength - The length at which to start truncating. Note that this does not include the `...` part that would be appended.
 *
@@ -1021,6 +1112,8 @@ var truncate_default = truncate;
 /**
 * Creates a template strings array given a regular array of strings
 *
+* @category Tagged Template
+*
 * @param strings - The array of strings.
 *
 * @returns A template strings array that can be passed as the first argument of any tagged template function.
@@ -1041,6 +1134,8 @@ var createTemplateStringsArray_default = createTemplateStringsArray;
 *
 * In this case, it will be functionally the same as if you just wrote the template string by itself.
 *
+* @category Tagged Template
+*
 * @param strings - The strings from the template to process.
 * @param interpolations - An array of all interpolations from the template.
 *
@@ -1062,6 +1157,8 @@ var interpolate_default = interpolate;
 *
 *      interpolateObjects`Template string here ${{ my: "object" }}`.
 *
+* @category Tagged Template
+*
 * @param strings - The strings from the template to process.
 * @param interpolations - An array of all interpolations from the template.
 *
@@ -1118,6 +1215,8 @@ function reduceLines(lines, { preserveTabs = true }) {
 *          with a new line
 *          and another new line`.
 *
+*@category Tagged Template
+*
 * @param first - The strings from the template to process, or the options to apply.
 * @param args - An array of all interpolations from the template.
 *