@alextheman/utility 4.2.1 → 4.3.1

package/dist/index.js

@@ -18,6 +18,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.
@@ -44,6 +46,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
 *
@@ -69,7 +73,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;
 	/**
@@ -101,10 +109,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).
@@ -136,6 +148,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",
@@ -144,15 +161,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.
 	*/
@@ -173,7 +194,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;
@@ -181,21 +202,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`.
 	*
@@ -206,6 +212,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.
 	*
@@ -217,24 +238,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;
@@ -244,6 +275,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.
 *
@@ -275,6 +308,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.
 *
@@ -292,6 +327,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.
@@ -317,6 +354,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.
@@ -345,6 +384,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.
@@ -363,6 +404,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)
 *
@@ -380,6 +423,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.
 *
@@ -395,6 +440,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.
@@ -418,6 +465,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.
@@ -439,6 +488,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.
 *
@@ -485,6 +536,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.
 *
@@ -503,6 +556,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.
@@ -535,6 +590,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.
@@ -600,6 +657,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.
@@ -617,6 +676,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.
@@ -638,6 +699,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.
@@ -656,6 +719,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.
@@ -672,6 +737,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.
 *
@@ -694,6 +761,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).
@@ -712,6 +781,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.
@@ -742,6 +813,8 @@ const envSchema = z$1.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").
@@ -758,6 +831,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.
@@ -780,6 +855,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"`).
@@ -799,6 +876,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.
@@ -826,6 +905,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.
@@ -846,6 +927,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.
@@ -865,6 +948,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.
 *
@@ -903,6 +988,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.
 *
@@ -940,13 +1027,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.
@@ -958,13 +1046,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.
@@ -977,6 +1066,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.
 *
@@ -992,6 +1083,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.
@@ -1012,6 +1105,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.
 *
@@ -1033,6 +1128,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.
 *
@@ -1089,6 +1186,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.
 *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alextheman/utility",
-  "version": "4.2.1",
+  "version": "4.3.1",
   "description": "Helpful utility functions",
   "repository": {
     "type": "git",
@@ -19,17 +19,17 @@
     "zod": "^4.2.1"
   },
   "devDependencies": {
-    "@alextheman/eslint-plugin": "^5.0.1",
+    "@alextheman/eslint-plugin": "^5.2.0",
     "@types/node": "^25.0.3",
     "alex-c-line": "^1.10.0",
     "dotenv-cli": "^11.0.0",
     "eslint": "^9.39.2",
-    "eslint-plugin-perfectionist": "^5.0.0",
     "globals": "^16.5.0",
     "husky": "^9.1.7",
     "jsdom": "^27.3.0",
     "prettier": "^3.7.4",
     "tsdown": "^0.18.1",
+    "typedoc": "^0.28.15",
     "typescript": "^5.9.3",
     "vite-tsconfig-paths": "^6.0.3",
     "vitest": "^4.0.16"
@@ -39,6 +39,7 @@
   },
   "scripts": {
     "build": "tsdown",
+    "create-feature-docs": "typedoc",
     "create-local-package": "pnpm run build && rm -f alextheman-utility-*.tgz && pnpm pack",
     "create-release-note-major": "git pull origin main && alex-c-line create-release-note major",
     "create-release-note-minor": "git pull origin main && alex-c-line create-release-note minor",
@@ -46,12 +47,12 @@
     "format": "pnpm run format-prettier && pnpm run format-eslint",
     "format-eslint": "eslint --fix --suppress-all \"package.json\" \"src/**/*.ts\" \"tests/**/*.ts\" && rm -f eslint-suppressions.json",
     "format-prettier": "pnpm run format-prettier-typescript && pnpm run format-prettier-javascript",
-    "format-prettier-javascript": "prettier --write \"./**/*.js\"",
+    "format-prettier-javascript": "prettier --write \"./**/*.js\" \"!docs\"",
     "format-prettier-typescript": "prettier --write --parser typescript \"./**/*.ts\"",
     "lint": "pnpm run lint-tsc && pnpm run lint-eslint && pnpm run lint-prettier",
     "lint-eslint": "eslint \"package.json\" \"src/**/*.ts\" \"tests/**/*.ts\"",
     "lint-prettier": "pnpm run lint-prettier-typescript && pnpm run lint-prettier-javascript",
-    "lint-prettier-javascript": "prettier --check \"./**/*.js\"",
+    "lint-prettier-javascript": "prettier --check \"./**/*.js\" \"!docs\"",
     "lint-prettier-typescript": "prettier --check --parser typescript \"./**/*.ts\"",
     "lint-tsc": "tsc --noEmit",
     "prepare-live-eslint-plugin": "pnpm uninstall @alextheman/eslint-plugin && pnpm install --save-dev @alextheman/eslint-plugin",