@arkyn/shared 3.0.1-beta.121 → 3.0.1-beta.123

package/dist/formats/formatDate.d.ts

@@ -5,7 +5,7 @@
  * **Note:** This function works with UTC+0 by default. The returned formatted string is not automatically converted to the machine's local timezone.
  * To adjust the timezone, you must manually specify the `timezone` parameter (e.g., -3 for UTC-3).
  *
- * @param {[string, string]} dateTime - An array containing the date and optional time.
+ * @param {string[]} dateTime - An array containing the date and optional time.
  *   - The first element is the date string.
  *   - The second element is the time string (default is "00:00:00").
  * @param {"brazilianDate" | "isoDate" | "timestamp"} inputFormat - The format of the input date.
@@ -57,6 +57,6 @@
  * console.log(formattedDate); // Output: "12-25-2023 15:30:00"
  * ```
  */
-declare function formatDate([date, time]: [string, string?], inputFormat: "brazilianDate" | "isoDate" | "timestamp", outputFormat: string, timezone?: number): string;
+declare function formatDate([date, time]: string[], inputFormat: "brazilianDate" | "isoDate" | "timestamp", outputFormat: string, timezone?: number): string;
 export { formatDate };
 //# sourceMappingURL=formatDate.d.ts.map

package/dist/formats/formatDate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formatDate.d.ts","sourceRoot":"","sources":["../../src/formats/formatDate.ts"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAEH,iBAAS,UAAU,CACjB,CAAC,IAAI,EAAE,IAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAC5C,WAAW,EAAE,eAAe,GAAG,SAAS,GAAG,WAAW,EACtD,YAAY,EAAE,MAAM,EACpB,QAAQ,GAAE,MAAU,GACnB,MAAM,CAkCR;AAED,OAAO,EAAE,UAAU,EAAE,CAAC"}
+{"version":3,"file":"formatDate.d.ts","sourceRoot":"","sources":["../../src/formats/formatDate.ts"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAEH,iBAAS,UAAU,CACjB,CAAC,IAAI,EAAE,IAAiB,CAAC,EAAE,MAAM,EAAE,EACnC,WAAW,EAAE,eAAe,GAAG,SAAS,GAAG,WAAW,EACtD,YAAY,EAAE,MAAM,EACpB,QAAQ,GAAE,MAAU,GACnB,MAAM,CAkCR;AAED,OAAO,EAAE,UAAU,EAAE,CAAC"}

package/dist/formats/formatDate.js

@@ -19,7 +19,7 @@ function formatDateString(date, format) {
  * **Note:** This function works with UTC+0 by default. The returned formatted string is not automatically converted to the machine's local timezone.
  * To adjust the timezone, you must manually specify the `timezone` parameter (e.g., -3 for UTC-3).
  *
- * @param {[string, string]} dateTime - An array containing the date and optional time.
+ * @param {string[]} dateTime - An array containing the date and optional time.
  *   - The first element is the date string.
  *   - The second element is the time string (default is "00:00:00").
  * @param {"brazilianDate" | "isoDate" | "timestamp"} inputFormat - The format of the input date.

package/dist/formats/formatToPhone.d.ts

@@ -1,34 +1,23 @@
-type FormatToPhoneFunction = (rawString: string) => string;
 /**
- * Formats a phone number string based on the provided country code and optional prefix.
+ * Formats a phone number string according to the country mask defined in `@arkyn/templates`.
  *
- * The input string should follow the format: `"<countryCode>-<prefix> <phoneNumber>"` or `"<countryCode> <phoneNumber>"`.
- * The function determines the appropriate formatting mask based on the country and applies it to the phone number.
+ * The function parses the input using libphonenumber-js to determine the country and
+ * national number, then applies the corresponding country's mask (underscore `_` used
+ * as digit placeholder) replacing placeholders with actual digits.
  *
- * @param prop - The phone number string to be formatted. It must include the country code and optionally a prefix.
- *               Example formats:
- *               - "+55 32912345678"
- *               - "+1 1234567890"
+ * @param {string} phoneNumber - The input phone number (can include country code or be in national format).
  *
- * @returns The formatted phone number string based on the country's formatting rules.
+ * @returns {string} The phone number formatted following the country's mask.
  *
- * @throws {Error} If the input phone number does not match the expected format.
- * @throws {Error} If the country code or phone number is missing from the input string.
- * @throws {Error} If the provided country code and prefix combination is invalid.
- * @throws {Error} If the provided country code is invalid.
- * @throws {Error} If the provided country code has a prefix but none is supplied in the input.
+ * @throws {Error} If the phone number is invalid or if no country mask is found for the parsed country.
  *
  * @example
  * ```typescript
