@konstit/dne 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +77 -351
- package/data/dne.bin +0 -0
- package/dist/bairro-runs.d.ts +20 -0
- package/dist/bairro-runs.js +202 -0
- package/dist/bairro-runs.js.map +1 -0
- package/dist/binary-db-format.d.ts +10 -2
- package/dist/binary-db-format.js +9 -1
- package/dist/binary-db-format.js.map +1 -1
- package/dist/binary-db-integrity.d.ts +4 -0
- package/dist/binary-db-integrity.js +20 -0
- package/dist/binary-db-integrity.js.map +1 -0
- package/dist/binary-db-reader.d.ts +29 -17
- package/dist/binary-db-reader.js +191 -335
- package/dist/binary-db-reader.js.map +1 -1
- package/dist/binary-db-validator.d.ts +13 -0
- package/dist/binary-db-validator.js +712 -0
- package/dist/binary-db-validator.js.map +1 -0
- package/dist/fsst.d.ts +18 -0
- package/dist/fsst.js +117 -0
- package/dist/fsst.js.map +1 -0
- package/dist/index.js +44 -44
- package/dist/index.js.map +16 -9
- package/dist/locality-runs.d.ts +18 -0
- package/dist/locality-runs.js +108 -0
- package/dist/locality-runs.js.map +1 -0
- package/dist/packed-bits.d.ts +6 -0
- package/dist/packed-bits.js +41 -0
- package/dist/packed-bits.js.map +1 -0
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,427 +1,153 @@
|
|
|
1
|
-
# CEPs do Brasil
|
|
1
|
+
# @konstit/dne: CEPs do Brasil
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Consulte CEPs do Brasil localmente em aplicações Bun, com uma base compacta incluída no pacote e dados do e-DNE dos Correios. As consultas funcionam offline, sem servidor. A CLI também permite criar e atualizar bases próprias em SQLite ou formato binário.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
**3,11 milhões de consultas por segundo:** no benchmark de leitura, `DneBinaryDatabaseReader` consultou 100 mil CEPs em **32,16 ms**, sendo **30,6× mais rápido que o leitor SQLite** da biblioteca na mesma carga.
|
|
8
|
-
|
|
9
|
-
| Métrica | Binário | SQLite |
|
|
10
|
-
| --- | ---: | ---: |
|
|
11
|
-
| Mediana por 100 mil consultas | **32,16 ms** | 984,34 ms |
|
|
12
|
-
| Consultas por segundo, calculadas pela mediana | **3,11 milhões** | 101,6 mil |
|
|
13
|
-
| Tamanho da base | **32,2 MB** | 109,2 MB |
|
|
14
|
-
|
|
15
|
-
Medição realizada em **30/09/2026**, em um **Apple M4 com Bun 1.4.2**, usando [bench/binary-lookup.bench.ts](bench/binary-lookup.bench.ts) e uma base com 1.611.629 CEPs. Cada rodada executou 50 mil consultas a CEPs existentes e 50 mil a CEPs ausentes, com duas rodadas de aquecimento e nove medições. Ambos os leitores encontraram os 50 mil CEPs esperados. Os tempos incluem somente as consultas após aquecimento, sem a abertura da base; os tamanhos estão em MB decimais.
|
|
16
|
-
|
|
17
|
-
Principais vantagens:
|
|
18
|
-
|
|
19
|
-
- **Rápido e compacto:** em um benchmark de 10 execuções realizado em 2026-08-30, a geração completa a partir do arquivo público levou 5,73 segundos em média, incluindo o download. A base final continha 1.605.136 registros e ocupava 125,4 MiB.
|
|
20
|
-
- **Consultas locais simples:** procure um CEP, consulte vários CEPs em lote ou execute SQL somente leitura diretamente no arquivo SQLite.
|
|
21
|
-
- **Formato binário opcional:** use `--format binary` para gerar um arquivo SoA com strings internadas e leitura mmap, otimizado para lookup por CEP.
|
|
22
|
-
- **Atualizações seguras:** o modo WAL e uma única transação permitem atualizar a base sem expor dados parciais aos processos de leitura.
|
|
23
|
-
- **Atualizações automáticas:** registre uma agenda com `Bun.cron` para manter a base atualizada no Linux ou macOS. Cada job usa uma versão fixada do pacote, e o lock exclusivo evita cargas simultâneas.
|
|
24
|
-
- **Pronto para automação:** a CLI oferece saídas JSON e JSONL estáveis, códigos de saída documentados e separação entre dados e mensagens de progresso.
|
|
25
|
-
|
|
26
|
-
Nas mesmas condições do benchmark, `uvx edne-correios-loader load --database-url sqlite:///dne.db` levou 30 segundos e gerou uma base de 394 MiB sem `VACUUM`. Nessa comparação, o `@konstit/dne` foi 5,2 vezes mais rápido e usou 68,2% menos espaço em disco.
|
|
27
|
-
|
|
28
|
-
O pacote oferece uma API de leitura e mantém a CLI via `bunx @konstit/dne`.
|
|
5
|
+
Consulte os [benchmarks de leitura e importação](https://github.com/Konstit-Engenharia/konstit-dne/blob/main/docs/performance.md) para os resultados medidos em cada formato.
|
|
29
6
|
|
|
30
7
|
## Requisitos
|
|
31
8
|
|
|
32
9
|
- Bun 1.4 ou mais recente
|
|
33
10
|
- macOS ou Linux
|
|
34
11
|
|
|
35
|
-
## Início rápido
|
|
12
|
+
## Início rápido: consultar a base incluída
|
|
36
13
|
|
|
37
|
-
Instale o pacote
|
|
14
|
+
Instale o pacote:
|
|
38
15
|
|
|
39
16
|
```sh
|
|
40
17
|
bun add @konstit/dne
|
|
41
18
|
```
|
|
42
19
|
|
|
20
|
+
Salve como `consulta.ts`:
|
|
21
|
+
|
|
43
22
|
```typescript
|
|
44
|
-
import {
|
|
45
|
-
DneBinaryDatabaseReader,
|
|
46
|
-
type DneRow,
|
|
47
|
-
} from '@konstit/dne';
|
|
23
|
+
import { DneBinaryDatabaseReader } from '@konstit/dne';
|
|
48
24
|
|
|
49
25
|
const db = new DneBinaryDatabaseReader();
|
|
50
26
|
try {
|
|
51
|
-
|
|
52
|
-
const bairro = db.queryNeighborhoodByCep('01141-000');
|
|
53
|
-
const faixas = bairro ? db.queryNeighborhoodCepRanges(bairro.bairro_id) : [];
|
|
54
|
-
console.log({ endereco, bairro, faixas });
|
|
27
|
+
console.log(JSON.stringify(db.queryCep('01141-000'), null, 2));
|
|
55
28
|
} finally {
|
|
56
29
|
db.close();
|
|
57
30
|
}
|
|
58
31
|
```
|
|
59
32
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
Para consultar uma base SQLite existente, importe `DneDatabaseReader` de `@konstit/dne` e informe seu caminho: `new DneDatabaseReader('/dados/dne.db')`.
|
|
63
|
-
|
|
64
|
-
Nos dois leitores, `queryCep`, `queryNeighborhood` e `queryNeighborhoodByCep` retornam `undefined` para entradas inválidas ou resultados ausentes. No leitor SQLite, `metadata` e `tableSchema` também retornam `undefined` quando os metadados ou a definição da tabela estão ausentes.
|
|
65
|
-
|
|
66
|
-
Os tipos `DneRow`, `DneBairro`, `DneFaixaCep`, `LoadMetadata`, `UF`, `LocalidadeTipo`, `LocalidadeSituacao`, `DneBinaryDatabaseErrorCode` e `DneDatabaseErrorCode` são exportados na raiz do pacote. As classes `DneBinaryDatabaseError`, `DneBinaryDatabaseIOError`, `DneBinaryDatabaseFormatError`, `DneBinaryDatabaseVersionError` e `DneBinaryDatabaseClosedError` também estão disponíveis para tratamento de erros, assim como as exceções tipadas do leitor SQLite descritas abaixo. Importar a biblioteca não executa a CLI.
|
|
67
|
-
|
|
68
|
-
Para criar ou consultar suas próprias bases pela CLI:
|
|
33
|
+
Execute com `bun consulta.ts`. Saída para a base usada neste exemplo:
|
|
69
34
|
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
35
|
+
```json
|
|
36
|
+
{
|
|
37
|
+
"bairro": "Várzea da Barra Funda",
|
|
38
|
+
"cep": "01141000",
|
|
39
|
+
"complemento": null,
|
|
40
|
+
"localidade_situacao": "codificada_por_logradouro",
|
|
41
|
+
"localidade_tipo": "municipio",
|
|
42
|
+
"logradouro": "Rua Rubens Meireles",
|
|
43
|
+
"municipio": "São Paulo",
|
|
44
|
+
"municipio_cod_ibge": 3550308,
|
|
45
|
+
"nome": null,
|
|
46
|
+
"uf": "SP"
|
|
47
|
+
}
|
|
75
48
|
```
|
|
76
49
|
|
|
77
|
-
|
|
50
|
+
O leitor abre a base incluída no pacote, independentemente do diretório de trabalho, sem baixar dados adicionais. Ela representa a fonte usada no empacotamento daquela versão: atualize o pacote para receber outra cópia ou informe o caminho de uma base própria ao construtor.
|
|
78
51
|
|
|
79
|
-
|
|
52
|
+
`queryCep()` aceita `01141000` ou `01141-000` e retorna `undefined` para CEPs inválidos ou ausentes. Consulte a [referência da API](https://github.com/Konstit-Engenharia/konstit-dne/blob/main/docs/api.md) para consultas de bairros e faixas de CEP, tipos e tratamento de erros.
|
|
80
53
|
|
|
81
|
-
|
|
82
|
-
bunx @konstit/dne --version
|
|
83
|
-
bunx @konstit/dne --json doctor --offline
|
|
84
|
-
```
|
|
54
|
+
## Qual formato usar?
|
|
85
55
|
|
|
86
|
-
|
|
56
|
+
| Necessidade | Formato | Como usar |
|
|
57
|
+
| ---------------------------------------------- | ------- | ------------------------------- |
|
|
58
|
+
| Consultar a base incluída no pacote | Binário | `new DneBinaryDatabaseReader()` |
|
|
59
|
+
| Gerar uma base compacta para consultas por CEP | Binário | `build --format binary` |
|
|
60
|
+
| Executar SQL ou integrar ferramentas SQLite | SQLite | `build --db ./dne.db` |
|
|
87
61
|
|
|
88
|
-
|
|
62
|
+
Os dois leitores oferecem consultas por CEP, bairro e faixas de CEP. O leitor binário também oferece `queryMunicipality(municipioCodIbge)`, que retorna `{ municipio, uf }` a partir do código IBGE, e `queryMunicipalityCodesByUf(uf)`, que lista os códigos IBGE de uma UF. Para abrir arquivos próprios na API, use `new DneBinaryDatabaseReader('/dados/dne.bin')` ou `new DneDatabaseReader('/dados/dne.db')`, importados de `@konstit/dne`.
|
|
89
63
|
|
|
90
|
-
|
|
91
|
-
2. `./dne.bin` em `build --format binary`; `./dne.db` nos demais comandos.
|
|
64
|
+
Na geração do banco binário, o processo valida integralmente os bytes serializados antes de calcular o hash. Cada arquivo termina com um rodapé SHA-256 sobre todos os bytes anteriores, incluindo o cabeçalho e o preenchimento de alinhamento.
|
|
92
65
|
|
|
93
|
-
|
|
66
|
+
O fluxo pressupõe uma base gerada por um processo confiável e mantida imutável durante o uso. A abertura verifica cabeçalho, versão, tamanho e checksum antes de usar o layout validado. As consultas verificam a entrada e o estado de `close()` e decodificam diretamente. Os erros de E/S, versão, tamanho, checksum e leitor fechado continuam tipados. O SHA-256 verifica a integridade do arquivo, mas não autentica a origem do produtor. A especificação do layout está em [Formato binário](docs/binary-layout.md).
|
|
94
67
|
|
|
95
|
-
|
|
68
|
+
## CLI: criar e consultar sua própria base
|
|
96
69
|
|
|
97
|
-
|
|
70
|
+
Execute sem instalação global. Para criar uma base SQLite a partir do arquivo público do e-DNE e consultar um CEP:
|
|
98
71
|
|
|
99
72
|
```sh
|
|
100
73
|
bunx @konstit/dne build --db ./dne.db
|
|
101
|
-
bunx @konstit/dne
|
|
102
|
-
bunx @konstit/dne build --db ./dne.db --source ./Delimitado
|
|
103
|
-
bunx @konstit/dne build --db ./dne.db --source https://example.com/eDNE_Basico.zip
|
|
104
|
-
bunx @konstit/dne build --db ./dne.db --force
|
|
105
|
-
bunx @konstit/dne build --db ./dne.db --check --json
|
|
106
|
-
```
|
|
107
|
-
|
|
108
|
-
`build` grava cada etapa e sua duração em formato compacto (`ms`, `s`, `min` ou `h`) em stderr. O resultado final é gravado em stdout. Use `--quiet` para ocultar o progresso. Use `--json` para receber o caminho da base, a quantidade de registros, o tamanho em bytes, os metadados da fonte, o tempo total em `elapsed_ms` e o estado da atualização.
|
|
109
|
-
|
|
110
|
-
Cada carga grava a versão do `@konstit/dne` em `edne_metadata` (ou no cabeçalho do arquivo binário). Ao usar uma fonte remota, a CLI também grava `Last-Modified`, ETag, tamanho do conteúdo, URL da fonte e horário da carga. Todos os validadores disponíveis devem continuar iguais para a base ser considerada atual. Uma execução posterior de `build` não recria a base se a fonte não mudou e mostra o `Last-Modified` remoto na saída textual. `--check` valida a estrutura de uma fonte local ou verifica se há uma atualização remota, sem alterar a base. `--force` ignora os metadados e recria a base.
|
|
111
|
-
|
|
112
|
-
O formato binário é selecionado explicitamente com `--format binary`. Ele mantém os mesmos dez campos da consulta por CEP em um layout próprio para `mmap`: o CEP usa um diretório de prefixos e sufixos de 10 bits; município e UF são compartilhados; campos opcionais usam bitmaps; os indicadores da localidade ocupam um byte por CEP; e as strings ficam em dicionários por coluna com front-coding em blocos de oito. `get`, `status` e `schema` detectam o formato automaticamente. O comando `sql` continua disponível somente para bases SQLite.
|
|
113
|
-
|
|
114
|
-
A especificação completa para implementar leitores em outras linguagens está em [docs/binary-layout.md](docs/binary-layout.md).
|
|
115
|
-
|
|
116
|
-
Para fontes HTTP ou HTTPS, a CLI tenta obter os metadados com `HEAD`. Se o servidor não aceitar esse método, ela usa uma requisição `GET` limitada ao primeiro byte. Requisições têm timeout de 30 segundos e até duas novas tentativas para falhas transitórias, respostas 408, 425, 429 e 5xx.
|
|
117
|
-
|
|
118
|
-
As entradas do ZIP são verificadas com seus valores CRC32 durante a leitura. A carga também valida CEP, UF, código IBGE, campos obrigatórios e referências entre os arquivos. Qualquer rejeição interrompe a transação. Uma carga válida grava em `quality_report` as linhas lidas, aceitas e rejeitadas por etapa e arquivo.
|
|
119
|
-
|
|
120
|
-
## Acesso simultâneo
|
|
121
|
-
|
|
122
|
-
Cada execução de `build` que pode alterar a base adquire um lock exclusivo antes de verificar a fonte. Outra instância do `@konstit/dne` aguarda por até 30 segundos, então verifica novamente os metadados e evita uma carga duplicada se a primeira instância já atualizou a base. `build --check` não adquire esse lock.
|
|
123
|
-
|
|
124
|
-
O lock fica no diretório temporário do sistema, dentro de `konstit-dne-<uid>`. Seu nome contém um hash do caminho absoluto da base, evitando conflitos entre bases com o mesmo nome. Ele é removido quando a execução termina e também ao receber `SIGHUP`, `SIGINT` ou `SIGTERM`. Se o processo for encerrado sem executar essa limpeza, a próxima execução identifica o PID inativo e remove o lock antes de continuar. Processos que coordenam a mesma base devem usar o mesmo host e usuário do sistema.
|
|
125
|
-
|
|
126
|
-
Uma base existente é atualizada no próprio arquivo com o modo WAL do SQLite e uma única transação. Outros processos podem manter a base aberta para leitura durante a atualização. Esses processos não veem uma tabela atualizada parcialmente.
|
|
127
|
-
|
|
128
|
-
Um leitor com uma transação ativa continua vendo a versão anterior até o fim da transação. A próxima transação vê os dados atualizados.
|
|
129
|
-
|
|
130
|
-
O SQLite permite um escritor por vez. Se outro processo mantiver uma transação de escrita, a atualização aguarda por até 30 segundos. Depois desse período, ela falha se o bloqueio continuar ativo.
|
|
131
|
-
|
|
132
|
-
## Atualização automática
|
|
133
|
-
|
|
134
|
-
Instale uma atualização semanal para a base:
|
|
135
|
-
|
|
136
|
-
```sh
|
|
137
|
-
bunx @konstit/dne cron install --db ./dne.db
|
|
74
|
+
bunx @konstit/dne get 01001-000 --db ./dne.db --json
|
|
138
75
|
```
|
|
139
76
|
|
|
140
|
-
|
|
77
|
+
Para gerar e consultar uma base binária:
|
|
141
78
|
|
|
142
79
|
```sh
|
|
143
|
-
bunx @konstit/dne
|
|
144
|
-
bunx @konstit/dne
|
|
145
|
-
bunx @konstit/dne cron install '@weekly' --db ./dne.db --dry-run
|
|
146
|
-
bunx @konstit/dne cron status --db ./dne.db --json
|
|
147
|
-
bunx @konstit/dne cron remove --db ./dne.db
|
|
80
|
+
bunx @konstit/dne build --format binary --db ./dne.bin
|
|
81
|
+
bunx @konstit/dne get 01001-000 --db ./dne.bin --json
|
|
148
82
|
```
|
|
149
83
|
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
Cada job recebe um módulo persistente e metadados no diretório de estado do usuário. O módulo executa os caminhos absolutos do `bunx`, da base e de fontes locais. A versão atual do `@konstit/dne` e a fonte ficam fixadas no comando. Alterar somente a expressão preserva a fonte já instalada. Execute `cron install` novamente depois de atualizar o pacote para usar a nova versão. A execução usa `--quiet`, descarta a saída normal e mantém erros em stderr para o agendador do sistema. `cron status` mostra a fonte e também calcula a próxima execução com `Bun.cron.parse`.
|
|
153
|
-
|
|
154
|
-
## Consultar CEPs
|
|
155
|
-
|
|
156
|
-
Consulta individual:
|
|
84
|
+
A CLI usa `./dne.db` por padrão; `build --format binary` gera `./dne.bin` por padrão. A CLI não seleciona automaticamente a base incluída no pacote: informe `--db` para consultar outro arquivo. `get`, `status` e `schema` detectam o formato do arquivo informado. O comando `sql` exige SQLite.
|
|
157
85
|
|
|
158
|
-
|
|
159
|
-
bunx @konstit/dne get 01001000
|
|
160
|
-
bunx @konstit/dne get 01001-000 --json
|
|
161
|
-
```
|
|
86
|
+
### Criar e atualizar
|
|
162
87
|
|
|
163
|
-
|
|
88
|
+
`build` aceita a fonte pública, um ZIP local ou um diretório com os arquivos do e-DNE. Ao usar uma fonte remota, repetir o comando atualiza a base somente quando necessário. `--check` verifica a fonte sem alterar a base.
|
|
164
89
|
|
|
165
90
|
```sh
|
|
166
|
-
bunx @konstit/dne
|
|
167
|
-
bunx @konstit/dne
|
|
168
|
-
|
|
91
|
+
bunx @konstit/dne build --db ./dne.db --source ./eDNE_Basico.zip
|
|
92
|
+
bunx @konstit/dne build --db ./dne.db --check --json
|
|
93
|
+
bunx @konstit/dne status --db ./dne.db --json
|
|
169
94
|
```
|
|
170
95
|
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
`get` abre o SQLite em modo somente leitura ou mapeia o arquivo binário com `mmap`. Se o caminho da base não existir, nenhum arquivo será criado. O formato JSONL lê a entrada e grava cada resultado de forma incremental, sem manter o lote completo na memória.
|
|
174
|
-
|
|
175
|
-
## Inspecionar a base
|
|
96
|
+
Para agendar a atualização semanal de uma base SQLite no Linux ou macOS:
|
|
176
97
|
|
|
177
98
|
```sh
|
|
178
|
-
bunx @konstit/dne
|
|
179
|
-
bunx @konstit/dne schema --json
|
|
180
|
-
bunx @konstit/dne schema --expected
|
|
181
|
-
bunx @konstit/dne doctor --json
|
|
182
|
-
bunx @konstit/dne doctor --offline --json
|
|
99
|
+
bunx @konstit/dne cron install --db ./dne.db
|
|
183
100
|
```
|
|
184
101
|
|
|
185
|
-
|
|
102
|
+
O agendamento padrão executa à meia-noite de sexta-feira e fixa a versão atual do pacote. Consulte [atualização automática](https://github.com/Konstit-Engenharia/konstit-dne/blob/main/docs/cli.md#atualização-automática) para alterar a agenda, verificar o job ou removê-lo.
|
|
186
103
|
|
|
187
|
-
|
|
104
|
+
### Consultar em lote ou executar SQL
|
|
188
105
|
|
|
189
106
|
```sh
|
|
190
|
-
bunx @konstit/dne
|
|
191
|
-
bunx @konstit/dne
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
O comando `sql` abre a base em modo somente leitura. Ele aceita `SELECT`, `WITH`, `PRAGMA` e `EXPLAIN`. O valor padrão de `--limit` é 100, com limite máximo de 10.000 registros.
|
|
195
|
-
|
|
196
|
-
## Contrato JSON
|
|
197
|
-
|
|
198
|
-
`--json` grava em stdout um envelope estável:
|
|
199
|
-
|
|
200
|
-
```json
|
|
201
|
-
{
|
|
202
|
-
"ok": true,
|
|
203
|
-
"data": {}
|
|
204
|
-
}
|
|
205
|
-
```
|
|
206
|
-
|
|
207
|
-
Erros de execução e de argumentos usam este formato em stderr:
|
|
208
|
-
|
|
209
|
-
```json
|
|
210
|
-
{
|
|
211
|
-
"ok": false,
|
|
212
|
-
"error": {
|
|
213
|
-
"code": "invalid-cep",
|
|
214
|
-
"message": "CEP inválido 'x'. Use 01001000 ou 01001-000."
|
|
215
|
-
}
|
|
216
|
-
}
|
|
217
|
-
```
|
|
218
|
-
|
|
219
|
-
O progresso e os diagnósticos são gravados em stderr. A saída JSON em stdout não inclui mensagens de progresso.
|
|
220
|
-
|
|
221
|
-
Códigos de saída:
|
|
222
|
-
|
|
223
|
-
- `0`: comando concluído
|
|
224
|
-
- `1`: falha na base, na fonte, na rede ou na execução
|
|
225
|
-
- `2`: argumentos inválidos ou CEP em formato inválido
|
|
226
|
-
- `3`: um ou mais CEPs válidos não foram encontrados
|
|
227
|
-
|
|
228
|
-
## Schema SQLite
|
|
229
|
-
|
|
230
|
-
```sql
|
|
231
|
-
CREATE TABLE IF NOT EXISTS "bairros" (
|
|
232
|
-
"bairro_id" INTEGER NOT NULL CHECK (bairro_id > 0),
|
|
233
|
-
"localidade_id" INTEGER NOT NULL CHECK (localidade_id > 0),
|
|
234
|
-
"uf" TEXT NOT NULL,
|
|
235
|
-
"nome" TEXT NOT NULL,
|
|
236
|
-
"nome_abreviado" TEXT,
|
|
237
|
-
PRIMARY KEY ("bairro_id")
|
|
238
|
-
);
|
|
239
|
-
|
|
240
|
-
CREATE TABLE IF NOT EXISTS "bairro_faixas" (
|
|
241
|
-
"bairro_id" INTEGER NOT NULL REFERENCES "bairros" ("bairro_id"),
|
|
242
|
-
"cep_inicial" TEXT NOT NULL CHECK (length(cep_inicial) = 8 AND cep_inicial NOT GLOB '*[^0-9]*'),
|
|
243
|
-
"cep_final" TEXT NOT NULL CHECK (length(cep_final) = 8 AND cep_final NOT GLOB '*[^0-9]*' AND cep_inicial <= cep_final),
|
|
244
|
-
PRIMARY KEY ("bairro_id", "cep_inicial", "cep_final")
|
|
245
|
-
) WITHOUT ROWID;
|
|
246
|
-
|
|
247
|
-
CREATE TABLE IF NOT EXISTS "dne" (
|
|
248
|
-
"cep" TEXT NOT NULL /* Contém somente os oito dígitos do CEP, sem separadores. */,
|
|
249
|
-
"logradouro" TEXT,
|
|
250
|
-
"complemento" TEXT,
|
|
251
|
-
"bairro_id" INTEGER REFERENCES "bairros" ("bairro_id"),
|
|
252
|
-
"localidade_nome" TEXT CHECK (localidade_nome IS NULL OR (bairro_id IS NULL AND localidade_tipo IN ('D', 'P'))) /* Original district or village name for a locality-wide CEP. */,
|
|
253
|
-
"municipio" TEXT NOT NULL,
|
|
254
|
-
"municipio_cod_ibge" INTEGER NOT NULL,
|
|
255
|
-
"uf" TEXT NOT NULL,
|
|
256
|
-
"nome" TEXT,
|
|
257
|
-
"localidade_situacao" INTEGER NOT NULL CHECK (localidade_situacao IN (0, 1, 2, 3)),
|
|
258
|
-
"localidade_tipo" TEXT NOT NULL CHECK (localidade_tipo IN ('M', 'D', 'P')),
|
|
259
|
-
PRIMARY KEY ("cep")
|
|
260
|
-
) WITHOUT ROWID;
|
|
261
|
-
|
|
262
|
-
CREATE VIEW "dne_consulta" AS
|
|
263
|
-
SELECT d.cep, d.logradouro, d.complemento, COALESCE(b.nome, d.localidade_nome) AS bairro,
|
|
264
|
-
d.municipio, d.municipio_cod_ibge, d.uf, d.nome, d.localidade_situacao, d.localidade_tipo
|
|
265
|
-
FROM "dne" d
|
|
266
|
-
LEFT JOIN "bairros" b ON b.bairro_id = d.bairro_id;
|
|
267
|
-
```
|
|
268
|
-
|
|
269
|
-
`cep` é a chave primária, sem digito separador. A tabela usa `WITHOUT ROWID` e páginas de 32 KiB para oferecer consultas diretas com menor uso de espaço.
|
|
270
|
-
|
|
271
|
-
`bairros` preserva o identificador original `BAI_NU`, a localidade `LOC_NU`, UF, nome e abreviação de `LOG_BAIRRO.TXT`, inclusive bairros sem CEP associado. Bairros homônimos continuam distintos. `dne.bairro_id` referencia esse cadastro; `bairro_faixas` armazena todos os intervalos de `LOG_FAIXA_BAIRRO.TXT`, com limites inclusivos e zeros à esquerda. As faixas não são consolidadas em um único mínimo/máximo: lacunas são preservadas, e pertencer a uma faixa não garante que um CEP esteja cadastrado.
|
|
272
|
-
|
|
273
|
-
Para manter os dez campos da consulta por CEP, incluindo o nome do bairro, use `dne_consulta`. Nos CEPs gerais de distritos e povoados, o nome original fica em `dne.localidade_nome`; esses registros não viram bairros artificiais. `get` e `queryCep()` continuam retornando o mesmo objeto.
|
|
274
|
-
|
|
275
|
-
```sql
|
|
276
|
-
SELECT * FROM dne_consulta WHERE cep = '01141000';
|
|
277
|
-
|
|
278
|
-
SELECT b.*, f.cep_inicial, f.cep_final
|
|
279
|
-
FROM dne d
|
|
280
|
-
JOIN bairros b ON b.bairro_id = d.bairro_id
|
|
281
|
-
LEFT JOIN bairro_faixas f ON f.bairro_id = b.bairro_id
|
|
282
|
-
WHERE d.cep = '01141000'
|
|
283
|
-
ORDER BY f.cep_inicial, f.cep_final;
|
|
107
|
+
bunx @konstit/dne get 01001000 20040002 --db ./dne.db --json
|
|
108
|
+
bunx @konstit/dne get --file ./ceps.txt --db ./dne.db --jsonl
|
|
109
|
+
bunx @konstit/dne sql "SELECT cep, municipio, uf FROM dne WHERE uf = 'SP' LIMIT 10" --db ./dne.db --json
|
|
284
110
|
```
|
|
285
111
|
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
- `queryNeighborhood(bairroId)`: retorna `{ bairro_id, localidade_id, uf, nome, nome_abreviado }` pelo identificador original.
|
|
289
|
-
- `queryNeighborhoodByCep(cep)`: retorna o bairro efetivamente associado ao CEP, ou `undefined` quando ausente, inclusive nos CEPs gerais de distritos e povoados.
|
|
290
|
-
- `queryNeighborhoodCepRanges(bairroId)`: retorna `{ cep_inicial, cep_final }[]`, ordenado pelos limites, ou `[]` quando não há faixas.
|
|
112
|
+
As consultas abrem a base somente para leitura. `--json` grava os dados em stdout e os erros em stderr; o progresso também fica em stderr. A [referência da CLI](https://github.com/Konstit-Engenharia/konstit-dne/blob/main/docs/cli.md) detalha opções, JSON/JSONL, códigos de saída, diagnóstico e acesso simultâneo.
|
|
291
113
|
|
|
292
|
-
|
|
114
|
+
## Desempenho
|
|
293
115
|
|
|
294
|
-
|
|
116
|
+
No benchmark de **01/10/2026**, em um **Apple M4 com Bun 1.4.2**, o leitor binário v5 foi **19,7× mais rápido que o leitor SQLite de esquema 4** da biblioteca na mesma carga:
|
|
295
117
|
|
|
296
|
-
|
|
|
297
|
-
|
|
|
298
|
-
|
|
|
299
|
-
|
|
|
300
|
-
|
|
|
301
|
-
| `DneDatabaseQueryError` | `QUERY_ERROR` | Falha do SQLite ao preparar ou executar uma consulta. |
|
|
302
|
-
| `DneDatabaseClosedError` | `READER_CLOSED` | Operação de leitura após `close()`, inclusive com entrada inválida. |
|
|
118
|
+
| Métrica | Binário | SQLite |
|
|
119
|
+
| ---------------------------------------------- | ---------------: | --------: |
|
|
120
|
+
| Mediana por 100 mil consultas | **27,76 ms** | 546,45 ms |
|
|
121
|
+
| Consultas por segundo, calculadas pela mediana | **3,60 milhões** | 183,0 mil |
|
|
122
|
+
| Tamanho da base | **19,12 MB** | 109,22 MB |
|
|
303
123
|
|
|
304
|
-
|
|
124
|
+
A base continha 1.611.629 CEPs. Cada formato foi medido em três processos, com duas rodadas de aquecimento e nove medições de 50 mil CEPs existentes e 50 mil ausentes. A tabela usa a mediana das três medianas. Os tempos excluem a abertura da base; os tamanhos estão em MB decimais.
|
|
305
125
|
|
|
306
|
-
|
|
126
|
+
Veja a [metodologia, os comandos de reprodução e os tempos de geração dos bancos](https://github.com/Konstit-Engenharia/konstit-dne/blob/main/docs/performance.md).
|
|
307
127
|
|
|
308
|
-
|
|
309
|
-
| --- | --- | --- |
|
|
310
|
-
| `localidade_tipo` | `M` | `municipio` |
|
|
311
|
-
| `localidade_tipo` | `D` | `distrito` |
|
|
312
|
-
| `localidade_tipo` | `P` | `povoado` |
|
|
313
|
-
| `localidade_situacao` | `0` | `sem_codificacao_por_logradouro` |
|
|
314
|
-
| `localidade_situacao` | `1` | `codificada_por_logradouro` |
|
|
315
|
-
| `localidade_situacao` | `2` | `inserida_na_codificacao_por_logradouro` |
|
|
316
|
-
| `localidade_situacao` | `3` | `em_codificacao_por_logradouro` |
|
|
128
|
+
## Documentação
|
|
317
129
|
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
FROM dne
|
|
327
|
-
WHERE localidade_tipo = 'M' AND localidade_situacao = 0
|
|
328
|
-
ORDER BY uf, municipio;
|
|
329
|
-
```
|
|
330
|
-
|
|
331
|
-
Um município com CEP geral ainda pode ter CEPs específicos de estabelecimentos ou unidades postais. Por isso, contar seus registros e exigir apenas um CEP não substitui os indicadores oficiais.
|
|
332
|
-
|
|
333
|
-
Bases anteriores precisam de uma nova importação para recuperar esses campos. Execute `build --force` com a fonte e o caminho da base desejados. A atualização do SQLite substitui o esquema dentro da transação somente após validar a nova carga. O esquema SQLite está na versão 4. O formato binário foi redefinido como versão 1, sem retrocompatibilidade; regenere os arquivos binários existentes. A versão do esquema é gravada em `schema_version`, e uma base com esquema antigo deixa de ser considerada atual mesmo quando os validadores da fonte remota não mudaram.
|
|
334
|
-
|
|
335
|
-
### Drizzle ORM schema
|
|
336
|
-
|
|
337
|
-
```typescript
|
|
338
|
-
import {
|
|
339
|
-
primaryKey,
|
|
340
|
-
sqliteTable,
|
|
341
|
-
} from 'drizzle-orm/sqlite-core';
|
|
342
|
-
|
|
343
|
-
export const bairrosTable = sqliteTable('bairros', (t) => ({
|
|
344
|
-
bairro_id: t.integer().primaryKey(),
|
|
345
|
-
localidade_id: t.integer().notNull(),
|
|
346
|
-
uf: t.text().notNull(),
|
|
347
|
-
nome: t.text().notNull(),
|
|
348
|
-
nome_abreviado: t.text(),
|
|
349
|
-
}));
|
|
350
|
-
|
|
351
|
-
export const bairroFaixasTable = sqliteTable(
|
|
352
|
-
'bairro_faixas',
|
|
353
|
-
(t) => ({
|
|
354
|
-
bairro_id: t.integer().notNull().references(() => bairrosTable.bairro_id),
|
|
355
|
-
cep_inicial: t.text().notNull(),
|
|
356
|
-
cep_final: t.text().notNull(),
|
|
357
|
-
}),
|
|
358
|
-
(t) => [primaryKey({ columns: [t.bairro_id, t.cep_inicial, t.cep_final] })],
|
|
359
|
-
);
|
|
360
|
-
|
|
361
|
-
export const dneTable = sqliteTable('dne', (t) => ({
|
|
362
|
-
cep: t.text().primaryKey(),
|
|
363
|
-
logradouro: t.text(),
|
|
364
|
-
complemento: t.text(),
|
|
365
|
-
bairro_id: t.integer().references(() => bairrosTable.bairro_id),
|
|
366
|
-
localidade_nome: t.text(),
|
|
367
|
-
municipio: t.text().notNull(),
|
|
368
|
-
municipio_cod_ibge: t.integer().notNull(),
|
|
369
|
-
uf: t.text().notNull(),
|
|
370
|
-
nome: t.text(),
|
|
371
|
-
localidade_situacao: t.integer().$type<0 | 1 | 2 | 3>().notNull(),
|
|
372
|
-
localidade_tipo: t.text({ enum: ['M', 'D', 'P'] }).notNull(),
|
|
373
|
-
}));
|
|
374
|
-
```
|
|
375
|
-
|
|
376
|
-
Este schema serve para consultar um banco criado pelo `@konstit/dne`. O Drizzle não representa `WITHOUT ROWID`; portanto, usar o Drizzle Kit para gerar ou migrar essas tabelas cria uma estrutura física diferente.
|
|
130
|
+
| Referência | Conteúdo |
|
|
131
|
+
| ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
|
|
132
|
+
| [API](https://github.com/Konstit-Engenharia/konstit-dne/blob/main/docs/api.md) | Leitores, bairros, faixas de CEP, tipos e exceções. |
|
|
133
|
+
| [CLI](https://github.com/Konstit-Engenharia/konstit-dne/blob/main/docs/cli.md) | Comandos, fontes, atualização automática, JSON e concorrência. |
|
|
134
|
+
| [SQLite e Drizzle](https://github.com/Konstit-Engenharia/konstit-dne/blob/main/docs/sqlite.md) | Tabelas, views, indicadores de localidade e migração de bases. |
|
|
135
|
+
| [Formato binário](https://github.com/Konstit-Engenharia/konstit-dne/blob/main/docs/binary-layout.md) | Especificação para implementar leitores em outras linguagens. |
|
|
136
|
+
| [Desempenho](https://github.com/Konstit-Engenharia/konstit-dne/blob/main/docs/performance.md) | Benchmarks de consulta e importação, reprodução e métricas de memória. |
|
|
137
|
+
| [Desenvolvimento](https://github.com/Konstit-Engenharia/konstit-dne/blob/main/docs/development.md) | Organização do código, validação e distribuição do pacote. |
|
|
377
138
|
|
|
378
139
|
## Desenvolvimento
|
|
379
140
|
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
| Arquivo | Responsabilidade |
|
|
383
|
-
| --------------------------- | ------------------------------------------------------------- |
|
|
384
|
-
| `src/sqlite-db-reader.ts` | Consultas, metadados e inspeção de arquivos SQLite. |
|
|
385
|
-
| `src/sqlite-db-errors.ts` | Exceções tipadas do leitor. |
|
|
386
|
-
| `src/sqlite-db-writer.ts` | Importação, validação dos registros e transações. |
|
|
387
|
-
| `src/sqlite-db-insert.ts` | Inserção de endereços em lotes e reutilização de statements. |
|
|
388
|
-
| `src/sqlite-db-schema.ts` | Geração de SQL, tabelas, views e identificadores. |
|
|
389
|
-
| `src/dne-source-parser.ts` | Leitura dos arquivos delimitados e seleção de campos. |
|
|
390
|
-
| `src/dne-source-quality.ts` | Contadores, motivos de rejeição e relatório de qualidade. |
|
|
391
|
-
| `src/db.ts` | Reexportações para compatibilidade com os imports existentes. |
|
|
392
|
-
|
|
393
|
-
O comando `zip` é necessário para os testes com arquivos ZIP aninhados. Os testes de distribuição também usam `npm` e `tar` para empacotar e instalar uma fixture isolada, sem baixar os dados reais.
|
|
141
|
+
Na raiz do repositório:
|
|
394
142
|
|
|
395
143
|
```sh
|
|
144
|
+
bun install
|
|
396
145
|
bun test
|
|
397
|
-
bun run coverage
|
|
398
146
|
bun run lint
|
|
399
|
-
bun run fmt
|
|
400
|
-
bun run benchmark
|
|
401
|
-
bun run benchmark:download
|
|
402
|
-
```
|
|
403
|
-
|
|
404
|
-
Outros scripts de benchmark específicos estão listados em `package.json`.
|
|
405
|
-
|
|
406
|
-
Para comparar consultas no binário e no SQLite usando os mesmos CEPs:
|
|
407
|
-
|
|
408
|
-
```sh
|
|
409
|
-
bun run bench/binary-lookup.bench.ts data/dne.bin 100000 ./dne.db
|
|
410
|
-
bun run bench/binary-lookup.bench.ts ./dne.db 100000 ./dne.db
|
|
411
147
|
```
|
|
412
148
|
|
|
413
|
-
|
|
149
|
+
Os testes também usam `zip`, `npm` e `tar`. Consulte o [guia de desenvolvimento](https://github.com/Konstit-Engenharia/konstit-dne/blob/main/docs/development.md) para cobertura, formatação, benchmarks e empacotamento.
|
|
414
150
|
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
### Distribuição do pacote
|
|
418
|
-
|
|
419
|
-
`bun run build` gera a CLI em `dist/index.js` e a biblioteca com declarações TypeScript em `dist/library.js` e `dist/library.d.ts`. `npm pack` e `bun pm pack` executam `prepack`: compilam essas entradas e geram `data/dne.bin` a partir da fonte pública dos Correios. A base completa acompanha o tarball; não há script de instalação para baixá-la. Os testes de publicação verificam a CLI e a leitura da base no pacote instalado.
|
|
420
|
-
|
|
421
|
-
Para empacotar a partir de um diretório ou ZIP local, informe `DNE_PACKAGE_SOURCE`:
|
|
422
|
-
|
|
423
|
-
```sh
|
|
424
|
-
DNE_PACKAGE_SOURCE=/dados/eDNE_Basico.zip npm pack
|
|
425
|
-
```
|
|
151
|
+
## Licença
|
|
426
152
|
|
|
427
|
-
|
|
153
|
+
O código é distribuído sob a [licença MIT](LICENSE).
|
package/data/dne.bin
CHANGED
|
Binary file
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import { type BinaryRegion, type ByteWidth } from './binary-db-format.ts';
|
|
2
|
+
export type BairroRuns = {
|
|
3
|
+
highBitCount: number;
|
|
4
|
+
highOffset: number;
|
|
5
|
+
idWidth: ByteWidth;
|
|
6
|
+
idsOffset: number;
|
|
7
|
+
lowBits: number;
|
|
8
|
+
lowOffset: number;
|
|
9
|
+
runCount: number;
|
|
10
|
+
samplesOffset: number;
|
|
11
|
+
zeroCount: number;
|
|
12
|
+
};
|
|
13
|
+
/** Encodes consecutive equal neighborhood indexes; Elias–Fano stores each run's starting row. */
|
|
14
|
+
export declare function encodeBairroRuns(dense: Uint8Array, rowCount: number, idWidth: ByteWidth): Uint8Array;
|
|
15
|
+
/** Reads locations after the file has passed integrity verification. */
|
|
16
|
+
export declare function readBairroRunsLayout(data: DataView, region: BinaryRegion, rowCount: number, idWidth: ByteWidth): BairroRuns;
|
|
17
|
+
/** Validates the complete encoded run index during generation. */
|
|
18
|
+
export declare function parseBairroRuns(data: DataView, region: BinaryRegion, rowCount: number, idWidth: ByteWidth, bairroCount: number): BairroRuns;
|
|
19
|
+
/** Finds the run containing a row using the Elias–Fano high bucket and its packed low values. */
|
|
20
|
+
export declare function readBairroRunIndex(data: DataView, runs: BairroRuns, row: number): number;
|