@konstit/dne 0.0.2 → 0.1.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 +215 -13
- package/data/dne.bin +0 -0
- package/dist/bairro.d.ts +27 -0
- package/dist/bairro.js +9 -0
- package/dist/bairro.js.map +1 -0
- package/dist/binary-db-errors.d.ts +56 -0
- package/dist/binary-db-errors.js +68 -0
- package/dist/binary-db-errors.js.map +1 -0
- package/dist/binary-db-format.d.ts +192 -0
- package/dist/binary-db-format.js +250 -0
- package/dist/binary-db-format.js.map +1 -0
- package/dist/binary-db-reader.d.ts +114 -0
- package/dist/binary-db-reader.js +700 -0
- package/dist/binary-db-reader.js.map +1 -0
- package/dist/cep.d.ts +50 -0
- package/dist/cep.js +184 -0
- package/dist/cep.js.map +1 -0
- package/dist/errors.d.ts +14 -0
- package/dist/errors.js +21 -0
- package/dist/errors.js.map +1 -0
- package/dist/index.js +55 -33
- package/dist/index.js.map +29 -16
- package/dist/library.d.ts +10 -0
- package/dist/library.js +8 -0
- package/dist/library.js.map +1 -0
- package/dist/schema.d.ts +88 -0
- package/dist/schema.js +233 -0
- package/dist/schema.js.map +1 -0
- package/dist/settings.d.ts +34 -0
- package/dist/settings.js +35 -0
- package/dist/settings.js.map +1 -0
- package/dist/sqlite-db-errors.d.ts +40 -0
- package/dist/sqlite-db-errors.js +54 -0
- package/dist/sqlite-db-errors.js.map +1 -0
- package/dist/sqlite-db-reader.d.ts +130 -0
- package/dist/sqlite-db-reader.js +307 -0
- package/dist/sqlite-db-reader.js.map +1 -0
- package/dist/sqlite-db-schema.d.ts +49 -0
- package/dist/sqlite-db-schema.js +115 -0
- package/dist/sqlite-db-schema.js.map +1 -0
- package/dist/types.d.ts +90 -0
- package/dist/types.js +49 -0
- package/dist/types.js.map +1 -0
- package/package.json +17 -4
package/README.md
CHANGED
|
@@ -1,20 +1,31 @@
|
|
|
1
|
-
#
|
|
1
|
+
# CEPs do Brasil com e-DNE dos Correios
|
|
2
2
|
|
|
3
|
-
Crie em segundos uma base
|
|
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.
|
|
4
4
|
|
|
5
|
-
O `@konstit/dne` recebe um diretório, um arquivo ZIP local ou o arquivo público mais recente do e-DNE. Os dados são processados em fluxo e gravados
|
|
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.
|
|
6
16
|
|
|
7
17
|
Principais vantagens:
|
|
8
18
|
|
|
9
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.
|
|
10
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.
|
|
11
22
|
- **Atualizações seguras:** o modo WAL e uma única transação permitem atualizar a base sem expor dados parciais aos processos de leitura.
|
|
12
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.
|
|
13
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.
|
|
14
25
|
|
|
15
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.
|
|
16
27
|
|
|
17
|
-
|
|
28
|
+
O pacote oferece uma API de leitura e mantém a CLI via `bunx @konstit/dne`.
|
|
18
29
|
|
|
19
30
|
## Requisitos
|
|
20
31
|
|
|
@@ -23,8 +34,43 @@ Este pacote fornece somente uma CLI. Ele não expõe uma API pública de bibliot
|
|
|
23
34
|
|
|
24
35
|
## Início rápido
|
|
25
36
|
|
|
37
|
+
Instale o pacote para consultar a base incluída:
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
bun add @konstit/dne
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
```typescript
|
|
44
|
+
import {
|
|
45
|
+
DneBinaryDatabaseReader,
|
|
46
|
+
type DneRow,
|
|
47
|
+
} from '@konstit/dne';
|
|
48
|
+
|
|
49
|
+
const db = new DneBinaryDatabaseReader();
|
|
50
|
+
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 });
|
|
55
|
+
} finally {
|
|
56
|
+
db.close();
|
|
57
|
+
}
|
|
58
|
+
```
|
|
59
|
+
|
|
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:
|
|
69
|
+
|
|
26
70
|
```sh
|
|
27
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
|
|
28
74
|
bunx @konstit/dne get 01001-000 --db ./dne.db
|
|
29
75
|
```
|
|
30
76
|
|
|
@@ -42,7 +88,9 @@ Os nomes de comandos, subcomandos, opções e flags permanecem em inglês. A aju
|
|
|
42
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:
|
|
43
89
|
|
|
44
90
|
1. `--db PATH`
|
|
45
|
-
2. `./dne.db`
|
|
91
|
+
2. `./dne.bin` em `build --format binary`; `./dne.db` nos demais comandos.
|
|
92
|
+
|
|
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`.
|
|
46
94
|
|
|
47
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.
|
|
48
96
|
|
|
@@ -59,7 +107,11 @@ bunx @konstit/dne build --db ./dne.db --check --json
|
|
|
59
107
|
|
|
60
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.
|
|
61
109
|
|
|
62
|
-
Cada carga grava a versão do `@konstit/dne` em `edne_metadata
|
|
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).
|
|
63
115
|
|
|
64
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.
|
|
65
117
|
|
|
@@ -118,7 +170,7 @@ printf '01001000\n20040002\n' | bunx @konstit/dne get --jsonl
|
|
|
118
170
|
|
|
119
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.
|
|
120
172
|
|
|
121
|
-
`get` abre o SQLite em modo somente leitura
|
|
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.
|
|
122
174
|
|
|
123
175
|
## Inspecionar a base
|
|
124
176
|
|
|
@@ -176,46 +228,173 @@ Códigos de saída:
|
|
|
176
228
|
## Schema SQLite
|
|
177
229
|
|
|
178
230
|
```sql
|
|
179
|
-
CREATE TABLE "
|
|
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" (
|
|
180
248
|
"cep" TEXT NOT NULL /* Contém somente os oito dígitos do CEP, sem separadores. */,
|
|
181
249
|
"logradouro" TEXT,
|
|
182
250
|
"complemento" TEXT,
|
|
183
|
-
"
|
|
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. */,
|
|
184
253
|
"municipio" TEXT NOT NULL,
|
|
185
254
|
"municipio_cod_ibge" INTEGER NOT NULL,
|
|
186
255
|
"uf" TEXT NOT NULL,
|
|
187
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')),
|
|
188
259
|
PRIMARY KEY ("cep")
|
|
189
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;
|
|
190
267
|
```
|
|
191
268
|
|
|
192
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.
|
|
193
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;
|
|
284
|
+
```
|
|
285
|
+
|
|
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.
|
|
291
|
+
|
|
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.
|
|
293
|
+
|
|
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:
|
|
295
|
+
|
|
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. |
|
|
303
|
+
|
|
304
|
+
Falhas encapsuladas preservam o erro original em `cause`. É seguro chamar `close()` mais de uma vez.
|
|
305
|
+
|
|
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`:
|
|
307
|
+
|
|
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` |
|
|
317
|
+
|
|
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
|
+
|
|
194
335
|
### Drizzle ORM schema
|
|
195
336
|
|
|
196
337
|
```typescript
|
|
197
|
-
import {
|
|
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
|
+
);
|
|
198
360
|
|
|
199
361
|
export const dneTable = sqliteTable('dne', (t) => ({
|
|
200
362
|
cep: t.text().primaryKey(),
|
|
201
363
|
logradouro: t.text(),
|
|
202
364
|
complemento: t.text(),
|
|
203
|
-
|
|
365
|
+
bairro_id: t.integer().references(() => bairrosTable.bairro_id),
|
|
366
|
+
localidade_nome: t.text(),
|
|
204
367
|
municipio: t.text().notNull(),
|
|
205
368
|
municipio_cod_ibge: t.integer().notNull(),
|
|
206
369
|
uf: t.text().notNull(),
|
|
207
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(),
|
|
208
373
|
}));
|
|
209
374
|
```
|
|
210
375
|
|
|
211
|
-
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
|
|
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.
|
|
212
377
|
|
|
213
378
|
## Desenvolvimento
|
|
214
379
|
|
|
215
|
-
|
|
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.
|
|
216
394
|
|
|
217
395
|
```sh
|
|
218
396
|
bun test
|
|
397
|
+
bun run coverage
|
|
219
398
|
bun run lint
|
|
220
399
|
bun run fmt
|
|
221
400
|
bun run benchmark
|
|
@@ -223,3 +402,26 @@ bun run benchmark:download
|
|
|
223
402
|
```
|
|
224
403
|
|
|
225
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
|
+
```
|
|
412
|
+
|
|
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.
|
|
414
|
+
|
|
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
|
+
```
|
|
426
|
+
|
|
427
|
+
`bun run build:package-database` prepara somente a base incluída. Os arquivos gerados permanecem fora do Git.
|
package/data/dne.bin
ADDED
|
Binary file
|
package/dist/bairro.d.ts
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
import type { UF } from './types.ts';
|
|
2
|
+
/** A neighborhood from `LOG_BAIRRO.TXT`, identified independently of its name. */
|
|
3
|
+
export type DneBairro = {
|
|
4
|
+
/** Original positive `BAI_NU` identifier from the DNE source. */
|
|
5
|
+
bairro_id: number;
|
|
6
|
+
/** Original `LOC_NU` identifier of the neighborhood's locality. */
|
|
7
|
+
localidade_id: number;
|
|
8
|
+
/** Full neighborhood name. Names are not globally unique. */
|
|
9
|
+
nome: string;
|
|
10
|
+
/** Abbreviated source name, or null when no abbreviation is supplied. */
|
|
11
|
+
nome_abreviado: string | null;
|
|
12
|
+
/** Two-letter Brazilian state abbreviation. */
|
|
13
|
+
uf: UF;
|
|
14
|
+
};
|
|
15
|
+
/** One inclusive CEP interval assigned to a neighborhood by the DNE source. */
|
|
16
|
+
export type DneFaixaCep = {
|
|
17
|
+
/** Inclusive lower bound, preserving all eight digits and leading zeroes. */
|
|
18
|
+
cep_inicial: string;
|
|
19
|
+
/** Inclusive upper bound, preserving all eight digits and leading zeroes. */
|
|
20
|
+
cep_final: string;
|
|
21
|
+
};
|
|
22
|
+
/**
|
|
23
|
+
* Checks whether a value can represent an original DNE neighborhood identifier.
|
|
24
|
+
* @param value - Candidate identifier; names and stringified identifiers are not accepted.
|
|
25
|
+
* @returns True for a positive unsigned 32-bit integer.
|
|
26
|
+
*/
|
|
27
|
+
export declare function isBairroId(value: number): boolean;
|
package/dist/bairro.js
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Checks whether a value can represent an original DNE neighborhood identifier.
|
|
3
|
+
* @param value - Candidate identifier; names and stringified identifiers are not accepted.
|
|
4
|
+
* @returns True for a positive unsigned 32-bit integer.
|
|
5
|
+
*/
|
|
6
|
+
export function isBairroId(value) {
|
|
7
|
+
return Number.isInteger(value) && value > 0 && value <= 0xffff_ffff;
|
|
8
|
+
}
|
|
9
|
+
//# sourceMappingURL=bairro.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"bairro.js","sourceRoot":"","sources":["../src/bairro.ts"],"names":[],"mappings":"AAwBA;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,IAAI,WAAW,CAAC;AACtE,CAAC"}
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
/** Stable categories exposed by the binary database reader for programmatic error handling. */
|
|
2
|
+
export type DneBinaryDatabaseErrorCode = 'IO_ERROR' | 'INVALID_FORMAT' | 'UNSUPPORTED_VERSION' | 'READER_CLOSED';
|
|
3
|
+
/** Base class for all errors exposed by the binary database reader and its file helpers. */
|
|
4
|
+
export declare abstract class DneBinaryDatabaseError extends Error {
|
|
5
|
+
/** Identifies the failure category without requiring callers to parse the message. */
|
|
6
|
+
abstract readonly code: DneBinaryDatabaseErrorCode;
|
|
7
|
+
/**
|
|
8
|
+
* Initializes a reader error and preserves an underlying failure in `cause` when provided.
|
|
9
|
+
* @param message - Human-readable diagnostic information.
|
|
10
|
+
* @param options - Standard error options, including the original cause.
|
|
11
|
+
*/
|
|
12
|
+
protected constructor(message: string, options?: ErrorOptions);
|
|
13
|
+
}
|
|
14
|
+
/** The database file could not be opened, mapped, or read. Inspect `cause` for the operating-system error. */
|
|
15
|
+
export declare class DneBinaryDatabaseIOError extends DneBinaryDatabaseError {
|
|
16
|
+
readonly path: string;
|
|
17
|
+
/** Identifies a failure to access the database file. */
|
|
18
|
+
readonly code = "IO_ERROR";
|
|
19
|
+
/**
|
|
20
|
+
* Creates an access error for a database path.
|
|
21
|
+
* @param path - Path supplied by the caller, without normalization.
|
|
22
|
+
* @param options - Error options containing the original file-system failure.
|
|
23
|
+
*/
|
|
24
|
+
constructor(path: string, options?: ErrorOptions);
|
|
25
|
+
}
|
|
26
|
+
/** The file or a decoded record violates the supported binary format. */
|
|
27
|
+
export declare class DneBinaryDatabaseFormatError extends DneBinaryDatabaseError {
|
|
28
|
+
/** Identifies invalid headers, sections, metadata, or record contents. */
|
|
29
|
+
readonly code = "INVALID_FORMAT";
|
|
30
|
+
/**
|
|
31
|
+
* Creates a validation or decoding error.
|
|
32
|
+
* @param message - Description of the invalid structure or failed decoding operation.
|
|
33
|
+
* @param options - Error options containing a native decoding error, when applicable.
|
|
34
|
+
*/
|
|
35
|
+
constructor(message: string, options?: ErrorOptions);
|
|
36
|
+
}
|
|
37
|
+
/** The file declares a binary format version that this reader does not support. */
|
|
38
|
+
export declare class DneBinaryDatabaseVersionError extends DneBinaryDatabaseError {
|
|
39
|
+
readonly actualVersion: number;
|
|
40
|
+
readonly supportedVersion: number;
|
|
41
|
+
/** Identifies a format-version mismatch that requires a compatible reader or a rebuilt file. */
|
|
42
|
+
readonly code = "UNSUPPORTED_VERSION";
|
|
43
|
+
/**
|
|
44
|
+
* Creates a version mismatch error.
|
|
45
|
+
* @param actualVersion - Version declared in the file header.
|
|
46
|
+
* @param supportedVersion - Version accepted by this reader.
|
|
47
|
+
*/
|
|
48
|
+
constructor(actualVersion: number, supportedVersion: number);
|
|
49
|
+
}
|
|
50
|
+
/** A lookup was attempted after the reader released its mapping references. */
|
|
51
|
+
export declare class DneBinaryDatabaseClosedError extends DneBinaryDatabaseError {
|
|
52
|
+
/** Identifies use of a reader after `close()`. */
|
|
53
|
+
readonly code = "READER_CLOSED";
|
|
54
|
+
/** Creates an error for a lookup attempted after `close()`. */
|
|
55
|
+
constructor();
|
|
56
|
+
}
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
/** Base class for all errors exposed by the binary database reader and its file helpers. */
|
|
2
|
+
export class DneBinaryDatabaseError extends Error {
|
|
3
|
+
/**
|
|
4
|
+
* Initializes a reader error and preserves an underlying failure in `cause` when provided.
|
|
5
|
+
* @param message - Human-readable diagnostic information.
|
|
6
|
+
* @param options - Standard error options, including the original cause.
|
|
7
|
+
*/
|
|
8
|
+
constructor(message, options) {
|
|
9
|
+
super(message, options);
|
|
10
|
+
this.name = new.target.name;
|
|
11
|
+
}
|
|
12
|
+
}
|
|
13
|
+
/** The database file could not be opened, mapped, or read. Inspect `cause` for the operating-system error. */
|
|
14
|
+
export class DneBinaryDatabaseIOError extends DneBinaryDatabaseError {
|
|
15
|
+
path;
|
|
16
|
+
/** Identifies a failure to access the database file. */
|
|
17
|
+
code = 'IO_ERROR';
|
|
18
|
+
/**
|
|
19
|
+
* Creates an access error for a database path.
|
|
20
|
+
* @param path - Path supplied by the caller, without normalization.
|
|
21
|
+
* @param options - Error options containing the original file-system failure.
|
|
22
|
+
*/
|
|
23
|
+
constructor(path, options) {
|
|
24
|
+
super(`Unable to read binary database: ${path}`, options);
|
|
25
|
+
this.path = path;
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
/** The file or a decoded record violates the supported binary format. */
|
|
29
|
+
export class DneBinaryDatabaseFormatError extends DneBinaryDatabaseError {
|
|
30
|
+
/** Identifies invalid headers, sections, metadata, or record contents. */
|
|
31
|
+
code = 'INVALID_FORMAT';
|
|
32
|
+
/**
|
|
33
|
+
* Creates a validation or decoding error.
|
|
34
|
+
* @param message - Description of the invalid structure or failed decoding operation.
|
|
35
|
+
* @param options - Error options containing a native decoding error, when applicable.
|
|
36
|
+
*/
|
|
37
|
+
// biome-ignore lint/complexity/noUselessConstructor: Exposes and documents the protected base constructor as a public API.
|
|
38
|
+
constructor(message, options) {
|
|
39
|
+
super(message, options);
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
/** The file declares a binary format version that this reader does not support. */
|
|
43
|
+
export class DneBinaryDatabaseVersionError extends DneBinaryDatabaseError {
|
|
44
|
+
actualVersion;
|
|
45
|
+
supportedVersion;
|
|
46
|
+
/** Identifies a format-version mismatch that requires a compatible reader or a rebuilt file. */
|
|
47
|
+
code = 'UNSUPPORTED_VERSION';
|
|
48
|
+
/**
|
|
49
|
+
* Creates a version mismatch error.
|
|
50
|
+
* @param actualVersion - Version declared in the file header.
|
|
51
|
+
* @param supportedVersion - Version accepted by this reader.
|
|
52
|
+
*/
|
|
53
|
+
constructor(actualVersion, supportedVersion) {
|
|
54
|
+
super(`Unsupported binary database version: ${actualVersion}. Rebuild the database with build --force.`);
|
|
55
|
+
this.actualVersion = actualVersion;
|
|
56
|
+
this.supportedVersion = supportedVersion;
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
/** A lookup was attempted after the reader released its mapping references. */
|
|
60
|
+
export class DneBinaryDatabaseClosedError extends DneBinaryDatabaseError {
|
|
61
|
+
/** Identifies use of a reader after `close()`. */
|
|
62
|
+
code = 'READER_CLOSED';
|
|
63
|
+
/** Creates an error for a lookup attempted after `close()`. */
|
|
64
|
+
constructor() {
|
|
65
|
+
super('Binary database is closed');
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
//# sourceMappingURL=binary-db-errors.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"binary-db-errors.js","sourceRoot":"","sources":["../src/binary-db-errors.ts"],"names":[],"mappings":"AAGA,4FAA4F;AAC5F,MAAM,OAAgB,sBAAuB,SAAQ,KAAK;IAIxD;;;;OAIG;IACH,YAAsB,OAAe,EAAE,OAAsB;QAC3D,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;IAC9B,CAAC;CACF;AAED,8GAA8G;AAC9G,MAAM,OAAO,wBAAyB,SAAQ,sBAAsB;IAS7C;IARrB,wDAAwD;IAC/C,IAAI,GAAG,UAAU,CAAC;IAE3B;;;;OAIG;IACH,YAAqB,IAAY,EAAE,OAAsB;QACvD,KAAK,CAAC,mCAAmC,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;QADvC,SAAI,GAAJ,IAAI,CAAQ;IAEjC,CAAC;CACF;AAED,yEAAyE;AACzE,MAAM,OAAO,4BAA6B,SAAQ,sBAAsB;IACtE,0EAA0E;IACjE,IAAI,GAAG,gBAAgB,CAAC;IAEjC;;;;OAIG;IACH,2HAA2H;IAC3H,YAAY,OAAe,EAAE,OAAsB;QACjD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC1B,CAAC;CACF;AAED,mFAAmF;AACnF,MAAM,OAAO,6BAA8B,SAAQ,sBAAsB;IASlD;IAAgC;IARrD,gGAAgG;IACvF,IAAI,GAAG,qBAAqB,CAAC;IAEtC;;;;OAIG;IACH,YAAqB,aAAqB,EAAW,gBAAwB;QAC3E,KAAK,CAAC,wCAAwC,aAAa,4CAA4C,CAAC,CAAC;QADtF,kBAAa,GAAb,aAAa,CAAQ;QAAW,qBAAgB,GAAhB,gBAAgB,CAAQ;IAE7E,CAAC;CACF;AAED,+EAA+E;AAC/E,MAAM,OAAO,4BAA6B,SAAQ,sBAAsB;IACtE,kDAAkD;IACzC,IAAI,GAAG,eAAe,CAAC;IAEhC,+DAA+D;IAC/D;QACE,KAAK,CAAC,2BAA2B,CAAC,CAAC;IACrC,CAAC;CACF"}
|