- * import { formatToPhone } from "./formatToPhone";
- *
- * const formattedPhone1 = formatToPhone("+55 11912345678");
- * console.log(formattedPhone1); // Output: "(11) 91234-5678" (brazilian phone number format)
- *
- * const formattedPhone2 = formatToPhone("+1-123 4567890");
- * console.log(formattedPhone2); // Output: "(123) 456-7890" (us phone number format)
+ * console.log(formatToPhone("+5534920524282")); // Output: "(34) 92052-4282" (Brazilian format)
+ * console.log(formatToPhone("+553420524282")); // Output: "(34) 2052-4282" (Brazilian format with optional ninth digit)
+ * console.log(formatToPhone("+12125550199")); // Output: "(212) 555-0199" (American Samoa format)
  * ```
  */
-declare const formatToPhone: FormatToPhoneFunction;
+declare function formatToPhone(phoneNumber: string): string;
 export { formatToPhone };
 //# sourceMappingURL=formatToPhone.d.ts.map

package/dist/formats/formatToPhone.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formatToPhone.d.ts","sourceRoot":"","sources":["../../src/formats/formatToPhone.ts"],"names":[],"mappings":"AAaA,KAAK,qBAAqB,GAAG,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;AAmG3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,QAAA,MAAM,aAAa,EAAE,qBAwBpB,CAAC;AAEF,OAAO,EAAE,aAAa,EAAE,CAAC"}
+{"version":3,"file":"formatToPhone.d.ts","sourceRoot":"","sources":["../../src/formats/formatToPhone.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,iBAAS,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CA0BlD;AAED,OAAO,EAAE,aAAa,EAAE,CAAC"}

package/dist/formats/formatToPhone.js

@@ -1,131 +1,44 @@
-import { countries } from "@arkyn/templates";
-import { removeNonNumeric } from "../utilities/removeNonNumeric";
-function getMask(value) {
-    const mask = value.length > 10 ? "NINE" : "EIGHT";
-    return mask;
-}
-const TYPES = {
-    EIGHT: "(99) 9999-9999",
-    NINE: "(99) 99999-9999",
-};
-const MAX_LENGTH = removeNonNumeric(TYPES.NINE).length;
-function applyMask(value, maskPattern) {
-    let result = "";
-    let digitIndex = 0;
-    for (let i = 0; i < maskPattern.length; i++) {
-        if (maskPattern[i] === "9") {
-            if (digitIndex < value.length) {
-                result += value[digitIndex];
-                digitIndex++;
-            }
-            else {
-                break;
-            }
-        }
-        else {
-            if (digitIndex < value.length) {
-                result += maskPattern[i];
-            }
-            else {
-                break;
-            }
-        }
-    }
-    return result;
-}
-function formatPhoneNumber(phoneNumber, country) {
-    if (country.code === "+55") {
-        let value = removeNonNumeric(phoneNumber);
-        const mask = getMask(value);
-        let nextLength = value.length;
-        if (nextLength > MAX_LENGTH)
-            return value;
-        value = applyMask(value, TYPES[mask]);
-        return value;
-    }
-    const mask = country.mask;
-    let formattedNumber = mask;
-    if (country.prefix) {
-        const prefixRegex = /\$+/g;
-        formattedNumber = formattedNumber.replace(prefixRegex, country.prefix);
-    }
-    for (let i = 0, j = 0; i < formattedNumber.length && j < phoneNumber.length; i++) {
-        if (formattedNumber[i] === "_") {
-            formattedNumber =
-                formattedNumber.substring(0, i) +
-                    phoneNumber[j] +
-                    formattedNumber.substring(i + 1);
-            j++;
-        }
-    }
-    return formattedNumber;
-}
-function getCountryWithPrefixCode(countryCode, prefix) {
-    const country = countries.find((country) => country.code === countryCode && country.prefix === prefix);
-    if (!country)
-        throw new Error("Invalid country code or prefix");
-    if (country.prefix !== prefix) {
-        throw new Error("Invalid country code or prefix");
-    }
-    if (!country.prefix) {
-        throw new Error("Invalid country code or prefix");
-    }
-    return country;
-}
-function getCountryWithoutPrefixCode(countryCode) {
-    const country = countries.find((country) => country.code === countryCode);
-    if (!country)
-        throw new Error("Invalid country code");
-    if (country.prefix)
-        throw new Error("Invalid country code");
-    return country;
-}
+import { parsePhoneNumberWithError } from "libphonenumber-js";
+import { findCountryMask } from "../utilities/findCountryMask";
 /**
- * Formats a phone number string based on the provided country code and optional prefix.
+ * Formats a phone number string according to the country mask defined in `@arkyn/templates`.
  *
- * The input string should follow the format: `"<countryCode>-<prefix> <phoneNumber>"` or `"<countryCode> <phoneNumber>"`.
- * The function determines the appropriate formatting mask based on the country and applies it to the phone number.
+ * The function parses the input using libphonenumber-js to determine the country and
+ * national number, then applies the corresponding country's mask (underscore `_` used
+ * as digit placeholder) replacing placeholders with actual digits.
  *
- * @param prop - The phone number string to be formatted. It must include the country code and optionally a prefix.
- *               Example formats:
- *               - "+55 32912345678"
- *               - "+1 1234567890"
+ * @param {string} phoneNumber - The input phone number (can include country code or be in national format).
  *
- * @returns The formatted phone number string based on the country's formatting rules.
+ * @returns {string} The phone number formatted following the country's mask.
  *
- * @throws {Error} If the input phone number does not match the expected format.
- * @throws {Error} If the country code or phone number is missing from the input string.
- * @throws {Error} If the provided country code and prefix combination is invalid.
- * @throws {Error} If the provided country code is invalid.
- * @throws {Error} If the provided country code has a prefix but none is supplied in the input.
+ * @throws {Error} If the phone number is invalid or if no country mask is found for the parsed country.
  *
  * @example
  * ```typescript
