@alextheman/utility 3.6.0 → 3.8.0

package/dist/index.d.ts

@@ -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, type ArrayElement, type CreateFormDataOptions, type CreateFormDataOptionsNullableResolution, type CreateFormDataOptionsUndefinedOrNullResolution, DataError, type DeepReadonly, type DisallowUndefined, type Email, type Env, type FormDataArrayResolutionStrategy, type FormDataNullableResolutionStrategy, type HTTPErrorCode, type IgnoreCase, type KebabToCamelOptions, NAMESPACE_EXPORT_REGEX, type NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, type OptionalOnCondition, type RecordKey, RemoveIndentsFunction, RemoveIndentsOptions, type StringListToArrayOptions, type 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, type ArrayElement, type CreateFormDataOptions, type CreateFormDataOptionsNullableResolution, type CreateFormDataOptionsUndefinedOrNullResolution, DataError, type DeepReadonly, type DisallowUndefined, type Email, type Env, type FormDataArrayResolutionStrategy, type FormDataNullableResolutionStrategy, type HTTPErrorCode, type IgnoreCase, KebabToCamelOptions, NAMESPACE_EXPORT_REGEX, type NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, type OptionalOnCondition, type RecordKey, RemoveIndentsFunction, RemoveIndentsOptions, type StringListToArrayOptions, type 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 };