@alextheman/utility 5.20.0 → 5.21.0

package/dist/index.cjs

@@ -827,6 +827,20 @@ function createFormData(data, options = {
 	return formData;
 }
 //#endregion
+//#region src/root/functions/miscellaneous/identity.ts
+/**
+* Gives back the original input.
+*
+* @template InputType - The input type.
+*
+* @param input - The input value.
+*
+* @returns The original input value.
+*/
+function identity(input) {
+	return input;
+}
+//#endregion
 //#region src/root/functions/miscellaneous/isOrdered.ts
 /**
 * Checks to see if the given array is sorted in ascending order.
@@ -957,6 +971,33 @@ I'll commit to you!
     `;
 }
 //#endregion
+//#region src/root/functions/miscellaneous/sortBy.ts
+/**
+* Provides a function to pass to the `sort` or `toSorted` methods on arrays, which will allow those methods to sort the items by the chosen value in the chosen direction.
+*
+* @template ItemType - The type of each array item.
+* @template SortValue - The type of the value to sort by.
+*
+* @param selector - A function that takes the item and returns the value to sort by.
+* @param direction - The sort direction.
+*
+* @returns A function to pass into the `.sort()` or `.toSorted()` methods on arrays.
+*/
+function sortBy(selector, direction = "asc") {
+	return (first, second) => {
+		const firstValue = selector(first);
+		const secondValue = selector(second);
+		if (firstValue instanceof Date && secondValue instanceof Date) {
+			const firstTime = firstValue.getTime();
+			const secondTime = secondValue.getTime();
+			return direction === "asc" ? firstTime - secondTime : secondTime - firstTime;
+		}
+		if (firstValue < secondValue) return direction === "asc" ? -1 : 1;
+		if (firstValue > secondValue) return direction === "asc" ? 1 : -1;
+		return 0;
+	};
+}
+//#endregion
 //#region src/root/functions/miscellaneous/stringifyDotenv.ts
 /**
 * Converts an object into a string in .env file format.
@@ -1101,6 +1142,12 @@ function parseBoolean(inputString) {
 	return normalisedString === "true";
 }
 //#endregion
+//#region src/root/types/SortDirection.ts
+const SortDirection = {
+	DESC: "desc",
+	ASC: "asc"
+};
+//#endregion
 //#region src/root/types/VersionNumber.ts
 /**
 * Represents a software version number, considered to be made up of a major, minor, and patch part.
@@ -1966,6 +2013,7 @@ exports.Env = Env;
 exports.FILE_PATH_PATTERN = FILE_PATH_PATTERN;
 exports.FILE_PATH_REGEX = FILE_PATH_REGEX;
 exports.ONE_DAY_IN_MILLISECONDS = ONE_DAY_IN_MILLISECONDS;
+exports.SortDirection = SortDirection;
 exports.UUID_PATTERN = UUID_PATTERN;
 exports.UUID_REGEX = UUID_REGEX;
 exports.VERSION_NUMBER_PATTERN = VERSION_NUMBER_PATTERN;
@@ -1993,6 +2041,7 @@ exports.getRandomNumber = getRandomNumber;
 exports.getRecordKeys = getRecordKeys;
 exports.getStringsAndInterpolations = getStringsAndInterpolations;
 exports.httpErrorCodeLookup = httpErrorCodeLookup;
+exports.identity = identity;
 exports.interpolate = interpolate;
 exports.interpolateObjects = interpolateObjects;
 exports.isAnniversary = isAnniversary;
@@ -2021,6 +2070,7 @@ exports.range = range;
 exports.removeDuplicates = removeDuplicates;
 exports.removeUndefinedFromObject = removeUndefinedFromObject;
 exports.sayHello = sayHello;
+exports.sortBy = sortBy;
 exports.stringListToArray = stringListToArray;
 exports.stringifyDotenv = stringifyDotenv;
 exports.toTitleCase = toTitleCase;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { DotenvParseOutput } from "dotenv";
 import z, { ZodCoercedDate, ZodCoercedNumber, ZodError, ZodType, z as z$1 } from "zod";
+import { DotenvParseOutput } from "dotenv";
 
 //#region src/root/constants/FILE_PATH_REGEX.d.ts
 declare const FILE_PATH_PATTERN: string;
@@ -402,6 +402,18 @@ declare function createFormData<DataType extends Record<PropertyKey, unknown>>(d
  */
 declare function getRandomNumber(lowerBound: number, upperBound: number): number;
 //#endregion
+//#region src/root/functions/miscellaneous/identity.d.ts
+/**
+ * Gives back the original input.
+ *
+ * @template InputType - The input type.
+ *
+ * @param input - The input value.
+ *
+ * @returns The original input value.
+ */
+declare function identity<InputType>(input: InputType): InputType;
+//#endregion
 //#region src/root/functions/miscellaneous/isOrdered.d.ts
 /**
  * Checks to see if the given array is sorted in ascending order.
@@ -424,117 +436,22 @@ declare function isOrdered(array: ReadonlyArray<number>): boolean;
  */
 declare function sayHello(): string;
 //#endregion
-//#region src/root/functions/miscellaneous/stringifyDotenv.d.ts
-type QuoteStyle = "double" | "single" | "none";
-interface StringifyDotenvOptions {
-  /** The quote style to use for the values (defaults to `"double"`) */
-  quoteStyle: QuoteStyle;
-}
-/**
- * Converts an object into a string in .env file format.
- *
- * @param contents - The object to convert. Must be a record whose values are strings.
- * @param options - Extra options to apply.
- *
- * @returns A string representation of the object in .env file format.
- */
-declare function stringifyDotenv(contents: Record<PropertyKey, string> | DotenvParseOutput, options?: StringifyDotenvOptions): string;
-//#endregion
-//#region src/root/functions/miscellaneous/stringListToArray.d.ts
-/**
- * Options to apply to the conversion of a string list to an array.
- *
- * @category Function Options
- */
-interface StringListToArrayOptions {
-  /** What each item in the list is separated by. */
-  separator?: string;
-  /** An option to trim any extra whitespace. */
-  trimWhitespace?: boolean;
-}
-/**
- * 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.
- * @param options.trimWhitespace - An option to trim any extra whitespace.
- *
- * @returns A new array with each item being an item from the given list.
- */
-declare function stringListToArray(stringList: string, {
-  separator,
-  trimWhitespace
-}?: StringListToArrayOptions): Array<string>;
-//#endregion
-//#region src/root/functions/miscellaneous/wait.d.ts
-/**
- * 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.
- */
-declare function wait(seconds: number): Promise<void>;
-//#endregion
-//#region src/root/functions/objectHelpers/getRecordKeys.d.ts
-/**
- * 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.
- *
- * @returns An array with all the keys of the input object in string form, but properly typed as `keyof InputRecordType`.
- */
-declare function getRecordKeys<InputRecordType extends Record<PropertyKey, unknown>>(record: InputRecordType & object): Array<keyof InputRecordType>;
-//#endregion
-//#region src/root/functions/objectHelpers/omitProperties.d.ts
-/**
- * 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.
- *
- * @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 object, KeysToOmit extends keyof ObjectType>(object: ObjectType, keysToOmit: KeysToOmit | ReadonlyArray<KeysToOmit>): Omit<ObjectType, KeysToOmit>;
-//#endregion
-//#region src/root/functions/objectHelpers/removeUndefinedFromObject.d.ts
-type RemoveUndefined<RecordType extends Record<PropertyKey, unknown>> = { [Key in keyof RecordType]: Exclude<RecordType[Key], undefined> };
+//#region src/root/types/CreateEnumType.d.ts
 /**
- * Removes entries whose values are `undefined` from a given object (not including null etc.).
+ * Get the value types from a const object so the object can behave similarly to an enum.
  *
- * @param object - The object to remove undefined entries from.
+ * @category Types
  *
- * @returns An object with a new reference in memory, with undefined entries removed.
+ * @template ObjectType - The type of the object to get the value types for.
  */
-declare function removeUndefinedFromObject<RecordType extends Record<PropertyKey, unknown>>(object: RecordType): RemoveUndefined<RecordType>;
+type CreateEnumType<ObjectType extends Record<PropertyKey, unknown>> = ObjectType[keyof ObjectType];
 //#endregion
-//#region src/root/functions/parsers/parseBoolean.d.ts
-/**
- * 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).
- *
- * @returns The string parsed as an actual boolean.
- */
-declare function parseBoolean(inputString: string): boolean;
+//#region src/root/types/SortDirection.d.ts
+declare const SortDirection: {
+  readonly DESC: "desc";
+  readonly ASC: "asc";
+};
+type SortDirection = CreateEnumType<typeof SortDirection>;
 //#endregion
 //#region src/root/types/VersionNumber.d.ts
 /**
@@ -648,16 +565,6 @@ type ArrayElement<ArrayType extends ReadonlyArray<unknown>> = ArrayType extends
 //#region src/root/types/CallReturnType.d.ts
 type CallReturnType<Function, Arguments> = Function extends ((arg: Arguments) => infer Return) ? Return : never;
 //#endregion
-//#region src/root/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<PropertyKey, unknown>> = ObjectType[keyof ObjectType];
-//#endregion
 //#region src/root/types/DisallowUndefined.d.ts
 /**
  * Resolves to an error message type if the type argument could potentially be undefined.
@@ -723,6 +630,133 @@ type NullableOnCondition<Condition extends boolean, ResolvedTypeIfTrue> = Condit
  */
 type OptionalOnCondition<Condition extends boolean, ResolvedTypeIfTrue> = Condition extends true ? ResolvedTypeIfTrue : ResolvedTypeIfTrue | undefined;
 //#endregion
+//#region src/root/functions/miscellaneous/sortBy.d.ts
+type SortFunction<ItemType> = (first: ItemType, second: ItemType) => number;
+/**
+ * Provides a function to pass to the `sort` or `toSorted` methods on arrays, which will allow those methods to sort the items by the chosen value in the chosen direction.
+ *
+ * @template ItemType - The type of each array item.
+ * @template SortValue - The type of the value to sort by.
+ *
+ * @param selector - A function that takes the item and returns the value to sort by.
+ * @param direction - The sort direction.
+ *
+ * @returns A function to pass into the `.sort()` or `.toSorted()` methods on arrays.
+ */
+declare function sortBy<ItemType, SortValue extends string | number | Date>(selector: (item: ItemType) => SortValue, direction?: SortDirection): SortFunction<ItemType>;
+//#endregion
+//#region src/root/functions/miscellaneous/stringifyDotenv.d.ts
+type QuoteStyle = "double" | "single" | "none";
+interface StringifyDotenvOptions {
+  /** The quote style to use for the values (defaults to `"double"`) */
+  quoteStyle: QuoteStyle;
+}
+/**
+ * Converts an object into a string in .env file format.
+ *
+ * @param contents - The object to convert. Must be a record whose values are strings.
+ * @param options - Extra options to apply.
+ *
+ * @returns A string representation of the object in .env file format.
+ */
+declare function stringifyDotenv(contents: Record<PropertyKey, string> | DotenvParseOutput, options?: StringifyDotenvOptions): string;
+//#endregion
+//#region src/root/functions/miscellaneous/stringListToArray.d.ts
+/**
+ * Options to apply to the conversion of a string list to an array.
+ *
+ * @category Function Options
+ */
+interface StringListToArrayOptions {
+  /** What each item in the list is separated by. */
+  separator?: string;
+  /** An option to trim any extra whitespace. */
+  trimWhitespace?: boolean;
+}
+/**
+ * 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.
+ * @param options.trimWhitespace - An option to trim any extra whitespace.
+ *
+ * @returns A new array with each item being an item from the given list.
+ */
+declare function stringListToArray(stringList: string, {
+  separator,
+  trimWhitespace
+}?: StringListToArrayOptions): Array<string>;
+//#endregion
+//#region src/root/functions/miscellaneous/wait.d.ts
+/**
+ * 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.
+ */
+declare function wait(seconds: number): Promise<void>;
+//#endregion
+//#region src/root/functions/objectHelpers/getRecordKeys.d.ts
+/**
+ * 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.
+ *
+ * @returns An array with all the keys of the input object in string form, but properly typed as `keyof InputRecordType`.
+ */
+declare function getRecordKeys<InputRecordType extends Record<PropertyKey, unknown>>(record: InputRecordType & object): Array<keyof InputRecordType>;
+//#endregion
+//#region src/root/functions/objectHelpers/omitProperties.d.ts
+/**
+ * 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.
+ *
+ * @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 object, KeysToOmit extends keyof ObjectType>(object: ObjectType, keysToOmit: KeysToOmit | ReadonlyArray<KeysToOmit>): Omit<ObjectType, KeysToOmit>;
+//#endregion
+//#region src/root/functions/objectHelpers/removeUndefinedFromObject.d.ts
+type RemoveUndefined<RecordType extends Record<PropertyKey, unknown>> = { [Key in keyof RecordType]: Exclude<RecordType[Key], undefined> };
+/**
+ * Removes entries whose values are `undefined` from a given object (not including null etc.).
+ *
+ * @param object - The object to remove undefined entries from.
+ *
+ * @returns An object with a new reference in memory, with undefined entries removed.
+ */
+declare function removeUndefinedFromObject<RecordType extends Record<PropertyKey, unknown>>(object: RecordType): RemoveUndefined<RecordType>;
+//#endregion
+//#region src/root/functions/parsers/parseBoolean.d.ts
+/**
+ * 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).
+ *
+ * @returns The string parsed as an actual boolean.
+ */
+declare function parseBoolean(inputString: string): boolean;
+//#endregion
 //#region src/root/functions/parsers/parseEnv.d.ts
 /**
  * Represents the three common development environments.
@@ -1423,4 +1457,4 @@ interface ZodParsingErrorData {
   issues: Array<z.core.$ZodIssue>;
 }
 //#endregion
-export { APIError, type ArrayElement, type CallReturnType, type CamelToKebabOptions, type CreateEnumType, type CreateFormDataOptions, type CreateFormDataOptionsNullableResolution, type CreateFormDataOptionsUndefinedOrNullResolution, DataError, type DisallowUndefined, Env, FILE_PATH_PATTERN, FILE_PATH_REGEX, type FormDataArrayResolutionStrategy, type FormDataNullableResolutionStrategy, type HTTPErrorCode, type IgnoreCase, type IsTypeArgumentString, type KebabToCamelOptions, type NonNull, type NonUndefined, type NormaliseIndentsFunction, type NormaliseIndentsOptions, type NormalizeIndentsFunction, type NormalizeIndentsOptions, type NullableOnCondition, ONE_DAY_IN_MILLISECONDS, type OptionalOnCondition, type ParallelTuple, type RecordKey, type RemoveUndefined, type StringListToArrayOptions, type ToTitleCaseOptions, UUID_PATTERN, UUID_REGEX, VERSION_NUMBER_PATTERN, VERSION_NUMBER_REGEX, VersionNumber, type FormatOptionsBase as VersionNumberToStringOptions, VersionType, type ZodParsingErrorData, addDaysToDate, appendSemicolon, assertNotNull, assertNotNullable, assertNotUndefined, az, calculateMonthlyDifference, camelToKebab, containsKeys, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, escapeRegexPattern, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, getStringsAndInterpolations, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isNonNullableObject, isOrdered, isSameDate, isTemplateStringsArray, kebabToCamel, normaliseIndents, normalizeIndents, objectContainsKeys, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseUUID, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, sayHello, stringListToArray, stringifyDotenv, toTitleCase, truncate, wait, zodVersionNumber };
+export { APIError, type ArrayElement, type CallReturnType, type CamelToKebabOptions, type CreateEnumType, type CreateFormDataOptions, type CreateFormDataOptionsNullableResolution, type CreateFormDataOptionsUndefinedOrNullResolution, DataError, type DisallowUndefined, Env, FILE_PATH_PATTERN, FILE_PATH_REGEX, type FormDataArrayResolutionStrategy, type FormDataNullableResolutionStrategy, type HTTPErrorCode, type IgnoreCase, type IsTypeArgumentString, type KebabToCamelOptions, type NonNull, type NonUndefined, type NormaliseIndentsFunction, type NormaliseIndentsOptions, type NormalizeIndentsFunction, type NormalizeIndentsOptions, type NullableOnCondition, ONE_DAY_IN_MILLISECONDS, type OptionalOnCondition, type ParallelTuple, type RecordKey, type RemoveUndefined, SortDirection, type StringListToArrayOptions, type ToTitleCaseOptions, UUID_PATTERN, UUID_REGEX, VERSION_NUMBER_PATTERN, VERSION_NUMBER_REGEX, VersionNumber, type FormatOptionsBase as VersionNumberToStringOptions, VersionType, type ZodParsingErrorData, addDaysToDate, appendSemicolon, assertNotNull, assertNotNullable, assertNotUndefined, az, calculateMonthlyDifference, camelToKebab, containsKeys, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, escapeRegexPattern, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, getStringsAndInterpolations, httpErrorCodeLookup, identity, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isNonNullableObject, isOrdered, isSameDate, isTemplateStringsArray, kebabToCamel, normaliseIndents, normalizeIndents, objectContainsKeys, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseUUID, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, sayHello, sortBy, stringListToArray, stringifyDotenv, toTitleCase, truncate, wait, zodVersionNumber };

package/dist/index.d.ts

@@ -402,6 +402,18 @@ declare function createFormData<DataType extends Record<PropertyKey, unknown>>(d
  */
 declare function getRandomNumber(lowerBound: number, upperBound: number): number;
 //#endregion
+//#region src/root/functions/miscellaneous/identity.d.ts
+/**
+ * Gives back the original input.
+ *
+ * @template InputType - The input type.
+ *
+ * @param input - The input value.
+ *
+ * @returns The original input value.
+ */
+declare function identity<InputType>(input: InputType): InputType;
+//#endregion
 //#region src/root/functions/miscellaneous/isOrdered.d.ts
 /**
  * Checks to see if the given array is sorted in ascending order.
@@ -424,117 +436,22 @@ declare function isOrdered(array: ReadonlyArray<number>): boolean;
  */
 declare function sayHello(): string;
 //#endregion
-//#region src/root/functions/miscellaneous/stringifyDotenv.d.ts
-type QuoteStyle = "double" | "single" | "none";
-interface StringifyDotenvOptions {
-  /** The quote style to use for the values (defaults to `"double"`) */
-  quoteStyle: QuoteStyle;
-}
-/**
- * Converts an object into a string in .env file format.
- *
- * @param contents - The object to convert. Must be a record whose values are strings.
- * @param options - Extra options to apply.
- *
- * @returns A string representation of the object in .env file format.
- */
-declare function stringifyDotenv(contents: Record<PropertyKey, string> | DotenvParseOutput, options?: StringifyDotenvOptions): string;
-//#endregion
-//#region src/root/functions/miscellaneous/stringListToArray.d.ts
-/**
- * Options to apply to the conversion of a string list to an array.
- *
- * @category Function Options
- */
-interface StringListToArrayOptions {
-  /** What each item in the list is separated by. */
-  separator?: string;
-  /** An option to trim any extra whitespace. */
-  trimWhitespace?: boolean;
-}
-/**
- * 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.
- * @param options.trimWhitespace - An option to trim any extra whitespace.
- *
- * @returns A new array with each item being an item from the given list.
- */
-declare function stringListToArray(stringList: string, {
-  separator,
-  trimWhitespace
-}?: StringListToArrayOptions): Array<string>;
-//#endregion
-//#region src/root/functions/miscellaneous/wait.d.ts
-/**
- * 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.
- */
-declare function wait(seconds: number): Promise<void>;
-//#endregion
-//#region src/root/functions/objectHelpers/getRecordKeys.d.ts
-/**
- * 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.
- *
- * @returns An array with all the keys of the input object in string form, but properly typed as `keyof InputRecordType`.
- */
-declare function getRecordKeys<InputRecordType extends Record<PropertyKey, unknown>>(record: InputRecordType & object): Array<keyof InputRecordType>;
-//#endregion
-//#region src/root/functions/objectHelpers/omitProperties.d.ts
-/**
- * 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.
- *
- * @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 object, KeysToOmit extends keyof ObjectType>(object: ObjectType, keysToOmit: KeysToOmit | ReadonlyArray<KeysToOmit>): Omit<ObjectType, KeysToOmit>;
-//#endregion
-//#region src/root/functions/objectHelpers/removeUndefinedFromObject.d.ts
-type RemoveUndefined<RecordType extends Record<PropertyKey, unknown>> = { [Key in keyof RecordType]: Exclude<RecordType[Key], undefined> };
+//#region src/root/types/CreateEnumType.d.ts
 /**
- * Removes entries whose values are `undefined` from a given object (not including null etc.).
+ * Get the value types from a const object so the object can behave similarly to an enum.
  *
- * @param object - The object to remove undefined entries from.
+ * @category Types
  *
- * @returns An object with a new reference in memory, with undefined entries removed.
+ * @template ObjectType - The type of the object to get the value types for.
  */
-declare function removeUndefinedFromObject<RecordType extends Record<PropertyKey, unknown>>(object: RecordType): RemoveUndefined<RecordType>;
+type CreateEnumType<ObjectType extends Record<PropertyKey, unknown>> = ObjectType[keyof ObjectType];
 //#endregion
-//#region src/root/functions/parsers/parseBoolean.d.ts
-/**
- * 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).
- *
- * @returns The string parsed as an actual boolean.
- */
-declare function parseBoolean(inputString: string): boolean;
+//#region src/root/types/SortDirection.d.ts
+declare const SortDirection: {
+  readonly DESC: "desc";
+  readonly ASC: "asc";
+};
+type SortDirection = CreateEnumType<typeof SortDirection>;
 //#endregion
 //#region src/root/types/VersionNumber.d.ts
 /**
@@ -648,16 +565,6 @@ type ArrayElement<ArrayType extends ReadonlyArray<unknown>> = ArrayType extends
 //#region src/root/types/CallReturnType.d.ts
 type CallReturnType<Function, Arguments> = Function extends ((arg: Arguments) => infer Return) ? Return : never;
 //#endregion
-//#region src/root/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<PropertyKey, unknown>> = ObjectType[keyof ObjectType];
-//#endregion
 //#region src/root/types/DisallowUndefined.d.ts
 /**
  * Resolves to an error message type if the type argument could potentially be undefined.
@@ -723,6 +630,133 @@ type NullableOnCondition<Condition extends boolean, ResolvedTypeIfTrue> = Condit
  */
 type OptionalOnCondition<Condition extends boolean, ResolvedTypeIfTrue> = Condition extends true ? ResolvedTypeIfTrue : ResolvedTypeIfTrue | undefined;
 //#endregion
+//#region src/root/functions/miscellaneous/sortBy.d.ts
+type SortFunction<ItemType> = (first: ItemType, second: ItemType) => number;
+/**
+ * Provides a function to pass to the `sort` or `toSorted` methods on arrays, which will allow those methods to sort the items by the chosen value in the chosen direction.
+ *
+ * @template ItemType - The type of each array item.
+ * @template SortValue - The type of the value to sort by.
+ *
+ * @param selector - A function that takes the item and returns the value to sort by.
+ * @param direction - The sort direction.
+ *
+ * @returns A function to pass into the `.sort()` or `.toSorted()` methods on arrays.
+ */
+declare function sortBy<ItemType, SortValue extends string | number | Date>(selector: (item: ItemType) => SortValue, direction?: SortDirection): SortFunction<ItemType>;
+//#endregion
+//#region src/root/functions/miscellaneous/stringifyDotenv.d.ts
+type QuoteStyle = "double" | "single" | "none";
+interface StringifyDotenvOptions {
+  /** The quote style to use for the values (defaults to `"double"`) */
+  quoteStyle: QuoteStyle;
+}
+/**
+ * Converts an object into a string in .env file format.
+ *
+ * @param contents - The object to convert. Must be a record whose values are strings.
+ * @param options - Extra options to apply.
+ *
+ * @returns A string representation of the object in .env file format.
+ */
+declare function stringifyDotenv(contents: Record<PropertyKey, string> | DotenvParseOutput, options?: StringifyDotenvOptions): string;
+//#endregion
+//#region src/root/functions/miscellaneous/stringListToArray.d.ts
+/**
+ * Options to apply to the conversion of a string list to an array.
+ *
+ * @category Function Options
+ */
+interface StringListToArrayOptions {
+  /** What each item in the list is separated by. */
+  separator?: string;
+  /** An option to trim any extra whitespace. */
+  trimWhitespace?: boolean;
+}
+/**
+ * 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.
+ * @param options.trimWhitespace - An option to trim any extra whitespace.
+ *
+ * @returns A new array with each item being an item from the given list.
+ */
+declare function stringListToArray(stringList: string, {
+  separator,
+  trimWhitespace
+}?: StringListToArrayOptions): Array<string>;
+//#endregion
+//#region src/root/functions/miscellaneous/wait.d.ts
+/**
+ * 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.
+ */
+declare function wait(seconds: number): Promise<void>;
+//#endregion
+//#region src/root/functions/objectHelpers/getRecordKeys.d.ts
+/**
+ * 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.
+ *
+ * @returns An array with all the keys of the input object in string form, but properly typed as `keyof InputRecordType`.
+ */
+declare function getRecordKeys<InputRecordType extends Record<PropertyKey, unknown>>(record: InputRecordType & object): Array<keyof InputRecordType>;
+//#endregion
+//#region src/root/functions/objectHelpers/omitProperties.d.ts
+/**
+ * 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.
+ *
+ * @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 object, KeysToOmit extends keyof ObjectType>(object: ObjectType, keysToOmit: KeysToOmit | ReadonlyArray<KeysToOmit>): Omit<ObjectType, KeysToOmit>;
+//#endregion
+//#region src/root/functions/objectHelpers/removeUndefinedFromObject.d.ts
+type RemoveUndefined<RecordType extends Record<PropertyKey, unknown>> = { [Key in keyof RecordType]: Exclude<RecordType[Key], undefined> };
+/**
+ * Removes entries whose values are `undefined` from a given object (not including null etc.).
+ *
+ * @param object - The object to remove undefined entries from.
+ *
+ * @returns An object with a new reference in memory, with undefined entries removed.
+ */
+declare function removeUndefinedFromObject<RecordType extends Record<PropertyKey, unknown>>(object: RecordType): RemoveUndefined<RecordType>;
+//#endregion
+//#region src/root/functions/parsers/parseBoolean.d.ts
+/**
+ * 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).
+ *
+ * @returns The string parsed as an actual boolean.
+ */
+declare function parseBoolean(inputString: string): boolean;
+//#endregion
 //#region src/root/functions/parsers/parseEnv.d.ts
 /**
  * Represents the three common development environments.
@@ -1423,4 +1457,4 @@ interface ZodParsingErrorData {
   issues: Array<z$1.core.$ZodIssue>;
 }
 //#endregion
-export { APIError, type ArrayElement, type CallReturnType, type CamelToKebabOptions, type CreateEnumType, type CreateFormDataOptions, type CreateFormDataOptionsNullableResolution, type CreateFormDataOptionsUndefinedOrNullResolution, DataError, type DisallowUndefined, Env, FILE_PATH_PATTERN, FILE_PATH_REGEX, type FormDataArrayResolutionStrategy, type FormDataNullableResolutionStrategy, type HTTPErrorCode, type IgnoreCase, type IsTypeArgumentString, type KebabToCamelOptions, type NonNull, type NonUndefined, type NormaliseIndentsFunction, type NormaliseIndentsOptions, type NormalizeIndentsFunction, type NormalizeIndentsOptions, type NullableOnCondition, ONE_DAY_IN_MILLISECONDS, type OptionalOnCondition, type ParallelTuple, type RecordKey, type RemoveUndefined, type StringListToArrayOptions, type ToTitleCaseOptions, UUID_PATTERN, UUID_REGEX, VERSION_NUMBER_PATTERN, VERSION_NUMBER_REGEX, VersionNumber, type FormatOptionsBase as VersionNumberToStringOptions, VersionType, type ZodParsingErrorData, addDaysToDate, appendSemicolon, assertNotNull, assertNotNullable, assertNotUndefined, az, calculateMonthlyDifference, camelToKebab, containsKeys, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, escapeRegexPattern, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, getStringsAndInterpolations, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isNonNullableObject, isOrdered, isSameDate, isTemplateStringsArray, kebabToCamel, normaliseIndents, normalizeIndents, objectContainsKeys, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseUUID, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, sayHello, stringListToArray, stringifyDotenv, toTitleCase, truncate, wait, zodVersionNumber };
+export { APIError, type ArrayElement, type CallReturnType, type CamelToKebabOptions, type CreateEnumType, type CreateFormDataOptions, type CreateFormDataOptionsNullableResolution, type CreateFormDataOptionsUndefinedOrNullResolution, DataError, type DisallowUndefined, Env, FILE_PATH_PATTERN, FILE_PATH_REGEX, type FormDataArrayResolutionStrategy, type FormDataNullableResolutionStrategy, type HTTPErrorCode, type IgnoreCase, type IsTypeArgumentString, type KebabToCamelOptions, type NonNull, type NonUndefined, type NormaliseIndentsFunction, type NormaliseIndentsOptions, type NormalizeIndentsFunction, type NormalizeIndentsOptions, type NullableOnCondition, ONE_DAY_IN_MILLISECONDS, type OptionalOnCondition, type ParallelTuple, type RecordKey, type RemoveUndefined, SortDirection, type StringListToArrayOptions, type ToTitleCaseOptions, UUID_PATTERN, UUID_REGEX, VERSION_NUMBER_PATTERN, VERSION_NUMBER_REGEX, VersionNumber, type FormatOptionsBase as VersionNumberToStringOptions, VersionType, type ZodParsingErrorData, addDaysToDate, appendSemicolon, assertNotNull, assertNotNullable, assertNotUndefined, az, calculateMonthlyDifference, camelToKebab, containsKeys, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, escapeRegexPattern, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, getStringsAndInterpolations, httpErrorCodeLookup, identity, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isNonNullableObject, isOrdered, isSameDate, isTemplateStringsArray, kebabToCamel, normaliseIndents, normalizeIndents, objectContainsKeys, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseUUID, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, sayHello, sortBy, stringListToArray, stringifyDotenv, toTitleCase, truncate, wait, zodVersionNumber };

package/dist/index.js

@@ -803,6 +803,20 @@ function createFormData(data, options = {
 	return formData;
 }
 //#endregion
+//#region src/root/functions/miscellaneous/identity.ts
+/**
+* Gives back the original input.
+*
+* @template InputType - The input type.
+*
+* @param input - The input value.
+*
+* @returns The original input value.
+*/
+function identity(input) {
+	return input;
+}
+//#endregion
 //#region src/root/functions/miscellaneous/isOrdered.ts
 /**
 * Checks to see if the given array is sorted in ascending order.
@@ -933,6 +947,33 @@ I'll commit to you!
     `;
 }
 //#endregion
+//#region src/root/functions/miscellaneous/sortBy.ts
+/**
+* Provides a function to pass to the `sort` or `toSorted` methods on arrays, which will allow those methods to sort the items by the chosen value in the chosen direction.
+*
+* @template ItemType - The type of each array item.
+* @template SortValue - The type of the value to sort by.
+*
+* @param selector - A function that takes the item and returns the value to sort by.
+* @param direction - The sort direction.
+*
+* @returns A function to pass into the `.sort()` or `.toSorted()` methods on arrays.
+*/
+function sortBy(selector, direction = "asc") {
+	return (first, second) => {
+		const firstValue = selector(first);
+		const secondValue = selector(second);
+		if (firstValue instanceof Date && secondValue instanceof Date) {
+			const firstTime = firstValue.getTime();
+			const secondTime = secondValue.getTime();
+			return direction === "asc" ? firstTime - secondTime : secondTime - firstTime;
+		}
+		if (firstValue < secondValue) return direction === "asc" ? -1 : 1;
+		if (firstValue > secondValue) return direction === "asc" ? 1 : -1;
+		return 0;
+	};
+}
+//#endregion
 //#region src/root/functions/miscellaneous/stringifyDotenv.ts
 /**
 * Converts an object into a string in .env file format.
@@ -1077,6 +1118,12 @@ function parseBoolean(inputString) {
 	return normalisedString === "true";
 }
 //#endregion
+//#region src/root/types/SortDirection.ts
+const SortDirection = {
+	DESC: "desc",
+	ASC: "asc"
+};
+//#endregion
 //#region src/root/types/VersionNumber.ts
 /**
 * Represents a software version number, considered to be made up of a major, minor, and patch part.
@@ -1936,4 +1983,4 @@ var DataError = class DataError extends Error {
 	}
 };
 //#endregion
-export { APIError, DataError, Env, FILE_PATH_PATTERN, FILE_PATH_REGEX, ONE_DAY_IN_MILLISECONDS, UUID_PATTERN, UUID_REGEX, VERSION_NUMBER_PATTERN, VERSION_NUMBER_REGEX, VersionNumber, VersionType, addDaysToDate, appendSemicolon, assertNotNull, assertNotNullable, assertNotUndefined, az, calculateMonthlyDifference, camelToKebab, containsKeys, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, escapeRegexPattern, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, getStringsAndInterpolations, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isNonNullableObject, isOrdered, isSameDate, isTemplateStringsArray, kebabToCamel, normaliseIndents, normalizeIndents, objectContainsKeys, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseUUID, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, sayHello, stringListToArray, stringifyDotenv, toTitleCase, truncate, wait, zodVersionNumber };
+export { APIError, DataError, Env, FILE_PATH_PATTERN, FILE_PATH_REGEX, ONE_DAY_IN_MILLISECONDS, SortDirection, UUID_PATTERN, UUID_REGEX, VERSION_NUMBER_PATTERN, VERSION_NUMBER_REGEX, VersionNumber, VersionType, addDaysToDate, appendSemicolon, assertNotNull, assertNotNullable, assertNotUndefined, az, calculateMonthlyDifference, camelToKebab, containsKeys, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, escapeRegexPattern, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, getStringsAndInterpolations, httpErrorCodeLookup, identity, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isNonNullableObject, isOrdered, isSameDate, isTemplateStringsArray, kebabToCamel, normaliseIndents, normalizeIndents, objectContainsKeys, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseUUID, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, sayHello, sortBy, stringListToArray, stringifyDotenv, toTitleCase, truncate, wait, zodVersionNumber };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alextheman/utility",
-  "version": "5.20.0",
+  "version": "5.21.0",
   "description": "Helpful utility functions.",
   "repository": {
     "type": "git",
@@ -41,8 +41,8 @@
   },
   "devDependencies": {
     "@alextheman/eslint-plugin": "5.17.0",
-    "@types/node": "25.9.1",
-    "alex-c-line": "2.9.1",
+    "@types/node": "25.9.3",
+    "alex-c-line": "2.9.2",
     "cross-env": "10.1.0",
     "dotenv-cli": "11.0.0",
     "eslint": "10.4.1",
@@ -50,7 +50,7 @@
     "husky": "9.1.7",
     "jsdom": "29.1.1",
     "markdownlint-cli2": "0.22.1",
-    "prettier": "3.8.3",
+    "prettier": "3.8.4",
     "tempy": "3.2.0",
     "tsdown": "0.22.2",
     "tsx": "4.22.4",
@@ -58,7 +58,7 @@
     "typedoc-plugin-markdown": "4.12.0",
     "typedoc-rhineai-theme": "1.2.0",
     "typescript": "6.0.3",
-    "typescript-eslint": "8.60.1",
+    "typescript-eslint": "8.61.0",
     "vite": "8.0.16",
     "vitest": "4.1.8",
     "zod": "4.4.3"