- * import { formatToPhone } from "./formatToPhone";
- *
- * const formattedPhone1 = formatToPhone("+55 11912345678");
- * console.log(formattedPhone1); // Output: "(11) 91234-5678" (brazilian phone number format)
- *
- * const formattedPhone2 = formatToPhone("+1-123 4567890");
- * console.log(formattedPhone2); // Output: "(123) 456-7890" (us phone number format)
+ * console.log(formatToPhone("+5534920524282")); // Output: "(34) 92052-4282" (Brazilian format)
+ * console.log(formatToPhone("+553420524282")); // Output: "(34) 2052-4282" (Brazilian format with optional ninth digit)
+ * console.log(formatToPhone("+12125550199")); // Output: "(212) 555-0199" (American Samoa format)
  * ```
  */
-const formatToPhone = (prop) => {
-    const phoneRegex = /^\+\d{1,4}(-\d{1,4})? \d+$/;
-    if (!phoneRegex.test(prop)) {
-        throw new Error("Invalid phone number format. Expected format: +<countryCode>-<optionalPrefix> <phoneNumber>");
-    }
-    const countryCode = prop.split(" ")[0].split("-")[0];
-    const prefixCode = prop.split(" ")[0].split("-")[1];
-    const phoneNumber = prop.split(" ")[1];
-    if (!countryCode || !phoneNumber) {
-        throw new Error("Invalid phone number format");
+function formatToPhone(phoneNumber) {
+    try {
+        const parsedPhone = parsePhoneNumberWithError(phoneNumber);
+        const phoneNumberDigits = parsedPhone.nationalNumber.toString();
+        let formattedNumber = findCountryMask(phoneNumber)[0];
+        for (let i = 0, j = 0; i < formattedNumber.length && j < phoneNumberDigits.length; i++) {
+            if (formattedNumber[i] === "_") {
+                formattedNumber =
+                    formattedNumber.substring(0, i) +
+                        phoneNumberDigits[j] +
+                        formattedNumber.substring(i + 1);
+                j++;
+            }
+        }
+        return formattedNumber;
     }
-    if (prefixCode) {
-        const country = getCountryWithPrefixCode(countryCode, prefixCode);
-        return formatPhoneNumber(phoneNumber, country);
+    catch (rawError) {
+        const error = rawError;
+        throw new Error(error.message);
     }
-    const country = getCountryWithoutPrefixCode(countryCode);
-    return formatPhoneNumber(phoneNumber, country);
-};
+}
 export { formatToPhone };

package/dist/index.d.ts

@@ -18,6 +18,7 @@ export { parseToDate } from "./parsers/parseToDate";
 export { ValidateDateService } from "./services/validateDateService";
 export { calculateCardInstallment } from "./utilities/calculateCardInstallment";
 export { ensureQuotes } from "./utilities/ensureQuotes";
+export { findCountryMask } from "./utilities/findCountryMask";
 export { isHtml } from "./utilities/isHtml";
 export { removeCurrencySymbols } from "./utilities/removeCurrencySymbols";
 export { removeNonNumeric } from "./utilities/removeNonNumeric";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EAAE,iCAAiC,EAAE,MAAM,6CAA6C,CAAC;AAChG,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAGxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAGzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAGrE,OAAO,EAAE,wBAAwB,EAAE,MAAM,sCAAsC,CAAC;AAChF,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EAAE,iCAAiC,EAAE,MAAM,6CAA6C,CAAC;AAChG,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAGxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAGzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAGrE,OAAO,EAAE,wBAAwB,EAAE,MAAM,sCAAsC,CAAC;AAChF,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/index.js

@@ -23,6 +23,7 @@ export { ValidateDateService } from "./services/validateDateService";
 // utilities
 export { calculateCardInstallment } from "./utilities/calculateCardInstallment";
 export { ensureQuotes } from "./utilities/ensureQuotes";
+export { findCountryMask } from "./utilities/findCountryMask";
 export { isHtml } from "./utilities/isHtml";
 export { removeCurrencySymbols } from "./utilities/removeCurrencySymbols";
 export { removeNonNumeric } from "./utilities/removeNonNumeric";

package/dist/parsers/parseToDate.d.ts

@@ -5,7 +5,7 @@
  * **Note:** This function works with UTC+0 by default. The returned Date object is not automatically converted to the machine's local timezone.
  * To adjust the timezone, you must manually specify the `timezone` parameter (e.g., -3 for UTC-3).
  *
- * @param {[string, string]} dateTime - An array containing the date and optional time.
+ * @param {string[]} dateTime - An array containing the date and optional time.
  *   - The first element is the date string.
  *   - The second element is the time string (default is "00:00:00")
  * @param {"brazilianDate" | "isoDate" | "timestamp"} inputFormat - The format of the input date.
@@ -36,6 +36,6 @@
  * console.log(date); // Outputs a Date object for "2023-12-25T15:30:00.000Z" (UTC)
  * ```
  */
