@arkyn/shared 1.4.52 → 1.4.55

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 };

package/src/generators/generateColorByString.ts

@@ -1,8 +1,22 @@
-function generateColorByString(string: string) {
+import type { GenerateColorByStringFunction } from "@arkyn/types";
+
+/**
+ * Generates a hexadecimal color code based on the input string.
+ * The function creates a hash from the string and uses it to calculate
+ * RGB values, which are then converted to a hexadecimal color code.
+ *
+ * @param prop - The input string used to generate the color.
+ * @returns A hexadecimal color code (e.g., "#a1b2c3") derived from the input string.
+ * @example
+ * const color = generateColorByString("example");
+ * console.log(color); // Outputs a consistent hex color like "#5e8f9a"
+ */
+
+const generateColorByString: GenerateColorByStringFunction = (prop) => {
   var hash = 0;
 
-  for (var i = 0; i < string.length; i++) {
-    hash = string.charCodeAt(i) + ((hash << 5) - hash);
+  for (var i = 0; i < prop.length; i++) {
+    hash = prop.charCodeAt(i) + ((hash << 5) - hash);
   }
 
   var red = (hash & 0xff0000) >> 16;
@@ -14,6 +28,6 @@ function generateColorByString(string: string) {
   var blueHex = blue.toString(16).padStart(2, "0");
 
   return "#" + redHex + greenHex + blueHex;
-}
+};
 
 export { generateColorByString };

package/src/generators/generateId.ts

@@ -1,6 +1,7 @@
 import { v4, v7 } from "uuid";
 
 function hexToBin(hex: string) {
+  hex = hex.replace(/-/g, "");
   const buffer = new Uint8Array(hex.length / 2);
 
   for (let i = 0; i < hex.length; i += 2) {
@@ -20,11 +21,41 @@ function uuidV7() {
   return { text: uuid, binary: hexToBin(uuid) };
 }
 
-function generateId(type: "text" | "binary") {
-  return {
-    v4: uuidV4()[type],
-    v7: uuidV7()[type],
-  };
+/**
+ * Generates a unique identifier (UUID) in the specified format and type.
+ *
+ * @param type - The desired output type of the UUID. Can be:
+ *   - `"text"`: Returns the UUID as a string.
+ *   - `"binary"`: Returns the UUID as a `Uint8Array` in binary format.
+ * @param format - The version of the UUID to generate. Can be:
+ *   - `"v4"`: Generates a random UUID (version 4).
+ *   - `"v7"`: Generates a time-ordered UUID (version 7).
+ * @returns The generated UUID in the specified type and format.
+ *   - If `type` is `"text"`, a string representation of the UUID is returned.
+ *   - If `type` is `"binary"`, a `Uint8Array` representation of the UUID is returned.
+ * @throws {Error} If an invalid `type` or `format` is provided.
+ *
+ * @example
+ * // Generate a version 4 UUID as a string
+ * const idTextV4 = generateId("text", "v4");
+ * console.log(idTextV4); // e.g., "550e8400-e29b-41d4-a716-446655440000"
+ *
+ * @example
+ * // Generate a version 7 UUID as binary
+ * const idBinaryV7 = generateId("binary", "v7");
+ * console.log(idBinaryV7); // Uint8Array([...])
+ */
+function generateId(type: "text", format: "v4" | "v7"): string;
+function generateId(type: "binary", format: "v4" | "v7"): Uint8Array;
+function generateId(
+  type: "text" | "binary",
+  format: "v4" | "v7"
+): string | Uint8Array {
+  if (type === "text" && format === "v4") return uuidV4().text;
+  if (type === "binary" && format === "v4") return uuidV4().binary;
+  if (type === "text" && format === "v7") return uuidV7().text;
+  if (type === "binary" && format === "v7") return uuidV7().binary;
+  throw new Error("Invalid type or format");
 }
 
 export { generateId };

package/src/generators/generateSlug.ts

@@ -1,5 +1,20 @@
-function generateSlug(string: string) {
-  let slug = string.normalize("NFD").replace(/[\u0300-\u036f]/g, "");
+/**
+ * Generates a URL-friendly slug from a given string.
+ *
+ * The function performs the following transformations:
+ * - Normalizes the string to remove diacritical marks (e.g., accents).
+ * - Removes non-alphanumeric characters except for spaces and hyphens.
+ * - Replaces spaces with hyphens.
+ * - Converts the string to lowercase.
+ * - Collapses multiple consecutive hyphens into a single hyphen.
+ * - Trims leading and trailing hyphens.
+ *
+ * @param string - The input string to be converted into a slug.
+ * @returns A URL-friendly slug derived from the input string.
+ */
+
+function generateSlug(prop: string) {
+  let slug = prop.normalize("NFD").replace(/[\u0300-\u036f]/g, "");
 
   slug = slug
     .replace(/[^\w\s-]/g, "")

package/src/index.ts

@@ -1,34 +1,26 @@
-// formats
-export { formatBrazilianDateHour } from "./formats/formatBrazilianDateHour";
-export { formatBrazilianDateToDate } from "./formats/formatBrazilianDateToDate";
-export { formatDateHour } from "./formats/formatDateHour";
+export { formatDate } from "./formats/formatDate";
 export { formatJsonObject } from "./formats/formatJsonObject";
 export { formatJsonString } from "./formats/formatJsonString";
-export { formatToBRL } from "./formats/formatToBRL";
 export { formatToCep } from "./formats/formatToCep";
-export { formatToCNPJ } from "./formats/formatToCNPJ";
-export { formatToCPF } from "./formats/formatToCPF";
+export { formatToCnpj } from "./formats/formatToCnpj";
+export { formatToCpf } from "./formats/formatToCpf";
 export { formatToCpfCnpj } from "./formats/formatToCpfCnpj";
+export { formatToCurrency } from "./formats/formatToCurrency";
 export { formatToEllipsis } from "./formats/formatToEllipsis";
 export { formatToHiddenDigits } from "./formats/formatToHiddenDigits";
 export { formatToPhone } from "./formats/formatToPhone";
 
-// generators
 export { generateColorByString } from "./generators/generateColorByString";
 export { generateId } from "./generators/generateId";
 export { generateSlug } from "./generators/generateSlug";
 
-// parsers
-export { parseToCharacters } from "./parsers/parseToCharacters";
+export { regex } from "./regex";
 
-// services
 export { calculateCardInstallment } from "./services/calculateCardInstallment";
 export { maskSensitiveData } from "./services/maskSensitiveData";
-export { normalizeRange, within } from "./services/range";
+export { removeNonNumeric } from "./services/removeNonNumeric";
 export { truncateLargeFields } from "./services/truncateLargeFields";
 
-// validations
-export { regex } from "./validations/regex";
-export { validateCPF } from "./validations/validateCPF";
+export { validateCpf } from "./validations/validateCpf";
 export { validateDate } from "./validations/validateDate";
 export { validatePhone } from "./validations/validatePhone";

package/src/regex/index.ts

@@ -0,0 +1,8 @@
+const RG = /(^\d{1,2}).?(\d{3}).?(\d{3})-?(\d{1}|X|x$)/;
+
+const PASSWORD =
+  /(?=^.{8,}$)((?=.*\w)(?=.*[A-Z])(?=.*[a-z])(?=.*[0-9])(?=.*[|!"$%&\/\(\)\?\^\'\\\+\-\*]))^.*/;
+
+const regex = { RG, PASSWORD };
+
+export { regex };

package/src/services/calculateCardInstallment.ts

@@ -1,21 +1,66 @@
-import type { CalculateCardInstallmentProps } from "@arkyn/types";
+import type { CalculateCardInstallmentFunction } from "@arkyn/types";
 
-function calculateCardInstallment(args: CalculateCardInstallmentProps) {
-  const { cash_price, number_installments, fees = 0.0349 } = args;
+/**
+ * Calculates the installment price and total price for a card payment plan.
+ *
+ * @remarks
+ * **Important:** When the interest amount (`fees`) is equal to 0 or the number of installments (`numberInstallments`) is equal to 1, no interest will be charged.
+ *
+ * @throws Will throw an error if the number of installments is less than or equal to 0.
+ * @throws Will throw an error if the fees are less than 0.
+ *
+ * @param props - The input parameters for the calculation.
+ * @param props.cashPrice - The total cash price of the product or service.
+ * @param props.numberInstallments - The number of installments for the payment plan.
+ * @param props.fees - The interest rate per installment (default is 0.0349).
+ *
+ * @returns An object containing:
+ * - `totalPrice`: The total price to be paid, rounded to two decimal places.
+ * - `installmentPrice`: The price of each installment, rounded to two decimal places.
+ *
+ * @example
+ * ```typescript
+ * const result = calculateCardInstallment({
+ *   cashPrice: 1000,
+ *   numberInstallments: 12,
+ *   fees: 0.02,
+ * });
+ * console.log(result);
+ * // Output: { totalPrice: 1124.62, installmentPrice: 93.72 }
+ * ```
+ */
 
-  let installment_price = 0;
-  let total_price = 0;
+const calculateCardInstallment: CalculateCardInstallmentFunction = (props) => {
+  const { cashPrice, numberInstallments, fees = 0.0349 } = props;
 
-  let numerator = Math.pow(1 + fees, number_installments) * fees;
-  let denominator = Math.pow(1 + fees, number_installments) - 1;
+  if (fees === 0 || numberInstallments === 1) {
+    return {
+      totalPrice: cashPrice,
+      installmentPrice: cashPrice / numberInstallments,
+    };
+  }
 
-  installment_price = cash_price * (numerator / denominator);
-  total_price = number_installments * installment_price;
+  if (numberInstallments <= 0) {
+    throw new Error("Number of installments must be greater than 0");
+  }
+
+  if (fees < 0) {
+    throw new Error("Fees must be greater than or equal to 0");
+  }
+
+  let installmentPrice = 0;
+  let totalPrice = 0;
+
+  let numerator = Math.pow(1 + fees, numberInstallments) * fees;
+  let denominator = Math.pow(1 + fees, numberInstallments) - 1;
+
+  installmentPrice = cashPrice * (numerator / denominator);
+  totalPrice = numberInstallments * installmentPrice;
 
   return {
-    total_price: +total_price.toFixed(2),
-    installment_price: +installment_price.toFixed(2),
+    totalPrice: +totalPrice.toFixed(2),
+    installmentPrice: +installmentPrice.toFixed(2),
   };
-}
+};
 
 export { calculateCardInstallment };

package/src/services/maskSensitiveData.ts

@@ -1,7 +1,32 @@
-function maskSensitiveData(
-  jsonString: string,
+import type { MaskSensitiveDataFunction } from "@arkyn/types";
+
+/**
+ * Masks sensitive data in a JSON string by replacing the values of specified keys with "****".
+ *
+ * @param jsonString - The JSON string to be processed.
+ * @param sensitiveKeys - An array of keys whose values should be masked. Defaults to `["password", "confirmPassword", "creditCard"]`.
+ * @returns A JSON string with sensitive data masked. If the input is not a valid JSON string, it returns the original string.
+ *
+ * @example
+ * ```typescript
+ * const jsonString = JSON.stringify({
+ *   username: "user123",
+ *   password: "secret",
+ *   profile: {
+ *     creditCard: "1234-5678-9012-3456",
+ *   },
+ * });
+ *
+ * const result = maskSensitiveData(jsonString, ["password", "creditCard"]);
+ * console.log(result);
+ * // Output: '{"username":"user123","password":"****","profile":{"creditCard":"****"}}'
+ * ```
+ */
+
+const maskSensitiveData: MaskSensitiveDataFunction = (
+  jsonString,
   sensitiveKeys = ["password", "confirmPassword", "creditCard"]
-): string {
+) => {
   function maskValue(key: string, value: any): any {
     if (sensitiveKeys.includes(key)) return "****";
     return value;
@@ -35,6 +60,6 @@ function maskSensitiveData(
   } catch (error) {
     return jsonString;
   }
-}
+};
 
 export { maskSensitiveData };

package/src/services/removeCurrencySymbols.ts

@@ -0,0 +1,25 @@
+/**
+ * Removes currency symbols from a given formatted string.
+ *
+ * This function takes a string that may contain currency symbols
+ * and removes them using a regular expression. The resulting string
+ * is also trimmed of any leading or trailing whitespace.
+ *
+ * @param formattedValue - The input string containing currency symbols.
+ * @returns A string with all currency symbols removed and trimmed of whitespace.
+ *
+ * @example
+ * removeCurrencySymbols("R$13,45"); // "13,45"
+ * removeCurrencySymbols("$123.45"); // "123.45"
+ * removeCurrencySymbols("€99.99"); // "99.99"
+ * removeCurrencySymbols("¥1,000"); // "1,000"
+ * removeCurrencySymbols("123.45"); // "123.45" (no symbols to remove)
+ */
+
+const removeCurrencySymbols = (formattedValue: string): string => {
+  return formattedValue
+    .replace(/(?:R\$|\p{Sc}|[$€¥£])/gu, "") // Inclui "R$" e outros símbolos comuns
+    .trim();
+};
+
+export { removeCurrencySymbols };

package/src/services/removeNonNumeric.ts

@@ -0,0 +1,18 @@
+/**
+ * Removes all non-numeric characters from a given string.
+ *
+ * @param prop - The input string from which non-numeric characters will be removed.
+ * @returns A new string containing only numeric characters from the input.
+ *
+ * @example
+ * ```typescript
+ * const result = removeNonNumeric("abc123def456");
+ * console.log(result); // Output: "123456"
+ * ```
+ */
+
+function removeNonNumeric(prop: string): string {
+  return prop.replace(/[^0-9]/g, "");
+}
+
+export { removeNonNumeric };

package/src/services/truncateLargeFields.ts

@@ -1,5 +1,39 @@
-function truncateLargeFields(jsonString: string, maxLength = 1000): string {
-  function truncateValue(key: string, value: any): any {
+import type { TruncateLargeFieldsFunction } from "@arkyn/types";
+
+/**
+ * Truncates large string fields in a JSON string to a specified maximum length.
+ *
+ * This function parses a JSON string, traverses its structure recursively, and truncates
+ * any string fields that exceed the specified maximum length. If a string field is truncated,
+ * it is replaced with a message indicating the original length of the field.
+ *
+ * @param jsonString - The JSON string to process.
+ * @param maxLength - The maximum allowed length for string fields. Defaults to 1000.
+ * @returns A JSON string with large string fields truncated.
+ *
+ * @throws {Error} Throws an error if the input is not a valid JSON string.
+ *
+ * @example
+ * ```typescript
+ * const json = JSON.stringify({
+ *   name: "John",
+ *   description: "A very long description that exceeds the maximum length...",
+ *   nested: {
+ *     details: "Another long string that needs truncation."
+ *   }
+ * });
+ *
+ * const result = truncateLargeFields(json, 50);
+ * console.log(result);
+ * // Output: '{"name":"John","description":"To large information: field as 57 characters","nested":{"details":"To large information: field as 43 characters"}}'
+ * ```
+ */
+
+const truncateLargeFields: TruncateLargeFieldsFunction = (
+  jsonString,
+  maxLength = 1000
+) => {
+  function truncateValue(value: any): any {
     if (typeof value === "string" && value.length > maxLength) {
       return `To large information: field as ${value.length} characters`;
     }
@@ -8,16 +42,16 @@ function truncateLargeFields(jsonString: string, maxLength = 1000): string {
 
   function recursiveTruncate(obj: any): any {
     if (Array.isArray(obj)) {
-      return obj.map(recursiveTruncate);
+      return obj.map((item) => recursiveTruncate(item)); // Corrigido para processar elementos do array
     } else if (obj !== null && typeof obj === "object") {
       return Object.fromEntries(
         Object.entries(obj).map(([key, value]) => [
           key,
-          truncateValue(key, recursiveTruncate(value)),
+          recursiveTruncate(value), // Corrigido para aplicar recursão corretamente
         ])
       );
     }
-    return obj;
+    return truncateValue(obj); // Corrigido para truncar valores diretamente
   }
 
   try {
@@ -27,6 +61,6 @@ function truncateLargeFields(jsonString: string, maxLength = 1000): string {
   } catch (error) {
     throw new Error("Invalid JSON string");
   }
-}
+};
 
 export { truncateLargeFields };