@alextheman/utility 3.6.0 → 3.8.0

package/dist/index.d.cts

@@ -3,8 +3,8 @@ import z, { ZodType, core, z as z$1 } from "zod";
 //#region src/constants/NAMESPACE_EXPORT_REGEX.d.ts
 declare const NAMESPACE_EXPORT_REGEX = "export\\s+\\*\\s+from";
 //#endregion
-//#region src/functions/appendSemicolon.d.ts
-declare function appendSemicolon(stringToAppendTo: string): string;
+//#region src/constants/VERSION_NUMBER_REGEX.d.ts
+declare const VERSION_NUMBER_REGEX: string;
 //#endregion
 //#region src/functions/arrayHelpers/fillArray.d.ts
 /**
@@ -70,8 +70,8 @@ declare function randomiseArray<ItemType$1>(array: ItemType$1[]): ItemType$1[];
 /**
  * Creates an array of numbers within a given range.
  *
- * The range is inclusive of `start` and exclusive of `stop`.
- * The sign of `step` must match the direction of the range.
+ * - The range is inclusive of `start` and exclusive of `stop`.
+ * - The sign of `step` must match the direction of the range.
  *
  * @param start - The number to start at (inclusive).
  * @param stop - The number to stop at (exclusive).
@@ -84,22 +84,124 @@ declare function randomiseArray<ItemType$1>(array: ItemType$1[]): ItemType$1[];
  */
 declare function range(start: number, stop: number, step?: number): number[];
 //#endregion
-//#region src/functions/camelToKebab.d.ts
-declare function camelToKebab(string: string): string;
+//#region src/functions/arrayHelpers/removeDuplicates.d.ts
+/**
+ * Removes duplicate values from an array.
+ *
+ * @template ItemType - The type of the array items.
+ *
+ * @param array - The array to remove duplicates from.
+ *
+ * @returns A new array with a different reference in memory, with the duplicates removed.
+ */
+declare function removeDuplicates<ItemType$1>(array: ItemType$1[] | readonly ItemType$1[]): ItemType$1[];
+//#endregion
+//#region src/functions/date/addDaysToDate.d.ts
+/**
+ * Adds a given number of days to the provided date, returning the result as a new instance of Date.
+ *
+ * @param currentDate - The starting date (defaults to today).
+ * @param dayIncrement - The amount of days you want to add (defaults to 1)
+ *
+ * @returns A new Date instance with the number of days added to the initially provided date.
+ */
+declare function addDaysToDate(currentDate?: Date, dayIncrement?: number): Date;
+//#endregion
+//#region src/functions/date/formatDateAndTime.d.ts
+/**
+ * Creates a human-readable string with information about the input date.
+ *
+ * @param inputDate - The date to base the string on.
+ *
+ * @returns A new string with information about the given date.
+ *
+ * - If the date given is today, the output will be something like `Today at HH:MM`
+ * - If the date given happened yesterday, the output will be something like `Yesterday at HH:MM`
+ * - For any other date, the output will be something like `DD/MM/YYYY, HH:MM`
+ */
+declare function formatDateAndTime(inputDate: Date): string;
+//#endregion
+//#region src/functions/date/isAnniversary.d.ts
+/**
+ * Checks if the provided dates are exactly a whole number of years apart.
+ *
+ * @param firstDate - The first date to compare.
+ * @param secondDate - The second date to compare.
+ *
+ * @returns True if the provided dates are exactly a whole number of years apart, and false otherwise.
+ */
+declare function isAnniversary(firstDate: Date, secondDate: Date): boolean;
 //#endregion
