@konstit/dne 0.1.0 → 0.3.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.
Files changed (82) hide show
  1. package/README.md +85 -352
  2. package/dist/address-search-index.d.ts +34 -0
  3. package/dist/address-search-index.js +326 -0
  4. package/dist/address-search-index.js.map +1 -0
  5. package/dist/address-search-pool-errors.d.ts +15 -0
  6. package/dist/address-search-pool-errors.js +25 -0
  7. package/dist/address-search-pool-errors.js.map +1 -0
  8. package/dist/address-search-pool.d.ts +40 -0
  9. package/dist/address-search-pool.js +215 -0
  10. package/dist/address-search-pool.js.map +1 -0
  11. package/dist/address-search-rank.d.ts +5 -0
  12. package/dist/address-search-rank.js +89 -0
  13. package/dist/address-search-rank.js.map +1 -0
  14. package/dist/address-search-text.d.ts +6 -0
  15. package/dist/address-search-text.js +16 -0
  16. package/dist/address-search-text.js.map +1 -0
  17. package/dist/address-search-worker-runtime.d.ts +41 -0
  18. package/dist/address-search-worker-runtime.js +38 -0
  19. package/dist/address-search-worker-runtime.js.map +1 -0
  20. package/dist/address-search-worker-source.d.ts +2 -0
  21. package/dist/address-search-worker-source.js +5 -0
  22. package/dist/address-search-worker-source.js.map +1 -0
  23. package/dist/address-search.d.ts +31 -0
  24. package/dist/address-search.js +152 -0
  25. package/dist/address-search.js.map +1 -0
  26. package/dist/bairro-runs.d.ts +20 -0
  27. package/dist/bairro-runs.js +202 -0
  28. package/dist/bairro-runs.js.map +1 -0
  29. package/dist/binary-db-errors.d.ts +1 -1
  30. package/dist/binary-db-errors.js +1 -1
  31. package/dist/binary-db-errors.js.map +1 -1
  32. package/dist/binary-db-format.d.ts +10 -2
  33. package/dist/binary-db-format.js +9 -1
  34. package/dist/binary-db-format.js.map +1 -1
  35. package/dist/binary-db-integrity.d.ts +4 -0
  36. package/dist/binary-db-integrity.js +20 -0
  37. package/dist/binary-db-integrity.js.map +1 -0
  38. package/dist/binary-db-reader.d.ts +46 -28
  39. package/dist/binary-db-reader.js +237 -360
  40. package/dist/binary-db-reader.js.map +1 -1
  41. package/dist/binary-db-validator.d.ts +13 -0
  42. package/dist/binary-db-validator.js +709 -0
  43. package/dist/binary-db-validator.js.map +1 -0
  44. package/dist/chunks/dynamic-completion-wbp85hh9-cytdw6ns.js +7 -0
  45. package/dist/chunks/dynamic-completion-wbp85hh9-cytdw6ns.js.map +10 -0
  46. package/dist/chunks/index-338dn00y.js +18 -0
  47. package/dist/chunks/index-338dn00y.js.map +10 -0
  48. package/dist/expand.d.ts +8 -0
  49. package/dist/expand.js +1484 -0
  50. package/dist/expand.js.map +1 -0
  51. package/dist/fsst.d.ts +18 -0
  52. package/dist/fsst.js +117 -0
  53. package/dist/fsst.js.map +1 -0
  54. package/dist/index.js +48 -48
  55. package/dist/index.js.map +30 -18
  56. package/dist/library.d.ts +9 -2
  57. package/dist/library.js +9 -2
  58. package/dist/library.js.map +1 -1
  59. package/dist/locality-runs.d.ts +18 -0
  60. package/dist/locality-runs.js +108 -0
  61. package/dist/locality-runs.js.map +1 -0
  62. package/dist/packed-bits.d.ts +6 -0
  63. package/dist/packed-bits.js +41 -0
  64. package/dist/packed-bits.js.map +1 -0
  65. package/dist/settings.d.ts +0 -2
  66. package/dist/settings.js +0 -2
  67. package/dist/settings.js.map +1 -1
  68. package/dist/shared-file.d.ts +2 -0
  69. package/dist/shared-file.js +35 -0
  70. package/dist/shared-file.js.map +1 -0
  71. package/dist/sqlite-db-reader.d.ts +13 -4
  72. package/dist/sqlite-db-reader.js +39 -17
  73. package/dist/sqlite-db-reader.js.map +1 -1
  74. package/dist/types.d.ts +29 -4
  75. package/dist/types.js +73 -4
  76. package/dist/types.js.map +1 -1
  77. package/package.json +13 -10
  78. package/data/dne.bin +0 -0
  79. package/dist/chunks/dynamic-completion-403da357-4jc4w04x.js +0 -7
  80. package/dist/chunks/dynamic-completion-403da357-4jc4w04x.js.map +0 -10
  81. package/dist/chunks/index-s0h4vdva.js +0 -17
  82. package/dist/chunks/index-s0h4vdva.js.map +0 -10
