validador-cnpj-cpf 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chrisJSeng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,267 @@
+# Validador CPF/CNPJ 🇧🇷
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
+[![Coverage](https://img.shields.io/badge/coverage-99%25+-green.svg)](https://github.com/chrisJSeng/validador-cpf-cnpj)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A high-performance, secure, and modular TypeScript library for validating Brazilian documents (CPF and CNPJ).
+
+## 🚀 Features
+
+- ✅ **TypeScript First**: Full type safety and IntelliSense support
+- ✅ **High Performance**: Uses efficient data structures (Set, Object.freeze)
+- ✅ **Security Focused**: Comprehensive input validation with guard rails
+- ✅ **99%+ Test Coverage**: Thoroughly tested with Jest
+- ✅ **SOLID Principles**: Clean, maintainable, and extensible architecture
+- ✅ **Modern JavaScript**: ES2022 target
+- ✅ **Zero Dependencies**: No external runtime dependencies
+- ✅ **Modular Design**: Import only what you need
+- ✅ **Clear Rules**: CPF is digits-only; CNPJ supports alphanumeric (`0-9`/`A-Z`)
+
+## 📦 Installation
+
+```bash
+npm install validador-cnpj-cpf
+```
+
+## 🔧 Usage
+
+> Notes
+>
+> - All public APIs accept **strings only**.
+> - CPF is **digits-only** (11 digits after cleaning/format stripping).
+> - CNPJ supports **alphanumeric** characters (`0-9` and `A-Z`) and must match the structure `^[0-9A-Z]{12}\d{2}$` after cleaning (last two characters are numeric check digits).
+
+### About the `{ validate: true }` flag
+
+`formatCPF`, `maskCPF`, and `formatCNPJ` are **best-effort by default**:
+
+- They try to clean/format what you pass in.
+- If the cleaned value has the wrong length/shape to be formatted, they return `null`.
+
+When you pass `{ validate: true }`, they become **strict**:
+
+- They first run the full validator (`validateCPF`/`validateCNPJ`).
+- If the document is invalid, they return `null`.
+
+Use strict mode when you want to **avoid formatting/masking invalid documents** (e.g., in UI output, logs, or API responses).
+
+### Basic CPF Validation
+
+```typescript
+import { validateCPF, formatCPF, cleanCPF, maskCPF } from 'validador-cnpj-cpf';
+
+// Validate CPF
+const result = validateCPF('111.444.777-35');
+if (result.isValid) {
+  console.log('Valid CPF!');
+} else {
+  console.log('Invalid CPF:', result.error);
+}
+
+// Format CPF
+const formatted = formatCPF('11144477735');
+console.log(formatted); // "111.444.777-35"
+
+// Format CPF only if valid
+const formattedStrict = formatCPF('12345678901', { validate: true });
+console.log(formattedStrict); // null
+
+// Mask CPF (hide middle digits)
+const masked = maskCPF('11144477735');
+console.log(masked); // "111.***.***-35"
+
+// Mask CPF only if valid
+const maskedStrict = maskCPF('12345678901', { validate: true });
+console.log(maskedStrict); // null
+
+// Clean CPF (remove formatting)
+const cleaned = cleanCPF('111.444.777-35');
+console.log(cleaned); // "11144477735"
+
+
+```
+
+### Basic CNPJ Validation
+
+```typescript
+import { validateCNPJ, formatCNPJ, cleanCNPJ } from 'validador-cnpj-cpf';
+
+// Validate CNPJ
+const result = validateCNPJ('11.222.333/0001-81');
+if (result.isValid) {
+  console.log('Valid CNPJ!');
+} else {
+  console.log('Invalid CNPJ:', result.error);
+}
+
+// Format CNPJ
+const formatted = formatCNPJ('11222333000181');
+console.log(formatted); // "11.222.333/0001-81"
+
+// Format CNPJ only if valid
+const formattedStrict = formatCNPJ('11222333000182', { validate: true });
+console.log(formattedStrict); // null
+
+// Clean CNPJ (remove formatting)
+const cleaned = cleanCNPJ('11.222.333/0001-81');
+console.log(cleaned); // "11222333000181"
+
+
+```
+
+### Advanced Usage with Classes
+
+```typescript
+import { CPFValidator, CNPJValidator } from 'validador-cnpj-cpf';
+
+// Using CPF validator class
+const cpfValidator = new CPFValidator();
+const cpfResult = cpfValidator.validate('111.444.777-35');
+
+// Using CNPJ validator class
+const cnpjValidator = new CNPJValidator();
+const cnpjResult = cnpjValidator.validate('11.222.333/0001-81');
+```
+
+### Custom Validation with Guards
+
+```typescript
+import {
+  guardIsString,
+  guardNotEmpty,
+  guardValidCharacters,
+  guardLength,
+  chainGuards,
+  stripDocumentFormatting,
+} from 'validador-cnpj-cpf';
+
+// Create custom validation pipeline
+const input = '12345678901';
+const stripped = stripDocumentFormatting(input);
+const guards = chainGuards(
+  guardIsString(input),
+  guardNotEmpty(input),
+  guardValidCharacters(stripped, /^\d+$/),
+  guardLength(stripped, 11, 'Must be 11 digits'),
+);
+
+if (!guards.isValid) {
+  console.error('Validation failed:', guards.error);
+}
+```
+
+## 🏗️ Architecture
+
+This library follows best practices and design principles:
+
+### SOLID Principles
+
+- **Single Responsibility**: Each validator handles one document type
+- **Open/Closed**: Extensible via interfaces without modifying existing code
+- **Liskov Substitution**: Validators implement common interfaces
+- **Interface Segregation**: Minimal, focused interfaces
+- **Dependency Inversion**: Depends on abstractions, not concretions
+
+### DRY, KISS, YAGNI
+
+- **DRY (Don't Repeat Yourself)**: Shared utilities and constants
+- **KISS (Keep It Simple, Stupid)**: Clear, straightforward implementations
+- **YAGNI (You Aren't Gonna Need It)**: Only implements necessary features
+
+### Performance Optimizations
+
+- Uses `Set` for O(1) invalid pattern lookups
+- Pre-calculates multipliers for check digit validation
+- Uses `Object.freeze()` for immutable constants
+- Efficient array operations with modern JavaScript
+
+## 🛡️ Security
+
+- Comprehensive input validation with guard rails
+- Type-safe TypeScript implementation
+- No eval() or unsafe operations
+- Sanitizes all user inputs
+- Prevents common attack vectors
+
+## 📊 API Reference
+
+### Validation Result
+
+```typescript
+interface ValidationResult {
+  isValid: boolean;
+  error?: string;
+}
+```
+
+### CPF Functions
+
+- `validateCPF(input: string): ValidationResult` - Validates a CPF
+- `formatCPF(input: string, options?: { validate?: boolean }): string | null` - Formats a CPF (best-effort by default; strict with `{ validate: true }`)
+- `maskCPF(input: string, options?: { validate?: boolean }): string | null` - Masks a CPF as `XXX.***.***-YY` (best-effort by default; strict with `{ validate: true }`)
+- `cleanCPF(input: string): string` - Removes formatting from CPF
+
+### CNPJ Functions
+
+- `validateCNPJ(input: string): ValidationResult` - Validates a CNPJ
+- `formatCNPJ(input: string, options?: { validate?: boolean }): string | null` - Formats a CNPJ (best-effort by default; strict with `{ validate: true }`)
+- `cleanCNPJ(input: string): string` - Removes formatting from CNPJ
+
+### Utils
+
+- `stripDocumentFormatting(input: string): string` - Removes `.`, `-`, `/` and whitespace
+
+### Classes
+
+- `CPFValidator` - Class-based CPF validator implementing `IDocumentValidator`
+- `CNPJValidator` - Class-based CNPJ validator implementing `IDocumentValidator`
+
+### Guards
+
+- `guardIsString(input: unknown): GuardResult`
+- `guardNotEmpty(input: string): GuardResult`
+- `guardValidCharacters(input: string, regex: RegExp): GuardResult`
+- `guardLength(input: string, length: number, error: string): GuardResult`
+- `chainGuards(...guards: GuardResult[]): GuardResult`
+
+## 🧪 Testing
+
+```bash
+# Run tests (includes coverage)
+npm test
+
+# Watch mode
+npm run test:watch
+```
+
+## 🔨 Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Lint
+npm run lint
+
+# Format
+npm run format
+```
+
+## 📝 License
+
+MIT © [chrisJSeng]
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📚 References
+
+- Receita Federal (gov.br) — Meu CPF: https://www.gov.br/receitafederal/pt-br/assuntos/meu-cpf
+- gov.br — Consultar Cadastro de Pessoa Física (CPF) na Receita Federal: https://www.gov.br/pt-br/servicos/consultar-cadastro-de-pessoas-fisicas
+- Receita Federal (gov.br) — CNPJ (Cadastro Nacional de Pessoas Jurídicas): https://www.gov.br/receitafederal/pt-br/assuntos/orientacao-tributaria/cadastros/cnpj
+- Receita Federal — IN RFB nº 2.119/2022 (Cadastro Nacional da Pessoa Jurídica – CNPJ): https://normasinternet2.receita.fazenda.gov.br/#/consulta/externa/127567

package/dist/cnpj-validator.d.ts

@@ -0,0 +1,14 @@
+import { FormatOptions, IDocumentValidator, ValidationResult } from './types';
+export declare class CNPJValidator implements IDocumentValidator {
+    private readonly firstDigitMultipliers;
+    private readonly secondDigitMultipliers;
+    constructor();
+    clean(input: string): string;
+    format(input: string): string | null;
+    validate(input: string): ValidationResult;
+    private validateCleanedInput;
+    private validateCheckDigits;
+}
+export declare function validateCNPJ(input: string): ValidationResult;
+export declare function formatCNPJ(input: string, options?: FormatOptions): string | null;
+export declare function cleanCNPJ(input: string): string;

package/dist/cnpj-validator.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CNPJValidator = void 0;
+exports.validateCNPJ = validateCNPJ;
+exports.formatCNPJ = formatCNPJ;
+exports.cleanCNPJ = cleanCNPJ;
+const constants_1 = require("./constants");
+const guards_1 = require("./guards");
+const utils_1 = require("./utils");
+class CNPJValidator {
+    firstDigitMultipliers;
+    secondDigitMultipliers;
+    constructor() {
+        this.firstDigitMultipliers = constants_1.CNPJ_FIRST_MULTIPLIERS;
+        this.secondDigitMultipliers = constants_1.CNPJ_SECOND_MULTIPLIERS;
+    }
+    clean(input) {
+        return (0, utils_1.removeNonAlphanumeric)((0, utils_1.stripDocumentFormatting)(input)).toUpperCase();
+    }
+    format(input) {
+        const cleaned = this.clean(input);
+        if (cleaned.length !== constants_1.CNPJ_LENGTH)
+            return null;
+        const part1 = cleaned.slice(0, 2);
+        const part2 = cleaned.slice(2, 5);
+        const part3 = cleaned.slice(5, 8);
+        const part4 = cleaned.slice(8, 12);
+        const part5 = cleaned.slice(12, 14);
+        return `${part1}.${part2}.${part3}/${part4}-${part5}`;
+    }
+    validate(input) {
+        const stringGuard = (0, guards_1.guardIsString)(input);
+        const notEmptyGuard = stringGuard.isValid
+            ? (0, guards_1.guardNotEmpty)(stringGuard.cleanedInput)
+            : stringGuard;
+        const baseGuard = (0, guards_1.chainGuards)(stringGuard, notEmptyGuard);
+        return baseGuard.isValid
+            ? this.validateCleanedInput(baseGuard.cleanedInput)
+            : (0, utils_1.invalidResult)(baseGuard.error);
+    }
+    validateCleanedInput(input) {
+        const cleaned = this.clean(input);
+        const charGuard = (0, guards_1.guardValidCharacters)(cleaned, constants_1.CNPJ_ALLOWED_CHARS_REGEX);
+        const lengthGuard = (0, guards_1.guardLength)(cleaned, constants_1.CNPJ_LENGTH, constants_1.ERROR_MESSAGES.INVALID_CNPJ_LENGTH);
+        const structureGuard = constants_1.CNPJ_ALPHANUMERIC_REGEX.test(cleaned)
+            ? { isValid: true, cleanedInput: cleaned }
+            : { isValid: false, error: constants_1.ERROR_MESSAGES.INVALID_CHARACTERS };
+        const patternGuard = constants_1.CNPJ_DIGIT_REGEX.test(cleaned) && constants_1.INVALID_CNPJ_PATTERNS.has(cleaned)
+            ? { isValid: false, error: constants_1.ERROR_MESSAGES.INVALID_CNPJ_PATTERN }
+            : { isValid: true, cleanedInput: cleaned };
+        const finalGuard = (0, guards_1.chainGuards)(charGuard, lengthGuard, structureGuard, patternGuard);
+        return finalGuard.isValid ? this.validateCheckDigits(cleaned) : (0, utils_1.invalidResult)(finalGuard.error);
+    }
+    validateCheckDigits(cnpj) {
+        const values = (0, utils_1.stringToBase36ValueArray)(cnpj);
+        const firstProvided = Number(cnpj[constants_1.CNPJ_FIRST_DIGIT_POSITION]);
+        const secondProvided = Number(cnpj[constants_1.CNPJ_SECOND_DIGIT_POSITION]);
+        const firstDigit = (0, utils_1.calculateCheckDigit)(values.slice(0, constants_1.CNPJ_FIRST_DIGIT_POSITION), this.firstDigitMultipliers);
+        if (firstDigit !== firstProvided)
+            return (0, utils_1.invalidResult)(constants_1.ERROR_MESSAGES.INVALID_CNPJ_DIGITS);
+        const secondDigit = (0, utils_1.calculateCheckDigit)([...values.slice(0, constants_1.CNPJ_FIRST_DIGIT_POSITION), firstDigit], this.secondDigitMultipliers);
+        if (secondDigit !== secondProvided)
+            return (0, utils_1.invalidResult)(constants_1.ERROR_MESSAGES.INVALID_CNPJ_DIGITS);
+        return (0, utils_1.validResult)();
+    }
+}
+exports.CNPJValidator = CNPJValidator;
+const cnpjValidatorInstance = new CNPJValidator();
+function validateCNPJ(input) {
+    return cnpjValidatorInstance.validate(input);
+}
+function formatCNPJ(input, options) {
+    const shouldValidate = options?.validate === true;
+    const isInvalidWhenStrict = shouldValidate && !cnpjValidatorInstance.validate(input).isValid;
+    if (isInvalidWhenStrict)
+        return null;
+    return cnpjValidatorInstance.format(input);
+}
+function cleanCNPJ(input) {
+    return cnpjValidatorInstance.clean(input);
+}

package/dist/constants.d.ts

@@ -0,0 +1,70 @@
+export declare const CPF_LENGTH = 11;
+export declare const CPF_FORMATTED_LENGTH = 14;
+export declare const CPF_FIRST_DIGIT_POSITION = 9;
+export declare const CPF_SECOND_DIGIT_POSITION = 10;
+export declare const CPF_FIRST_DIGIT_MULTIPLIER_START = 10;
+export declare const CPF_SECOND_DIGIT_MULTIPLIER_START = 11;
+export declare const CPF_FORMAT_REGEX: RegExp;
+export declare const CPF_DIGIT_REGEX: RegExp;
+export declare const CPF_ALLOWED_CHARS_REGEX: RegExp;
+export declare const CPF_ALPHANUMERIC_REGEX: RegExp;
+export declare const CPF_FIRST_MULTIPLIERS: readonly number[];
+export declare const CPF_SECOND_MULTIPLIERS: readonly number[];
+export declare const CNPJ_LENGTH = 14;
+export declare const CNPJ_FORMATTED_LENGTH = 18;
+export declare const CNPJ_FIRST_DIGIT_POSITION = 12;
+export declare const CNPJ_SECOND_DIGIT_POSITION = 13;
+export declare const CNPJ_FORMAT_REGEX: RegExp;
+export declare const CNPJ_DIGIT_REGEX: RegExp;
+export declare const CNPJ_ALLOWED_CHARS_REGEX: RegExp;
+export declare const CNPJ_ALPHANUMERIC_REGEX: RegExp;
+export declare const CNPJ_FIRST_MULTIPLIERS: readonly number[];
+export declare const CNPJ_SECOND_MULTIPLIERS: readonly number[];
+export declare const MODULO_DIVISOR = 11;
+export declare const MIN_REMAINDER_FOR_ZERO = 2;
+export declare const DIGIT_ZERO = 0;
+export declare const DIGITS_ONLY_REGEX: RegExp;
+export declare const NON_DIGIT_REGEX: RegExp;
+export declare const DOCUMENT_FORMATTING_REGEX: RegExp;
+export declare const NON_ALPHANUMERIC_REGEX: RegExp;
+export declare const CPF_RULES: Readonly<{
+    LENGTH: 11;
+    FIRST_DIGIT_POSITION: 9;
+    SECOND_DIGIT_POSITION: 10;
+    FIRST_MULTIPLIERS: readonly number[];
+    SECOND_MULTIPLIERS: readonly number[];
+    ALLOWED_CHARS_REGEX: RegExp;
+    STRUCTURE_REGEX: RegExp;
+    NUMERIC_ONLY_REGEX: RegExp;
+}>;
+export declare const CNPJ_RULES: Readonly<{
+    LENGTH: 14;
+    FIRST_DIGIT_POSITION: 12;
+    SECOND_DIGIT_POSITION: 13;
+    FIRST_MULTIPLIERS: readonly number[];
+    SECOND_MULTIPLIERS: readonly number[];
+    ALLOWED_CHARS_REGEX: RegExp;
+    STRUCTURE_REGEX: RegExp;
+    NUMERIC_ONLY_REGEX: RegExp;
+}>;
+export declare const CHECK_DIGIT_RULES: Readonly<{
+    MODULO_DIVISOR: 11;
+    MIN_REMAINDER_FOR_ZERO: 2;
+    DIGIT_ZERO: 0;
+}>;
+export declare const INVALID_CPF_PATTERNS: Readonly<Set<string>>;
+export declare const INVALID_CNPJ_PATTERNS: Readonly<Set<string>>;
+export declare const ERROR_MESSAGES: Readonly<{
+    INVALID_TYPE: "Input must be a string";
+    EMPTY_INPUT: "Input cannot be empty";
+    INVALID_CPF_LENGTH: "CPF must have exactly 11 characters";
+    INVALID_CNPJ_LENGTH: "CNPJ must have exactly 14 characters";
+    INVALID_CPF_PATTERN: "CPF contains invalid pattern";
+    INVALID_CNPJ_PATTERN: "CNPJ contains invalid pattern";
+    INVALID_CPF_DIGITS: "CPF verification digits are invalid";
+    INVALID_CNPJ_DIGITS: "CNPJ verification digits are invalid";
+    INVALID_CHARACTERS: "Input contains invalid characters";
+}>;
+export declare const INTERNAL_MESSAGES: Readonly<{
+    CHAIN_GUARDS_REQUIRES_AT_LEAST_ONE: "chainGuards requires at least one guard";
+}>;

package/dist/constants.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INTERNAL_MESSAGES = exports.ERROR_MESSAGES = exports.INVALID_CNPJ_PATTERNS = exports.INVALID_CPF_PATTERNS = exports.CHECK_DIGIT_RULES = exports.CNPJ_RULES = exports.CPF_RULES = exports.NON_ALPHANUMERIC_REGEX = exports.DOCUMENT_FORMATTING_REGEX = exports.NON_DIGIT_REGEX = exports.DIGITS_ONLY_REGEX = exports.DIGIT_ZERO = exports.MIN_REMAINDER_FOR_ZERO = exports.MODULO_DIVISOR = exports.CNPJ_SECOND_MULTIPLIERS = exports.CNPJ_FIRST_MULTIPLIERS = exports.CNPJ_ALPHANUMERIC_REGEX = exports.CNPJ_ALLOWED_CHARS_REGEX = exports.CNPJ_DIGIT_REGEX = exports.CNPJ_FORMAT_REGEX = exports.CNPJ_SECOND_DIGIT_POSITION = exports.CNPJ_FIRST_DIGIT_POSITION = exports.CNPJ_FORMATTED_LENGTH = exports.CNPJ_LENGTH = exports.CPF_SECOND_MULTIPLIERS = exports.CPF_FIRST_MULTIPLIERS = exports.CPF_ALPHANUMERIC_REGEX = exports.CPF_ALLOWED_CHARS_REGEX = exports.CPF_DIGIT_REGEX = exports.CPF_FORMAT_REGEX = exports.CPF_SECOND_DIGIT_MULTIPLIER_START = exports.CPF_FIRST_DIGIT_MULTIPLIER_START = exports.CPF_SECOND_DIGIT_POSITION = exports.CPF_FIRST_DIGIT_POSITION = exports.CPF_FORMATTED_LENGTH = exports.CPF_LENGTH = void 0;
+exports.CPF_LENGTH = 11;
+exports.CPF_FORMATTED_LENGTH = 14;
+exports.CPF_FIRST_DIGIT_POSITION = 9;
+exports.CPF_SECOND_DIGIT_POSITION = 10;
+exports.CPF_FIRST_DIGIT_MULTIPLIER_START = 10;
+exports.CPF_SECOND_DIGIT_MULTIPLIER_START = 11;
+exports.CPF_FORMAT_REGEX = /^(\d{3})\.(\d{3})\.(\d{3})-(\d{2})$/;
+exports.CPF_DIGIT_REGEX = /^\d+$/;
+exports.CPF_ALLOWED_CHARS_REGEX = /^\d+$/;
+exports.CPF_ALPHANUMERIC_REGEX = /^\d{11}$/;
+exports.CPF_FIRST_MULTIPLIERS = Object.freeze([10, 9, 8, 7, 6, 5, 4, 3, 2]);
+exports.CPF_SECOND_MULTIPLIERS = Object.freeze([11, 10, 9, 8, 7, 6, 5, 4, 3, 2]);
+exports.CNPJ_LENGTH = 14;
+exports.CNPJ_FORMATTED_LENGTH = 18;
+exports.CNPJ_FIRST_DIGIT_POSITION = 12;
+exports.CNPJ_SECOND_DIGIT_POSITION = 13;
+exports.CNPJ_FORMAT_REGEX = /^(\d{2})\.(\d{3})\.(\d{3})\/(\d{4})-(\d{2})$/;
+exports.CNPJ_DIGIT_REGEX = /^\d+$/;
+exports.CNPJ_ALLOWED_CHARS_REGEX = /^[0-9A-Z]+$/;
+exports.CNPJ_ALPHANUMERIC_REGEX = /^[0-9A-Z]{12}\d{2}$/;
+exports.CNPJ_FIRST_MULTIPLIERS = Object.freeze([5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2]);
+exports.CNPJ_SECOND_MULTIPLIERS = Object.freeze([6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2]);
+exports.MODULO_DIVISOR = 11;
+exports.MIN_REMAINDER_FOR_ZERO = 2;
+exports.DIGIT_ZERO = 0;
+exports.DIGITS_ONLY_REGEX = /^\d+$/;
+exports.NON_DIGIT_REGEX = /\D/g;
+exports.DOCUMENT_FORMATTING_REGEX = /[.\-/\s]/g;
+exports.NON_ALPHANUMERIC_REGEX = /[^0-9A-Za-z]/g;
+exports.CPF_RULES = Object.freeze({
+    LENGTH: exports.CPF_LENGTH,
+    FIRST_DIGIT_POSITION: exports.CPF_FIRST_DIGIT_POSITION,
+    SECOND_DIGIT_POSITION: exports.CPF_SECOND_DIGIT_POSITION,
+    FIRST_MULTIPLIERS: exports.CPF_FIRST_MULTIPLIERS,
+    SECOND_MULTIPLIERS: exports.CPF_SECOND_MULTIPLIERS,
+    ALLOWED_CHARS_REGEX: exports.CPF_ALLOWED_CHARS_REGEX,
+    STRUCTURE_REGEX: exports.CPF_ALPHANUMERIC_REGEX,
+    NUMERIC_ONLY_REGEX: exports.CPF_DIGIT_REGEX,
+});
+exports.CNPJ_RULES = Object.freeze({
+    LENGTH: exports.CNPJ_LENGTH,
+    FIRST_DIGIT_POSITION: exports.CNPJ_FIRST_DIGIT_POSITION,
+    SECOND_DIGIT_POSITION: exports.CNPJ_SECOND_DIGIT_POSITION,
+    FIRST_MULTIPLIERS: exports.CNPJ_FIRST_MULTIPLIERS,
+    SECOND_MULTIPLIERS: exports.CNPJ_SECOND_MULTIPLIERS,
+    ALLOWED_CHARS_REGEX: exports.CNPJ_ALLOWED_CHARS_REGEX,
+    STRUCTURE_REGEX: exports.CNPJ_ALPHANUMERIC_REGEX,
+    NUMERIC_ONLY_REGEX: exports.CNPJ_DIGIT_REGEX,
+});
+exports.CHECK_DIGIT_RULES = Object.freeze({
+    MODULO_DIVISOR: exports.MODULO_DIVISOR,
+    MIN_REMAINDER_FOR_ZERO: exports.MIN_REMAINDER_FOR_ZERO,
+    DIGIT_ZERO: exports.DIGIT_ZERO,
+});
+exports.INVALID_CPF_PATTERNS = Object.freeze(new Set([
+    '00000000000',
+    '11111111111',
+    '22222222222',
+    '33333333333',
+    '44444444444',
+    '55555555555',
+    '66666666666',
+    '77777777777',
+    '88888888888',
+    '99999999999',
+]));
+exports.INVALID_CNPJ_PATTERNS = Object.freeze(new Set([
+    '00000000000000',
+    '11111111111111',
+    '22222222222222',
+    '33333333333333',
+    '44444444444444',
+    '55555555555555',
+    '66666666666666',
+    '77777777777777',
+    '88888888888888',
+    '99999999999999',
+]));
+exports.ERROR_MESSAGES = Object.freeze({
+    INVALID_TYPE: 'Input must be a string',
+    EMPTY_INPUT: 'Input cannot be empty',
+    INVALID_CPF_LENGTH: 'CPF must have exactly 11 characters',
+    INVALID_CNPJ_LENGTH: 'CNPJ must have exactly 14 characters',
+    INVALID_CPF_PATTERN: 'CPF contains invalid pattern',
+    INVALID_CNPJ_PATTERN: 'CNPJ contains invalid pattern',
+    INVALID_CPF_DIGITS: 'CPF verification digits are invalid',
+    INVALID_CNPJ_DIGITS: 'CNPJ verification digits are invalid',
+    INVALID_CHARACTERS: 'Input contains invalid characters',
+});
+exports.INTERNAL_MESSAGES = Object.freeze({
+    CHAIN_GUARDS_REQUIRES_AT_LEAST_ONE: 'chainGuards requires at least one guard',
+});

package/dist/cpf-validator.d.ts

@@ -0,0 +1,14 @@
+import { FormatOptions, IDocumentValidator, ValidationResult } from './types';
+export declare class CPFValidator implements IDocumentValidator {
+    private readonly firstDigitMultipliers;
+    private readonly secondDigitMultipliers;
+    constructor();
+    clean(input: string): string;
+    format(input: string): string | null;
+    validate(input: string): ValidationResult;
+    private validateCheckDigits;
+}
+export declare function validateCPF(input: string): ValidationResult;
+export declare function formatCPF(input: string, options?: FormatOptions): string | null;
+export declare function cleanCPF(input: string): string;
+export declare function maskCPF(input: string, options?: FormatOptions): string | null;

package/dist/cpf-validator.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CPFValidator = void 0;
+exports.validateCPF = validateCPF;
+exports.formatCPF = formatCPF;
+exports.cleanCPF = cleanCPF;
+exports.maskCPF = maskCPF;
+const constants_1 = require("./constants");
+const guards_1 = require("./guards");
+const utils_1 = require("./utils");
+class CPFValidator {
+    firstDigitMultipliers;
+    secondDigitMultipliers;
+    constructor() {
+        this.firstDigitMultipliers = constants_1.CPF_FIRST_MULTIPLIERS;
+        this.secondDigitMultipliers = constants_1.CPF_SECOND_MULTIPLIERS;
+    }
+    clean(input) {
+        return (0, utils_1.removeNonDigits)((0, utils_1.stripDocumentFormatting)(input));
+    }
+    format(input) {
+        const cleaned = this.clean(input);
+        if (cleaned.length !== constants_1.CPF_LENGTH)
+            return null;
+        const part1 = cleaned.slice(0, 3);
+        const part2 = cleaned.slice(3, 6);
+        const part3 = cleaned.slice(6, 9);
+        const part4 = cleaned.slice(9, 11);
+        return `${part1}.${part2}.${part3}-${part4}`;
+    }
+    validate(input) {
+        const stringGuard = (0, guards_1.guardIsString)(input);
+        const notEmptyGuard = stringGuard.isValid
+            ? (0, guards_1.guardNotEmpty)(stringGuard.cleanedInput)
+            : stringGuard;
+        const baseGuard = (0, guards_1.chainGuards)(stringGuard, notEmptyGuard);
+        if (!baseGuard.isValid)
+            return (0, utils_1.invalidResult)(baseGuard.error);
+        const cleaned = this.clean(baseGuard.cleanedInput);
+        const charGuard = (0, guards_1.guardValidCharacters)(cleaned, constants_1.CPF_ALLOWED_CHARS_REGEX);
+        const lengthGuard = (0, guards_1.guardLength)(cleaned, constants_1.CPF_LENGTH, constants_1.ERROR_MESSAGES.INVALID_CPF_LENGTH);
+        const structureGuard = constants_1.CPF_ALPHANUMERIC_REGEX.test(cleaned)
+            ? { isValid: true, cleanedInput: cleaned }
+            : { isValid: false, error: constants_1.ERROR_MESSAGES.INVALID_CHARACTERS };
+        const patternGuard = constants_1.CPF_DIGIT_REGEX.test(cleaned) && constants_1.INVALID_CPF_PATTERNS.has(cleaned)
+            ? { isValid: false, error: constants_1.ERROR_MESSAGES.INVALID_CPF_PATTERN }
+            : { isValid: true, cleanedInput: cleaned };
+        const finalGuard = (0, guards_1.chainGuards)(charGuard, lengthGuard, structureGuard, patternGuard);
+        return finalGuard.isValid ? this.validateCheckDigits(cleaned) : (0, utils_1.invalidResult)(finalGuard.error);
+    }
+    validateCheckDigits(cpf) {
+        const values = (0, utils_1.stringToDigitArray)(cpf);
+        const firstProvided = Number(cpf[constants_1.CPF_FIRST_DIGIT_POSITION]);
+        const secondProvided = Number(cpf[constants_1.CPF_SECOND_DIGIT_POSITION]);
+        const firstDigit = (0, utils_1.calculateCheckDigit)(values.slice(0, constants_1.CPF_FIRST_DIGIT_POSITION), this.firstDigitMultipliers);
+        if (firstDigit !== firstProvided)
+            return (0, utils_1.invalidResult)(constants_1.ERROR_MESSAGES.INVALID_CPF_DIGITS);
+        const secondDigit = (0, utils_1.calculateCheckDigit)([...values.slice(0, constants_1.CPF_FIRST_DIGIT_POSITION), firstDigit], this.secondDigitMultipliers);
+        if (secondDigit !== secondProvided)
+            return (0, utils_1.invalidResult)(constants_1.ERROR_MESSAGES.INVALID_CPF_DIGITS);
+        return (0, utils_1.validResult)();
+    }
+}
+exports.CPFValidator = CPFValidator;
+const cpfValidatorInstance = new CPFValidator();
+function validateCPF(input) {
+    return cpfValidatorInstance.validate(input);
+}
+function formatCPF(input, options) {
+    const shouldValidate = options?.validate === true;
+    const isInvalidWhenStrict = shouldValidate && !cpfValidatorInstance.validate(input).isValid;
+    if (isInvalidWhenStrict)
+        return null;
+    return cpfValidatorInstance.format(input);
+}
+function cleanCPF(input) {
+    return cpfValidatorInstance.clean(input);
+}
+function maskCPF(input, options) {
+    const shouldValidate = options?.validate === true;
+    const isInvalidWhenStrict = shouldValidate && !cpfValidatorInstance.validate(input).isValid;
+    if (isInvalidWhenStrict)
+        return null;
+    const cleaned = cpfValidatorInstance.clean(input);
+    if (cleaned.length !== constants_1.CPF_LENGTH)
+        return null;
+    const prefix = cleaned.slice(0, 3);
+    const suffix = cleaned.slice(9, 11);
+    return `${prefix}.***.***-${suffix}`;
+}

package/dist/guards.d.ts

@@ -0,0 +1,6 @@
+import { GuardResult } from './types';
+export declare function guardIsString(input: unknown): GuardResult;
+export declare function guardNotEmpty(input: string): GuardResult;
+export declare function guardValidCharacters(input: string, allowedChars: RegExp): GuardResult;
+export declare function guardLength(input: string, expectedLength: number, errorMessage: string): GuardResult;
+export declare function chainGuards(...guards: GuardResult[]): GuardResult;

package/dist/guards.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.guardIsString = guardIsString;
+exports.guardNotEmpty = guardNotEmpty;
+exports.guardValidCharacters = guardValidCharacters;
+exports.guardLength = guardLength;
+exports.chainGuards = chainGuards;
+const constants_1 = require("./constants");
+function guardValid(cleanedInput) {
+    return {
+        isValid: true,
+        cleanedInput,
+    };
+}
+function guardInvalid(error) {
+    return {
+        isValid: false,
+        error,
+    };
+}
+function guardIsString(input) {
+    if (typeof input !== 'string')
+        return guardInvalid(constants_1.ERROR_MESSAGES.INVALID_TYPE);
+    return guardValid(input);
+}
+function guardNotEmpty(input) {
+    const trimmedInput = input.trim();
+    if (trimmedInput.length === 0)
+        return guardInvalid(constants_1.ERROR_MESSAGES.EMPTY_INPUT);
+    return guardValid(trimmedInput);
+}
+function guardValidCharacters(input, allowedChars) {
+    if (!allowedChars.test(input))
+        return guardInvalid(constants_1.ERROR_MESSAGES.INVALID_CHARACTERS);
+    return guardValid(input);
+}
+function guardLength(input, expectedLength, errorMessage) {
+    if (input.length !== expectedLength)
+        return guardInvalid(errorMessage);
+    return guardValid(input);
+}
+function chainGuards(...guards) {
+    if (guards.length === 0)
+        throw new Error(constants_1.INTERNAL_MESSAGES.CHAIN_GUARDS_REQUIRES_AT_LEAST_ONE);
+    for (const guard of guards) {
+        if (!guard.isValid) {
+            return guard;
+        }
+    }
+    return guards.at(-1);
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { CPFValidator, validateCPF, formatCPF, cleanCPF, maskCPF } from './cpf-validator';
+export { CNPJValidator, validateCNPJ, formatCNPJ, cleanCNPJ } from './cnpj-validator';
+export { ValidationResult, DocumentType, IDocumentValidator } from './types';
+export { CPF_LENGTH, CPF_FORMATTED_LENGTH, CNPJ_LENGTH, CNPJ_FORMATTED_LENGTH, CPF_ALPHANUMERIC_REGEX, ERROR_MESSAGES, CPF_RULES, CNPJ_RULES, CHECK_DIGIT_RULES, } from './constants';
+export { guardIsString, guardNotEmpty, guardValidCharacters, guardLength, chainGuards, } from './guards';
+export { stripDocumentFormatting, removeNonDigits, } from './utils';

package/dist/index.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.removeNonDigits = exports.stripDocumentFormatting = exports.chainGuards = exports.guardLength = exports.guardValidCharacters = exports.guardNotEmpty = exports.guardIsString = exports.CHECK_DIGIT_RULES = exports.CNPJ_RULES = exports.CPF_RULES = exports.ERROR_MESSAGES = exports.CPF_ALPHANUMERIC_REGEX = exports.CNPJ_FORMATTED_LENGTH = exports.CNPJ_LENGTH = exports.CPF_FORMATTED_LENGTH = exports.CPF_LENGTH = exports.DocumentType = exports.cleanCNPJ = exports.formatCNPJ = exports.validateCNPJ = exports.CNPJValidator = exports.maskCPF = exports.cleanCPF = exports.formatCPF = exports.validateCPF = exports.CPFValidator = void 0;
+var cpf_validator_1 = require("./cpf-validator");
+Object.defineProperty(exports, "CPFValidator", { enumerable: true, get: function () { return cpf_validator_1.CPFValidator; } });
+Object.defineProperty(exports, "validateCPF", { enumerable: true, get: function () { return cpf_validator_1.validateCPF; } });
+Object.defineProperty(exports, "formatCPF", { enumerable: true, get: function () { return cpf_validator_1.formatCPF; } });
+Object.defineProperty(exports, "cleanCPF", { enumerable: true, get: function () { return cpf_validator_1.cleanCPF; } });
+Object.defineProperty(exports, "maskCPF", { enumerable: true, get: function () { return cpf_validator_1.maskCPF; } });
+var cnpj_validator_1 = require("./cnpj-validator");
+Object.defineProperty(exports, "CNPJValidator", { enumerable: true, get: function () { return cnpj_validator_1.CNPJValidator; } });
+Object.defineProperty(exports, "validateCNPJ", { enumerable: true, get: function () { return cnpj_validator_1.validateCNPJ; } });
+Object.defineProperty(exports, "formatCNPJ", { enumerable: true, get: function () { return cnpj_validator_1.formatCNPJ; } });
+Object.defineProperty(exports, "cleanCNPJ", { enumerable: true, get: function () { return cnpj_validator_1.cleanCNPJ; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "DocumentType", { enumerable: true, get: function () { return types_1.DocumentType; } });
+var constants_1 = require("./constants");
+Object.defineProperty(exports, "CPF_LENGTH", { enumerable: true, get: function () { return constants_1.CPF_LENGTH; } });
+Object.defineProperty(exports, "CPF_FORMATTED_LENGTH", { enumerable: true, get: function () { return constants_1.CPF_FORMATTED_LENGTH; } });
+Object.defineProperty(exports, "CNPJ_LENGTH", { enumerable: true, get: function () { return constants_1.CNPJ_LENGTH; } });
+Object.defineProperty(exports, "CNPJ_FORMATTED_LENGTH", { enumerable: true, get: function () { return constants_1.CNPJ_FORMATTED_LENGTH; } });
+Object.defineProperty(exports, "CPF_ALPHANUMERIC_REGEX", { enumerable: true, get: function () { return constants_1.CPF_ALPHANUMERIC_REGEX; } });
+Object.defineProperty(exports, "ERROR_MESSAGES", { enumerable: true, get: function () { return constants_1.ERROR_MESSAGES; } });
+Object.defineProperty(exports, "CPF_RULES", { enumerable: true, get: function () { return constants_1.CPF_RULES; } });
+Object.defineProperty(exports, "CNPJ_RULES", { enumerable: true, get: function () { return constants_1.CNPJ_RULES; } });
+Object.defineProperty(exports, "CHECK_DIGIT_RULES", { enumerable: true, get: function () { return constants_1.CHECK_DIGIT_RULES; } });
+var guards_1 = require("./guards");
+Object.defineProperty(exports, "guardIsString", { enumerable: true, get: function () { return guards_1.guardIsString; } });
+Object.defineProperty(exports, "guardNotEmpty", { enumerable: true, get: function () { return guards_1.guardNotEmpty; } });
+Object.defineProperty(exports, "guardValidCharacters", { enumerable: true, get: function () { return guards_1.guardValidCharacters; } });
+Object.defineProperty(exports, "guardLength", { enumerable: true, get: function () { return guards_1.guardLength; } });
+Object.defineProperty(exports, "chainGuards", { enumerable: true, get: function () { return guards_1.chainGuards; } });
+var utils_1 = require("./utils");
+Object.defineProperty(exports, "stripDocumentFormatting", { enumerable: true, get: function () { return utils_1.stripDocumentFormatting; } });
+Object.defineProperty(exports, "removeNonDigits", { enumerable: true, get: function () { return utils_1.removeNonDigits; } });

package/dist/types.d.ts

@@ -0,0 +1,21 @@
+export interface ValidationResult {
+    isValid: boolean;
+    error?: string;
+}
+export declare enum DocumentType {
+    CPF = "CPF",
+    CNPJ = "CNPJ"
+}
+export interface IDocumentValidator {
+    validate(input: string): ValidationResult;
+    format(input: string): string | null;
+    clean(input: string): string;
+}
+export interface GuardResult {
+    isValid: boolean;
+    error?: string;
+    cleanedInput?: string;
+}
+export interface FormatOptions {
+    validate?: boolean;
+}

package/dist/types.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocumentType = void 0;
+var DocumentType;
+(function (DocumentType) {
+    DocumentType["CPF"] = "CPF";
+    DocumentType["CNPJ"] = "CNPJ";
+})(DocumentType || (exports.DocumentType = DocumentType = {}));

package/dist/utils.d.ts

@@ -0,0 +1,11 @@
+import { ValidationResult } from './types';
+export declare function calculateCheckDigit(digits: ReadonlyArray<number>, multipliers: ReadonlyArray<number>): number;
+export declare function stringToDigitArray(input: string): ReadonlyArray<number>;
+export declare function removeNonDigits(input: string): string;
+export declare function areAllDigitsSame(input: string): boolean;
+export declare function stripDocumentFormatting(input: string): string;
+export declare function removeNonAlphanumeric(input: string): string;
+export declare function charToBase36Value(char: string): number;
+export declare function stringToBase36ValueArray(input: string): ReadonlyArray<number>;
+export declare function validResult(): ValidationResult;
+export declare function invalidResult(error?: string): ValidationResult;

package/dist/utils.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateCheckDigit = calculateCheckDigit;
+exports.stringToDigitArray = stringToDigitArray;
+exports.removeNonDigits = removeNonDigits;
+exports.areAllDigitsSame = areAllDigitsSame;
+exports.stripDocumentFormatting = stripDocumentFormatting;
+exports.removeNonAlphanumeric = removeNonAlphanumeric;
+exports.charToBase36Value = charToBase36Value;
+exports.stringToBase36ValueArray = stringToBase36ValueArray;
+exports.validResult = validResult;
+exports.invalidResult = invalidResult;
+const constants_1 = require("./constants");
+function calculateCheckDigit(digits, multipliers) {
+    const sum = digits.reduce((acc, digit, index) => acc + digit * multipliers[index], constants_1.DIGIT_ZERO);
+    const remainder = sum % constants_1.MODULO_DIVISOR;
+    return remainder < constants_1.MIN_REMAINDER_FOR_ZERO ? constants_1.DIGIT_ZERO : constants_1.MODULO_DIVISOR - remainder;
+}
+function stringToDigitArray(input) {
+    return Array.from(input, Number);
+}
+function removeNonDigits(input) {
+    return input.replaceAll(constants_1.NON_DIGIT_REGEX, '');
+}
+function areAllDigitsSame(input) {
+    const firstChar = input[0];
+    return input.split('').every((char) => char === firstChar);
+}
+function stripDocumentFormatting(input) {
+    return input.replaceAll(constants_1.DOCUMENT_FORMATTING_REGEX, '');
+}
+function removeNonAlphanumeric(input) {
+    return input.replaceAll(constants_1.NON_ALPHANUMERIC_REGEX, '');
+}
+function charToBase36Value(char) {
+    return Number.parseInt(char, 36);
+}
+function stringToBase36ValueArray(input) {
+    return Array.from(input, (char) => charToBase36Value(char.toUpperCase()));
+}
+function validResult() {
+    return { isValid: true };
+}
+function invalidResult(error) {
+    return { isValid: false, error };
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "validador-cnpj-cpf",
+  "version": "1.0.1",
+  "description": "Performant and secure Brazilian document validator (CPF/CNPJ)",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\" && tsc",
+    "test": "jest --coverage",
+    "test:watch": "jest --watch",
+    "lint": "eslint 'src/**/*.ts'",
+    "lint:fix": "eslint 'src/**/*.ts' --fix",
+    "format": "prettier --write 'src/**/*.ts'",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "cpf",
+    "cnpj",
+    "validator",
+    "brazil",
+    "document",
+    "validation",
+    "typescript"
+  ],
+  "author": "Christopher Pinto - @chrisJSeng",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chrisJSeng/validador-cpf-cnpj.git"
+  },
+  "bugs": {
+    "url": "https://github.com/chrisJSeng/validador-cpf-cnpj/issues"
+  },
+  "homepage": "https://github.com/chrisJSeng/validador-cpf-cnpj#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.11",
+    "@types/node": "^20.10.6",
+    "@typescript-eslint/eslint-plugin": "^6.17.0",
+    "@typescript-eslint/parser": "^6.17.0",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.1.1",
+    "ts-jest": "^29.1.1",
+    "typescript": "^5.3.3"
+  },
+  "files": [
+    "dist"
+  ]
+}