@alextheman/utility 4.3.0 → 4.3.2

package/README.md

@@ -1,5 +1,16 @@
 # @alextheman/utility
 
+![npm version](https://img.shields.io/npm/v/@alextheman/utility)
+![npm downloads](https://img.shields.io/npm/dm/@alextheman/utility)
+![npm license](https://img.shields.io/npm/l/@alextheman/utility)
+
+[![CI](https://github.com/AlexMan123456/utility/actions/workflows/ci.yml/badge.svg)](https://github.com/AlexMan123456/utility/actions/workflows/ci.yml)
+[![Publish to NPM Registry](https://github.com/AlexMan123456/utility/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/AlexMan123456/utility/actions/workflows/npm-publish.yml)
+[![Publish to Netlify](https://github.com/AlexMan123456/utility/actions/workflows/netlify-docs-publish.yml/badge.svg)](https://github.com/AlexMan123456/utility/actions/workflows/netlify-docs-publish.yml)
+
+[![Netlify Status](https://api.netlify.com/api/v1/badges/74fd3eaf-3002-472b-ae5e-2bd0ab984b9e/deploy-status)](https://app.netlify.com/projects/alextheman-utility-docs/deploys)
+
+
 This is my personal utility package. It provides custom utility functions that can be used in more or less any TypeScript or JavaScript project, using either the browser or Node environment.
 
 ## Installation
@@ -24,3 +35,9 @@ import { formatDateAndTime } from "@alextheman/utility";
 const myVariable: NonUndefined<string> = formatDateAndTime(new Date());
 // ...
 ```
+
+## Documentation
+
+You can find the relevant documentation of all features of the package in the [docs/features/markdown](https://github.com/AlexMan123456/utility/tree/main/docs/features/markdown) directory of the repository. The hosted documentation site can be found [here](https://alextheman-utility-docs.netlify.app/).
+
+See the GitHub repository [here](https://github.com/AlexMan123456/utility).

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).
@@ -163,25 +175,21 @@ var DataError = class extends Error {
 };
 var DataError_default = DataError;
 
-//#endregion
-//#region src/types/VersionType.ts
-const VersionType = {
-	MAJOR: "major",
-	MINOR: "minor",
-	PATCH: "patch"
-};
-
 //#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.
 	*/
@@ -210,21 +218,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 +228,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,35 +254,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);
 	}
 	/**
-	* Checks if the provided version numbers have the exact same major, minor, and patch numbers.
+	* Get a string representation of the current version number.
 	*
-	* @param firstVersion - The first version number to compare.
-	* @param secondVersion - The second version number to compare.
+	* @param options - Extra additional options to apply.
 	*
-	* @returns `true` if the provided version numbers have exactly the same major, minor, and patch numbers, and returns `false` otherwise.
+	* @returns A stringified representation of the current version number, leaving out the prefix if `omitPrefix` option was set to true.
 	*/
-	static isEqual(firstVersion, secondVersion) {
-		return firstVersion.major === secondVersion.major && firstVersion.minor === secondVersion.minor && firstVersion.patch === secondVersion.patch;
+	toString(options) {
+		const rawString = `${this.major}.${this.minor}.${this.patch}`;
+		return VersionNumber.formatString(rawString, options);
 	}
 };
 var VersionNumber_default = VersionNumber;
@@ -284,6 +291,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.
 *
@@ -315,6 +324,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.
 *
@@ -332,6 +343,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.
@@ -357,6 +370,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.
@@ -385,6 +400,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.
@@ -403,6 +420,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)
 *
@@ -420,6 +439,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.
 *
@@ -435,6 +456,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.
@@ -458,6 +481,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.
@@ -479,6 +504,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.
 *
@@ -525,6 +552,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.
 *
@@ -543,6 +572,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.
@@ -575,6 +606,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.
@@ -640,6 +673,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.
@@ -657,6 +692,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.
@@ -678,6 +715,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.
@@ -696,6 +735,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.
@@ -712,6 +753,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.
 *
@@ -734,6 +777,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).
@@ -752,6 +797,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.
@@ -774,14 +821,21 @@ var parseZodSchema_default = parseZodSchema;
 
 //#endregion
 //#region src/functions/parsers/parseEnv.ts
-const envSchema = zod.z.enum([
-	"test",
-	"development",
-	"production"
-]);
+/**
+* Represents the three common development environments.
+*
+* @category Types
+*/
+const Env = {
+	TEST: "test",
+	DEVELOPMENT: "development",
+	PRODUCTION: "production"
+};
 /**
 * 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").
@@ -789,7 +843,7 @@ const envSchema = zod.z.enum([
 * @returns The specified environment if allowed.
 */
 function parseEnv(data) {
-	return parseZodSchema_default(envSchema, data, new DataError_default(data, "INVALID_ENV", "The provided environment type must be one of `test | development | production`"));
+	return parseZodSchema_default(zod.z.enum(Env), data, new DataError_default(data, "INVALID_ENV", "The provided environment type must be one of `test | development | production`"));
 }
 var parseEnv_default = parseEnv;
 
@@ -798,6 +852,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.
@@ -818,8 +874,20 @@ var parseFormData_default = parseFormData;
 //#endregion
 //#region src/functions/parsers/parseVersionType.ts
 /**
+* Represents the three common software version types.
+*
+* @category Types
+*/
+const VersionType = {
+	MAJOR: "major",
+	MINOR: "minor",
+	PATCH: "patch"
+};
+/**
 * 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"`).
@@ -839,6 +907,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.
@@ -866,6 +936,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.
@@ -886,6 +958,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.
@@ -905,6 +979,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.
 *
@@ -943,6 +1019,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.
 *
@@ -980,13 +1058,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.
@@ -998,13 +1077,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.
@@ -1017,6 +1097,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.
 *
@@ -1032,6 +1114,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.
@@ -1048,10 +1132,14 @@ var createTemplateStringsArray_default = createTemplateStringsArray;
 *
 * You can pass a template string directly by doing:
 *
-*      interpolate`Template string here`.
+* ```
+* interpolate`Template string here`.
+* ```
 *
 * 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.
 *
@@ -1071,7 +1159,11 @@ var interpolate_default = interpolate;
 *
 * You can pass a template string directly by doing:
 *
-*      interpolateObjects`Template string here ${{ my: "object" }}`.
+* ```typescript
+* 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.
@@ -1119,15 +1211,21 @@ function reduceLines(lines, { preserveTabs = true }) {
 *
 * You can pass a template string directly by doing:
 *
-*      normaliseIndents`Template string here
-*          with a new line
-*          and another new line`.
+* ```typescript
+* normaliseIndents`Template string here
+*     with a new line
+*     and another new line`.
+* ```
 *
 * You may also pass the options first, then invoke the resulting function with a template string:
 *
-*      normaliseIndents({ preserveTabs: false })`Template string here
-*          with a new line
-*          and another new line`.
+* ```typescript
+* normaliseIndents({ preserveTabs: false })`Template string here
+*     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.
@@ -1150,15 +1248,19 @@ function normaliseIndents(first, ...args) {
 *
 * You can pass a template string directly by doing:
 *
-*      normalizeIndents`Template string here
-*          with a new line
-*          and another new line`.
+* ```typescript
+* normalizeIndents`Template string here
+*     with a new line
+*     and another new line`.
+* ```
 *
 * You may also pass the options first, then invoke the resulting function with a template string:
 *
-*      normalizeIndents({ preserveTabs: false })`Template string here
-*          with a new line
-*          and another new line`.
+* ```typescript
+* normalizeIndents({ preserveTabs: false })`Template string here
+*     with a new line
+*     and another new line`.
+* ```
 *
 * @param first - The strings from the template to process, or the options to apply.
 * @param args - An array of all interpolations from the template.
@@ -1263,6 +1365,7 @@ var incrementVersion_default = incrementVersion;
 //#endregion
 exports.APIError = APIError_default;
 exports.DataError = DataError_default;
+exports.Env = Env;
 exports.NAMESPACE_EXPORT_REGEX = NAMESPACE_EXPORT_REGEX_default;
 exports.VERSION_NUMBER_REGEX = VERSION_NUMBER_REGEX_default;
 exports.VersionNumber = VersionNumber_default;