@arkyn/shared 1.5.0 → 1.5.1

package/src/generators/__test__/generateSlug.spec.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect } from "vitest";
+import { generateSlug } from "../generateSlug";
+
+describe("generateSlug", () => {
+  it("should convert a string to a URL-friendly slug", () => {
+    expect(generateSlug("Hello World")).toBe("hello-world");
+    expect(generateSlug("This is a Test")).toBe("this-is-a-test");
+  });
+
+  it("should remove diacritical marks (accents)", () => {
+    expect(generateSlug("Olá Mundo")).toBe("ola-mundo");
+    expect(generateSlug("Crème brûlée")).toBe("creme-brulee");
+  });
+
+  it("should remove non-alphanumeric characters except spaces and hyphens", () => {
+    expect(generateSlug("Hello, World!")).toBe("hello-world");
+    expect(generateSlug("C# Programming")).toBe("c-programming");
+  });
+
+  it("should collapse multiple spaces into a single hyphen", () => {
+    expect(generateSlug("Hello     World")).toBe("hello-world");
+  });
+
+  it("should collapse multiple consecutive hyphens into a single hyphen", () => {
+    expect(generateSlug("Hello--World")).toBe("hello-world");
+    expect(generateSlug("Hello---World")).toBe("hello-world");
+  });
+
+  it("should trim leading and trailing hyphens", () => {
+    expect(generateSlug("-Hello World-")).toBe("hello-world");
+    expect(generateSlug("--Hello World--")).toBe("hello-world");
+  });
+
+  it("should handle empty strings", () => {
+    expect(generateSlug("")).toBe("");
+  });
+
+  it("should handle strings with only special characters", () => {
+    expect(generateSlug("!@#$%^&*()")).toBe("");
+    expect(generateSlug("---")).toBe("");
+  });
+
+  it("should handle strings with numbers", () => {
+    expect(generateSlug("Version 2.0")).toBe("version-20");
+    expect(generateSlug("123 Testing")).toBe("123-testing");
+  });
+});

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,14 +1,12 @@
 // 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";
@@ -18,17 +16,16 @@ export { generateColorByString } from "./generators/generateColorByString";
 export { generateId } from "./generators/generateId";
 export { generateSlug } from "./generators/generateSlug";
 
-// parsers
-export { parseToCharacters } from "./parsers/parseToCharacters";
-
 // 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";
+// utils
+export { validateCep } from "./validations/validateCep";
+export { validateCnpj } from "./validations/validateCnpj";
+export { validateCpf } from "./validations/validateCpf";
 export { validateDate } from "./validations/validateDate";
 export { validatePhone } from "./validations/validatePhone";
+export { validateRg } from "./validations/validateRg";

package/src/services/__test__/calculateCardInstallment.spec.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect } from "vitest";
+import { calculateCardInstallment } from "../calculateCardInstallment";
+
+describe("calculateCardInstallment", () => {
+  it("should calculate the total and installment price with default fees", () => {
+    const result = calculateCardInstallment({
+      cashPrice: 1000,
+      numberInstallments: 12,
+    });
+
+    expect(result).toEqual({
+      totalPrice: 1241.08,
+      installmentPrice: 103.42,
+    });
+  });
+
+  it("should calculate the total and installment price with custom fees", () => {
+    const result = calculateCardInstallment({
+      cashPrice: 1000,
+      numberInstallments: 12,
+      fees: 0.02,
+    });
+
+    expect(result).toEqual({
+      totalPrice: 1134.72,
+      installmentPrice: 94.56,
+    });
+  });
+
+  it("should calculate correctly for a single installment (no interest)", () => {
+    const result = calculateCardInstallment({
+      cashPrice: 1000,
+      numberInstallments: 1,
+      fees: 0,
+    });
+
+    expect(result).toEqual({
+      totalPrice: 1000,
+      installmentPrice: 1000,
+    });
+  });
+
+  it("should calculate correctly for zero fees", () => {
+    const result = calculateCardInstallment({
+      cashPrice: 500,
+      numberInstallments: 5,
+      fees: 0,
+    });
+
+    expect(result).toEqual({
+      totalPrice: 500,
+      installmentPrice: 100,
+    });
+  });
+
+  it("should handle edge case with zero installments", () => {
+    expect(() =>
+      calculateCardInstallment({
+        cashPrice: 1000,
+        numberInstallments: 0,
+      })
+    ).toThrow("Number of installments must be greater than 0");
+  });
+
+  it("should handle edge case with negative fees", () => {
+    expect(() =>
+      calculateCardInstallment({
+        cashPrice: 1000,
+        numberInstallments: 12,
+        fees: -0.01,
+      })
+    ).toThrow("Fees must be greater than or equal to 0");
+  });
+
+  it("should handle large numbers for cash price and installments", () => {
+    const result = calculateCardInstallment({
+      cashPrice: 1000000,
+      numberInstallments: 24,
+      fees: 0.01,
+    });
+
+    expect(result).toEqual({
+      totalPrice: 1129763.33,
+      installmentPrice: 47073.47,
+    });
+  });
+});

