CEP

Valida um CEP (código de endereçamento postal).

• Aceita string ou number. Um CEP que começa com 0 precisa ser string, já que um número não preserva o zero à esquerda, e um número só é lido quando é um inteiro seguro não negativo.
• Espaços, pontos, hífens e barras são ignorados. Qualquer outro caractere invalida o valor.
• getAddressInfoByCep e formatCep com pad: true são mais tolerantes com números: preenchem um número com zeros à esquerda até 8 dígitos (1310100 vira 01310-100), enquanto isValidCep e getStateByCep leem 1310100 como 7 dígitos e o rejeitam.

import { isValidCep } from '@brazilian-utils/brazilian-utils';

isValidCep('01310100'); // true
isValidCep('92500-000'); // true (hífen entre os grupos)
isValidCep('92.500-000'); // true (ponto e hífen)
isValidCep('013 10 100'); // true (espaços em qualquer posição entre os dígitos)
isValidCep(20040020); // true (entrada numérica)
isValidCep(-20040020); // false (não é um inteiro seguro não negativo)
isValidCep('9250000A'); // false (letras são rejeitadas)
isValidCep('12345'); // false (tamanho inválido)

Formata um CEP (código de endereçamento postal).

• Opções (FormatCepOptions): pad preenche o valor com zeros à esquerda até 8 dígitos antes de aplicar a máscara (padrão false). Um valor vazio, ou sem dígitos, devolve '' mesmo com pad.
• Um CEP que começa com 0 passado como número perde esse zero: passe uma string ou use pad. Um número só é lido quando é um inteiro seguro não negativo; qualquer outro número retorna ''.

import { formatCep } from '@brazilian-utils/brazilian-utils';

formatCep('92500000'); // 92500-000
formatCep('9250000', { pad: true }); // 09250-000
formatCep(-92500000); // '' (não é um inteiro seguro não negativo)

Remove a formatação do CEP, mantém apenas os dígitos e limita o resultado a 8 dígitos.

import { parseCep } from '@brazilian-utils/brazilian-utils';

parseCep('92500-000'); // 92500000

Gera um CEP aleatório. Um CEP não tem dígito verificador, então o CEP é sorteado dentro das faixas que os Correios atribuem aos estados, com a mesma chance para cada CEP. Ele sempre pertence a um estado, então getStateByCep nunca responde null para ele; 00000-000 a 00999-999 e 78900-000 a 78999-999, que nenhum estado possui, nunca são gerados. Uma faixa é o bloco que um estado possui, não uma garantia de que todo CEP dela está em uso, então o CEP pode não ser o de um endereço real.

import { generateCep } from '@brazilian-utils/brazilian-utils';

generateCep(); // '92500000'

Busca o endereço de um CEP em vários provedores ao mesmo tempo e resolve com a primeira resposta bem-sucedida. O resultado é um AddressInfo: cep, state, city, neighborhood e street.

• Opções (GetAddressInfoByCepOptions):
  • providers (CepProvider[]) lista os provedores a disputar (padrão ['viacep', 'brasilapi']). 'widenet' está descontinuado, fica fora da lista padrão e costuma estar indisponível: seu endpoint agora redireciona para ws.apicep.com, que respondia 502 na última verificação, então ele só acrescenta um provedor que falha à disputa.
  • timeoutMs (number) limita a busca inteira, tentativas incluídas (padrão: sem limite). Quando o tempo acaba, todas as requisições são abortadas e a chamada rejeita com GetAddressInfoByCepServiceError.
  • signal (AbortSignal) cancela a busca; a chamada rejeita com signal.reason, como o fetch.
• Aceita string ou número. Uma string tem removido todo caractere que não é dígito ('CEP 01310-100' é 01310100) e precisa sobrar com 8 dígitos. Um número é preenchido com zeros à esquerda até 8 dígitos, já que não carrega o zero inicial de um CEP de São Paulo, mas só a partir de 1000000 (01000-000, o menor CEP que os Correios atribuem). Um número menor, negativo ou fracionário é rejeitado com GetAddressInfoByCepValidationError antes de qualquer requisição.
• Repete falhas transitórias de rede por provedor.
• Rejeita com GetAddressInfoByCepValidationError quando o CEP é inválido, providers não nomeia nenhum provedor conhecido ou timeoutMs não é um número finito positivo, com GetAddressInfoByCepNotFoundError quando todos os provedores falharam e pelo menos um informou que o CEP é desconhecido, e com GetAddressInfoByCepServiceError quando todos os provedores falharam por outro motivo.
• A BrasilAPI responde 404 tanto para um CEP desconhecido quanto quando os serviços por trás dela estão fora do ar, então o 404 dela só conta como "CEP desconhecido" quando nenhum outro provedor deixou de responder.
• Um endereço só é aceito quando concorda com o CEP pedido: seus dígitos, preenchidos com zeros à esquerda até 8 (um provedor que responde 1310100 para 01310-100 quer dizer o mesmo CEP), precisam ser o CEP e o estado dele, quando informado, precisa ser o estado dono da faixa do CEP (veja getStateByCep). Caso contrário, esse provedor conta como não conhecendo o CEP. A BrasilAPI, por exemplo, respondeu o 99999-999, um CEP do Rio Grande do Sul, com uma cidade do Paraná.
• Quando a busca termina, as requisições dos provedores que perderam a disputa são abortadas.
• Os três estendem GetAddressInfoByCepError, então um único catch cobre todos.