-declare function parseToDate([date, time]: [string, string?], inputFormat: "brazilianDate" | "isoDate" | "timestamp", timezone?: number): Date;
+declare function parseToDate([date, time]: string[], inputFormat: "brazilianDate" | "isoDate" | "timestamp", timezone?: number): Date;
 export { parseToDate };
 //# sourceMappingURL=parseToDate.d.ts.map

package/dist/parsers/parseToDate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parseToDate.d.ts","sourceRoot":"","sources":["../../src/parsers/parseToDate.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,iBAAS,WAAW,CAClB,CAAC,IAAI,EAAE,IAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAC5C,WAAW,EAAE,eAAe,GAAG,SAAS,GAAG,WAAW,EACtD,QAAQ,GAAE,MAAU,GACnB,IAAI,CAkCN;AAED,OAAO,EAAE,WAAW,EAAE,CAAC"}
+{"version":3,"file":"parseToDate.d.ts","sourceRoot":"","sources":["../../src/parsers/parseToDate.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,iBAAS,WAAW,CAClB,CAAC,IAAI,EAAE,IAAiB,CAAC,EAAE,MAAM,EAAE,EACnC,WAAW,EAAE,eAAe,GAAG,SAAS,GAAG,WAAW,EACtD,QAAQ,GAAE,MAAU,GACnB,IAAI,CAkCN;AAED,OAAO,EAAE,WAAW,EAAE,CAAC"}

package/dist/parsers/parseToDate.js

@@ -6,7 +6,7 @@ import { ValidateDateService } from "../services/validateDateService";
  * **Note:** This function works with UTC+0 by default. The returned Date object is not automatically converted to the machine's local timezone.
  * To adjust the timezone, you must manually specify the `timezone` parameter (e.g., -3 for UTC-3).
  *
- * @param {[string, string]} dateTime - An array containing the date and optional time.
+ * @param {string[]} dateTime - An array containing the date and optional time.
  *   - The first element is the date string.
  *   - The second element is the time string (default is "00:00:00")
  * @param {"brazilianDate" | "isoDate" | "timestamp"} inputFormat - The format of the input date.

package/dist/utilities/findCountryMask.d.ts

@@ -0,0 +1,45 @@
+import { type CountryType } from "@arkyn/templates";
+/**
+ * Finds and returns the phone mask for a given phone number based on the project's
+ * country templates (masks use "_" as digit placeholders).
+ *
+ * The function typically:
+ * - Parses the provided phone number to determine the country (using libphonenumber-js).
+ * - Looks up the corresponding country mask in the `@arkyn/templates` list.
+ * - Returns the mask string (e.g. "(__) _____-____") to be used for formatting.
+ *
+ * @param {string} phoneNumber - The input phone number (can include country code or be in national format).
+ * @returns {string} The country mask string containing "_" placeholders for digits.
+ *
+ * @throws {Error} If the phone number is invalid or if no mask is found for the parsed country.
+ *
+ * @example
+ * ```typescript
+ * console.log(findCountryMask("+5511999999999"));
+ * // output:
+ * [
+ *  ["(__) _____-____", ["(__) ____-____"]],
+ *  {
+ *    name: "Brazil",
+ *    code: "+55",
+ *    iso: "BR",
+ *    flag: "🇧🇷",
+ *    mask: ["(__) _____-____", ["(__) ____-____"]] }
+ * ]
+ *
+ * console.log(findCountryMask("+19700000000"));
+ * // output:
+ * [
+ *  "(___) ___-____",
+ *  {
+ *    name: "United States",
+ *    code: "+1",
+ *    iso: "US",
+ *    flag: "🇺🇸",
+ *    mask: "(___) ___-____" }
+ * ]
+ * ```
+ */
+declare function findCountryMask(phoneNumber: string): [string, CountryType];
+export { findCountryMask };
+//# sourceMappingURL=findCountryMask.d.ts.map

package/dist/utilities/findCountryMask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"findCountryMask.d.ts","sourceRoot":"","sources":["../../src/utilities/findCountryMask.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAI/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,iBAAS,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CA+BnE;AAED,OAAO,EAAE,eAAe,EAAE,CAAC"}

package/dist/utilities/findCountryMask.js

@@ -0,0 +1,73 @@
+import { countries } from "@arkyn/templates";
+import { parsePhoneNumberWithError } from "libphonenumber-js";
+import { removeNonNumeric } from "./removeNonNumeric";
+/**
+ * Finds and returns the phone mask for a given phone number based on the project's
+ * country templates (masks use "_" as digit placeholders).
+ *
+ * The function typically:
+ * - Parses the provided phone number to determine the country (using libphonenumber-js).
+ * - Looks up the corresponding country mask in the `@arkyn/templates` list.
+ * - Returns the mask string (e.g. "(__) _____-____") to be used for formatting.
+ *
+ * @param {string} phoneNumber - The input phone number (can include country code or be in national format).
+ * @returns {string} The country mask string containing "_" placeholders for digits.
+ *
+ * @throws {Error} If the phone number is invalid or if no mask is found for the parsed country.
+ *
+ * @example
+ * ```typescript
+ * console.log(findCountryMask("+5511999999999"));
+ * // output:
+ * [
+ *  ["(__) _____-____", ["(__) ____-____"]],
+ *  {
+ *    name: "Brazil",
+ *    code: "+55",
+ *    iso: "BR",
+ *    flag: "🇧🇷",
+ *    mask: ["(__) _____-____", ["(__) ____-____"]] }
+ * ]
+ *
+ * console.log(findCountryMask("+19700000000"));
+ * // output:
+ * [
+ *  "(___) ___-____",
+ *  {
+ *    name: "United States",
+ *    code: "+1",
+ *    iso: "US",
+ *    flag: "🇺🇸",
+ *    mask: "(___) ___-____" }
+ * ]
+ * ```
+ */
+function findCountryMask(phoneNumber) {
+    try {
+        const parsedPhone = parsePhoneNumberWithError(phoneNumber);
+        const countryCode = parsedPhone?.country;
+        if (!countryCode)
+            throw new Error("Invalid phone number");
+        const country = countries.find((c) => c.iso === countryCode);
+        if (!country)
+            throw new Error("Phone number country not supported");
+        if (typeof country.mask === "string")
+            return [country.mask, country];
+        const maskForLength = country.mask.find((mask) => {
+            const maskDigits = mask.replace(/[^_]/g, "");
+            const phoneDigits = removeNonNumeric(parsedPhone.nationalNumber);
+            const maskDigitsCount = maskDigits.length;
+            const phoneDigitsCount = phoneDigits.length;
+            return maskDigitsCount === phoneDigitsCount;
+        });
+        if (!maskForLength) {
+            throw new Error("No mask found for the given phone number length");
+        }
+        return [maskForLength, country];
+    }
+    catch (rawError) {
+        const error = rawError;
+        throw new Error(error.message);
+    }
+}
+export { findCountryMask };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkyn/shared",
-  "version": "3.0.1-beta.121",
+  "version": "3.0.1-beta.123",
   "main": "./dist/bundle.js",
   "module": "./dist/bundle.js",
   "type": "module",
@@ -31,6 +31,7 @@
     "typecheck": "bunx tsc --project tsconfig.json --noEmit"
   },
   "dependencies": {
+    "libphonenumber-js": "^1.12.37",
     "uuid": "^10.0.0"
   },
   "devDependencies": {