Utility Library - @jonasantunes/utility_lib_miew

A comprehensive utility library for arrays, dates, objects, strings, files, urls and general utilities. This library provides a wide range of helper functions to simplify common programming tasks.

Installation

Install the library via npm:

npm install @jonasantunes/utility_lib_miew

Usage

Import the desired function(s) into your project:

import { name_of_the_function } from '@jonasantunes/utility_lib_miew';

Available Functions

Arrays

| Function Name | Description | | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | removeDuplicates<T>(array: Array<T>, caseSensitive: boolean = false): Array<T> | Removes duplicate elements from an array. | | commonElements<T>(arrayX: Array<T>, arrayY: Array<T>, caseSensitive: boolean = false): Array<T> | Finds common elements between two arrays. | | arrayDifference<T>(arrayX: Array<T>, arrayY: Array<T>, caseSensitive: boolean = false, withDuplicates: boolean = false): Array<T> | Returns the difference between two arrays. | | countOccurrences<T>(array: Array<T>, caseSensitive: boolean = false): Array<[string, number]> | Counts the occurrences of each element in an array. | | returnDuplicates<T>(array: Array<T>, caseSensitive: boolean = false): Array<T> | Returns the duplicate elements in an array. | | removeDuplicatesByKeyInArray<T, K extends keyof T>(array: Array<T>, key: K, caseSensitive: boolean = false): Array<T> | Removes duplicate objects in an array based on a specific key. | | removeFalsyValues<T>(array: Array<T>): Array<T> | Removes falsy values (e.g., null, undefined, false, 0) from an array. | | sortArrayByKey<T, K extends keyof T>(array: Array<T>, key: K, desc: boolean = false): Array<T> | Sorts an array of objects by a specific key. | | groupArrayByKey<T, K extends keyof T>(array: Array<T>, key: K): Array<T[]> | Groups an array of objects by a specific key. | | splitArrayByKeyValue<T, K extends keyof T, V extends T[K]>(array: Array<T>, key: K, value: V): Array<T[]> | Splits an array into two based on a key-value condition. |

Dates

| Function Name | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | isLeapYear(param?: number \| string \| Date): boolean | Checks if a given year is a leap year. | | differenceBetweenDates(date1: Date, date2: Date): number | Calculates the absolute difference in days between two dates. | | weekNumber(date: Date, iso: boolean = false): number | Calculates the week number of the year for a given date. | | addToDate(date: Date, seconds: number = 0, minutes: number = 0, hours: number = 0, days: number = 0, months: number = 0, years: number = 0, utc: boolean = false ): Date \| boolean | Adds a specified number of seconds, minutes, hours, days, months and years to a given date. | | isSameDay(date1: Date, date2: Date, utc: boolean = false): boolean | Checks if two Date objects represent the same calendar day. | | daysInMonth(year: number, month: number): number | Returns the number of days in a given month of a specific year. | | subtractDays(date: Date, days: number, utc: boolean = false): Date \| boolean | Subtracts a specified number of days from a given date. | | convertToRelativeTime(date: Date): string | Converts a date to a relative time string. | | firstDayOfMonth(date: Date, utc: boolean = false): Date \| boolean | Returns the date representing the first day of the month. | | lastDayOfMonth(date: Date, utc: boolean = false): Date \| boolean | Returns the date representing the last day of the month. | | isWeekend(date: Date, utc: boolean = false): boolean | Checks if the given date falls on a weekend (Saturday or Sunday). | | isValidDateString(str: string): boolean | Checks if a given string can be parsed into a valid Date. | | isValidISODateString(strDate: string): boolean | Checks if a string is a valid ISO 8601 date. | | formatDate(date: Date, format: string): string | Formats a date object into a string using a given format. |

Files

| Function Name | Description | | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | blobToFile(blob: Blob, fileName: string): File | Converts a Blob object to a File object with a specified file name. | | fileToBlob(file: File): Blob | Converts a File object to a Blob object. | | urlToFile(url: string, filename: string, mimeType?: string): Promise<File> | Downloads a file from the specified URL and converts it into a File object. |

General Utilities

| Function Name | Description | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | isIBAN(stringIban: string): boolean | Validates if a string is a valid IBAN. | | isPhoneNumberPT(stringPhoneNumber: string): boolean | Validates if a string is a valid Portuguese phone number. | | isTIN(tin: string, countryCode: string): boolean | Validates if a string is a valid Tax Identification Number (TIN) for a given country. | | isCAE(cae: string \| number): boolean | Checks whether a given value is a valid CAE code format (Portuguese Economic Activity Code). | | isValidEmail(email: string): boolean | Validates whether the input string is a valid email address. | | retry<T extends (...args: Parameters<T>) => Promise<any>>(fn: T, args: Parameters<T>, maxRetries: number, retryCount: number = 1): Promise<{ result: Awaited<ReturnType<T>>; attempt: number }> | Attempts to execute an asynchronous function and retries it if it fails, up to a specified number of times. | | sleep(ms: number): Promise<boolean> | Pauses execution for a given period of time and returns true after completion. |

