fix: adjust apis

Author: hyanmandian

docs/pt-br/utilities.md

@@ -25,7 +25,7 @@ formatCpf('746506880', { pad: true }); // 007.465.068-80
 
 ## parseCpf
 
-Remove a formatação do CPF e retorna apenas os dígitos.
+Remove a formatação do CPF, mantém apenas os dígitos e limita o resultado a 11 dígitos.
 
 ```javascript
 import { parseCpf } from '@brazilian-utils/brazilian-utils';
@@ -67,7 +67,7 @@ formatCnpj('12OUT345000199', { version: 2 }); // 12.OUT.345/0001-99
 
 ## parseCnpj
 
-Remove a formatação do CNPJ e retorna um valor normalizado.
+Remove a formatação do CNPJ, retorna um valor normalizado e limita o resultado a 14 caracteres.
 
 ```javascript
 import { parseCnpj } from '@brazilian-utils/brazilian-utils';
@@ -119,7 +119,7 @@ formatBoleto('1900000901149', { pad: true }); // 00000.00000 00000.000019 00000.
 
 ## parseBoleto
 
-Remove a formatação do boleto e retorna apenas os dígitos.
+Remove a formatação do boleto, mantém apenas os dígitos e limita o resultado a 47 dígitos.
 
 ```javascript
 import { parseBoleto } from '@brazilian-utils/brazilian-utils';
@@ -182,12 +182,13 @@ formatPhone('11900000000', { mask: 'auto' }); // Detecta automaticamente a másc
 
 ## parsePhone
 
-Remove a formatação do telefone e retorna apenas os dígitos.
+Remove a formatação do telefone, mantém apenas os dígitos e limita o resultado a 11 dígitos.
 
 ```javascript
 import { parsePhone } from '@brazilian-utils/brazilian-utils';
 
 parsePhone('(11) 90000-0000'); // 11900000000
+parsePhone('+55 (11) 90000-0000'); // 55119000000
 ```
 
 ## isValidMobilePhone
@@ -258,7 +259,7 @@ formatPis('123456789', { pad: true }); // 001.23456.78-9
 
 ## parsePis
 
-Remove a formatação do PIS e retorna apenas os dígitos.
+Remove a formatação do PIS, mantém apenas os dígitos e limita o resultado a 11 dígitos.
 
 ```javascript
 import { parsePis } from '@brazilian-utils/brazilian-utils';
@@ -278,7 +279,7 @@ formatCep('92500000'); // 92500-000
 
 ## parseCep
 
-Remove a formatação do CEP e retorna apenas os dígitos.
+Remove a formatação do CEP, mantém apenas os dígitos e limita o resultado a 8 dígitos.
 
 ```javascript
 import { parseCep } from '@brazilian-utils/brazilian-utils';
@@ -328,7 +329,7 @@ formatProcessoJuridico('00020802520125150049'); // 0002080-25.2012.515.0049
 
 ## parseProcessoJuridico
 
-Remove a formatação do processo jurídico e retorna apenas os dígitos.
+Remove a formatação do processo jurídico, mantém apenas os dígitos e limita o resultado a 20 dígitos.
 
 ```javascript
 import { parseProcessoJuridico } from '@brazilian-utils/brazilian-utils';
@@ -518,7 +519,7 @@ isValidPassport('12345678'); // false
 
 ## formatPassport
 
-Formata um número de passaporte brasileiro (maiúsculas, sem símbolos).
+Formata um número de passaporte brasileiro (maiúsculas, sem símbolos, limitado a 8 caracteres).
 
 ```javascript
 import { formatPassport } from '@brazilian-utils/brazilian-utils';
@@ -539,7 +540,7 @@ generatePassport(); // 'RY393097'
 
 ## parsePassport
 
-Remove todos os caracteres não alfanuméricos (incluindo '-', '.' e espaços) de um número de passaporte.
+Remove todos os caracteres não alfanuméricos de um número de passaporte, converte para maiúsculas e limita o resultado a 8 caracteres.
 
 ```javascript
 import { parsePassport } from '@brazilian-utils/brazilian-utils';
@@ -591,7 +592,7 @@ generateCnh(); // '02650306461'
 
 ## parseCnh
 
