global-docs

A library for validating and formatting country-specific documents in international applications.

global-docs is designed to provide a standardized, extensible and reliable way to handle document validation and masking rules that vary from country to country, while exposing a consistent API to consumers.

The project is modular by design: each country (and each document within that country) lives in its own isolated module, making it easy to maintain, test and extend.

✨ Features

• ✅ Validation and formatting (masking)
• 🌍 Country-specific document rules
• 🧩 Modular and extensible architecture
• 🧪 Fully unit-tested
• 📦 Tree-shakable and framework-agnostic
• 🛡️ Strict separation of concerns (validate ≠ mask)

📦 Supported Countries

Currently, global-docs focuses on Brazilian documents, with the architecture ready to support additional countries in the future.

🌍 Country Packages

global-docs acts as a core specification and shared foundation. Country-specific rules live in separate companion packages, allowing each country to evolve independently while following the same design principles.

Currently available country packages:

• global-docs-br — Brazilian documents (CPF, CNPJ, IE, professional registrations, etc.)

Planned / upcoming:

• global-docs-us — United States documents
• global-docs-fr — France documents
• global-docs-eu — European Union documents (where applicable)

Each country package provides its own documentation, validation rules, masks and test suites.

📂 Project Structure (Simplified)

global-docs/
├─ src/
│  ├─ index.ts
│  ├─ mask.ts
│  ├─ registry.ts
│  ├─ types.ts
│  └─ validate.ts
├─ package.json
├─ README.md
└─ tsconfig.json

The test structure mirrors the source structure to ensure clarity and maintainability.

🧪 Testing Philosophy

• Each document has its own test suite
• IE tests are split per state
• Validation and masking are tested independently
• No real or sensitive personal data is used
• Valid test data is generated via helper functions

🧠 Design Principles

• Single Responsibility: validation and formatting are separate concerns
• Explicitness: state-specific rules are never abstracted away incorrectly
• Correctness over convenience
• Documentation-driven development (official sources first)

🚀 Roadmap

• Add more countries
• Add more Brazilian complementary documents
• Improve error reporting
• Optional strict validation modes

📄 License

MIT