@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 CHANGED
@@ -1,427 +1,153 @@
1
- # CEPs do Brasil com e-DNE dos Correios
1
+ # @konstit/dne: CEPs do Brasil
2
2
 
3
- Crie em segundos uma base local, em SQLite ou em formato binário compacto, pronta para consultar os CEPs do Brasil com dados do e-DNE dos Correios. Depois da carga, as consultas funcionam sem servidor e sem acesso à rede.
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
- O `@konstit/dne` inclui uma base binária pronta para consultas em aplicações Bun. A CLI também recebe um diretório, um arquivo ZIP local ou o arquivo público mais recente do e-DNE para gerar bases próprias. Os dados são processados em fluxo e gravados nas tabelas `dne`, `bairros` e `bairro_faixas`, sem tabelas brutas intermediárias.
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 para consultar a base incluída:
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
- const endereco: DneRow | undefined = db.queryCep('01141-000');
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
- Sem argumentos, o leitor abre `data/dne.bin` dentro do pacote instalado, independentemente do diretório de trabalho. Nenhum download é feito na instalação ou na consulta. A base representa a fonte usada no empacotamento daquela versão; instale uma versão mais recente para receber outra cópia ou passe o caminho de uma base própria: `new DneBinaryDatabaseReader('/dados/dne.bin')`.
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
- ```sh
71
- bunx @konstit/dne build --db ./dne.db
72
- bunx @konstit/dne build --format binary
73
- bunx @konstit/dne get 01001-000 --db ./dne.bin
74
- bunx @konstit/dne get 01001-000 --db ./dne.db
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
- ## Execução
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
- Execute a CLI sem instalação global:
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
- ```sh
82
- bunx @konstit/dne --version
83
- bunx @konstit/dne --json doctor --offline
84
- ```
54
+ ## Qual formato usar?
85
55
 
86
- Os nomes de comandos, subcomandos, opções e flags permanecem em inglês. A ajuda, o progresso, os resultados textuais e as mensagens de erro são exibidos em português. O contrato JSON mantém chaves, códigos e valores de estado estáveis em inglês.
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
- `--db` é uma opção global. Ela pode aparecer antes ou depois de um subcomando. O caminho da base segue esta ordem de precedência:
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
- 1. `--db PATH`
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
- No build binário, a extensão do caminho é substituída por `.bin` ou adicionada quando não existe: `--db ./base.db` e `--db ./base` geram `./base.bin`. Para consultar ou inspecionar o arquivo binário, informe seu caminho com `--db ./base.bin`.
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
- Use `--color` para forçar cores e `--no-color` para desativá-las. Sem essas opções, a CLI detecta o terminal. A presença da variável `NO_COLOR` sempre desativa as cores.
68
+ ## CLI: criar e consultar sua própria base
96
69
 
97
- ## Criar e atualizar
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 build --db ./dne.db --source ./eDNE_Basico.zip
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
- O padrão `0 0 * * 5` executa à meia-noite de sexta-feira, no fuso local do cron. Informe outra expressão como argumento quando necessário:
77
+ Para gerar e consultar uma base binária:
141
78
 
142
79
  ```sh
143
- bunx @konstit/dne cron install '30 6 * * 5' --db ./dne.db
144
- bunx @konstit/dne cron install --db ./dne.db --source https://example.com/eDNE_Basico.zip
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
- `cron install` usa `Bun.cron` para registrar o job no agendador do sistema operacional: `crontab` no Linux e `launchd` no macOS. O título contém um hash do caminho absoluto da base. Uma nova instalação para a mesma base substitui o job existente, enquanto bases diferentes mantêm agendamentos independentes. `cron remove` usa `Bun.cron.remove`.
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
- ```sh
159
- bunx @konstit/dne get 01001000
160
- bunx @konstit/dne get 01001-000 --json
161
- ```
86
+ ### Criar e atualizar
162
87
 
163
- Consulta em lote:
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 get 01001000 20040002 --json
167
- bunx @konstit/dne get --file ./ceps.txt --jsonl
168
- printf '01001000\n20040002\n' | bunx @konstit/dne get --jsonl
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
- Os formatos aceitos são `01001000` e `01001-000`. A entrada por arquivo ou stdin pode usar espaços, vírgulas ou pontos e vírgulas como separadores.
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 status --json
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
- `status` informa o tamanho do arquivo, a quantidade de registros, o esquema atual, a versão do pacote, o `Last-Modified` da fonte e os demais metadados da carga. A saída textual formata datas e números com a localidade `pt-BR`; a saída JSON mantém os valores originais. `schema` lê o esquema real do SQLite. `schema --expected` mostra o esquema definido pela CLI. `doctor` verifica o Bun, a configuração da base e o acesso à fonte remota. O modo offline não faz a verificação de rede.
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
- ## SQL somente leitura
104
+ ### Consultar em lote ou executar SQL
188
105
 