-Remove a formatação da CNH e retorna apenas os dígitos.
+Remove a formatação da CNH, mantém apenas os dígitos e limita o resultado a 11 dígitos.
 
 ```javascript
 import { parseCnh } from '@brazilian-utils/brazilian-utils';
@@ -668,7 +669,7 @@ generateLegalNature(); // '2062'
 
 ## parseLegalNature
 
-Remove a formatação da natureza jurídica e retorna apenas os dígitos.
+Remove a formatação da natureza jurídica, mantém apenas os dígitos e limita o resultado a 4 dígitos.
 
 ```javascript
 import { parseLegalNature } from '@brazilian-utils/brazilian-utils';
@@ -738,7 +739,7 @@ getFormatLicensePlate('INVALID'); // null
 
 ## parseLicensePlate
 
-Remove separadores de uma placa e normaliza para letras maiúsculas.
+Remove separadores de uma placa, normaliza para letras maiúsculas e limita o resultado a 7 caracteres.
 
 ```javascript
 import { parseLicensePlate } from '@brazilian-utils/brazilian-utils';
@@ -816,7 +817,7 @@ generateVoterId('SP'); // título de eleitor aleatório válido de São Paulo
 
 ## parseVoterId
 
-Remove a formatação do título de eleitor e retorna apenas os dígitos.
+Remove a formatação do título de eleitor, mantém apenas os dígitos e limita o resultado a 12 dígitos.
 
 ```javascript
 import { parseVoterId } from '@brazilian-utils/brazilian-utils';

docs/utilities.md

@@ -25,7 +25,7 @@ formatCpf('746506880', { pad: true }); // 007.465.068-80
 
 ## parseCpf
 
-Remove CPF formatting and return only digits.
+Remove CPF formatting, keep only digits, and cap the result to 11 digits.
 
 ```javascript
 import { parseCpf } from '@brazilian-utils/brazilian-utils';
@@ -67,7 +67,7 @@ formatCnpj('12OUT345000199', { version: 2 }); // 12.OUT.345/0001-99
 
 ## parseCnpj
 
-Remove CNPJ formatting and return a normalized value.
+Remove CNPJ formatting, return a normalized value, and cap the result to 14 characters.
 
 ```javascript
 import { parseCnpj } from '@brazilian-utils/brazilian-utils';
@@ -119,7 +119,7 @@ formatBoleto('1900000901149', { pad: true }); // 00000.00000 00000.000019 00000.
 
 ## parseBoleto
 
-Remove boleto formatting and return only digits.
+Remove boleto formatting, keep only digits, and cap the result to 47 digits.
 
 ```javascript
 import { parseBoleto } from '@brazilian-utils/brazilian-utils';
@@ -182,12 +182,13 @@ formatPhone('11900000000', { mask: 'auto' }); // Automatically detects mask base
 
 ## parsePhone
 
-Remove phone formatting and return only digits.
+Remove phone formatting, keep only digits, and cap the result to 11 digits.
 
 ```javascript
 import { parsePhone } from '@brazilian-utils/brazilian-utils';
 
 parsePhone('(11) 90000-0000'); // 11900000000
+parsePhone('+55 (11) 90000-0000'); // 55119000000
 ```
 
 ## isValidMobilePhone
@@ -258,7 +259,7 @@ formatPis('123456789', { pad: true }); // 001.23456.78-9
 
 ## parsePis
 
-Remove PIS formatting and return only digits.
+Remove PIS formatting, keep only digits, and cap the result to 11 digits.
 
 ```javascript
 import { parsePis } from '@brazilian-utils/brazilian-utils';
@@ -278,7 +279,7 @@ formatCep('92500000'); // 92500-000
 
 ## parseCep
 
-Remove CEP formatting and return only digits.
+Remove CEP formatting, keep only digits, and cap the result to 8 digits.
 
 ```javascript
 import { parseCep } from '@brazilian-utils/brazilian-utils';
@@ -328,7 +329,7 @@ formatProcessoJuridico('00020802520125150049'); // 0002080-25.2012.515.0049
 
 ## parseProcessoJuridico
 
-Remove processo jurídico formatting and return only digits.
+Remove processo jurídico formatting, keep only digits, and cap the result to 20 digits.
 
 ```javascript
 import { parseProcessoJuridico } from '@brazilian-utils/brazilian-utils';
@@ -518,7 +519,7 @@ isValidPassport('12345678'); // false
 
 ## formatPassport
 
-Format a Brazilian passport number (uppercase, without symbols).
+Format a Brazilian passport number (uppercase, without symbols, capped to 8 characters).
 
 ```javascript
 import { formatPassport } from '@brazilian-utils/brazilian-utils';
@@ -539,7 +540,7 @@ generatePassport(); // 'RY393097'
 
 ## parsePassport
 
-Remove all non-alphanumeric characters (including '-', '.', and whitespaces) from a passport number.
+Remove all non-alphanumeric characters from a passport number, uppercase the result, and cap it to 8 characters.
 
 ```javascript
 import { parsePassport } from '@brazilian-utils/brazilian-utils';