package/src/services/__test__/maskSensitiveData.spec.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from "vitest";
+import { maskSensitiveData } from "../maskSensitiveData";
+
+describe("maskSensitiveData", () => {
+  it("should mask sensitive keys in a flat JSON object", () => {
+    const jsonString = JSON.stringify({
+      username: "user123",
+      password: "secret",
+      email: "user@example.com",
+    });
+
+    const result = maskSensitiveData(jsonString, ["password"]);
+    expect(result).toBe(
+      '{"username":"user123","password":"****","email":"user@example.com"}'
+    );
+  });
+
+  it("should mask sensitive keys in nested objects", () => {
+    const jsonString = JSON.stringify({
+      profile: {
+        username: "user123",
+        creditCard: "1234-5678-9012-3456",
+      },
+    });
+
+    const result = maskSensitiveData(jsonString, ["creditCard"]);
+    expect(result).toBe(
+      '{"profile":{"username":"user123","creditCard":"****"}}'
+    );
+  });
+
+  it("should mask sensitive keys in arrays", () => {
+    const jsonString = JSON.stringify({
+      users: [
+        { username: "user1", password: "pass1" },
+        { username: "user2", password: "pass2" },
+      ],
+    });
+
+    const result = maskSensitiveData(jsonString, ["password"]);
+    expect(result).toBe(
+      '{"users":[{"username":"user1","password":"****"},{"username":"user2","password":"****"}]}'
+    );
+  });
+
+  it("should handle non-JSON strings gracefully", () => {
+    const invalidJson = "not a json string";
+    const result = maskSensitiveData(invalidJson, ["password"]);
+    expect(result).toBe("not a json string");
+  });
+
+  it("should handle empty JSON objects", () => {
+    const jsonString = JSON.stringify({});
+    const result = maskSensitiveData(jsonString, ["password"]);
+    expect(result).toBe("{}");
+  });
+
+  it("should handle empty arrays", () => {
+    const jsonString = JSON.stringify([]);
+    const result = maskSensitiveData(jsonString, ["password"]);
+    expect(result).toBe("[]");
+  });
+
+  it("should use default sensitive keys if none are provided", () => {
+    const jsonString = JSON.stringify({
+      username: "user123",
+      password: "secret",
+      confirmPassword: "secret",
+      creditCard: "1234-5678-9012-3456",
+    });
+
+    const result = maskSensitiveData(jsonString);
+    expect(result).toBe(
+      '{"username":"user123","password":"****","confirmPassword":"****","creditCard":"****"}'
+    );
+  });
+
+  it("should not mask keys that are not in the sensitive keys list", () => {
+    const jsonString = JSON.stringify({
+      username: "user123",
+      email: "user@example.com",
+    });
+
+    const result = maskSensitiveData(jsonString, ["password"]);
+    expect(result).toBe('{"username":"user123","email":"user@example.com"}');
+  });
+
+  it("should handle deeply nested objects", () => {
+    const jsonString = JSON.stringify({
+      level1: {
+        level2: {
+          level3: {
+            password: "secret",
+          },
+        },
+      },
+    });
+
+    const result = maskSensitiveData(jsonString, ["password"]);
+    expect(result).toBe('{"level1":{"level2":{"level3":{"password":"****"}}}}');
+  });
+});

package/src/services/__test__/removeCurrencySymbols.spec.ts

@@ -0,0 +1,41 @@
+import { describe, it, expect } from "vitest";
+import { removeCurrencySymbols } from "../removeCurrencySymbols";
+
+describe("removeCurrencySymbols", () => {
+  it("should remove common currency symbols from the string", () => {
+    expect(removeCurrencySymbols("R$13,45")).toBe("13,45");
+    expect(removeCurrencySymbols("$123.45")).toBe("123.45");
+    expect(removeCurrencySymbols("€99.99")).toBe("99.99");
+    expect(removeCurrencySymbols("¥1,000")).toBe("1,000");
+  });
+
+  it("should handle strings without currency symbols", () => {
+    expect(removeCurrencySymbols("123.45")).toBe("123.45");
+    expect(removeCurrencySymbols("1,000")).toBe("1,000");
+  });
+
+  it("should handle strings with multiple currency symbols", () => {
+    expect(removeCurrencySymbols("R$ $123.45")).toBe("123.45");
+    expect(removeCurrencySymbols("€¥99,99")).toBe("99,99");
+  });
+
+  it("should handle strings with leading and trailing whitespace", () => {
+    expect(removeCurrencySymbols("  $123.45  ")).toBe("123.45");
+    expect(removeCurrencySymbols("\t€99.99\n")).toBe("99.99");
+  });
+
+  it("should return an empty string if the input is only currency symbols", () => {
+    expect(removeCurrencySymbols("R$")).toBe("");
+    expect(removeCurrencySymbols("$")).toBe("");
+    expect(removeCurrencySymbols("€")).toBe("");
+  });
+
+  it("should handle an empty string input", () => {
+    expect(removeCurrencySymbols("")).toBe("");
+  });
+
+  it("should handle strings with special characters but no currency symbols", () => {
+    expect(removeCurrencySymbols("123-45")).toBe("123-45");
+    expect(removeCurrencySymbols("1,000.00")).toBe("1,000.00");
+  });
+});

