@alextheman/utility 4.3.0 → 4.3.1

package/dist/index.d.cts

@@ -44,6 +44,8 @@ type ParallelTuple<A, B> = [A, B | undefined];
  * 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
  *
@@ -58,6 +60,8 @@ declare function paralleliseArrays<FirstArrayItem, SecondArrayItem>(firstArray:
 /**
  * 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.
@@ -73,6 +77,8 @@ declare function randomiseArray<ItemType>(array: ItemType[]): ItemType[];
  * - 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.
@@ -88,6 +94,8 @@ declare function range(start: number, stop: number, step?: number): number[];
 /**
  * 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.
@@ -100,6 +108,8 @@ declare function removeDuplicates<ItemType>(array: ItemType[] | readonly ItemTyp
 /**
  * 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)
  *
@@ -111,6 +121,8 @@ declare function addDaysToDate(currentDate?: Date, dayIncrement?: number): Date;
 /**
  * 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.
@@ -125,6 +137,8 @@ declare function formatDateAndTime(inputDate: Date): string;
 /**
  * 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.
  *
@@ -136,6 +150,8 @@ declare function isAnniversary(firstDate: Date, secondDate: Date): boolean;
 /**
  * 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.
@@ -148,6 +164,8 @@ declare function isLeapYear(year: number): boolean;
 /**
  * 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.
  *
@@ -159,6 +177,8 @@ declare function isMonthlyMultiple(firstDate: Date, secondDate: Date): boolean;
 /**
  * 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.
  *
@@ -170,6 +190,8 @@ declare function isSameDate(firstDate: Date, secondDate: Date): boolean;
 /**
  * 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.
@@ -181,7 +203,11 @@ declare function convertFileToBase64(file: File): Promise<string>;
 //#region src/types/APIError.d.ts
 type HTTPErrorCode = 400 | 401 | 403 | 404 | 418 | 500;
 declare const httpErrorCodeLookup: Record<HTTPErrorCode, string>;
-/** Represents common errors you may get from a HTTP API request. */
+/**
+ * Represents common errors you may get from a HTTP API request.
+ *
+ * @category Types
+ */
 declare class APIError extends Error {
   status: number;
   /**
@@ -201,10 +227,14 @@ declare class APIError extends Error {
 }
 //#endregion
 //#region src/types/DataError.d.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
+ */
 declare class DataError extends Error {
-  data: unknown;
   code: string;
+  data: unknown;
   /**
    * @param data - The data that caused the error.
    * @param code - A standardised code (e.g. UNEXPECTED_DATA).
@@ -223,18 +253,29 @@ declare class DataError extends Error {
 }
 //#endregion
 //#region src/types/RecordKey.d.ts
-/** Represents the native Record's possible key type. */
+/**
+ * Represents the native Record's possible key type.
+ *
+ * @category Types
+ */
 type RecordKey = string | number | symbol;
 //#endregion
 //#region src/types/CreateEnumType.d.ts
 /**
  * Get the value types from a const object so the object can behave similarly to an enum.
  *
+ * @category Types
+ *
  * @template ObjectType - The type of the object to get the value types for.
  */
 type CreateEnumType<ObjectType extends Record<RecordKey, unknown>> = ObjectType[keyof ObjectType];
 //#endregion
 //#region src/types/VersionType.d.ts
+/**
+ * Represents the three common software version types.
+ *
+ * @category Types
+ */
 declare const VersionType: {
   readonly MAJOR: "major";
   readonly MINOR: "minor";
@@ -246,34 +287,39 @@ type VersionType = CreateEnumType<typeof VersionType>;
 interface ToStringOptions {
   omitPrefix?: boolean;
 }
-/** 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
+ */
 declare class VersionNumber {
+  private static readonly NON_NEGATIVE_TUPLE_ERROR;
   /** The major number. Increments when a feature is removed or changed in a way that is not backwards-compatible with the previous release. */
   readonly major: number;
   /** The minor number. Increments when a new feature is added/deprecated and is expected to be backwards-compatible with the previous release. */
   readonly minor: number;
   /** The patch number. Increments when the next release is fixing a bug or doing a small refactor that should not be noticeable in practice. */
   readonly patch: number;
-  private static readonly NON_NEGATIVE_TUPLE_ERROR;
   /**
    * @param input - The input to create a new instance of `VersionNumber` from.
    */
   constructor(input: string | [number, number, number] | VersionNumber);
-  private static formatString;
-  /**
-   * 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?: ToStringOptions): string;
   /**
    * Gets the current version type of the current instance of `VersionNumber`.
    *
    * @returns Either `"major"`, `"minor"`, or `"patch"`, depending on the version type.
    */
   get type(): VersionType;
+  private static formatString;
+  /**
+   * 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: VersionNumber, secondVersion: VersionNumber): boolean;
   /**
    * Determines whether the current instance of `VersionNumber` is a major, minor, or patch version.
    *
@@ -286,20 +332,21 @@ declare class VersionNumber {
    */
   increment(incrementType: VersionType): VersionNumber;
   /**
-   * 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: VersionNumber, secondVersion: VersionNumber): boolean;
+  toString(options?: ToStringOptions): string;
 }
 //#endregion
 //#region src/types/ArrayElement.d.ts
 /**
  * Gets the individual element types from an array type.
  *
+ * @category Types
+ *
  * @template ArrayType - The type of the array itself.
  */
 type ArrayElement<ArrayType extends readonly unknown[]> = ArrayType extends readonly (infer ElementType)[] ? ElementType : never;
@@ -308,6 +355,8 @@ type ArrayElement<ArrayType extends readonly unknown[]> = ArrayType extends read
 /**
  * Resolves to an error message type if the type argument could potentially be undefined.
  *
+ * @category Types
+ *
  * @template InputType - The type to disallow undefined on.
  */
 type DisallowUndefined<InputType> = undefined extends InputType ? ["Error: Generic type cannot include undefined"] : InputType;
@@ -316,6 +365,8 @@ type DisallowUndefined<InputType> = undefined extends InputType ? ["Error: Gener
 /**
  * Allows case-insensitive variants of a known string type.
  *
+ * @category Types
+ *
  * @template StringType - The input string type.
  */
 type IgnoreCase<StringType extends string> = string extends StringType ? string : StringType extends `${infer FirstCharacter}${infer SecondCharacter}${infer Remainder}` ? `${Uppercase<FirstCharacter> | Lowercase<FirstCharacter>}${Uppercase<SecondCharacter> | Lowercase<SecondCharacter>}${IgnoreCase<Remainder>}` : StringType extends `${infer FirstCharacter}${infer Remainder}` ? `${Uppercase<FirstCharacter> | Lowercase<FirstCharacter>}${IgnoreCase<Remainder>}` : "";
@@ -324,6 +375,8 @@ type IgnoreCase<StringType extends string> = string extends StringType ? string
 /**
  * Resolves to `never` if the given type may be undefined.
  *
+ * @category Types
+ *
  * @template InputType - The type to check.
  */
 type NonUndefined<InputType> = InputType extends undefined ? never : InputType;
@@ -332,6 +385,8 @@ type NonUndefined<InputType> = InputType extends undefined ? never : InputType;
 /**
  * Resolves to the given type if the first type is `true`, otherwise resolves to `undefined`
  *
+ * @category Types
+ *
  * @param Condition - The condition to check.
  * @param ResolvedTypeIfTrue - The type to resolve to if the condition may be `true`.
  */
@@ -364,6 +419,8 @@ type CreateFormDataOptions<Key extends RecordKey> = CreateFormDataOptionsUndefin
 /**
  * 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.
@@ -377,6 +434,8 @@ declare function createFormData<DataType extends Record<RecordKey, unknown>>(dat
 /**
  * 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.
  *
@@ -388,6 +447,8 @@ declare function getRandomNumber(lowerBound: number, upperBound: number): number
 /**
  * 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.
@@ -404,6 +465,8 @@ interface StringListToArrayOptions {
 /**
  * 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.
@@ -420,6 +483,8 @@ declare function stringListToArray(stringList: string, {
 /**
  * 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.
@@ -430,6 +495,8 @@ declare function wait(seconds: number): Promise<void>;
 /**
  * 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.
@@ -442,6 +509,8 @@ declare function getRecordKeys<InputRecordType extends Record<RecordKey, unknown
 /**
  * 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.
  *
@@ -456,6 +525,8 @@ declare function omitProperties<ObjectType extends Record<string, unknown> | Rea
 /**
  * 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).
@@ -470,11 +541,17 @@ declare const envSchema: z.ZodEnum<{
   development: "development";
   production: "production";
 }>;
-/** Represents the most common development environments */
+/**
+ * Represents the most common development environments
+ *
+ * @category Types
+ */
 type Env = z.infer<typeof envSchema>;
 /**
  * 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").
@@ -508,6 +585,8 @@ declare function parseFormData(formData: FormData): Record<string, string | Blob
 /**
  * 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.
  *
@@ -521,6 +600,8 @@ declare function parseIntStrict(string: string, radix?: number): number;
 /**
  * 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"`).
@@ -533,6 +614,8 @@ declare function parseVersionType(data: unknown): VersionType;
 /**
  * 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.
@@ -552,6 +635,8 @@ declare function parseZodSchema<Output, Input, Internals extends core.$ZodTypeIn
 /**
  * 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.
@@ -567,6 +652,8 @@ declare function deepCopy<ObjectType extends object>(object: ObjectType): Object
  * 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.
@@ -579,6 +666,8 @@ declare function deepFreeze<ObjectType extends object>(object: ObjectType): Read
 /**
  * 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.
@@ -595,6 +684,8 @@ interface CamelToKebabOptions {
 /**
  * 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.
  *
@@ -610,6 +701,8 @@ interface KebabToCamelOptions {
 /**
  * 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.
  *
@@ -620,13 +713,14 @@ declare function kebabToCamel(string: string, options?: KebabToCamelOptions): st
 //#region src/functions/stringHelpers/normalizeImportPath.d.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.
@@ -634,13 +728,14 @@ declare function kebabToCamel(string: string, options?: KebabToCamelOptions): st
 declare function normalizeImportPath(importPath: string): string;
 /**
  * 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.
@@ -651,6 +746,8 @@ declare const normaliseImportPath: typeof 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.
  *
@@ -662,6 +759,8 @@ declare function truncate(stringToTruncate: string, maxLength?: number): string;
 /**
  * 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.
@@ -678,6 +777,8 @@ declare function createTemplateStringsArray(strings: readonly string[]): Templat
  *
  * 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.
  *
@@ -693,6 +794,8 @@ declare function interpolate(strings: TemplateStringsArray, ...interpolations: u
  *
  *      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.
  *
@@ -711,6 +814,8 @@ type NormalizeIndentsFunction = NormaliseIndentsFunction;
 /**
  * Provides a new function that removes any extraneous indents from a multi-line template string, with the given options applied.
  *
+ * @category Tagged Template
+ *
  * @param options - The options to apply.
  *
  * @returns A function that takes a template string, and returns a new string with the strings and interpolations from the template applied, and extraneous indents removed.
@@ -725,6 +830,8 @@ declare function normaliseIndents(options: NormaliseIndentsOptions): NormaliseIn
  *          with a new line
  *          and another new line`.
  *
+ *@category Tagged Template
+ *
  * @param strings - The strings from the template to process.
  * @param interpolations - An array of all interpolations from the template.
  *