package/README.md CHANGED
@@ -1,31 +1,8 @@
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
+ Crie e consulte bases locais de CEPs do Brasil em aplicações Bun a partir de dados do e-DNE dos Correios. Informe um diretório, arquivo ZIP ou URL com `--source` para gerar uma base SQLite ou binária. As consultas funcionam offline, sem servidor.
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
 
@@ -34,394 +11,150 @@ O pacote oferece uma API de leitura e mantém a CLI via `bunx @konstit/dne`.
34
11
 
35
12
  ## Início rápido
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
18
+ bunx @konstit/dne build --format binary --db ./dne.bin --source ./eDNE_Basico.zip
41
19
  ```
42
20
 
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')`.
21
+ Salve como `consulta.ts`:
61
22
 
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
-
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
75
- ```
76
-
77
- ## Execução
78
-
79
- Execute a CLI sem instalação global:
23
+ ```typescript
24
+ import { DneBinaryDatabaseReader } from '@konstit/dne';
80
25
 
81
- ```sh
82
- bunx @konstit/dne --version
83
- bunx @konstit/dne --json doctor --offline
26
+ const db = new DneBinaryDatabaseReader('./dne.bin');
27
+ console.log(db.queryCep('01141-000'));
28
+ db.close();
84
29
  ```
85
30
 
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.
87
-
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:
31
+ Execute com `bun consulta.ts`. Saída para a base usada neste exemplo:
89
32
 
90
- 1. `--db PATH`
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`.
94
-
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.
96
-
97
- ## Criar e atualizar
98
-
99
- ```sh
100
- 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
33
+ ```text
34
+ {
35
+ bairro: "Várzea da Barra Funda",
36
+ cep: "01141000",
37
+ complemento: null,
38
+ localidade_situacao: "codificada_por_logradouro",
39
+ localidade_tipo: "municipio",
40
+ logradouro: "Rua Rubens Meireles",
41
+ municipio: "São Paulo",
42
+ municipio_cod_ibge: 3550308,
43
+ nome: null,
44
+ uf: "SP",
45
+ }
106
46
  ```
