@alextheman/utility 5.4.0 → 5.5.0

package/dist/index.cjs

@@ -549,6 +549,21 @@ function addDaysToDate(currentDate = /* @__PURE__ */ new Date(), dayIncrement =
 	return newDate;
 }
 
+//#endregion
+//#region src/root/functions/date/calculateMonthlyDifference.ts
+/**
+* Calculates the monthly difference between two given dates, subtracting the first from
+* the second and gives a negative result if the first date occurs earlier than the second.
+*
+* @param firstDate - The first date
+* @param secondDate - The second date
+*
+* @returns The calculated difference as a number
+*/
+function calculateMonthlyDifference(firstDate, secondDate) {
+	return firstDate.getMonth() - secondDate.getMonth();
+}
+
 //#endregion
 //#region src/root/functions/date/isSameDate.ts
 /**
@@ -1402,6 +1417,25 @@ function parseFormData(formData, dataParser) {
 	return object;
 }
 
+//#endregion
+//#region src/root/functions/parsers/parseUUID.ts
+/**
+* Parses the input and verifies it is a valid UUID.
+*
+* @category Parsers
+*
+* @param input - The data to parse.
+*
+* @throws {DataError} If the data does not match the general UUID pattern.
+*
+* @returns The UUID again if successful.
+*/
+function parseUUID(input) {
+	if (!(typeof input === "string")) throw new DataError({ input }, "INVALID_TYPE", "Invalid type - expected string.");
+	if (!UUID_REGEX.test(input)) throw new DataError({ input }, "INVALID_UUID", "The provided input does not match the expected shape for a UUID.");
+	return input;
+}
+
 //#endregion
 //#region src/root/functions/parsers/parseVersionType.ts
 /**
@@ -1630,6 +1664,7 @@ exports.VersionNumber = VersionNumber;
 exports.VersionType = VersionType;
 exports.addDaysToDate = addDaysToDate;
 exports.appendSemicolon = appendSemicolon;
+exports.calculateMonthlyDifference = calculateMonthlyDifference;
 exports.camelToKebab = camelToKebab;
 exports.convertFileToBase64 = convertFileToBase64;
 exports.createFormData = createFormData;
@@ -1660,6 +1695,7 @@ exports.parseBoolean = parseBoolean;
 exports.parseEnv = parseEnv;
 exports.parseFormData = parseFormData;
 exports.parseIntStrict = parseIntStrict;
+exports.parseUUID = parseUUID;
 exports.parseVersionType = parseVersionType;
 exports.parseZodSchema = parseZodSchema;
 exports.parseZodSchemaAsync = parseZodSchemaAsync;

package/dist/index.d.cts

@@ -127,6 +127,18 @@ declare function removeDuplicates<ItemType>(array: ItemType[] | readonly ItemTyp
  */
 declare function addDaysToDate(currentDate?: Date, dayIncrement?: number): Date;
 //#endregion
+//#region src/root/functions/date/calculateMonthlyDifference.d.ts
+/**
+ * Calculates the monthly difference between two given dates, subtracting the first from
+ * the second and gives a negative result if the first date occurs earlier than the second.
+ *
+ * @param firstDate - The first date
+ * @param secondDate - The second date
+ *
+ * @returns The calculated difference as a number
+ */
+declare function calculateMonthlyDifference(firstDate: Date, secondDate: Date): number;
+//#endregion
 //#region src/root/functions/date/formatDateAndTime.d.ts
 /**
  * Creates a human-readable string with information about the input date.
@@ -740,6 +752,20 @@ declare function parseFormData(formData: FormData): Record<string, string | Blob
  */
 declare function parseIntStrict(string: string, radix?: number): number;
 //#endregion
+//#region src/root/functions/parsers/parseUUID.d.ts
+/**
+ * Parses the input and verifies it is a valid UUID.
+ *
+ * @category Parsers
+ *
+ * @param input - The data to parse.
+ *
+ * @throws {DataError} If the data does not match the general UUID pattern.
+ *
+ * @returns The UUID again if successful.
+ */
+declare function parseUUID(input: unknown): string;
+//#endregion
 //#region src/root/functions/parsers/parseVersionType.d.ts
 /**
  * Represents the three common software version types.
@@ -1086,4 +1112,4 @@ declare function normaliseIndents(strings: TemplateStringsArray, ...interpolatio
  */
 declare const normalizeIndents: typeof normaliseIndents;
 //#endregion
