@arkyn/shared 1.4.52 → 2.0.1-beta.1

package/src/formats/formatJsonObject.ts

@@ -1,35 +1,77 @@
-function formatJsonObject(obj: any, indentLevel: number): string {
+import type { FormatJsonObjectFunction } from "@arkyn/types";
+
+/**
+ * Formats a JSON object into a human-readable string with proper indentation.
+ *
+ * @param obj - The JSON object or value to format. It can be an object, array, string, or primitive value.
+ * @param indentLevel - The current level of indentation to apply. This is used recursively to format nested structures.
+ * @returns A formatted string representation of the JSON object.
+ *
+ * @remarks
+ * - If the input is an object, it will be formatted with keys and values properly indented.
+ * - If the input is an array, each element will be formatted and indented on a new line.
+ * - If the input is a string that can be parsed as JSON, it will attempt to parse and format it.
+ * - Primitive values (e.g., numbers, booleans, null) will be converted to their string representation.
+ *
+ * @example
+ * ```typescript
+ * const obj = { name: "John", age: 30, hobbies: ["reading", "gaming"] };
+ * const formatted = formatJsonObject(obj, 0);
+ * console.log(formatted);
+ * // Output:
+ * // {
+ * //   "name": "John",
+ * //   "age": 30,
+ * //   "hobbies": [
+ * //     "reading",
+ * //     "gaming"
+ * //   ]
+ * // }
+ * ```
+ */
+
+const formatJsonObject: FormatJsonObjectFunction = (obj, indentLevel) => {
   const indent = "  ".repeat(indentLevel);
   let formattedString = "";
 
   if (typeof obj === "object" && obj !== null) {
     if (Array.isArray(obj)) {
-      formattedString += "[\n";
-      obj.forEach((item, index) => {
-        formattedString +=
-          indent + "  " + formatJsonObject(item, indentLevel + 1);
-        if (index < obj.length - 1) {
-          formattedString += ",";
-        }
-        formattedString += "\n";
-      });
-      formattedString += indent + "]";
+      if (obj.length === 0) {
+        // Caso especial para arrays vazios
+        formattedString += "[]";
+      } else {
+        formattedString += "[\n";
+        obj.forEach((item, index) => {
+          formattedString +=
+            indent + "  " + formatJsonObject(item, indentLevel + 1);
+          if (index < obj.length - 1) {
+            formattedString += ",";
+          }
+          formattedString += "\n";
+        });
+        formattedString += indent + "]";
+      }
     } else {
-      formattedString += "{\n";
       const keys = Object.keys(obj);
-      keys.forEach((key, index) => {
-        formattedString +=
-          indent +
-          '  "' +
-          key +
-          '": ' +
-          formatJsonObject(obj[key], indentLevel + 1);
-        if (index < keys.length - 1) {
-          formattedString += ",";
-        }
-        formattedString += "\n";
-      });
-      formattedString += indent + "}";
+      if (keys.length === 0) {
+        // Caso especial para objetos vazios
+        formattedString += "{}";
+      } else {
+        formattedString += "{\n";
+        keys.forEach((key, index) => {
+          formattedString +=
+            indent +
+            '  "' +
+            key +
+            '": ' +
+            formatJsonObject(obj[key], indentLevel + 1);
+          if (index < keys.length - 1) {
+            formattedString += ",";
+          }
+          formattedString += "\n";
+        });
+        formattedString += indent + "}";
+      }
     }
   } else if (typeof obj === "string") {
     try {
@@ -43,6 +85,6 @@ function formatJsonObject(obj: any, indentLevel: number): string {
   }
 
   return formattedString;
-}
+};
 
 export { formatJsonObject };

package/src/formats/formatJsonString.ts

@@ -1,13 +1,49 @@
+import type { FormatJsonStringFunction } from "@arkyn/types";
 import { formatJsonObject } from "./formatJsonObject";
 
-function formatJsonString(jsonString: string): string {
+/**
+ * Formats a JSON string into a more readable format.
+ *
+ * This function attempts to parse the provided JSON string into a JavaScript object,
+ * and then formats it using the `formatJsonObject` function. If the input string
+ * is not a valid JSON, it logs an error to the console and returns an empty string.
+ *
+ * @param jsonString - The JSON string to be formatted.
+ * @returns A formatted JSON string, or an empty string if the input is invalid.
+ *
+ * @throws Will log an error to the console if the input is not a valid JSON string.
+ *
+ * @example
+ * ```typescript
+ * const jsonString = '{"name":"John","age":30,"hobbies":["reading","gaming"]}';
+ * const formatted = formatJsonString(jsonString);
+ * console.log(formatted);
+ * // Output:
+ * // {
+ * //   "name": "John",
+ * //   "age": 30,
+ * //   "hobbies": [
+ * //     "reading",
+ * //     "gaming"
+ * //   ]
+ * // }
+
+ * const invalidJsonString = '{"name":"John", "age":30,';
+ * const formatted = formatJsonString(invalidJsonString);
+ * console.log(formatted);
+ * // Output:
+ * // (Logs "Invalid JSON string: ..." to the console)
+ * // ""
+ * ```
+ */
+
+const formatJsonString: FormatJsonStringFunction = (jsonString) => {
   try {
     const jsonObject = JSON.parse(jsonString);
     return formatJsonObject(jsonObject, 0);
   } catch (error) {
-    console.error("Invalid JSON string:", error);
-    return "";
+    throw new Error(`Invalid JSON string \n ${error}`);
   }
-}
+};
 
 export { formatJsonString };

package/src/formats/formatToCep.ts

@@ -1,10 +1,38 @@
-function formatToCep(value: string): string {
-  const cleaned = value.replace(/\D/g, "");
+import type { FormatToCepFunction } from "@arkyn/types";
+import { removeNonNumeric } from "../services/removeNonNumeric";
+
+/**
+ * Formats a given string into a Brazilian postal code (CEP) format.
+ *
+ * The function removes all non-numeric characters from the input string
+ * and attempts to format it as a CEP in the pattern `XXXXX-XXX`.
+ * If the input does not match the expected format, an error is thrown.
+ *
+ * @param value - The input string to be formatted as a CEP.
+ * @returns The formatted CEP string in the pattern `XXXXX-XXX`.
+ * @throws {Error} If the input does not match the expected CEP format.
+ *
+ * @example
+ * ```typescript
+ * import { formatToCep } from "./formatToCep";
+ *
+ * const formattedCep = formatToCep("12345678");
+ * console.log(formattedCep); // Output: "12345-678"
+ *
+ * try {
+ *   formatToCep("1234");
+ * } catch (error) {
+ *   console.error(error.message); // Output: "Invalid CEP format"
+ * }
+ * ```
+ */
+
+const formatToCep: FormatToCepFunction = (value) => {
+  const cleaned = removeNonNumeric(value);
   const match = cleaned.match(/^(\d{5})(\d{3})$/);
-  if (match) {
-    return `${match[1]}-${match[2]}`;
-  }
-  return value;
-}
+
+  if (match) return `${match[1]}-${match[2]}`;
+  throw new Error("Invalid CEP format");
+};
 
 export { formatToCep };

package/src/formats/formatToCnpj.ts

@@ -0,0 +1,39 @@
+import type { FormatToCnpjFunction } from "@arkyn/types";
+import { removeNonNumeric } from "../services/removeNonNumeric";
+
+/**
+ * Formats a given string or number into a CNPJ (Cadastro Nacional da Pessoa Jurídica) format.
+ *
+ * The CNPJ format is: `XX.XXX.XXX/XXXX-XX`, where `X` represents a digit.
+ *
+ * @param value - The input value to be formatted. It can be a string or number containing the CNPJ digits.
+ *                Non-numeric characters will be removed before formatting.
+ *
+ * @returns A string formatted as a CNPJ.
+ *
+ * @throws {Error} Throws an error if the input does not contain exactly 14 numeric digits.
+ *
+ * @example
+ * ```typescript
+ * import { formatToCnpj } from "./formatToCNPJ";
+ *
+ * const formattedCnpj = formatToCnpj("12345678000195");
+ * console.log(formattedCnpj); // Output: "12.345.678/0001-95"
+ *
+ * try {
+ *   formatToCnpj("12345");
+ * } catch (error) {
+ *   console.error(error.message); // Output: "Invalid CNPJ length"
+ * }
+ * ```
+ */
+
+const formatToCnpj: FormatToCnpjFunction = (value) => {
+  const cleaned = removeNonNumeric(value);
+  const match = cleaned.match(/^(\d{2})(\d{3})(\d{3})(\d{4})(\d{2})$/);
+  if (match)
+    return `${match[1]}.${match[2]}.${match[3]}/${match[4]}-${match[5]}`;
+  throw new Error("Invalid CNPJ length");
+};
+
+export { formatToCnpj };

package/src/formats/formatToCpf.ts

@@ -0,0 +1,39 @@
+import type { FormatToCpfFunction } from "@arkyn/types";
+import { removeNonNumeric } from "../services/removeNonNumeric";
+
+/**
+ * Formats a given string into a CPF (Cadastro de Pessoas Físicas) format.
+ * 
+ * A CPF is a Brazilian individual taxpayer registry identification format.
+ * This function ensures the input is cleaned of non-numeric characters and
+ * then formats it into the standard CPF format: `XXX.XXX.XXX-XX`.
+ *
+ * @param value - The input string to be formatted as a CPF.
+ * @returns The formatted CPF string.
+ * @throws {Error} If the input string does not match the expected CPF format.
+ *
+ * @example
+ * ```typescript
+ * import { formatToCpf } from "./formatToCPF";
+ *
+ * const formattedCpf = formatToCpf("12345678909");
+ * console.log(formattedCpf); // Output: "123.456.789-09"
+
+ * try {
+ *   const formattedCpf = formatToCpf("12345");
+ * } catch (error) {
+ *   console.error(error.message); // Output: "Invalid CPF format"
+ * }
+ * 
+ * ```
+ */
+
+const formatToCpf: FormatToCpfFunction = (value) => {
+  const cleaned = removeNonNumeric(value);
+  const match = cleaned.match(/^(\d{3})(\d{3})(\d{3})(\d{2})$/);
+
+  if (match) return `${match[1]}.${match[2]}.${match[3]}-${match[4]}`;
+  throw new Error("Invalid CPF format");
+};
+
+export { formatToCpf };

package/src/formats/formatToCpfCnpj.ts

@@ -1,14 +1,38 @@
-import { formatToCNPJ } from "./formatToCNPJ";
-import { formatToCPF } from "./formatToCPF";
+import type { FormatToCpfCnpjFunction } from "@arkyn/types";
 
-function formatToCpfCnpj(value: string): string {
+import { formatToCnpj } from "./formatToCnpj";
+import { formatToCpf } from "./formatToCpf";
+
+/**
+ * Formats a given string value into either a CPF or CNPJ format based on its length.
+ *
+ * - If the input contains 11 numeric characters, it is formatted as a CPF.
+ * - If the input contains 14 numeric characters, it is formatted as a CNPJ.
+ * - Throws an error if the input length is neither 11 nor 14 after removing non-numeric characters.
+ *
+ * @param value - The string value to be formatted. It may contain non-numeric characters, which will be removed.
+ * @returns The formatted CPF or CNPJ string.
+ * @throws {Error} If the input does not have a valid CPF or CNPJ length.
+ *
+ * @example
+ * ```typescript
+ * formatToCpfCnpj("123.456.789-09"); // Returns "123.456.789-09" (CPF format)
+ * formatToCpfCnpj("12.345.678/0001-95"); // Returns "12.345.678/0001-95" (CNPJ format)
+ * formatToCpfCnpj("12345678909"); // Returns "123.456.789-09" (CPF format)
+ * formatToCpfCnpj("12345678000195"); // Returns "12.345.678/0001-95" (CNPJ format)
+ * formatToCpfCnpj("123"); // Throws an error: "Invalid CPF or CNPJ length"
+ * ```
+ */
+
+const formatToCpfCnpj: FormatToCpfCnpjFunction = (value) => {
   const cleaned = value.replace(/\D/g, "");
   if (cleaned.length === 11) {
-    return formatToCPF(cleaned);
+    return formatToCpf(cleaned);
   } else if (cleaned.length === 14) {
-    return formatToCNPJ(cleaned);
+    return formatToCnpj(cleaned);
   }
-  return value;
-}
+
+  throw new Error("Invalid CPF or CNPJ length");
+};
 
 export { formatToCpfCnpj };

package/src/formats/formatToCurrency.ts

@@ -0,0 +1,53 @@
+import { countryCurrencies } from "@arkyn/templates";
+import type { FormatToCurrency } from "@arkyn/types";
+
+import { removeCurrencySymbols } from "../services/removeCurrencySymbols";
+
+/**
+ * Formats a numeric value into a currency string based on the specified currency and configuration.
+ *
+ * @param value - The numeric value to be formatted.
+ * @param currency - The currency code used to determine the formatting style.
+ * @param config - Optional configuration object.
+ * @param config.showPrefix - Determines whether the currency symbol/prefix should be included in the formatted string. Defaults to `true`.
+ *
+ * @returns A formatted currency string. If `config.showPrefix` is `false`, the currency symbol is removed.
+ *
+ * @example
+ * ```typescript
+ * const formatted = formatToCurrency(1234.56, "USD", { showPrefix: true });
+ * console.log(formatted); // "$1,234.56"
+ *
+ * const withoutPrefix = formatToCurrency(1234.56, "USD", { showPrefix: false });
+ * console.log(withoutPrefix); // "1,234.56"
+ *
+ * const formattedBRL = formatToCurrency(1234.56, "BRL", { showPrefix: true });
+ * console.log(formattedBRL); // "R$ 1.234,56"
+ *
+ * const withoutPrefixBRL = formatToCurrency(1234.56, "BRL", { showPrefix: false });
+ * console.log(withoutPrefixBRL); // "1.234,56"
+ * ```
+ */
+
+const formatToCurrency: FormatToCurrency = (
+  value,
+  currency,
+  config = { showPrefix: true }
+) => {
+  if (!countryCurrencies[currency]) {
+    throw new Error("Unsupported currency code");
+  }
+
+  const { countryCurrency, countryLanguage } = countryCurrencies[currency];
+
+  const format = new Intl.NumberFormat(countryLanguage, {
+    style: "currency",
+    currency: countryCurrency,
+  }).format(value);
+
+  return config.showPrefix
+    ? format.replace(/\s/g, " ")
+    : removeCurrencySymbols(format).replace(/\s/g, " ");
+};
+
+export { formatToCurrency };

package/src/formats/formatToEllipsis.ts

@@ -1,5 +1,25 @@
-function formatToEllipsis(text: string, size = 40): string {
-  return text.length > size ? `${text.substring(0, size)}...` : text;
-}
+import type { FormatToEllipsisFunction } from "@arkyn/types";
+
+/**
+ * Truncates a given text to a specified maximum length and appends an ellipsis ("...")
+ * if the text exceeds the maximum length.
+ *
+ * @param text - The input string to be truncated.
+ * @param maxLength - The maximum allowed length of the string before truncation.
+ * @returns The truncated string with an ellipsis if the input exceeds the maximum length,
+ *          or the original string if it does not.
+ * @example
+ * const result = formatToEllipsis("Hello, world!", 5);
+ * console.log(result); // Output: "Hello..."
+ */
+
+const formatToEllipsis: FormatToEllipsisFunction = (text, maxLength) => {
+  if (text.length > maxLength) {
+    let trimmedText = text.substring(0, maxLength).trimEnd();
+    trimmedText = trimmedText.replace(/[.,!?;:]$/, "");
+    return `${trimmedText}...`;
+  }
+  return text;
+};
 
 export { formatToEllipsis };

package/src/formats/formatToHiddenDigits.ts

@@ -1,12 +1,80 @@
-import type { FormatToHiddenDigitsOptions } from "@arkyn/types";
+import type { FormatToHiddenDigitsFunction } from "@arkyn/types";
 
-import { parseToCharacters } from "../parsers/parseToCharacters";
-import { normalizeRange, within } from "../services/range";
+const DIGIT = /^\d$/;
 
-const formatToHiddenDigits = (
-  value: string,
-  options: FormatToHiddenDigitsOptions = {}
-): string => {
+type DigitCharacterNode = {
+  kind: "digit";
+  digit: number;
+  character: string;
+};
+
+type OtherCharacterNode = {
+  kind: "other";
+  character: string;
+};
+
+type RootCharacterNode = {
+  kind: "root";
+  digits: number;
+  children: (DigitCharacterNode | OtherCharacterNode)[];
+};
+
+const parseToCharacters = (value: string): RootCharacterNode => {
+  let digits = 0;
+
+  const children = value
+    .split("")
+    .map((character: string): DigitCharacterNode | OtherCharacterNode => {
+      if (DIGIT.test(character))
+        return { character, kind: "digit", digit: ++digits };
+      return { character, kind: "other" };
+    });
+
+  return { digits, children, kind: "root" };
+};
+
+const normalizeRange = (
+  range: number | [number, number],
+  limit: number
+): [number, number] => {
+  if (Array.isArray(range)) return range;
+  if (range >= 0) return [0, range];
+  return [limit + 1 - Math.abs(range), limit];
+};
+
+const within = (range: [number, number], value: number): boolean =>
+  value >= range[0] && value <= range[1];
+
+/**
+ * Formats a string by hiding specific digits within a given range.
+ *
+ * This function takes a string input and replaces digits within a specified range
+ * with a hiding character (e.g., "*"). Non-digit characters remain unchanged.
+ *
+ * @param value - The input string to be formatted.
+ * @param options - Configuration options for formatting.
+ * @param options.range - The range of digits to hide. It can be:
+ *   - A single number (e.g., `3`), which hides the first `n` digits if positive,
+ *     or the last `n` digits if negative.
+ *   - A tuple `[start, end]` specifying the range of digits to hide (inclusive).
+ *   - Defaults to `3`, hiding the first three digits.
+ * @param options.hider - The character used to hide digits. Defaults to `"*"`.
+ *
+ * @returns The formatted string with specified digits hidden.
+ *
+ * @example
+ * ```typescript
+ * import { formatToHiddenDigits } from "./formatToHiddenDigits";
+ *
+ * formatToHiddenDigits("123-456-7890", { range: 3 });
+ * // Output: "***-456-7890"
+ *
+ * formatToHiddenDigits("123-456-7890", { range: [4, 6], hider: "#" });
+ * // Output: "123-###-7890"
+ * ```
+ */
+
+const formatToHiddenDigits: FormatToHiddenDigitsFunction = (value, options) => {
   const characters = parseToCharacters(value);
   const range = normalizeRange(options.range ?? 3, characters.digits);
   return characters.children

package/src/formats/formatToPhone.ts

@@ -1,10 +1,160 @@
-function formatToPhone(value: string): string {
-  const cleaned = value.replace(/\D/g, "");
-  const match = cleaned.match(/^(\d{2})(\d{5})(\d{4})$/);
-  if (match) {
-    return `(${match[1]}) ${match[2]}-${match[3]}`;
+import { countries } from "@arkyn/templates";
+import type { CountryType, FormatToPhoneFunction } from "@arkyn/types";
+
+import { removeNonNumeric } from "../services/removeNonNumeric";
+
+function getMask(value: string): "NINE" | "EIGTH" {
+  const mask = value.length > 10 ? "NINE" : "EIGTH";
+  return mask;
+}
+
+const TYPES = {
+  EIGTH: "(99) 9999-9999",
+  NINE: "(99) 99999-9999",
+};
+
+const MAX_LENGTH = removeNonNumeric(TYPES.NINE).length;
+
+function applyMask(value: string, maskPattern: string) {
+  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: string, country: CountryType): string {
+  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] as "EIGTH" | "NINE");
+    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: string, prefix: string) {
+  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");
   }
-  return value;
+
+  if (!country.prefix) {
+    throw new Error("Invalid country code or prefix");
+  }
+  return country;
 }
 
+function getCountryWithoutPrefixCode(countryCode: string) {
+  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;
+}
+
+/**
+ * Formats a phone number string based on the provided country code and optional prefix.
+ *
+ * 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.
+ *
+ * @param prop - The phone number string to be formatted. It must include the country code and optionally a prefix.
+ *               Example formats:
+ *               - "+55-11 912345678"
+ *               - "+1 1234567890"
+ *
+ * @returns The formatted phone number string based on the country's formatting rules.
+ *
+ * @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.
+ *
+ * @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)
+ * ```
+ */
+
+const formatToPhone: FormatToPhoneFunction = (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");
+  }
+
+  if (prefixCode) {
+    const country = getCountryWithPrefixCode(countryCode, prefixCode);
+    return formatPhoneNumber(phoneNumber, country);
+  }
+
+  const country = getCountryWithoutPrefixCode(countryCode);
+  return formatPhoneNumber(phoneNumber, country);
+};
+
 export { formatToPhone };