frontend-utils

Biblioteca de utilitários para normalização, validação e máscara de entradas comuns no front-end.

Foco atual:

• CPF
• CNPJ (incluindo alfanumérico)
• Cellphone BR
• Phone (telefone fixo BR)
• E-mail
• CEP
• Helpers e regex reutilizáveis

Instalação

npm install @solfacil/frontend-utils
# pnpm add @solfacil/frontend-utils
# yarn add @solfacil/frontend-utils

Como importar

Você pode importar do pacote raiz ou por subpath.

Opção 1 — pacote raiz

import { cpf, cnpj, cellphone, phone, cep, email } from '@solfacil/frontend-utils'

Opção 2 — subpath (recomendado por domínio)

import { cpf } from '@solfacil/frontend-utils/cpf'
import { cnpj } from '@solfacil/frontend-utils/cnpj'
import { cellphone } from '@solfacil/frontend-utils/cellphone'
import { phone } from '@solfacil/frontend-utils/phone'
import { cep } from '@solfacil/frontend-utils/cep'
import { email } from '@solfacil/frontend-utils/email'

API completa por domínio

Nesta seção, cada domínio mostra:

• import recomendado (namespace)
• exports diretos disponíveis
• exemplos com entrada -> saída

As strings mask / *InputMask seguem o Maska v1 (# = dígito; no CNPJ, X = alfanumérico nos 12 primeiros caracteres e # = só dígito nos 2 verificadores). Evite * nessas máscaras: no Maska v1 * é metacaractere de repetição.

CPF

Import recomendado (namespace):

import { cpf } from '@solfacil/frontend-utils/cpf'

cpf.mask // '###.###.###-##'
cpf.applyMask('5299') // '529.9'
cpf.validInput('529.982.247-25') // true
cpf.normalize('529.982.247-25') // '52998224725'

Exports diretos de @solfacil/frontend-utils/cpf:

import {
  cpfInputMask,
  formatCpfTyping,
  formatCpfMasked,
  stripCpfMask,
  normalizeCpfDigits,
  cpfToApiPayload,
  isValidCpfInput,
  isValidCpfNormalized,
} from '@solfacil/frontend-utils/cpf'

cpfInputMask // '###.###.###-##'

formatCpfTyping('52998') // '529.98'
formatCpfMasked('52998224725') // '529.982.247-25'
formatCpfMasked('52998') // '52998' (incompleto -> retorna original)

stripCpfMask('529.982.247-25') // '52998224725'
normalizeCpfDigits('529.982.247-25') // '52998224725'
cpfToApiPayload('529.982.247-25') // '52998224725'

isValidCpfInput('529.982.247-25') // true
isValidCpfNormalized('52998224725') // true

CNPJ

Import recomendado (namespace):

import { cnpj } from '@solfacil/frontend-utils/cnpj'

cnpj.mask // 'XX.XXX.XXX/XXXX-##'
cnpj.applyMask('19JA2') // '19.JA2'
cnpj.validInput('19.JA2.KO8/Z001-51') // true
cnpj.normalize('19.JA2.KO8/Z001-51') // '19JA2KO8Z00151'

Exports diretos de @solfacil/frontend-utils/cnpj:

import {
  cnpjInputMask,
  formatCnpjTyping,
  formatCnpjMasked,
  stripCnpjMask,
  normalizeCnpjAlphanumeric,
  cnpjToApiPayload,
  cnpjCharToValidationValue,
  isValidCnpjInput,
  isValidCnpjNormalized,
} from '@solfacil/frontend-utils/cnpj'

cnpjInputMask // 'XX.XXX.XXX/XXXX-##'

formatCnpjTyping('19JA2') // '19.JA2'
formatCnpjMasked('19JA2KO8Z00151') // '19.JA2.KO8/Z001-51'
formatCnpjMasked('19JA2') // '19JA2' (incompleto -> retorna original)

stripCnpjMask('19.JA2.KO8/Z001-51') // '19JA2KO8Z00151'
normalizeCnpjAlphanumeric('19.JA2.KO8/Z001-51') // '19JA2KO8Z00151'
cnpjToApiPayload('19.JA2.KO8/Z001-51') // '19JA2KO8Z00151'

cnpjCharToValidationValue('A') // 17

isValidCnpjInput('19.JA2.KO8/Z001-51') // true
isValidCnpjNormalized('19JA2KO8Z00151') // true

Cellphone BR

Regra: para ser válido como celular, precisa ter 11 dígitos (DDD + 9 dígitos) e o terceiro dígito deve ser 9.

Import recomendado (namespace):

import { cellphone } from '@solfacil/frontend-utils/cellphone'

cellphone.mask // '(##) #####-####'
cellphone.applyMask('119876') // '(11) 9876'
cellphone.validInput('(11) 98765-4321') // true
cellphone.normalize('+55 (11) 98765-4321') // '11987654321'
cellphone.normalizeWithCountryCode('(11) 98765-4321') // '+5511987654321'

Exports diretos de @solfacil/frontend-utils/cellphone:

import {
  cellphoneInputMask,
  formatCellphoneTyping,
  formatCellphoneMasked,
  stripCellphoneMask,
  normalizeCellphoneDigits,
  normalizeCellphoneWithCountryCode,
  cellphoneToApiPayload,
  isValidCellphoneInput,
  isValidCellphoneNormalized,
  validBrDdd,
} from '@solfacil/frontend-utils/cellphone'

cellphoneInputMask // '(##) #####-####'

formatCellphoneTyping('119876') // '(11) 9876'
formatCellphoneMasked('11987654321') // '(11) 98765-4321'
formatCellphoneMasked('119876') // '119876' (incompleto -> retorna original)

stripCellphoneMask('+55 (11) 98765-4321') // '11987654321'
normalizeCellphoneDigits('+55 (11) 98765-4321') // '11987654321'
normalizeCellphoneWithCountryCode('(11) 98765-4321') // '+5511987654321'
cellphoneToApiPayload('+55 (11) 98765-4321') // '11987654321'

isValidCellphoneInput('(11) 98765-4321') // true
isValidCellphoneNormalized('11987654321') // true
isValidCellphoneNormalized('1187654321') // false (sem nono dígito 9)

validBrDdd.has('11') // true

Phone (telefone fixo BR)

Regra: para ser válido como fixo, precisa ter 10 dígitos e primeiro dígito local entre 2 e 5.

Import recomendado (namespace):

import { phone } from '@solfacil/frontend-utils/phone'

phone.mask // '(##) ####-####'
phone.applyMask('1123') // '(11) 23'
phone.validInput('(11) 2345-6789') // true
phone.normalize('+55 (11) 2345-6789') // '1123456789'
phone.normalizeWithCountryCode('(11) 2345-6789') // '+551123456789'

Exports diretos de @solfacil/frontend-utils/phone:

import {
  phoneInputMask,
  formatPhoneTyping,
  formatPhoneMasked,
  stripPhoneMask,
  normalizePhoneDigits,
  normalizePhoneWithCountryCode,
  isValidPhoneInput,
  isValidPhoneNormalized,
} from '@solfacil/frontend-utils/phone'

phoneInputMask // '(##) ####-####'

formatPhoneTyping('1123') // '(11) 23'
formatPhoneMasked('1123456789') // '(11) 2345-6789'
formatPhoneMasked('1123') // '1123' (incompleto -> retorna original)

stripPhoneMask('+55 (11) 2345-6789') // '1123456789'
normalizePhoneDigits('+55 (11) 2345-6789') // '1123456789'
normalizePhoneWithCountryCode('(11) 2345-6789') // '+551123456789'

isValidPhoneInput('(11) 2345-6789') // true
isValidPhoneNormalized('1123456789') // true

CEP

Import recomendado (namespace):

import { cep } from '@solfacil/frontend-utils/cep'

cep.mask // '#####-###'
cep.applyMask('013101') // '01310-1'
cep.validInput('01310-100') // true
cep.normalize('01310-100') // '01310100'

E-mail

Import recomendado (namespace):

import { email } from '@solfacil/frontend-utils/email'

email.validInput('[email protected]') // true
email.normalize(' [email protected] ') // '[email protected]'
email.toApiPayload(' [email protected] ') // '[email protected]'

Exports diretos de @solfacil/frontend-utils/email:

import { normalizeEmail, isValidEmailInput } from '@solfacil/frontend-utils/email'

normalizeEmail(' [email protected] ') // '[email protected]'
isValidEmailInput('[email protected]') // true
isValidEmailInput('no-at-sign') // false

Utilitários e validadores compartilhados

utils

import {
  applyMaskPattern,
  applyDigitMask,
  applyAlphanumericMask,
  sanitizeDigits,
  sanitizeAlphanumericUpper,
  parseE164ToBrDigits,
} from '@solfacil/frontend-utils/utils'

applyMaskPattern('AB12', 'XX-XX', {
  normalize: (v) => v.replace(/[^A-Za-z0-9]/g, '').toUpperCase(),
}) // 'AB-12'

applyDigitMask('529982', '###.###.###-##') // '529.982'
sanitizeDigits('(11) 98765-4321') // '11987654321'
parseE164ToBrDigits('+55 (11) 98765-4321') // '11987654321'

validators

import {
  cpfNormalizedRegex,
  cnpjNormalizedRegex,
  emailInputRegex,
} from '@solfacil/frontend-utils/validators'

cpfNormalizedRegex.test('52998224725') // true
emailInputRegex.test('[email protected]') // true

Cobertura de testes

A cobertura é validada no CI com os limites mínimos:

• Linhas: 90%
• Declarações: 90%
• Funções: 90%
• Desvios (branches): 80%

Rodar localmente:

npm run coverage

TODO (pendente para depois)

• Reativar CHANGELOG.md automático via @semantic-release/changelog + @semantic-release/git quando houver bypass controlado para o bot no ruleset da main.
• Avaliar suporte de MCP para integração com IA, com escopo e estratégia de consumo definidos para não impactar o uso da lib no frontend.