-export { APIError, ArrayElement, CallReturnType, CamelToKebabOptions, CreateEnumType, CreateFormDataOptions, CreateFormDataOptionsNullableResolution, CreateFormDataOptionsUndefinedOrNullResolution, DataError, DisallowUndefined, Env, FILE_PATH_PATTERN, FILE_PATH_REGEX, FormDataArrayResolutionStrategy, FormDataNullableResolutionStrategy, HTTPErrorCode, IgnoreCase, IsTypeArgumentString, KebabToCamelOptions, NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, ONE_DAY_IN_MILLISECONDS, OptionalOnCondition, ParallelTuple, RecordKey, RemoveUndefined, StringListToArrayOptions, UUID_PATTERN, UUID_REGEX, VERSION_NUMBER_PATTERN, VERSION_NUMBER_REGEX, VersionNumber, FormatOptionsBase as VersionNumberToStringOptions, VersionType, addDaysToDate, appendSemicolon, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, encryptWithKey, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, getStringsAndInterpolations, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, isTemplateStringsArray, kebabToCamel, normaliseIndents, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, sayHello, stringListToArray, stringifyDotenv, truncate, wait, zodVersionNumber };
+export { APIError, ArrayElement, CallReturnType, CamelToKebabOptions, CreateEnumType, CreateFormDataOptions, CreateFormDataOptionsNullableResolution, CreateFormDataOptionsUndefinedOrNullResolution, DataError, DisallowUndefined, Env, FILE_PATH_PATTERN, FILE_PATH_REGEX, FormDataArrayResolutionStrategy, FormDataNullableResolutionStrategy, HTTPErrorCode, IgnoreCase, IsTypeArgumentString, KebabToCamelOptions, NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, ONE_DAY_IN_MILLISECONDS, OptionalOnCondition, ParallelTuple, RecordKey, RemoveUndefined, StringListToArrayOptions, UUID_PATTERN, UUID_REGEX, VERSION_NUMBER_PATTERN, VERSION_NUMBER_REGEX, VersionNumber, FormatOptionsBase as VersionNumberToStringOptions, VersionType, addDaysToDate, appendSemicolon, calculateMonthlyDifference, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, encryptWithKey, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, getStringsAndInterpolations, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, isTemplateStringsArray, kebabToCamel, normaliseIndents, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseUUID, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, sayHello, stringListToArray, stringifyDotenv, truncate, wait, zodVersionNumber };

package/dist/index.d.ts