-//#region src/functions/convertFileToBase64.d.ts
+//#region src/functions/date/isLeapYear.d.ts
+/**
+ * Checks if the provided year is a leap year.
+ *
+ * @param year - The year to check as a number.
+ *
+ * @throws {TypeError} If the year provided is not an integer.
+ *
+ * @returns True if the year is a leap year, and false otherwise.
+ */
+declare function isLeapYear(year: number): boolean;
+//#endregion
+//#region src/functions/date/isMonthlyMultiple.d.ts
+/**
+ * Checks if the provided dates are exactly a whole number of months apart.
+ *
+ * @param firstDate - The first date to compare.
+ * @param secondDate - The second date to compare.
+ *
+ * @returns True if the provided dates are exactly a whole number of months apart, and false otherwise.
+ */
+declare function isMonthlyMultiple(firstDate: Date, secondDate: Date): boolean;
+//#endregion
+//#region src/functions/date/isSameDate.d.ts
+/**
+ * Checks if the provided dates happen on the exact same day, month, and year.
+ *
+ * @param firstDate - The first date to compare.
+ * @param secondDate - The second date to compare.
+ *
+ * @returns True if the provided dates occur on exactly the same day, month, and year, and returns false otherwise.
+ */
+declare function isSameDate(firstDate: Date, secondDate: Date): boolean;
+//#endregion
+//#region src/functions/miscellaneous/convertFileToBase64.d.ts
+/**
+ * Asynchronously converts a file to a base 64 string
+ *
+ * @param file - The file to convert.
+ *
+ * @throws {Error} If the file reader gives an error.
+ *
+ * @returns A promise that resolves to the encoded base 64 string.
+ */
 declare function convertFileToBase64(file: File): Promise<string>;
 //#endregion
 //#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. */
 declare class APIError extends Error {
   status: number;
+  /**
+   * @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?: HTTPErrorCode | number, message?: string, options?: ErrorOptions);
+  /**
+   * 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: unknown): input is APIError;
 }
 //#endregion
 //#region src/types/DataError.d.ts
+/** Represents errors you may get that may've been caused by a specific piece of data. */
 declare class DataError extends Error {
   data: unknown;
   code: string;
@@ -110,6 +212,13 @@ declare class DataError extends Error {
    * @param options - Extra options to pass to super Error constructor.
    */
   constructor(data: unknown, message?: string, code?: string, options?: ErrorOptions);
+  /**
+   * 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: unknown): input is DataError;
 }
 //#endregion
@@ -128,147 +237,179 @@ type UUID = z.infer<typeof uuidSchema>;
 declare function parseUUID(UUID: unknown): UUID;
 //#endregion
 //#region src/types/ArrayElement.d.ts
-type ArrayElement<T extends readonly unknown[]> = T extends readonly (infer ElementType)[] ? ElementType : never;
+/**
+ * Gets the individual element types from an array type.
+ *
+ * @template ArrayType - The type of the array itself.
+ */
+type ArrayElement<ArrayType extends readonly unknown[]> = ArrayType extends readonly (infer ElementType)[] ? ElementType : never;
 //#endregion
 //#region src/types/DeepReadonly.d.ts
+/** @deprecated This type did not work with the deepFreeze function as intended and therefore should not be used. */
 type DeepReadonly<T> = T extends ((...args: unknown[]) => unknown) ? T : T extends (infer ItemType)[] ? readonly DeepReadonly<ItemType>[] : T extends object ? { readonly [K in keyof T]: DeepReadonly<T[K]> } : T;
 //#endregion
 //#region src/types/DisallowUndefined.d.ts
-type DisallowUndefined<T> = undefined extends T ? ["Error: Generic type cannot include undefined"] : T;
+/**
+ * Resolves to an error message type if the type argument could potentially be undefined.
+ *
+ * @template InputType - The type to disallow undefined on.
+ */
+type DisallowUndefined<InputType> = undefined extends InputType ? ["Error: Generic type cannot include undefined"] : InputType;
 //#endregion
 //#region src/types/IgnoreCase.d.ts
-type IgnoreCase<T extends string> = string extends T ? string : T extends `${infer F1}${infer F2}${infer R}` ? `${Uppercase<F1> | Lowercase<F1>}${Uppercase<F2> | Lowercase<F2>}${IgnoreCase<R>}` : T extends `${infer F}${infer R}` ? `${Uppercase<F> | Lowercase<F>}${IgnoreCase<R>}` : "";
+/**
+ * Allows case-insensitive variants of a known string type.
+ *
+ * @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>}` : "";
 //#endregion
 //#region src/types/NonUndefined.d.ts
-type NonUndefined<T> = T extends undefined ? never : T;
+/**
+ * Resolves to `never` if the given type may be undefined.
+ *
+ * @template InputType - The type to check.
+ */
+type NonUndefined<InputType> = InputType extends undefined ? never : InputType;
 //#endregion
 //#region src/types/OptionalOnCondition.d.ts
-type OptionalOnCondition<Condition extends boolean, T> = Condition extends true ? T : T | undefined;
+/**
+ * Resolves to the given type if the first type is `true`, otherwise resolves to `undefined`
+ *
+ * @param Condition - The condition to check.
+ * @param ResolvedTypeIfTrue - The type to resolve to if the condition may be `true`.
+ */
+type OptionalOnCondition<Condition extends boolean, ResolvedTypeIfTrue> = Condition extends true ? ResolvedTypeIfTrue : ResolvedTypeIfTrue | undefined;
 //#endregion
 //#region src/types/RecordKey.d.ts
+/** Represents the native Record's possible key type. */
 type RecordKey = string | number | symbol;
 //#endregion
-//#region src/functions/createFormData.d.ts
+//#region src/functions/miscellaneous/createFormData.d.ts
 type FormDataNullableResolutionStrategy = "stringify" | "empty" | "omit";
 type FormDataArrayResolutionStrategy = "stringify" | "multiple";
-interface CreateFormDataOptionsBase<K$1 extends RecordKey> {
-  arrayResolution?: FormDataArrayResolutionStrategy | Partial<Record<K$1, FormDataArrayResolutionStrategy>>;
+interface CreateFormDataOptionsBase<Key extends RecordKey> {
+  /** How to resolve any arrays provided in the data (can either stringify them or add them multiple times). */
+  arrayResolution?: FormDataArrayResolutionStrategy | Partial<Record<Key, FormDataArrayResolutionStrategy>>;
 }
-interface CreateFormDataOptionsUndefinedOrNullResolution<K$1 extends RecordKey> extends CreateFormDataOptionsBase<K$1> {
-  undefinedResolution?: FormDataNullableResolutionStrategy | Partial<Record<K$1, FormDataNullableResolutionStrategy>>;
-  nullResolution?: FormDataNullableResolutionStrategy | Partial<Record<K$1, FormDataNullableResolutionStrategy>>;
+interface CreateFormDataOptionsUndefinedOrNullResolution<Key extends RecordKey> extends CreateFormDataOptionsBase<Key> {
+  /** How to resolve undefined data (May either stringify to 'undefined', resolve to an empty string, or omit entirely). */
+  undefinedResolution?: FormDataNullableResolutionStrategy | Partial<Record<Key, FormDataNullableResolutionStrategy>>;
+  /** How to resolve null data (May either stringify to 'null', resolve to an empty string, or omit entirely). */
+  nullResolution?: FormDataNullableResolutionStrategy | Partial<Record<Key, FormDataNullableResolutionStrategy>>;
+  /** @note This must not be provided at the same time as undefinedResolution and/or nullResolution. */
   nullableResolution?: never;
 }
-interface CreateFormDataOptionsNullableResolution<K$1 extends RecordKey> extends CreateFormDataOptionsBase<K$1> {
+interface CreateFormDataOptionsNullableResolution<Key extends RecordKey> extends CreateFormDataOptionsBase<Key> {
+  /** @note This must not be provided at the same time as nullableResolution. */
   undefinedResolution?: never;
+  /** @note This must not be provided at the same time as nullableResolution. */
   nullResolution?: never;
-  nullableResolution: FormDataNullableResolutionStrategy | Partial<Record<K$1, FormDataNullableResolutionStrategy>>;
+  /** How to resolve nullable data (May either stringify to 'undefined | null', resolve to an empty string, or omit entirely). */
+  nullableResolution: FormDataNullableResolutionStrategy | Partial<Record<Key, FormDataNullableResolutionStrategy>>;
 }
-type CreateFormDataOptions<K$1 extends RecordKey> = CreateFormDataOptionsUndefinedOrNullResolution<K$1> | CreateFormDataOptionsNullableResolution<K$1>;
-declare function createFormData<T extends Record<RecordKey, unknown>>(data: T, options?: CreateFormDataOptions<keyof T>): FormData;
-//#endregion
-//#region src/functions/createTemplateStringsArray.d.ts
-declare function createTemplateStringsArray(strings: readonly string[]): TemplateStringsArray;
-//#endregion
-//#region src/functions/date/addDaysToDate.d.ts
+type CreateFormDataOptions<Key extends RecordKey> = CreateFormDataOptionsUndefinedOrNullResolution<Key> | CreateFormDataOptionsNullableResolution<Key>;
 /**
- * Adds a given number of days to the provided date, returning the result as a new instance of Date.
+ * Creates FormData from a given object, resolving non-string types as appropriate.
  *
- * @param currentDate - The starting date (defaults to today).
- * @param dayIncrement - The amount of days you want to add (defaults to 1)
+ * @template DataType - The type of the given data.
  *
- * @returns A new Date instance with the number of days added to the initially provided date.
+ * @param data - The data to create FormData from.
+ * @param options - Options to apply to the conversion.
+ *
+ * @returns A FormData object with the data applied.
  */
-declare function addDaysToDate(currentDate?: Date, dayIncrement?: number): Date;
+declare function createFormData<DataType extends Record<RecordKey, unknown>>(data: DataType, options?: CreateFormDataOptions<keyof DataType>): FormData;
 //#endregion
-//#region src/functions/date/formatDateAndTime.d.ts
+//#region src/functions/miscellaneous/getRandomNumber.d.ts
 /**
- * Creates a human-readable string with information about the input date.
- *
- * @param inputDate - The date to base the string on.
+ * Gets a random number between the given bounds.
  *
- * @returns A new string with information about the given date.
+ * @param lowerBound - The lowest number that can be chosen.
+ * @param upperBound - The highest number that can be chosen.
  *
- * - If the date given is today, the output will be something like `Today at HH:MM`
- * - If the date given happened yesterday, the output will be something like `Yesterday at HH:MM`
- * - For any other date, the output will be something like `DD/MM/YYYY, HH:MM`
+ * @returns A random number between the provided lower bound and upper bound.
  */
-declare function formatDateAndTime(inputDate: Date): string;
+declare function getRandomNumber(lowerBound: number, upperBound: number): number;
 //#endregion
-//#region src/functions/date/isAnniversary.d.ts
+//#region src/functions/miscellaneous/isOrdered.d.ts
 /**
- * Checks if the provided dates are exactly a whole number of years apart.
+ * Checks to see if the given array is sorted in ascending order.
  *
- * @param firstDate - The first date to compare.
- * @param secondDate - The second date to compare.
+ * @param array - The array to check.
  *
- * @returns True if the provided dates are exactly a whole number of years apart, and false otherwise.
+ * @returns `true` if the array is sorted in ascending order, and `false` otherwise.
  */
-declare function isAnniversary(firstDate: Date, secondDate: Date): boolean;
+declare function isOrdered(array: readonly number[]): boolean;
 //#endregion
-//#region src/functions/date/isLeapYear.d.ts
+//#region src/functions/miscellaneous/stringListToArray.d.ts
+interface StringListToArrayOptions {
+  /** What each item in the list is separated by. */
+  separator?: string;
+  /** An option to trim any extra whitespace. */
+  trimWhitespace?: boolean;
+}
 /**
- * Checks if the provided year is a leap year.
- *
- * @param year - The year to check as a number.
+ * Converts a stringly-typed list to a proper array.
  *
- * @throws {TypeError} If the year provided is not an integer.
+ * @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.
+ * @param options.trimWhitespace - An option to trim any extra whitespace.
  *
- * @returns True if the year is a leap year, and false otherwise.
+ * @returns A new array with each item being an item from the given list.
  */
-declare function isLeapYear(year: number): boolean;
+declare function stringListToArray(stringList: string, {
+  separator,
+  trimWhitespace
+}?: StringListToArrayOptions): string[];
 //#endregion
-//#region src/functions/date/isMonthlyMultiple.d.ts
+//#region src/functions/miscellaneous/wait.d.ts
 /**
- * Checks if the provided dates are exactly a whole number of months apart.
+ * Waits for the given number of seconds
  *
- * @param firstDate - The first date to compare.
- * @param secondDate - The second date to compare.
+ * @param seconds - The number of seconds to wait.
  *
- * @returns True if the provided dates are exactly a whole number of months apart, and false otherwise.
+ * @returns A Promise that resolves after the given number of seconds.
  */
-declare function isMonthlyMultiple(firstDate: Date, secondDate: Date): boolean;
+declare function wait(seconds: number): Promise<void>;
 //#endregion
-//#region src/functions/date/isSameDate.d.ts
+//#region src/functions/objectHelpers/getRecordKeys.d.ts
 /**
- * Checks if the provided dates happen on the exact same day, month, and year.
+ * Gets the keys from a given record object, properly typed to be an array of the key of the input object's type.
  *
- * @param firstDate - The first date to compare.
- * @param secondDate - The second date to compare.
+ * @template InputRecordType - The type of the input object.
  *
- * @returns True if the provided dates occur on exactly the same day, month, and year, and returns false otherwise.
+ * @param record - The record to get the keys from.
+ *
+ * @returns An array with all the keys of the input object in string form, but properly typed as `keyof InputRecordType`.
  */
-declare function isSameDate(firstDate: Date, secondDate: Date): boolean;
-//#endregion
-//#region src/functions/deepCopy.d.ts
-declare function deepCopy<T extends object>(object: T): T;
-//#endregion
-//#region src/functions/deepFreeze.d.ts
-declare function deepFreeze<T extends object>(object: T): Readonly<T>;
-//#endregion
-//#region src/functions/getRandomNumber.d.ts
-declare function getRandomNumber(lowerBound: number, upperBound: number): number;
+declare function getRecordKeys<InputRecordType extends Record<RecordKey, unknown>>(record: InputRecordType & object): (keyof InputRecordType)[];
 //#endregion
-//#region src/functions/getRecordKeys.d.ts
-declare function getRecordKeys<T extends Record<RecordKey, unknown>>(record: T & object): (keyof T)[];
-//#endregion
-//#region src/functions/isOrdered.d.ts
-declare function isOrdered(array: readonly number[] | number[]): boolean;
-//#endregion
-//#region src/functions/kebabToCamel.d.ts
-interface KebabToCamelOptions {
-  startWithUpper?: boolean;
-}
-declare function kebabToCamel(string: string, options?: KebabToCamelOptions): string;
-//#endregion
-//#region src/functions/normalizeImportPath.d.ts
-declare function normalizeImportPath(importPath: string): string;
-declare const normaliseImportPath: typeof normalizeImportPath;
-//#endregion
-//#region src/functions/omitProperties.d.ts
-declare function omitProperties<T extends Record<string, unknown> | Readonly<Record<string, unknown>>, K$1 extends keyof T>(object: T, keysToOmit: K$1 | readonly K$1[]): Omit<T, K$1>;
+//#region src/functions/objectHelpers/omitProperties.d.ts
+/**
+ * Omits properties from a given object.
+ *
+ * @template ObjectType - The type of the input object.
+ * @template KeysToOmit - A type representing the keys to omit from the object.
+ *
+ * @param object - The object to omit properties from.
+ * @param keysToOmit - The keys to omit from the object. Can either be a single string to omit one, or an array to omit multiple.
+ *
+ * @returns An object with a new reference in memory, with the properties omitted.
+ */
+declare function omitProperties<ObjectType extends Record<string, unknown> | Readonly<Record<string, unknown>>, KeysToOmit extends keyof ObjectType>(object: ObjectType, keysToOmit: KeysToOmit | readonly KeysToOmit[]): Omit<ObjectType, KeysToOmit>;
 //#endregion
 //#region src/functions/parsers/parseBoolean.d.ts
+/**
+ * Takes a stringly-typed boolean and converts it to an actual boolean type.
+ *
+ * @param inputString - The string to parse.
+ *
+ * @throws {TypeError} If the string is not either `true` or `false` (case insensitive).
+ *
+ * @returns The string parsed as an actual boolean.
+ */
 declare function parseBoolean(inputString: string): boolean;
 /** @deprecated This function has been renamed to parseBoolean. */
 declare const stringToBoolean: typeof parseBoolean;
@@ -279,47 +420,268 @@ declare const envSchema: z$1.ZodEnum<{
   development: "development";
   production: "production";
 }>;
+/** Represents the most common development environments */
 type Env = z$1.infer<typeof envSchema>;
+/**
+ * Parses the input and verifies it matches one of the environments allowed by the Env types ("test" | "development" | "production").
+ *
+ * @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").
+ *
+ * @returns The specified environment if allowed.
+ */
 declare function parseEnv(data: unknown): Env;
 //#endregion
 //#region src/functions/parsers/parseFormData.d.ts
-declare function parseFormData<T>(formData: FormData, dataParser: (data: Record<string, string | Blob>) => T): T;
+/**
+ * Returns a parsed object given FormData and a data parser function to call on the resulting object.
+ *
+ * @template DataType - The type of the resulting object when called from the dataParser.
+ *
+ * @param formData - The FormData to parse.
+ * @param dataParser - A parser to call on the object before it gets returned.
+ *
+ * @returns A parsed object based on the contents of the input formData and the result of parsing with the data parser.
+ */
+declare function parseFormData<DataType>(formData: FormData, dataParser: (data: Record<string, string | Blob>) => DataType): DataType;
+/**
+ * Returns an object given FormData.
+ *
+ * @param formData - The FormData to parse.
+ *
+ * @returns An object based on the contents of the input formData.
+ */
 declare function parseFormData(formData: FormData): Record<string, string | Blob>;
 //#endregion
 //#region src/functions/parsers/parseIntStrict.d.ts
-declare function parseIntStrict(...[string, radix]: Parameters<typeof parseInt>): number;
+/**
+ * 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.
+ *
+ * @returns The integer parsed from the input string.
+ */
+declare function parseIntStrict(string: string, radix?: number): number;
 //#endregion
 //#region src/functions/parsers/parseZodSchema.d.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.
+ */
 declare function parseZodSchema<Output, Input, Internals extends core.$ZodTypeInternals<Output, Input>>(schema: ZodType<Output, Input, Internals>, data: unknown): core.output<ZodType<Output, Input, Internals>>;
 //#endregion
-//#region src/functions/removeDuplicates.d.ts
-declare function removeDuplicates<T>(array: T[] | readonly T[]): T[];
+//#region src/functions/recursive/deepCopy.d.ts
+/**
+ * Deeply copies an object or array such that all child objects/arrays are also copied.
+ *
+ * @template ObjectType - The type of the input object.
+ *
+ * @param object - The object to copy. May also be an array.
+ *
+ * @returns An identical object with a new reference in memory.
+ */
+declare function deepCopy<ObjectType extends object>(object: ObjectType): ObjectType;
 //#endregion
-//#region src/functions/stringListToArray.d.ts
-interface StringListToArrayOptions {
-  separator?: string;
-  trimWhitespace?: boolean;
+//#region src/functions/recursive/deepFreeze.d.ts
+/**
+ * Deeply freezes an object or array such that all child objects/arrays are also frozen.
+ *
+ * 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.
+ *
+ * @template ObjectType - The type of the input object.
+ *
+ * @param object - The object to freeze. May also be an array.
+ *
+ * @returns The input object completely frozen.
+ */
+declare function deepFreeze<ObjectType extends object>(object: ObjectType): Readonly<ObjectType>;
+//#endregion
+//#region src/functions/stringHelpers/appendSemicolon.d.ts
+/**
+ * Appends a semicolon to the end of a string, trimming where necessary first.
+ *
+ * @param stringToAppendTo - The string to append a semicolon to.
+ *
+ * @throws {Error} If the string contains multiple lines.
+ *
+ * @returns A string with the semicolon appended.
+ */
+declare function appendSemicolon(stringToAppendTo: string): string;
+//#endregion
+//#region src/functions/stringHelpers/camelToKebab.d.ts
+/**
+ * Converts a string from camelCase to kebab-case
+ *
+ * @param string - The string to convert.
+ *
+ * @returns The string converted to kebab-case.
+ */
+declare function camelToKebab(string: string): string;
+//#endregion
+//#region src/functions/stringHelpers/kebabToCamel.d.ts
+interface KebabToCamelOptions {
+  /** Whether or not the converted string should start with an uppercase (e.g. CamelCase instead of camelCase). */
+  startWithUpper?: boolean;
 }
-declare function stringListToArray(stringList: string, {
-  separator,
-  trimWhitespace
-}?: StringListToArrayOptions): string[];
+/**
+ * Converts a string from kebab-case to camelCase
+ *
+ * @param string - The string to convert.
+ * @param options - Options to apply to the conversion.
+ *
+ * @returns The string converted to camelCase.
+ */
+declare function kebabToCamel(string: string, options?: KebabToCamelOptions): string;
+//#endregion
+//#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.
+ *
+ * @param importPath - The import path to normalize.
+ *
+ * @returns The import path normalized.
+ */
+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.
+ *
+ * @param importPath - The import path to normalise.
+ *
+ * @returns The import path normalised.
+ */
+declare const normaliseImportPath: typeof normalizeImportPath;
+//#endregion
+//#region src/functions/stringHelpers/truncate.d.ts
+/**
+ * Truncates a string and appends `...` to the end of it
+ *
+ * @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.
+ *
+ * @returns A new string that has been truncated based on the length provided.
+ */
+declare function truncate(stringToTruncate: string, maxLength?: number): string;
+//#endregion
+//#region src/functions/taggedTemplate/createTemplateStringsArray.d.ts
+/**
+ * Creates a template strings array given a regular array of strings
+ *
+ * @param strings - The array of strings.
+ *
+ * @returns A template strings array that can be passed as the first argument of any tagged template function.
+ */
+declare function createTemplateStringsArray(strings: readonly string[]): TemplateStringsArray;
 //#endregion
 //#region src/functions/taggedTemplate/interpolate.d.ts
+/**
+ * Returns the result of interpolating a template string when given the strings and interpolations separately.
+ *
+ * You can pass a template string directly by doing:
+ *
+ *      interpolate`Template string here`.
+ *
+ * In this case, it will be functionally the same as if you just wrote the template string by itself.
+ *
+ * @param strings - The strings from the template to process.
+ * @param interpolations - An array of all interpolations from the template.
+ *
+ * @returns A new string with the strings and interpolations from the template applied.
+ */
 declare function interpolate(strings: TemplateStringsArray, ...interpolations: unknown[]): string;
 //#endregion
 //#region src/functions/taggedTemplate/interpolateObjects.d.ts
-declare function interpolateObjects(strings: TemplateStringsArray, ...values: unknown[]): string;
+/**
+ * Returns the result of interpolating a template string, also stringifying objects.
+ *
+ * You can pass a template string directly by doing:
+ *
+ *      interpolateObjects`Template string here ${{ my: "object" }}`.
+ *
+ * @param strings - The strings from the template to process.
+ * @param interpolations - An array of all interpolations from the template.
+ *
+ * @returns A new string with the strings and interpolations from the template applied, with objects stringified.
+ */
+declare function interpolateObjects(strings: TemplateStringsArray, ...interpolations: unknown[]): string;
 //#endregion
 //#region src/functions/taggedTemplate/normaliseIndents.d.ts
 interface NormaliseIndentsOptions {
+  /** Whether to preserve extra tabs or not (defaults to true) */
   preserveTabs?: boolean;
 }
 type NormalizeIndentsOptions = NormaliseIndentsOptions;
 type NormaliseIndentsFunction = (strings: TemplateStringsArray, ...interpolations: unknown[]) => string;
 type NormalizeIndentsFunction = NormaliseIndentsFunction;
+/**
+ * Provides a new function that removes any extraneous indents from a multi-line template string, with the given options applied.
+ *
+ * @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.
+ */
 declare function normaliseIndents(options: NormaliseIndentsOptions): NormaliseIndentsFunction;
+/**
+ * Removes any extraneous indents from a multi-line template string.
+ *
+ * You can pass a template string directly by doing:
+ *
+ *      normaliseIndents`Template string here
+ *          with a new line
+ *          and another new line`.
+ *
+ * @param strings - The strings from the template to process.
+ * @param interpolations - An array of all interpolations from the template.
+ *
+ * @returns A new string with the strings and interpolations from the template applied, and extraneous indents removed.
+ */
 declare function normaliseIndents(strings: TemplateStringsArray, ...interpolations: unknown[]): string;
+/**
+ * Applies any options if provided, then removes any extraneous indents from a multi-line template string.
+ *
+ * You can pass a template string directly by doing:
+ *
+ *      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`.
+ *
+ * @param first - The strings from the template to process, or the options to apply.
+ * @param args - An array of all interpolations from the template.
+ *
+ * @returns An additional function to invoke, or a new string with the strings and interpolations from the template applied, and extraneous indents removed.
+ */
 declare const normalizeIndents: typeof normaliseIndents;
 //#endregion
 //#region src/functions/taggedTemplate/removeIndents.d.ts
@@ -339,10 +701,43 @@ declare function removeIndents(options: RemoveIndentsOptions): RemoveIndentsFunc
  */
 declare function removeIndents(strings: TemplateStringsArray, ...interpolations: unknown[]): string;
 //#endregion
-//#region src/functions/truncate.d.ts
-declare function truncate(stringToTruncate: string, maxLength?: number): string;
+//#region src/functions/versioning/determineVersionType.d.ts
+type VersionType = "major" | "minor" | "patch";
+/**
+ * Determines whether the given version is a major, minor, or patch version.
+ *
+ * @param version - The version number.
+ *
+ * @returns Either `"major"`, `"minor"`, or `"patch"`, depending on the version type.
+ */
+declare function determineVersionType(version: string): VersionType;
 //#endregion
-//#region src/functions/wait.d.ts
-declare function wait(seconds: number): Promise<void>;
+//#region src/functions/versioning/getIndividualVersionNumbers.d.ts
+/**
+ * Gets the individual version numbers from a given version number as a tuple of numbers.
+ *
+ * @param version - The version number.
+ *
+ * @returns A tuple of three numbers indicating `[major, minor, patch]`.
+ */
+declare function getIndividualVersionNumbers(version: string): [number, number, number];
+//#endregion
+//#region src/functions/versioning/parseVersion.d.ts
+interface ParseVersionOptions {
+  omitPrefix?: boolean;
+}
+/**
+ * Parses a string and verifies it is a valid package version number.
+ *
+ * Valid formats: `X.Y.Z` or `vX.Y.Z`, where X, Y, and Z are non-negative integers.
+ *
+ * @param input - The version string to parse.
+ * @param options - Extra options to apply.
+ *
+ * @throws {DataError} If the input is not a valid version number.
+ *
+ * @returns The validated version number, prefixed with `v` if it was not already.
+ */
+declare function parseVersion(input: string, options?: ParseVersionOptions): string;
 //#endregion
-export { APIError, ArrayElement, CreateFormDataOptions, CreateFormDataOptionsNullableResolution, CreateFormDataOptionsUndefinedOrNullResolution, DataError, DeepReadonly, DisallowUndefined, Email, Env, FormDataArrayResolutionStrategy, FormDataNullableResolutionStrategy, HTTPErrorCode, IgnoreCase, KebabToCamelOptions, NAMESPACE_EXPORT_REGEX, NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, OptionalOnCondition, RecordKey, RemoveIndentsFunction, RemoveIndentsOptions, StringListToArrayOptions, UUID, addDaysToDate, appendSemicolon, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, kebabToCamel, normaliseImportPath, normaliseIndents, normalizeImportPath, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEmail, parseEnv, parseFormData, parseIntStrict, parseUUID, parseZodSchema, randomiseArray, range, removeDuplicates, removeIndents, stringListToArray, stringToBoolean, truncate, wait };
+export { APIError, ArrayElement, CreateFormDataOptions, CreateFormDataOptionsNullableResolution, CreateFormDataOptionsUndefinedOrNullResolution, DataError, DeepReadonly, DisallowUndefined, Email, Env, FormDataArrayResolutionStrategy, FormDataNullableResolutionStrategy, HTTPErrorCode, IgnoreCase, KebabToCamelOptions, NAMESPACE_EXPORT_REGEX, NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, OptionalOnCondition, RecordKey, RemoveIndentsFunction, RemoveIndentsOptions, StringListToArrayOptions, UUID, VERSION_NUMBER_REGEX, VersionType, addDaysToDate, appendSemicolon, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, determineVersionType, fillArray, formatDateAndTime, getIndividualVersionNumbers, getRandomNumber, getRecordKeys, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, kebabToCamel, normaliseImportPath, normaliseIndents, normalizeImportPath, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEmail, parseEnv, parseFormData, parseIntStrict, parseUUID, parseVersion, parseZodSchema, randomiseArray, range, removeDuplicates, removeIndents, stringListToArray, stringToBoolean, truncate, wait };