@@ -591,7 +592,7 @@ generateCnh(); // '02650306461'
 
 ## parseCnh
 
-Remove CNH formatting and return only digits.
+Remove CNH formatting, keep only digits, and cap the result to 11 digits.
 
 ```javascript
 import { parseCnh } from '@brazilian-utils/brazilian-utils';
@@ -668,7 +669,7 @@ generateLegalNature(); // '2062'
 
 ## parseLegalNature
 
-Remove legal nature formatting and return only digits.
+Remove legal nature formatting, keep only digits, and cap the result to 4 digits.
 
 ```javascript
 import { parseLegalNature } from '@brazilian-utils/brazilian-utils';
@@ -738,7 +739,7 @@ getFormatLicensePlate('INVALID'); // null
 
 ## parseLicensePlate
 
-Remove separators from a license plate and normalize it to uppercase.
+Remove separators from a license plate, normalize it to uppercase, and cap it to 7 characters.
 
 ```javascript
 import { parseLicensePlate } from '@brazilian-utils/brazilian-utils';
@@ -816,7 +817,7 @@ generateVoterId('SP'); // valid random voter ID for Sao Paulo
 
 ## parseVoterId
 
-Remove voter ID formatting and return only digits.
+Remove voter ID formatting, keep only digits, and cap the result to 12 digits.
 
 ```javascript
 import { parseVoterId } from '@brazilian-utils/brazilian-utils';

src/_internals/sanitize-to-alphanumeric/sanitize-to-alphanumeric.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from "../test/runtime";
+import { sanitizeToAlphanumeric } from "./sanitize-to-alphanumeric";
+
+describe("sanitizeToAlphanumeric", () => {
+	it("should remove non alphanumeric characters and uppercase the result", () => {
+		expect(sanitizeToAlphanumeric("ab-12.3")).toBe("AB123");
+	});
+
+	it("should support number input", () => {
+		expect(sanitizeToAlphanumeric(12345)).toBe("12345");
+	});
+});

src/_internals/sanitize-to-alphanumeric/sanitize-to-alphanumeric.ts

@@ -0,0 +1,15 @@
+/**
+ * Sanitizes the input value by removing all non-alphanumeric characters and uppercasing the result.
+ *
+ * @param {string|number} value - The input value to be sanitized. It can be a string or a number.
+ * @returns {string} A string containing only uppercase alphanumeric characters from the input value.
+ *
+ * @example
+ * ```typescript
+ * sanitizeToAlphanumeric("abc123") // "ABC123"
+ * sanitizeToAlphanumeric("Ab-12.3") // "AB123"
+ * sanitizeToAlphanumeric(12345) // "12345"
+ * ```
+ */
+export const sanitizeToAlphanumeric = (value: string | number): string =>
+	value.toString().replace(/[^A-Za-z0-9]/g, "").toUpperCase();

src/format-cnh/format-cnh.test.ts