@@ -127,6 +127,18 @@ declare function removeDuplicates<ItemType>(array: ItemType[] | readonly ItemTyp
  */
 declare function addDaysToDate(currentDate?: Date, dayIncrement?: number): Date;
 //#endregion
+//#region src/root/functions/date/calculateMonthlyDifference.d.ts
+/**
+ * Calculates the monthly difference between two given dates, subtracting the first from
+ * the second and gives a negative result if the first date occurs earlier than the second.
+ *
+ * @param firstDate - The first date
+ * @param secondDate - The second date
+ *
+ * @returns The calculated difference as a number
+ */
+declare function calculateMonthlyDifference(firstDate: Date, secondDate: Date): number;
+//#endregion
 //#region src/root/functions/date/formatDateAndTime.d.ts
 /**
  * Creates a human-readable string with information about the input date.
@@ -740,6 +752,20 @@ declare function parseFormData(formData: FormData): Record<string, string | Blob
  */
 declare function parseIntStrict(string: string, radix?: number): number;
 //#endregion
+//#region src/root/functions/parsers/parseUUID.d.ts
+/**
+ * Parses the input and verifies it is a valid UUID.
+ *
+ * @category Parsers
+ *
+ * @param input - The data to parse.
+ *
+ * @throws {DataError} If the data does not match the general UUID pattern.
+ *
+ * @returns The UUID again if successful.
+ */
+declare function parseUUID(input: unknown): string;
+//#endregion
 //#region src/root/functions/parsers/parseVersionType.d.ts
 /**
  * Represents the three common software version types.
@@ -1086,4 +1112,4 @@ declare function normaliseIndents(strings: TemplateStringsArray, ...interpolatio
  */
 declare const normalizeIndents: typeof normaliseIndents;
 //#endregion
-export { APIError, type ArrayElement, type CallReturnType, 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, KebabToCamelOptions, type NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, ONE_DAY_IN_MILLISECONDS, type OptionalOnCondition, ParallelTuple, type RecordKey, type RemoveUndefined, type StringListToArrayOptions, UUID_PATTERN, UUID_REGEX, VERSION_NUMBER_PATTERN, VERSION_NUMBER_REGEX, VersionNumber, type FormatOptionsBase as VersionNumberToStringOptions, VersionType, addDaysToDate, appendSemicolon, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, encryptWithKey, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, getStringsAndInterpolations, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, isTemplateStringsArray, kebabToCamel, normaliseIndents, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, sayHello, stringListToArray, stringifyDotenv, truncate, wait, zodVersionNumber };
+export { APIError, type ArrayElement, type CallReturnType, 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, KebabToCamelOptions, type NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, ONE_DAY_IN_MILLISECONDS, type OptionalOnCondition, ParallelTuple, type RecordKey, type RemoveUndefined, type StringListToArrayOptions, UUID_PATTERN, UUID_REGEX, VERSION_NUMBER_PATTERN, VERSION_NUMBER_REGEX, VersionNumber, type FormatOptionsBase as VersionNumberToStringOptions, VersionType, addDaysToDate, appendSemicolon, calculateMonthlyDifference, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, encryptWithKey, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, getStringsAndInterpolations, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, isTemplateStringsArray, kebabToCamel, normaliseIndents, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseUUID, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, sayHello, stringListToArray, stringifyDotenv, truncate, wait, zodVersionNumber };

package/dist/index.js

@@ -519,6 +519,21 @@ function addDaysToDate(currentDate = /* @__PURE__ */ new Date(), dayIncrement =
 	return newDate;
 }
 
+//#endregion
+//#region src/root/functions/date/calculateMonthlyDifference.ts
+/**
+* Calculates the monthly difference between two given dates, subtracting the first from
+* the second and gives a negative result if the first date occurs earlier than the second.
+*
+* @param firstDate - The first date
+* @param secondDate - The second date
+*
+* @returns The calculated difference as a number
+*/
+function calculateMonthlyDifference(firstDate, secondDate) {
+	return firstDate.getMonth() - secondDate.getMonth();
+}
+
 //#endregion
 //#region src/root/functions/date/isSameDate.ts
 /**
@@ -1372,6 +1387,25 @@ function parseFormData(formData, dataParser) {
 	return object;
 }
 
+//#endregion
+//#region src/root/functions/parsers/parseUUID.ts
+/**
+* Parses the input and verifies it is a valid UUID.
+*
+* @category Parsers
+*
+* @param input - The data to parse.
+*
+* @throws {DataError} If the data does not match the general UUID pattern.
+*
+* @returns The UUID again if successful.
+*/
+function parseUUID(input) {
+	if (!(typeof input === "string")) throw new DataError({ input }, "INVALID_TYPE", "Invalid type - expected string.");
+	if (!UUID_REGEX.test(input)) throw new DataError({ input }, "INVALID_UUID", "The provided input does not match the expected shape for a UUID.");
+	return input;
+}
+
 //#endregion
 //#region src/root/functions/parsers/parseVersionType.ts
 /**
@@ -1586,4 +1620,4 @@ function truncate(stringToTruncate, maxLength = 5) {
 }
 
 //#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, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, encryptWithKey, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, getStringsAndInterpolations, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, isTemplateStringsArray, kebabToCamel, normaliseIndents, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, sayHello, stringListToArray, stringifyDotenv, truncate, wait, zodVersionNumber };
+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, calculateMonthlyDifference, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, encryptWithKey, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, getStringsAndInterpolations, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, isTemplateStringsArray, kebabToCamel, normaliseIndents, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseUUID, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, sayHello, stringListToArray, stringifyDotenv, truncate, wait, zodVersionNumber };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alextheman/utility",
-  "version": "5.4.0",
+  "version": "5.5.0",
   "description": "Helpful utility functions.",
   "repository": {
     "type": "git",