BrasilAPI / BrasilAPI/cep-promise
[Sugestões] Melhorias no suporte para TypeScript + Error handling
- 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
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