@@ -3,8 +3,18 @@ import { formatCnh } from "./format-cnh";
 
 describe("formatCnh", () => {
 	it("should format CNH values", () => {
-		expect(formatCnh("00000000119")).toBe("000000001-19");
+		expect(formatCnh("")).toBe("");
+		expect(formatCnh("0")).toBe("0");
+		expect(formatCnh("00")).toBe("00");
+		expect(formatCnh("000")).toBe("000");
+		expect(formatCnh("0000")).toBe("0000");
+		expect(formatCnh("00000")).toBe("00000");
+		expect(formatCnh("000000")).toBe("000000");
+		expect(formatCnh("0000000")).toBe("0000000");
+		expect(formatCnh("00000000")).toBe("00000000");
 		expect(formatCnh("000000001")).toBe("000000001");
+		expect(formatCnh("0000000011")).toBe("000000001-1");
+		expect(formatCnh("00000000119")).toBe("000000001-19");
 	});
 
 	it("should remove non numeric characters", () => {

src/format-cnpj/format-cnpj.ts

@@ -1,12 +1,12 @@
 import { type FormatParams, format } from "../_internals/format/format";
+import { sanitizeToAlphanumeric } from "../_internals/sanitize-to-alphanumeric/sanitize-to-alphanumeric";
 import { sanitizeToDigits } from "../_internals/sanitize-to-digits/sanitize-to-digits";
 
 export type FormatCnpjOptions = Pick<FormatParams, "pad"> & { version?: 1 | 2 };
 
 const sanitize = (value: string | number, version?: FormatCnpjOptions["version"]) => {
 	if (version === 2) {
-		const enhancedValue = value.toString();
-		return enhancedValue.replace(/[^A-Za-z0-9]/g, "").toUpperCase();
+		return sanitizeToAlphanumeric(value);
 	}
 
 	return sanitizeToDigits(value);

src/format-legal-nature/format-legal-nature.test.ts

@@ -3,6 +3,10 @@ import { formatLegalNature } from "./format-legal-nature";
 
 describe("formatLegalNature", () => {
 	it("should format legal nature values", () => {
+		expect(formatLegalNature("")).toBe("");
+		expect(formatLegalNature("2")).toBe("2");
+		expect(formatLegalNature("20")).toBe("20");
+		expect(formatLegalNature("206")).toBe("206");
 		expect(formatLegalNature("2062")).toBe("206-2");
 	});
 });

src/format-license-plate/format-license-plate.test.ts

@@ -3,10 +3,29 @@ import { formatLicensePlate } from "./format-license-plate";
 
 describe("formatLicensePlate", () => {
 	it("should format old pattern license plates", () => {
+		expect(formatLicensePlate("")).toBe("");
+		expect(formatLicensePlate("a")).toBe("A");
+		expect(formatLicensePlate("ab")).toBe("AB");
+		expect(formatLicensePlate("abc")).toBe("ABC");
+		expect(formatLicensePlate("abc1")).toBe("ABC-1");
+		expect(formatLicensePlate("abc12")).toBe("ABC-12");
+		expect(formatLicensePlate("abc123")).toBe("ABC-123");
 		expect(formatLicensePlate("abc1234")).toBe("ABC-1234");
 	});
 
 	it("should keep mercosul plates normalized", () => {
+		expect(formatLicensePlate("")).toBe("");
+		expect(formatLicensePlate("a")).toBe("A");
+		expect(formatLicensePlate("ab")).toBe("AB");
+		expect(formatLicensePlate("abc")).toBe("ABC");
+		expect(formatLicensePlate("abc1")).toBe("ABC-1");
+		expect(formatLicensePlate("abc1d")).toBe("ABC1D");
+		expect(formatLicensePlate("abc1d2")).toBe("ABC1D2");
 		expect(formatLicensePlate("abc1d23")).toBe("ABC1D23");
 	});
+
+	it("should remove non alphanumeric characters", () => {
+		expect(formatLicensePlate("abc-1234")).toBe("ABC-1234");
+		expect(formatLicensePlate("abc1-d23")).toBe("ABC1D23");
+	});
 });

src/format-license-plate/format-license-plate.ts

@@ -4,13 +4,32 @@ import { OLD_FORMAT_SEPARATOR_INDEX } from "./constants";
 
 export const formatLicensePlate = (value: string): string => {
 	const parsed = parseLicensePlate(value);
-	const format = getFormatLicensePlate(parsed);
 
-	if (!format) return "";
+	if (!parsed) return "";
+
+	const format = getFormatLicensePlate(parsed);
 
 	if (format === "LLLNNNN") {
 		return `${parsed.slice(0, OLD_FORMAT_SEPARATOR_INDEX)}-${parsed.slice(OLD_FORMAT_SEPARATOR_INDEX)}`;
 	}
 
-	return parsed;
+	if (format) return parsed;
+
+	if (!/^[A-Z]{1,3}$/.test(parsed.slice(0, Math.min(parsed.length, OLD_FORMAT_SEPARATOR_INDEX)))) {
+		return "";
+	}
+
+	if (parsed.length <= OLD_FORMAT_SEPARATOR_INDEX) return parsed;
+
+	const tail = parsed.slice(OLD_FORMAT_SEPARATOR_INDEX);
+
+	if (/^\d{1,4}$/.test(tail)) {
+		return `${parsed.slice(0, OLD_FORMAT_SEPARATOR_INDEX)}-${tail}`;
+	}
+
+	if (/^\d[A-Z]\d{0,2}$/.test(tail) || /^\d{2}[A-Z]\d?$/.test(tail)) {
+		return parsed;
+	}
+
+	return "";
 };

src/format-passport/constants.ts

@@ -0,0 +1 @@
+export const LENGTH = 8;