Brazilian document validators and formatters for global-docs
npm install global-docs-brglobal-docs ecosystem.
ts
// Example (IE - Goiás)
mask("1234") → "12.34"
mask("12345678") → "12.345.678"
mask("123456789") → "12.345.678-9"
`
---
$3
Every document validator:
- has deterministic unit tests
- has a makeValid* helper to generate valid values
- never depends on real or sensitive data (LGPD-compliance on development)
> No real personal or company data is used or required.
---
🚀 Quick Start (Standalone)
First, install the package:
`bash
npm install global-docs-br
`
You can use Brazilian document validators directly, without any registration step:
`ts
import { CPF, CNPJ, IE } from "global-docs-br";
// CPF
CPF.validate("11144477735"); // true
CPF.mask("11144477735"); // "111.444.777-35"
// CNPJ
CNPJ.validate("11444777000161"); // true
CNPJ.mask("11444777000161"); // "11.444.777/0001-61"
// State Registration (IE) — requires UF context
IE.validate("123456789", { uf: "GO" }); // false
IE.mask("123456789", { uf: "GO" }); // "12.345.678-9"
`
> No registration step is required when using documents directly.
---
$3
If you are using the core global-docs engine with country-based resolution, you must explicitly register Brazilian documents:
#### 1️⃣ Register Brazilian documents
`ts
import { registerBrazilDocuments } from "global-docs-br";
registerBrazilDocuments();
`
This registers all Brazilian document validators under country code BR.
---
#### 2️⃣ Validate and mask using the engine API
`ts
import { validate, mask } from "global-docs";
// Validation
validate("BR", "CPF", "11144477735"); // true
validate("BR", "CNPJ", "11444777000161"); // true
// Masking
mask("BR", "CPF", "11144477735"); // "111.444.777-35"
mask("BR", "CNPJ", "11444777000161"); // "11.444.777/0001-61"
`
You may also use the path-based helpers:
`ts
import { validatePath, maskPath } from "global-docs";
validatePath("BR.CPF", "11144477735"); // true
maskPath("BR.CPF", "11144477735"); // "111.444.777-35"
`
> registerBrazilDocuments is only required when using the dynamic country based registry mechanism provided by global-docs.
> If you are importing documents directly from global-docs-br, registration is not needed.
---
🧪 Testing
Tests are organized by responsibility:
`
documents/
├─ cau/
│ ├─ __tests__/
│ │ ├─ cau.spec.ts
│ │ ├─ validate.spec.ts
│ │ └─ mask.spec.ts
│ ├─ cau.ts
│ ├─ index.ts
│ ├─ mask.ts
│ └─ validate.ts
├─ cnh/
│ ├─ __tests__/
│ │ ├─ cnh.spec.ts
│ │ ├─ validate.spec.ts
│ │ └─ mask.spec.ts
│ ├─ cnh.ts
│ ├─ index.ts
│ ├─ mask.ts
│ └─ validate.ts
├─ ie/
│ ├─ index.ts
│ ├─ registry.ts
│ ├─ types.ts
│ ├─ states/
│ │ ├─ ac.ts
│ │ ├─ al.ts
│ │ ├─ am.ts
│ │ ├─ ap0.ts
│ │ └─ ...
│ └─ __tests__/
│ ├─ registry.spec.ts
│ ├─ mask.spec.ts # generic IE mask routing
│ ├─ validate.spec.ts # generic IE validate routing
│ ├─ helpers # IE faker
│ ├─ ac.ts
│ ├─ al.ts
│ ├─ am.ts
│ ├─ ap.ts
│ └─ ...
│ └─ states/
│ ├─ ac.spec.ts
│ ├─ al.spec.ts
│ ├─ am.spec.ts
│ ├─ ap.spec.ts
│ └─ ...
``