107
47
 
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.
48
+ O leitor exige o caminho de uma base existente. Caminhos relativos usam o diretório de trabalho. Para atualizar os dados, execute novamente `build` com a fonte desejada e abra outro leitor.
111
49
 
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.
50
+ Arquivos físicos e assets importados pela aplicação são lidos integralmente em memória. As consultas usam essa cópia até o leitor ser fechado. Para distribuir seus dados com um bundle ou executável Bun, consulte o [guia de distribuição](docs/address-search.md#bundles-e-executáveis-do-bun).
113
51
 
114
- A especificação completa para implementar leitores em outras linguagens está em [docs/binary-layout.md](docs/binary-layout.md).
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.
115
53
 
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.
54
+ ## Qual formato usar?
117
55
 
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.
56
+ | Necessidade | Formato | Como usar |
57
+ | ---------------------------------------------- | ------- | ------------------------------- |
58
+ | Consultar uma base compacta | Binário | `new DneBinaryDatabaseReader('./dne.bin')` |
59
+ | Gerar uma base compacta para consultas por CEP | Binário | `build --format binary --source ./eDNE_Basico.zip` |
60
+ | Executar SQL ou integrar ferramentas SQLite | SQLite | `build --db ./dne.db --source ./eDNE_Basico.zip` |
119
61
 
120
- ## Acesso simultâneo
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`.
121
63
 
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.
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.
123
65
 
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.
66
+ O fluxo pressupõe uma base gerada por um processo confiável e mantida imutável durante o carregamento. 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 da cópia em memória. 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).
125
67
 
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.
68
+ ## Autocomplete de endereços
127
69
 
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.
70
+ A API `DneAddressSearch` pesquisa endereços por palavras e prefixo, com filtros por UF e código IBGE. Um CEP completo no texto pode determinar o município da busca. Gere o índice opcional com `bunx @konstit/dne build-search-index --db ./dne.bin`; veja [autocomplete de endereços](docs/address-search.md) para exemplos e regras.
129
71
 
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.
72
+ Para endpoints, `DneAddressSearchPool` oferece a mesma busca de forma assíncrona em workers nativos persistentes do Bun, compartilhando os bytes da base e do índice via `SharedArrayBuffer`, com fila limitada e cancelamento por `AbortSignal`. O código dos workers acompanha a biblioteca e é iniciado por Blob URL, permitindo [bundles e executáveis do Bun](docs/address-search.md#bundles-e-executáveis-do-bun). Veja a [API do pool](docs/address-search.md#pool-assíncrono-de-workers) e o [exemplo documentado com `Bun.serve`](examples/README.md).
131
73
 
132
- ## Atualização automática
74
+ ## CLI: criar e consultar sua própria base
133
75
 
134
- Instale uma atualização semanal para a base:
76
+ Execute sem instalação global. Forneça o arquivo e-DNE para criar uma base SQLite e consultar um CEP.
135
77
 
136
78
  ```sh
137
- bunx @konstit/dne cron install --db ./dne.db
79
+ bunx @konstit/dne build --db ./dne.db --source ./eDNE_Basico.zip
80
+ bunx @konstit/dne get 01001-000 --db ./dne.db --json
138
81
  ```
139
82
 
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:
83
+ Para gerar e consultar uma base binária:
141
84
 
142
85
  ```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
86
+ bunx @konstit/dne build --format binary --db ./dne.bin --source ./eDNE_Basico.zip
87
+ bunx @konstit/dne get 01001-000 --db ./dne.bin --json
148
88
  ```
149
89
 
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`.
90
+ A CLI usa `./dne.db` por padrão. `build --format binary` gera `./dne.bin` por padrão. Informe `--db` para consultar outro arquivo. `get`, `status` e `schema` detectam o formato do arquivo informado. O comando `sql` exige SQLite.
151
91
 
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`.
92
+ ### Criar e atualizar
153
93
 
154
- ## Consultar CEPs
155
-
156
- Consulta individual:
94
+ `build` exige `--source` com uma URL, 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.
157
95
 
158
96
  ```sh
159
- bunx @konstit/dne get 01001000
160
- bunx @konstit/dne get 01001-000 --json
97
+ bunx @konstit/dne build --db ./dne.db --source ./eDNE_Basico.zip
98
+ bunx @konstit/dne build --db ./dne.db --source ./eDNE_Basico.zip --check --json
99
+ bunx @konstit/dne status --db ./dne.db --json
161
100
  ```
162
101
 
163
- Consulta em lote:
102
+ Para agendar a atualização semanal de uma base SQLite no Linux ou macOS:
164
103
 
165
104
  ```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
105
+ bunx @konstit/dne cron install --db ./dne.db --source https://example.com/eDNE_Basico.zip
169
106
  ```
170
107
 
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.
108
+ 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.
172
109
 
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
110
+ ### Consultar em lote ou executar SQL
176
111
 
177
112
  ```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
113
+ bunx @konstit/dne get 01001000 20040002 --db ./dne.db --json
114
+ bunx @konstit/dne get --file ./ceps.txt --db ./dne.db --jsonl
115
+ bunx @konstit/dne sql "SELECT cep, municipio, uf FROM dne WHERE uf = 'SP' LIMIT 10" --db ./dne.db --json
183
116
  ```
184
117
 
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.
118
+ 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.
186
119
 
187
- ## SQL somente leitura
120
+ ## Desempenho
188
121
 
189
- ```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
- ```
122
+ No benchmark de **02/10/2026**, em um **Apple M4 com Bun 1.4.2**, o leitor binário v5 foi **19,2× mais rápido que o leitor SQLite de esquema 4** da biblioteca na mesma carga:
193
123
 
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.
124
+ | Métrica | Binário | SQLite |
125
+ | ---------------------------------------------- | ---------------: | --------: |
126
+ | Mediana por 100 mil consultas | **27,63 ms** | 531,46 ms |
127
+ | Consultas por segundo, calculadas pela mediana | **3,62 milhões** | 188,2 mil |
128
+ | Tamanho da base | **19,12 MB** | 109,22 MB |
195
129
 
196
- ## Contrato JSON
130
+ A base continha 1.611.629 CEPs. O leitor binário atual carrega o arquivo integralmente em memória com `readFileSync()`. 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.
197
131
 
198
- `--json` grava em stdout um envelope estável:
132
+ 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).
199
133
 
200
- ```json
201
- {
202
- "ok": true,
203
- "data": {}
204
- }
205
- ```
134
+ ## Documentação
206
135
 
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;
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
-
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.
136
+ | Referência | Conteúdo |
137
+ | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
138
+ | [API](https://github.com/Konstit-Engenharia/konstit-dne/blob/main/docs/api.md) | Leitores, bairros, faixas de CEP, tipos e exceções. |
139
+ | [Exemplos executáveis](examples/README.md) | Todas as APIs públicas: leitores, busca, pool, helpers, tipos e erros. |
140
+ | [CLI](https://github.com/Konstit-Engenharia/konstit-dne/blob/main/docs/cli.md) | Comandos, fontes, atualização automática, JSON e concorrência. |
141
+ | [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. |
142
+ | [Formato binário](https://github.com/Konstit-Engenharia/konstit-dne/blob/main/docs/binary-layout.md) | Especificação para implementar leitores em outras linguagens. |
143
+ | [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. |
144
+ | [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
145
 
378
146
  ## Desenvolvimento
379
147
 
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.
148
+ Na raiz do repositório:
394
149
 
395
150
  ```sh
151
+ bun install
396
152
  bun test
397
- bun run coverage
398
153
  bun run lint
399
- bun run fmt
400
- bun run benchmark
401
- bun run benchmark:download
402
154
  ```
403
155
 
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:
156
+ 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.
407
157
 
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
- ```
158
+ ## Licença
426
159
 
427
- `bun run build:package-database` prepara somente a base incluída. Os arquivos gerados permanecem fora do Git.
160
+ O código é distribuído sob a [licença MIT](LICENSE).
@@ -0,0 +1,34 @@
1
+ import { type ByteWidth } from './binary-db-format.ts';
2
+ import type { DneBinaryDatabaseReader } from './binary-db-reader.ts';
3
+ import { type UF } from './types.ts';
4
+ /** Numeric field sequences retain word positions; geography uses dense municipality IDs. */
5
+ export type AddressSearchIndex = {
6
+ data: DataView;
7
+ terms: string[];
8
+ offsets: number;
9
+ postings: Uint8Array;
10
+ rowCount: number;
11
+ rowMunicipalities: number;
12
+ rowFields: number;
13
+ fieldOffsets: number;
14
+ fieldCount: number;
15
+ fieldTokens: number;
16
+ fieldWidth: ByteWidth;
17
+ tokenWidth: ByteWidth;
18
+ municipalityWidth: ByteWidth;
19
+ municipalityCodes: number[];
20
+ municipalityUfs: UF[];
21
+ municipalityByCode: Map<number, number>;
22
+ };
23
+ /** Builds an optional, versioned search index bound to the reader's exact database snapshot. */
24
+ export declare function buildAddressSearchIndex(database: DneBinaryDatabaseReader): Uint8Array;
25
+ /** Validates integrity, source identity, and every range before queries can use the index. */
26
+ export declare function parseAddressSearchIndex(bytes: Uint8Array, checksum: string, rowCount: number): AddressSearchIndex;
27
+ /** Visits an ordered posting without materializing it, checking delta and range invariants. */
28
+ export declare function visitSearchPosting(index: AddressSearchIndex, id: number, visit?: (row: number) => void): void;
29
+ /** Resolves an index row ID to the eight-digit CEP used by the database reader. */
30
+ export declare function searchRowCep(index: AddressSearchIndex, id: number): string;
31
+ /** Reads geographic membership directly, without enumerating any geographic posting list. */
32
+ export declare function searchRowMunicipality(index: AddressSearchIndex, id: number): number;
33
+ /** Finds a CEP anchor using the search index, without decoding an address. */
34
+ export declare function findSearchCep(index: AddressSearchIndex, cep: string): number;