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)
``
text
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