package/src/services/__test__/removeNonNumeric.spec.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from "vitest";
+import { removeNonNumeric } from "../removeNonNumeric";
+
+describe("removeNonNumeric", () => {
+  it("should remove all non-numeric characters from a string", () => {
+    expect(removeNonNumeric("abc123def456")).toBe("123456");
+    expect(removeNonNumeric("!@#123$%^456&*()")).toBe("123456");
+    expect(removeNonNumeric("a1b2c3")).toBe("123");
+  });
+
+  it("should return an empty string if there are no numeric characters", () => {
+    expect(removeNonNumeric("abcdef")).toBe("");
+    expect(removeNonNumeric("!@#$%^&*()")).toBe("");
+  });
+
+  it("should return the same string if it contains only numeric characters", () => {
+    expect(removeNonNumeric("123456")).toBe("123456");
+    expect(removeNonNumeric("000123")).toBe("000123");
+  });
+
+  it("should handle an empty string input", () => {
+    expect(removeNonNumeric("")).toBe("");
+  });
+
+  it("should handle strings with spaces and remove them", () => {
+    expect(removeNonNumeric("123 456 789")).toBe("123456789");
+    expect(removeNonNumeric(" 1 2 3 ")).toBe("123");
+  });
+
+  it("should handle strings with special characters and preserve only numbers", () => {
+    expect(removeNonNumeric("12-34.56/78")).toBe("12345678");
+  });
+});

package/src/services/__test__/truncateLargeFields.spec.ts

@@ -0,0 +1,90 @@
+import { describe, it, expect } from "vitest";
+import { truncateLargeFields } from "../truncateLargeFields";
+
+describe("truncateLargeFields", () => {
+  it("should truncate string fields exceeding the maxLength", () => {
+    const json = JSON.stringify({
+      name: "John",
+      description: "A very long description that exceeds the maximum length...",
+    });
+
+    const result = truncateLargeFields(json, 20);
+    expect(result).toBe(
+      '{"name":"John","description":"To large information: field as 58 characters"}'
+    );
+  });
+
+  it("should handle nested objects and truncate large string fields", () => {
+    const json = JSON.stringify({
+      nested: {
+        details: "Another long string that needs truncation.",
+      },
+    });
+
+    const result = truncateLargeFields(json, 20);
+    expect(result).toBe(
+      '{"nested":{"details":"To large information: field as 42 characters"}}'
+    );
+  });
+
+  it("should handle arrays and truncate large string fields within them", () => {
+    const json = JSON.stringify({
+      items: ["short", "A very long string in an array that exceeds the limit"],
+    });
+
+    const result = truncateLargeFields(json, 20);
+    expect(result).toBe(
+      '{"items":["short","To large information: field as 53 characters"]}'
+    );
+  });
+
+  it("should not modify fields that are within the maxLength", () => {
+    const json = JSON.stringify({
+      name: "John",
+      description: "Short description",
+    });
+
+    const result = truncateLargeFields(json, 20);
+    expect(result).toBe('{"name":"John","description":"Short description"}');
+  });
+
+  it("should throw an error for invalid JSON strings", () => {
+    const invalidJson = "{ name: 'John' }"; // Invalid JSON
+    expect(() => truncateLargeFields(invalidJson, 20)).toThrow(
+      "Invalid JSON string"
+    );
+  });
+
+  it("should handle empty JSON objects", () => {
+    const json = JSON.stringify({});
+    const result = truncateLargeFields(json, 20);
+    expect(result).toBe("{}");
+  });
+
+  it("should handle empty arrays", () => {
+    const json = JSON.stringify([]);
+    const result = truncateLargeFields(json, 20);
+    expect(result).toBe("[]");
+  });
+
+  it("should handle non-string fields without modification", () => {
+    const json = JSON.stringify({
+      number: 123,
+      boolean: true,
+      nullValue: null,
+    });
+
+    const result = truncateLargeFields(json, 20);
+    expect(result).toBe('{"number":123,"boolean":true,"nullValue":null}');
+  });
+
+  it("should use the default maxLength of 1000 if not provided", () => {
+    const longString = "a".repeat(1500);
+    const json = JSON.stringify({ longField: longString });
+    const result = truncateLargeFields(json);
+
+    expect(result).toBe(
+      `{"longField":"To large information: field as 1500 characters"}`
+    );
+  });
+});

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