npm package: @jonasantunes/utility_lib_miew
Description: 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.
Latest version: 1.0.6

# **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:

```bash
npm install @jonasantunes/utility_lib_miew
```

## **Usage**

Import the desired function(s) into your project:

```bash
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&lt;T extends (...args: Parameters&lt;T&gt;) =&gt; Promise&lt;any&gt;&gt;(fn: T, args: Parameters&lt;T&gt;, maxRetries: number, retryCount: number = 1): Promise&lt;{ result: Awaited&lt;ReturnType&lt;T&gt;&gt;; attempt: number }&gt;` | 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. |