189
106
  ```sh
190
- bunx @konstit/dne sql 'SELECT cep, municipio, uf FROM dne WHERE uf = "SP" LIMIT 10' --json
191
- bunx @konstit/dne sql 'PRAGMA page_size' --limit 20 --json
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
- Os leitores `DneDatabaseReader` e `DneBinaryDatabaseReader` oferecem as mesmas consultas adicionais:
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
- Identificadores inválidos ou desconhecidos retornam `undefined`/`[]`. No binário, o cadastro de bairros tem índices internos compactos e preserva os identificadores originais; os intervalos usam pares de inteiros de 32 bits e são convertidos para oito dígitos na leitura.
114
+ ## Desempenho
293
115
 
294
- O leitor SQLite e suas exceções são exportados pela raiz de `@konstit/dne`. Internamente, ficam em [`src/sqlite-db-reader.ts`](src/sqlite-db-reader.ts), também disponíveis pelos imports existentes de `src/db.ts`. Todas as exceções do leitor herdam de `DneDatabaseError` e expõem um `code` estável:
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
- | Classe | `code` | Situação |
297
- | ------------------------ | ---------------- | ------------------------------------------------------------------------- |
298
- | `DneDatabaseIOError` | `IO_ERROR` | Falha ao abrir, configurar ou fechar a conexão; `path` identifica a base. |
299
- | `DneDatabaseSchemaError` | `INVALID_SCHEMA` | Esquema sem a view normalizada ou os campos de localidade necessários. |
300
- | `DneDatabaseDataError` | `INVALID_DATA` | Indicadores de localidade inválidos no registro consultado. |
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
- Falhas encapsuladas preservam o erro original em `cause`. É seguro chamar `close()` mais de uma vez.
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
- No SQLite, `localidade_situacao` preserva `LOC_IN_SIT` (`0`, `1`, `2` ou `3`) e `localidade_tipo` preserva `LOC_IN_TIPO_LOC` (`M`, `D` ou `P`). O binário mantém esses indicadores compactados em um byte por CEP. `queryCep()` converte os códigos para strings descritivas nos dois leitores; a CLI também retorna essas strings nas consultas `get`:
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
- | Campo | Código DNE | Valor retornado pela API |
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
- `LocalidadeTipo` e `LocalidadeSituacao` são string unions desses valores. Consultas SQL diretas continuam usando os códigos originais. A conversão acontece na leitura e não exige reconstruir bases existentes do formato atual.
319
-
320
- Na situação `3`, o CEP geral e os CEPs de logradouros coexistem durante a transição, conforme `Delimitado/Leiautes_delimitador.doc` incluído no [arquivo oficial do e-DNE](https://www2.correios.com.br/sistemas/edne/download/eDNE_Basico.zip). Os indicadores pertencem à localidade de origem de cada CEP, inclusive nos registros de logradouros, caixas postais comunitárias, grandes usuários e unidades operacionais. Para distritos e povoados, `municipio` e `municipio_cod_ibge` continuam identificando o município superior.
321
-
322
- Para listar municípios com CEP único:
323
-
324
- ```sql
325
- SELECT DISTINCT municipio, municipio_cod_ibge, uf
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
- A implementação SQLite segue a separação entre leitura e escrita usada pelo formato binário:
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
- O terceiro argumento fornece a base SQLite usada para selecionar 50% de CEPs existentes e 50% de ausentes. O resultado inclui nove medições após duas rodadas de aquecimento. `memoryBytes` registra a memória antes de abrir a base, após abri-la, após o primeiro lote de consultas, após a coleta de lixo desse lote e ao final das medições, sempre antes de fechar o leitor. A coleta de lixo inicial e a do primeiro lote ficam fora das medições de tempo.
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
- Todos os valores de memória estão em bytes. `rss` é o consumo do processo reportado pelo Bun, incluindo o runtime e a lista de consultas; não representa apenas o banco. `heapUsed`, `heapTotal`, `external` e `arrayBuffers` são os valores originais de `process.memoryUsage()`. Não os some: há sobreposição, e o Bun pode incluir buffers externos em `heapUsed`. `heapObjectBytes` separa os objetos do heap de strings e buffers alocados externamente, usando `heapSize - extraMemorySize` de `bun:jsc`. Esse contador reflete a última coleta de lixo; compare `beforeOpen` com `afterFirstBatchGc` para avaliar os objetos que continuam ocupando memória. [Detalhes das métricas do Bun](https://bun.com/reference/bun/jsc/heapStats).
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
- `bun run build:package-database` prepara somente a base incluída. Os arquivos gerados permanecem fora do Git.
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;