BrasilAPI / BrasilAPI/cep-promise

[Sugestões] Melhorias no suporte para TypeScript + Error handling

Open
#224 6 comments 5 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
3k
Forks
317
PR merge metrics
No merged PRs in 30d

Description

Infelizmente não tenho conhecimento para fazer esse PR, mas gostaria de dá sugestões que poderiam ser adicionadas no roadmap do projeto baseado no que outras bibliotecas e o mercado como um todo estão adotando:

1. Melhorar o suporte ao TypeScript na biblioteca (https://github.com/BrasilAPI/cep-promise/issues/223#issuecomment-884502083, https://github.com/BrasilAPI/cep-promise/issues/212)

2. Quando você digita um cep inválido, mesmo com 8 caracteres, a biblioteca retorna um erro dizendo que nenhum provedor encontrou aquele cep. Acho interessante continuar tendo essa opção de retornar um erro, mas também dá a opção para o desenvolvedor de retornar apenas NULL. Acho muito mais legível fazer isso:

```ts
const cepData = await cep('58308000', { rejectOnNotFound: false })
if (!cepData) {
...envia uma mensagem para o usuário
}
```

Do que isso:

```ts
const cepData = cep('58308000')
.then((res) => console.log(res))
.catch(err) => console.log('VOCÊ TRATA O ERRO NO BLOCO CATCH'))
```

Sobre a convenção de nome "rejectOnNotFound", estou me inspirando no Prisma que é um ORM e utilizam essa mesma convenção:
https://www.prisma.io/docs/reference/api-reference/prisma-client-reference#rejectonnotfound

**Validação do CEP:**
Ainda sobre error handling, seria legal disparar um erro caso o CEP não tenha 8 caracteres (não cheguei a ver se a biblioteca já faz isso). Poderia usar essa diretiva "rejectOnNotFound" também. Ficaria assim:

```ts
const cepData = await cep('58308000', { rejectOnNotFound: {
cepNotFound: false,
cepInvalid: true,
} })
```

O cep-promise não traz uma função do tipo `"cep('58308000').isValid()"` e realmente compreendo que talvez os criadores da biblioteca acreditem que isso foge do escopo do projeto. Na minha opinião não foge do escopo, tendo em vista que quando é requisitado dados sobre um cep, usando a biblioteca cep-promise, é esperado que o cep seja válido (8 caracteres, somente números), ou você está apenas fazendo requisições inúteis e gastando banda de 3 - 4 servidores de API que de boa-fé, disponibilizam seus serviços para todos gratuitamente.

Dá a opção de escolher ao desenvolvedor se deveria ser lançado ou não uma exceção quando o cep fosse inválido, seria interessante.

Exemplo: Se eu já fiz a validação do cep usando outra biblioteca, mas mesmo assim o cep chega mal formatado no cep promise, eu como desenvolvedor vou querer que isso sempre gere uma exceção, pois é um comportamento inesperado da minha aplicação.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the current cep(...) API and the linked discussions in issues 223 and 212. Clarify the desired TypeScript support, not-found behavior, and invalid-CEP validation before proposing separate, testable changes. Done should include an agreed API design and verified behavior for each requested option.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, typescript
Domain
api, backend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.