import { getAddressInfoByCep, GetAddressInfoByCepNotFoundError } from '@brazilian-utils/brazilian-utils';

// Usando os provedores padrão (['viacep', 'brasilapi'])
const address = await getAddressInfoByCep('01310100');
// { cep: '01310100', state: 'SP', city: 'São Paulo', neighborhood: 'Bela Vista', street: 'Avenida Paulista' }

// Usando um provedor específico, e distinguindo um CEP desconhecido de uma falha
try {
  await getAddressInfoByCep('01310-100', { providers: ['brasilapi'] });
} catch (error) {
  if (error instanceof GetAddressInfoByCepNotFoundError) {
    // nenhum provedor conhece o CEP
  }
}

// Usando número como entrada (será preenchido automaticamente com zeros à esquerda)
const addressFromNumber = await getAddressInfoByCep(1310100);

// Desistindo depois de 5 segundos
const addressWithinFiveSeconds = await getAddressInfoByCep('01310100', { timeoutMs: 5000 });

Busca os CEPs de um endereço na ViaCEP. Resolve com um array de CepAddressInfo.

• O argumento (GetCepInfoByAddressParams) traz federalUnit, city e street. federalUnit pode estar em minúsculas; city e street têm os espaços nas pontas removidos e os acentos retirados antes da consulta, e cada um precisa ser uma string com pelo menos 3 caracteres depois disso, o mínimo que a ViaCEP aceita.
• Rejeita com GetCepInfoByAddressValidationError quando a UF, a cidade ou a rua está ausente ou inválida (um valor em branco, um valor que não é string, ou uma cidade ou rua com menos de 3 caracteres, todos rejeitados antes de qualquer requisição), com GetCepInfoByAddressNotFoundError quando nenhum endereço corresponde à busca, e com GetCepInfoByAddressError quando a ViaCEP responde com um status de erro HTTP.
• Repete falhas transitórias de rede, como getAddressInfoByCep.
• Cada item traz a resposta da ViaCEP sem alterações, com os nomes de campo da própria ViaCEP.
• A ViaCEP limita a lista a 50 endereços, então um nome de rua curto que corresponde a mais ruas retorna só os 50 primeiros.

import { getCepInfoByAddress } from '@brazilian-utils/brazilian-utils';

const ceps = await getCepInfoByAddress({
  federalUnit: 'MG',
  city: 'Ouro Preto',
  street: 'Rua Direita'
});

// [
//   {
//     cep: '35411-152',
//     logradouro: 'Rua Direita',
//     complemento: '',
//     unidade: '',
//     bairro: 'Riacho (Amarantina)',
//     localidade: 'Ouro Preto',
//     uf: 'MG',
//     estado: 'Minas Gerais',
//     regiao: 'Sudeste',
//     ibge: '3146107',
//     gia: '',
//     ddd: '31',
//     siafi: '4921'
//   }
// ]

Retorna o estado brasileiro ao qual um CEP pertence, a partir das faixas de CEP que os Correios atribuem a cada UF (a "Faixa de CEP" de cada UF).

• Funciona offline: nenhuma API de CEP é chamada, então a resposta diz qual estado é dono da faixa, não se o CEP está em uso.
• Aceita o que o isValidCep aceita: 8 dígitos, como string ou número, ignorando espaços, pontos, hífens e barras. Um CEP que começa com 0 precisa ser uma string, e um número negativo ou fracionário é rejeitado. getAddressInfoByCep e formatCep com pad: true preenchem números com zeros à esquerda (1310100 vira 01310-100).
• Amazonas, Distrito Federal e Goiás têm duas faixas cada, e nenhuma faixa estadual cobre 00000-000 a 00999-999 nem 78900-000 a 78999-999.
• A faixa é o bloco que pertence ao estado, não uma garantia de que todo CEP dentro dela está em uso: 10000-000 está sem uso dentro da faixa de São Paulo e ainda assim responde São Paulo.
• Retorna null para um CEP inválido ou fora de todas as faixas. Exporta o tipo State.

import { getStateByCep } from '@brazilian-utils/brazilian-utils';

getStateByCep('01310-100');
// { code: 'SP', name: 'São Paulo', regionCode: 'SE', regionName: 'Sudeste', ibgeCode: 35 }

getStateByCep(20040020);
// { code: 'RJ', name: 'Rio de Janeiro', regionCode: 'SE', regionName: 'Sudeste', ibgeCode: 33 }

getStateByCep('69300-000')?.code; // 'RR'
getStateByCep('72800-000')?.code; // 'GO'
getStateByCep('00999-999'); // null
getStateByCep('12345'); // null

Fonte: Correios, Busca Faixa de CEP