@alextheman/utility 5.19.2 → 5.21.0

package/dist/index.cjs

@@ -115,7 +115,7 @@ var CodeError = class CodeError extends Error {
 	*/
 	static check(input) {
 		if (input instanceof CodeError) return true;
-		return typeof input === "object" && input !== null && "message" in input && typeof input.message === "string" && "code" in input && typeof input.code === "string";
+		return containsKeys(input, ["message", "code"]) && typeof input.message === "string" && typeof input.code === "string";
 	}
 	static checkCaughtError(error, options) {
 		if (this.check(error)) {
@@ -228,7 +228,11 @@ var DataError$1 = class DataError$1 extends CodeError {
 	*/
 	static check(input) {
 		if (input instanceof DataError$1) return true;
-		return typeof input === "object" && input !== null && "message" in input && typeof input.message === "string" && "code" in input && typeof input.code === "string" && "data" in input && typeof input.data === "object" && input.data !== null;
+		return containsKeys(input, [
+			"data",
+			"code",
+			"message"
+		]) && typeof input.message === "string" && typeof input.code === "string" && isNonNullableObject(input.data);
 	}
 	/**
 	* Check a `DataError` against its error code
@@ -325,6 +329,107 @@ function range(start, stop, step = 1) {
 	return numbers;
 }
 //#endregion
+//#region src/root/functions/typeAssertions/assertNotNull.ts
+/**
+* Asserts that a given input is not `null`, and throws a DataError if it does.
+*
+* If no error is thrown from this, the input type gets narrowed down to not include `null`.
+*
+* @category Type Assertions
+*
+* @template InputType The type of the input.
+*
+* @param input - The input to assert against
+*
+* @throws {DataError} If the input is `null`.
+*/
+function assertNotNull(input) {
+	if (input === null) throw new DataError$1({ input }, "NULL_INPUT", "Expected the input not to be null");
+}
+//#endregion
+//#region src/root/functions/typeAssertions/assertNotNullable.ts
+/**
+* Asserts that a given input is not `undefined` or `null`, and throws a DataError if it does.
+*
+* If no error is thrown from this, the input type gets narrowed down to not include `undefined` or `null`.
+*
+* @category Type Assertions
+*
+* @template InputType The type of the input.
+*
+* @param input - The input to assert against.
+*
+* @throws {DataError} If the input is `undefined` or `null`.
+*/
+function assertNotNullable(input) {
+	if (input === null || input === void 0) throw new DataError$1({ input }, "NULLABLE_INPUT", "Expected the input not to be undefined or null");
+}
+//#endregion
+//#region src/root/functions/typeAssertions/assertNotUndefined.ts
+/**
+* Asserts that a given input is not `undefined`, and throws a DataError if it does.
+*
+* If no error is thrown from this, the input type gets narrowed down to not include `undefined`.
+*
+* @category Type Assertions
+*
+* @template InputType The type of the input.
+*
+* @param input - The input to assert against.
+*
+* @throws {DataError} If the input is `undefined`.
+*/
+function assertNotUndefined(input) {
+	if (input === void 0) throw new DataError$1({ input }, "UNDEFINED_INPUT", "Expected the input not to be undefined");
+}
+//#endregion
+//#region src/root/functions/typeAssertions/isNonNullableObject.ts
+/**
+* Determines if the given input is a non-nullable object, narrowing the type down as such if it is
+*
+* @category Type Assertions
+*
+* @param input - The input to check
+*
+* @returns `true` if the input is a non-nullable object, and `false` otherwise. The input type will also be narrowed down to be a non-nullable object.
+*/
+function isNonNullableObject(input) {
+	return typeof input === "object" && input !== null;
+}
+//#endregion
+//#region src/root/functions/typeAssertions/objectContainsKeys.ts
+/**
+* Determines if the given object contains all of the keys provided.
+*
+* @category Type Assertions
+*
+* @param input - The input object to check.
+* @param keys - The keys expected to be in the input object.
+*
+* @returns `true` if the input object contains all provided keys, and `false` otherwise. The input type will also be narrowed down to be a record with the provided keys with an unknown value type.
+*/
+function objectContainsKeys(input, keys) {
+	const expectedKeys = Array.isArray(keys) ? keys : [keys];
+	if (expectedKeys.length === 0) return false;
+	for (const key of expectedKeys) if (!(key in input)) return false;
+	return true;
+}
+//#endregion
+//#region src/root/functions/typeAssertions/containsKeys.ts
+/**
+* Determines if the given input is a non-nullable object, and if that object contains all of the keys provided.
+*
+* @category Type Assertions
+*
+* @param input - The input to check.
+* @param keys - The keys expected to be in the input if it's an object.
+*
+* @returns `true` if the input is an object containing all provided keys, and `false` otherwise. The input type will also be narrowed down to be a record with the provided keys, each with an unknown value type.
+*/
+function containsKeys(input, keys) {
+	return isNonNullableObject(input) && objectContainsKeys(input, keys);
+}
+//#endregion
 //#region src/root/functions/arrayHelpers/fillArray.ts
 /**
 * Creates a new array where each element is the result of the provided callback.
@@ -352,7 +457,7 @@ function fillArray(callback, length = 1, options) {
 		return callback(index);
 	});
 	if (outputArray.some((item) => {
-		return item instanceof Promise || typeof item === "object" && item !== null && "then" in item && typeof item.then === "function";
+		return item instanceof Promise || containsKeys(item, "then") && typeof item.then === "function";
 	})) return Promise.all(outputArray);
 	return outputArray;
 }
@@ -653,7 +758,7 @@ function convertFileToBase64(file) {
 //#endregion
 //#region src/root/functions/miscellaneous/createFormData.ts
 function getNullableResolutionStrategy(key, strategy) {
-	return (typeof strategy === "object" ? strategy[key] : strategy) ?? "empty";
+	return (isNonNullableObject(strategy) ? strategy[key] : strategy) ?? "empty";
 }
 function isPrimitive(item) {
 	return typeof item === "string" || typeof item === "number" || typeof item === "boolean";
@@ -722,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.
@@ -852,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.
@@ -996,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.
@@ -1354,7 +1506,7 @@ function parseVersionType(input) {
 //#endregion
 //#region src/root/functions/recursive/deepCopy.ts
 function callDeepCopy(input) {
-	return typeof input === "object" && input !== null ? deepCopy(input) : input;
+	return isNonNullableObject(input) ? deepCopy(input) : input;
 }
 /**
 * Deeply copies an object or array such that all child objects/arrays are also copied.
@@ -1673,7 +1825,7 @@ function interpolateObjects(strings, ...interpolations) {
 * @returns `true` if the input is a valid `TemplateStringsArray`, and false otherwise. The type of the input will also be narrowed down to `TemplateStringsArray` if `true`.
 */
 function isTemplateStringsArray(input) {
-	return typeof input === "object" && input !== null && "raw" in input;
+	return containsKeys(input, "raw");
 }
 //#endregion
 //#region src/root/functions/taggedTemplate/normaliseIndents.ts
@@ -1728,7 +1880,7 @@ function reduceLines(lines, { preserveTabs = true }) {
 * @returns An additional function to invoke, or a new string with the strings and interpolations from the template applied, and extraneous indents removed.
 */
 function normaliseIndents(first, ...args) {
-	if (typeof first === "object" && first !== null && !Array.isArray(first)) {
+	if (isNonNullableObject(first) && !Array.isArray(first)) {
 		const options = first;
 		return (strings, ...interpolations) => {
 			return normaliseIndents(strings, ...interpolations, options);
@@ -1855,60 +2007,13 @@ var DataError = class DataError extends Error {
 	}
 };
 //#endregion
-//#region src/root/errors/assertNotNull.ts
-/**
-* Asserts that a given input is not `null`, and throws a DataError if it does.
-*
-* If no error is thrown from this, the input type gets narrowed down to not include `null`.
-*
-* @template InputType The type of the input.
-*
-* @param input - The input to assert against
-*
-* @throws {DataError} If the input is `null`.
-*/
-function assertNotNull(input) {
-	if (input === null) throw new DataError$1({ input }, "NULL_INPUT", "Expected the input not to be null");
-}
-//#endregion
-//#region src/root/errors/assertNotNullable.ts
-/**
-* Asserts that a given input is not `undefined` or `null`, and throws a DataError if it does.
-*
-* If no error is thrown from this, the input type gets narrowed down to not include `undefined` or `null`.
-*
-* @template InputType The type of the input.
-*
-* @param input - The input to assert against.
-*
-* @throws {DataError} If the input is `undefined` or `null`.
-*/
-function assertNotNullable(input) {
-	if (input === null || input === void 0) throw new DataError$1({ input }, "NULLABLE_INPUT", "Expected the input not to be undefined or null");
-}
-//#endregion
-//#region src/root/errors/assertNotUndefined.ts
-/**
-* Asserts that a given input is not `undefined`, and throws a DataError if it does.
-*
-* If no error is thrown from this, the input type gets narrowed down to not include `undefined`.
-*
-* @template InputType The type of the input.
-*
-* @param input - The input to assert against.
-*
-* @throws {DataError} If the input is `undefined`.
-*/
-function assertNotUndefined(input) {
-	if (input === void 0) throw new DataError$1({ input }, "UNDEFINED_INPUT", "Expected the input not to be undefined");
-}
-//#endregion
 exports.APIError = APIError;
 exports.DataError = DataError;
 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;
@@ -1923,6 +2028,7 @@ exports.assertNotUndefined = assertNotUndefined;
 exports.az = az;
 exports.calculateMonthlyDifference = calculateMonthlyDifference;
 exports.camelToKebab = camelToKebab;
+exports.containsKeys = containsKeys;
 exports.convertFileToBase64 = convertFileToBase64;
 exports.createFormData = createFormData;
 exports.createTemplateStringsArray = createTemplateStringsArray;
@@ -1935,17 +2041,20 @@ exports.getRandomNumber = getRandomNumber;
 exports.getRecordKeys = getRecordKeys;
 exports.getStringsAndInterpolations = getStringsAndInterpolations;
 exports.httpErrorCodeLookup = httpErrorCodeLookup;
+exports.identity = identity;
 exports.interpolate = interpolate;
 exports.interpolateObjects = interpolateObjects;
 exports.isAnniversary = isAnniversary;
 exports.isLeapYear = isLeapYear;
 exports.isMonthlyMultiple = isMonthlyMultiple;
+exports.isNonNullableObject = isNonNullableObject;
 exports.isOrdered = isOrdered;
 exports.isSameDate = isSameDate;
 exports.isTemplateStringsArray = isTemplateStringsArray;
 exports.kebabToCamel = kebabToCamel;
 exports.normaliseIndents = normaliseIndents;
 exports.normalizeIndents = normalizeIndents;
+exports.objectContainsKeys = objectContainsKeys;
 exports.omitProperties = omitProperties;
 exports.paralleliseArrays = paralleliseArrays;
 exports.parseBoolean = parseBoolean;
@@ -1961,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;