H7 Mask Utils

H7 Mask Utils is a TypeScript library designed to format common Brazilian data and others formats in general, such as phone numbers, CPF, CNPJ, and ZIP codes. It transforms numeric inputs into readable and validated formats.

💖 Support This Project / Apoie Este Projeto

If this project has been helpful to you, please consider making a donation to support its ongoing development. Maintaining and improving this package takes time and effort, and your contribution helps ensure we can keep delivering quality solutions to the community.

Se este projeto foi útil para você, considere fazer uma doação para apoiar seu desenvolvimento contínuo. Manter este pacote atualizado e funcional exige tempo e esforço. Sua contribuição ajuda a garantir que possamos continuar fornecendo soluções de qualidade para a comunidade.

👉 Donate Here / Doe Aqui

Even a small contribution makes a big difference. Thank you for helping make this project possible!

Mesmo uma pequena contribuição faz uma grande diferença. Obrigado por ajudar a tornar este projeto possível! 🙏

Why donate? / Por que doar?

• ✅ To help develop new features.

  Para ajudar no desenvolvimento de novos recursos.

• ✅ To maintain compatibility with the latest versions of libraries and tools.

  Para manter a compatibilidade com as últimas versões de bibliotecas e ferramentas.

• ✅ To support a developer who values community contributions.

  Para apoiar um desenvolvedor que acredita na contribuição com a comunidade.

📦 Installation

Install the library using the following command:

npm install h7-mask-utils

🚀 Usage

Here’s how to use the mask function to format different types of data:

import { mask } from 'h7-mask-utils';

// Usando máscara padrão
console.log(mask('cpf', '12345678901')); // "123.456.789-01"
console.log(mask('phone', '11987654321')); // "(11) 98765-4321"
console.log(mask('zipCode', '12345678')); // "12345-678"
console.log(mask('custom', '1234567890', '##.##.##.##.##')); // "12.34.56.78.90"

📖 Supported Masks

| Type | Input Example | Output Example | Custom formats | |------------|-------------------|------------------------|---------------| | phone | 11111111111 | (11) 11111-1111 | | | cpf | 11111111111 | 111.111.111-11 | | | cnpj | 11111111111111 | 11.111.111/1111-11 | | | zipCode | 11111111 | 11111-111 | | | custom | 111111 | 111-111 | ###.### |

📖 Features

• Brazilian data formatting:
  • Phone (phone)
  • CPF (cpf)
  • CNPJ (cnpj)
  • ZIP Code (zipCode)
• Others formats
  • Custom (Card, format)
• Automatic validation: Checks if the input length matches the required type.
• TypeScript support: Fully typed for seamless integration in TypeScript projects.
• Lightweight and efficient: A simple library with no external dependencies.

🛠️ How It Works

The library performs the following steps to format data:

1. Removes non-numeric characters.
2. Verifies the input length.
3. Applies the correct mask based on the specified type.
4. Apply custom mask based on input characteres

If the input is invalid, it returns false.

📜 Example Use Case

Imagine an application where users must provide a CPF, CNPJ, or phone number for registration. With this library, you can ensure the data is properly formatted before storing it:

import { mask } from 'h7-mask-utils';

const cpf = '12345678909';
const formattedCPF = mask('cpf', cpf);

if (formattedCPF) {
  console.log(`Formatted CPF: ${formattedCPF}`);
} else {
  console.log('Invalid CPF. Please try again.');
}

🤝 Contributing

Feel free to contribute to this project by opening issues or submitting pull requests. All contributions are welcome!

👨‍💻 Author

Developed by Herlandio. If you find this library helpful, consider starring the repository on GitHub!

📝 License

This project is licensed under the MIT License. You are free to use, modify, and distribute it as long as you provide proper attribution.