Objects

| Function Name | Description | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | countKeysInObject(obj: object, nested: boolean = false): number | Counts the number of keys in an object. If nested is true, counts nested keys also. | | isObjectEmpty(obj: object): boolean | Checks if an object is empty. | | removePropertiesFromObject<T extends object, K extends keyof T>( obj: T, props: Array<K> \| Set<K>, nested: boolean = false): T | Removes specified properties from an object. If nested is true, it will also remove matching keys from nested objects recursively. | | freezeObject(obj: object): boolean \| object | Freezes an object to make it immutable. | | hasObjectKeys<T extends object, K extends keyof T>(obj: T, props: Array<K> \| Set<K>,nested: boolean = false): boolean | Checks if an object contains specific keys. Optionally checks recursively for nested keys. | | objectWithSpecifiedKeys<T extends object, K extends keyof T>(obj: T, keys: K[]): T | Returns a new object with only the specified keys. | | mergeTwoObjects(object1: object, object2: object): object \| boolean | Merges two objects into one. | | renameKeysOfObject(obj: object, objNewKeys: object): object | Renames keys in an object based on a mapping object. | | cleanObject(obj: object, nested: boolean = false): object | Removes null or undefined values from an object. If nested is true, the cleaning is applied recursively to all nested objects. | | deepCopyObject(obj: object): object | Creates a deep copy of an object. | | groupByKeyObjects<T extends object, K extends keyof T>(objects: T[], key: K): T | Groups an array of objects by a specific key. | | nestedValue<T extends object, U>(obj: T, path: string[]): U | Retrieves a nested value from an object using a given path array. | | nestedKeys<T extends object, K extends keyof T>(obj: T): Array<K> | Recursively retrieves all keys (including nested keys) from an object. | | deepCompareKeysIntersection<T extends object, U extends object>(obj1: T, obj2: U, duplicates: boolean = false ): Set<keyof T & keyof U> \| Array<keyof T & keyof U> | Compares two objects and returns their common keys (intersection) at all levels of nesting. | | deepCompareKeysSymmetricDifference<T extends object, U extends object>(obj1: T, obj2: U, duplicates: boolean = false): Set<keyof T \| keyof U> \| Array<keyof T \| keyof U> | Compares two objects and returns the symmetric difference of their keys (keys that are in one object but not the other). | | deepCompareKeysIsSupersetOf<T extends object, U extends object>(obj1: T, obj2: U, duplicates: boolean = false): boolean | Compares two objects and checks if the keys of the first object (obj1) are a superset of the keys of the second object (obj2). | | deepCompareKeysIsSubsetOf<T extends object, U extends object>(obj1: T, obj2: U, duplicates: boolean = false): boolean | Compares two objects and checks if the keys of the first object (obj1) are a subset of the keys of the second object (obj2). | | deepCompareKeysDifference<T extends object, U extends object>(obj1: T,obj2: U,duplicates: boolean = false): Set<keyof T \| keyof U> \| Array<keyof T \| keyof U> | Compares two objects and returns the keys that are present in one object but not in the other. | | deepCompare<T, K extends keyof T>(var1: T, var2: T): boolean | Recursively compares two values (objects or arrays) for deep equality. |

Strings

| Function Name | Description | | --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | camelCaseToSnakeCase(string: string, toConst: boolean = false): string | Converts a camelCase string to snake_case. | | snakeCaseToCamelCase(string: string): string | Converts a snake_case string to camelCase. | | removeDuplicateSpacesAndNormalizes(string: string, form?: string): string | Removes duplicate spaces and normalizes a string. | | stringToTitleCase(string: string): string | Converts a string to title case. | | replaceAllOcurrencesInString(text: string, substringSearch: string, substringReplace: string, caseSensitive: boolean = false): string | Replaces all occurrences of a substring in a string. | | countOccurrencesString(text: string, substring: string, caseSensitive: boolean = false): number \| string | Counts the occurrences of a substring in a string. | | decodeStringFromBase64(string: string): string | Decodes a Base64-encoded string. | | encodeStringToBase64(string: string): string | Encodes a string to Base64. |

URLS

| Function Name | Description | | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | isSecureUrl(url: string): boolean | Checks if a URL uses HTTPS protocol. | | parseURLToObject<T>(url: string \| URL): T | Parses query parameters from a URL (string or URL object) into a plain object. | | serializeObjectToQuery<T extends object>(obj: T): string | Serializes a flat object into a URL query string. | | removeQueryParam(url: string, key: string): string | Removes a query parameter from a given URL string. | | addQueryParam(url: string, key: string, value: string): string | Adds or updates a query parameter in the given URL. | | convertToUrlFriendly(str: string): string \| boolean | Converts a string into a URL-friendly format . | | pathSegments(url: string): string[] | Extracts and returns the non-empty path segments of a given valid URL. | | parentPathname(url: string): string | Retrieves the parent pathname of a given URL by removing the last segment of the pathname. |