@konstit/dne 0.0.2 → 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.
Files changed (62) hide show
  1. package/README.md +87 -159
  2. package/data/dne.bin +0 -0
  3. package/dist/bairro-runs.d.ts +20 -0
  4. package/dist/bairro-runs.js +202 -0
  5. package/dist/bairro-runs.js.map +1 -0
  6. package/dist/bairro.d.ts +27 -0
  7. package/dist/bairro.js +9 -0
  8. package/dist/bairro.js.map +1 -0
  9. package/dist/binary-db-errors.d.ts +56 -0
  10. package/dist/binary-db-errors.js +68 -0
  11. package/dist/binary-db-errors.js.map +1 -0
  12. package/dist/binary-db-format.d.ts +200 -0
  13. package/dist/binary-db-format.js +258 -0
  14. package/dist/binary-db-format.js.map +1 -0
  15. package/dist/binary-db-integrity.d.ts +4 -0
  16. package/dist/binary-db-integrity.js +20 -0
  17. package/dist/binary-db-integrity.js.map +1 -0
  18. package/dist/binary-db-reader.d.ts +126 -0
  19. package/dist/binary-db-reader.js +556 -0
  20. package/dist/binary-db-reader.js.map +1 -0
  21. package/dist/binary-db-validator.d.ts +13 -0
  22. package/dist/binary-db-validator.js +712 -0
  23. package/dist/binary-db-validator.js.map +1 -0
  24. package/dist/cep.d.ts +50 -0
  25. package/dist/cep.js +184 -0
  26. package/dist/cep.js.map +1 -0
  27. package/dist/errors.d.ts +14 -0
  28. package/dist/errors.js +21 -0
  29. package/dist/errors.js.map +1 -0
  30. package/dist/fsst.d.ts +18 -0
  31. package/dist/fsst.js +117 -0
  32. package/dist/fsst.js.map +1 -0
  33. package/dist/index.js +55 -33
  34. package/dist/index.js.map +36 -16
  35. package/dist/library.d.ts +10 -0
  36. package/dist/library.js +8 -0
  37. package/dist/library.js.map +1 -0
  38. package/dist/locality-runs.d.ts +18 -0
  39. package/dist/locality-runs.js +108 -0
  40. package/dist/locality-runs.js.map +1 -0
  41. package/dist/packed-bits.d.ts +6 -0
  42. package/dist/packed-bits.js +41 -0
  43. package/dist/packed-bits.js.map +1 -0
  44. package/dist/schema.d.ts +88 -0
  45. package/dist/schema.js +233 -0
  46. package/dist/schema.js.map +1 -0
  47. package/dist/settings.d.ts +34 -0
  48. package/dist/settings.js +35 -0
  49. package/dist/settings.js.map +1 -0
  50. package/dist/sqlite-db-errors.d.ts +40 -0
  51. package/dist/sqlite-db-errors.js +54 -0
  52. package/dist/sqlite-db-errors.js.map +1 -0
  53. package/dist/sqlite-db-reader.d.ts +130 -0
  54. package/dist/sqlite-db-reader.js +307 -0
  55. package/dist/sqlite-db-reader.js.map +1 -0
  56. package/dist/sqlite-db-schema.d.ts +49 -0
  57. package/dist/sqlite-db-schema.js +115 -0
  58. package/dist/sqlite-db-schema.js.map +1 -0
  59. package/dist/types.d.ts +90 -0
  60. package/dist/types.js +49 -0
  61. package/dist/types.js.map +1 -0
  62. package/package.json +18 -5
package/README.md CHANGED
@@ -1,225 +1,153 @@
1
- # CLI para e-DNE dos Correios
1
+ # @konstit/dne: CEPs do Brasil
2
2
 
3
- Crie em segundos uma base SQLite local, compacta e 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` 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 diretamente em uma única tabela `dne` indexada, sem tabelas brutas intermediárias.
6
-
7
- Principais vantagens:
8
-
9
- - **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
- - **Consultas locais simples:** procure um CEP, consulte vários CEPs em lote ou execute SQL somente leitura diretamente no arquivo SQLite.
11
- - **Atualizações seguras:** o modo WAL e uma única transação permitem atualizar a base sem expor dados parciais aos processos de leitura.
12
- - **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
- - **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
-
15
- 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
-
17
- Este pacote fornece somente uma CLI. Ele não expõe uma API pública de biblioteca.
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.
18
6
 
19
7
  ## Requisitos
20
8
 
21
9
  - Bun 1.4 ou mais recente
22
10
  - macOS ou Linux
23
11
 
24
- ## Início rápido
12
+ ## Início rápido: consultar a base incluída
25
13
 
26
- ```sh
27
- bunx @konstit/dne build --db ./dne.db
28
- bunx @konstit/dne get 01001-000 --db ./dne.db
29
- ```
30
-
31
- ## Execução
32
-
33
- Execute a CLI sem instalação global:
14
+ Instale o pacote:
34
15
 
35
16
  ```sh
36
- bunx @konstit/dne --version
37
- bunx @konstit/dne --json doctor --offline
17
+ bun add @konstit/dne
38
18
  ```
39
19
 
40
- 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.
41
-
42
- `--db` é uma opção global. Ela pode aparecer antes ou depois de um subcomando. O caminho da base segue esta ordem de precedência:
20
+ Salve como `consulta.ts`:
43
21
 
44
- 1. `--db PATH`
45
- 2. `./dne.db`
46
-
47
- 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
-
49
- ## Criar e atualizar
22
+ ```typescript
23
+ import { DneBinaryDatabaseReader } from '@konstit/dne';
50
24
 
51
- ```sh
52
- bunx @konstit/dne build --db ./dne.db
53
- bunx @konstit/dne build --db ./dne.db --source ./eDNE_Basico.zip
54
- bunx @konstit/dne build --db ./dne.db --source ./Delimitado
55
- bunx @konstit/dne build --db ./dne.db --source https://example.com/eDNE_Basico.zip
56
- bunx @konstit/dne build --db ./dne.db --force
57
- bunx @konstit/dne build --db ./dne.db --check --json
25
+ const db = new DneBinaryDatabaseReader();
26
+ try {
27
+ console.log(JSON.stringify(db.queryCep('01141-000'), null, 2));
28
+ } finally {
29
+ db.close();
30
+ }
58
31
  ```
59
32
 
60
- `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
-
62
- Cada carga grava a versão do `@konstit/dne` em `edne_metadata`. 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.
33
+ Execute com `bun consulta.ts`. Saída para a base usada neste exemplo:
63
34
 
64
- 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.
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
+ }
48
+ ```
65
49
 
66
- 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.
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.
67
51
 
68
- ## Acesso simultâneo
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.
69
53
 
70
- 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.
54
+ ## Qual formato usar?
71
55
 
72
- 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.
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` |
73
61
 
74
- 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.
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`.
75
63
 
76
- 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.
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.
77
65
 
78
- 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.
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).
79
67
 
80
- ## Atualização automática
68
+ ## CLI: criar e consultar sua própria base
81
69
 
82
- Instale uma atualização semanal para a base:
70
+ Execute sem instalação global. Para criar uma base SQLite a partir do arquivo público do e-DNE e consultar um CEP:
83
71
 
84
72
  ```sh
85
- bunx @konstit/dne cron install --db ./dne.db
73
+ bunx @konstit/dne build --db ./dne.db
74
+ bunx @konstit/dne get 01001-000 --db ./dne.db --json
86
75
  ```
87
76
 
88
- 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:
89
78
 
90
79
  ```sh
91
- bunx @konstit/dne cron install '30 6 * * 5' --db ./dne.db
92
- bunx @konstit/dne cron install --db ./dne.db --source https://example.com/eDNE_Basico.zip
93
- bunx @konstit/dne cron install '@weekly' --db ./dne.db --dry-run
94
- bunx @konstit/dne cron status --db ./dne.db --json
95
- 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
96
82
  ```
97
83
 
98
- `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`.
99
-
100
- 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`.
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.
101
85
 
102
- ## Consultar CEPs
86
+ ### Criar e atualizar
103
87
 
104
- Consulta individual:
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.
105
89
 
106
90
  ```sh
107
- bunx @konstit/dne get 01001000
108
- bunx @konstit/dne get 01001-000 --json
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
109
94
  ```
110
95
 
111
- Consulta em lote:
96
+ Para agendar a atualização semanal de uma base SQLite no Linux ou macOS:
112
97
 
113
98
  ```sh
114
- bunx @konstit/dne get 01001000 20040002 --json
115
- bunx @konstit/dne get --file ./ceps.txt --jsonl
116
- printf '01001000\n20040002\n' | bunx @konstit/dne get --jsonl
99
+ bunx @konstit/dne cron install --db ./dne.db
117
100
  ```
118
101
 
119
- 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
-
121
- `get` abre o SQLite em modo somente leitura. 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.
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.
122
103
 
123
- ## Inspecionar a base
104
+ ### Consultar em lote ou executar SQL
124
105
 
125
106
  ```sh
126
- bunx @konstit/dne status --json
127
- bunx @konstit/dne schema --json
128
- bunx @konstit/dne schema --expected
129
- bunx @konstit/dne doctor --json
130
- bunx @konstit/dne doctor --offline --json
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
131
110
  ```
132
111
 
133
- `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.
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.
134
113
 
135
- ## SQL somente leitura
114
+ ## Desempenho
136
115
 
137
- ```sh
138
- bunx @konstit/dne sql 'SELECT cep, municipio, uf FROM dne WHERE uf = "SP" LIMIT 10' --json
139
- bunx @konstit/dne sql 'PRAGMA page_size' --limit 20 --json
140
- ```
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:
141
117
 
142
- 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.
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 |
143
123
 
144
- ## Contrato JSON
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.
145
125
 
146
- `--json` grava em stdout um envelope estável:
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).
147
127
 
148
- ```json
149
- {
150
- "ok": true,
151
- "data": {}
152
- }
153
- ```
128
+ ## Documentação
154
129
 
155
- Erros de execução e de argumentos usam este formato em stderr:
156
-
157
- ```json
158
- {
159
- "ok": false,
160
- "error": {
161
- "code": "invalid-cep",
162
- "message": "CEP inválido 'x'. Use 01001000 ou 01001-000."
163
- }
164
- }
165
- ```
166
-
167
- O progresso e os diagnósticos são gravados em stderr. A saída JSON em stdout não inclui mensagens de progresso.
168
-
169
- Códigos de saída:
170
-
171
- - `0`: comando concluído
172
- - `1`: falha na base, na fonte, na rede ou na execução
173
- - `2`: argumentos inválidos ou CEP em formato inválido
174
- - `3`: um ou mais CEPs válidos não foram encontrados
175
-
176
- ## Schema SQLite
177
-
178
- ```sql
179
- CREATE TABLE "dne" (
180
- "cep" TEXT NOT NULL /* Contém somente os oito dígitos do CEP, sem separadores. */,
181
- "logradouro" TEXT,
182
- "complemento" TEXT,
183
- "bairro" TEXT,
184
- "municipio" TEXT NOT NULL,
185
- "municipio_cod_ibge" INTEGER NOT NULL,
186
- "uf" TEXT NOT NULL,
187
- "nome" TEXT,
188
- PRIMARY KEY ("cep")
189
- ) WITHOUT ROWID;
190
- ```
191
-
192
- `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
-
194
- ### Drizzle ORM schema
195
-
196
- ```typescript
197
- import { sqliteTable } from 'drizzle-orm/sqlite-core';
198
-
199
- export const dneTable = sqliteTable('dne', (t) => ({
200
- cep: t.text().primaryKey(),
201
- logradouro: t.text(),
202
- complemento: t.text(),
203
- bairro: t.text(),
204
- municipio: t.text().notNull(),
205
- municipio_cod_ibge: t.integer().notNull(),
206
- uf: t.text().notNull(),
207
- nome: t.text(),
208
- }));
209
- ```
210
-
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 essa tabela 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. |
212
138
 
213
139
  ## Desenvolvimento
214
140
 
215
- O comando `zip` é necessário para os testes de desenvolvimento que usam fixtures e arquivos ZIP aninhados.
141
+ Na raiz do repositório:
216
142
 
217
143
  ```sh
144
+ bun install
218
145
  bun test
219
146
  bun run lint
220
- bun run fmt
221
- bun run benchmark
222
- bun run benchmark:download
223
147
  ```
224
148
 
225
- Outros scripts de benchmark específicos estão listados em `package.json`.
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.
150
+
151
+ ## Licença
152
+
153
+ O código é distribuído sob a [licença MIT](LICENSE).
package/data/dne.bin ADDED
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;
@@ -0,0 +1,202 @@
1
+ import { DneBinaryDatabaseFormatError } from "./binary-db-errors.js";
2
+ import { createPopcountTable, readPackedInteger, writePackedInteger, } from "./binary-db-format.js";
3
+ const HEADER_BYTES = 8;
4
+ const SAMPLE_SHIFT = 3;
5
+ const SAMPLE_STEP = 1 << SAMPLE_SHIFT;
6
+ const popcount = createPopcountTable();
7
+ /** Encodes consecutive equal neighborhood indexes; Elias–Fano stores each run's starting row. */
8
+ export function encodeBairroRuns(dense, rowCount, idWidth) {
9
+ const view = new DataView(dense.buffer, dense.byteOffset, dense.byteLength);
10
+ const starts = [];
11
+ const ids = [];
12
+ let previous = -1;
13
+ for (let row = 0; row < rowCount; row++) {
14
+ const id = readPackedInteger(view, row * idWidth, idWidth);
15
+ if (id !== previous) {
16
+ starts.push(row);
17
+ ids.push(id);
18
+ previous = id;
19
+ }
20
+ }
21
+ const runCount = starts.length;
22
+ const lowBits = Math.floor(Math.log2(rowCount / runCount));
23
+ const lowBase = 2 ** lowBits;
24
+ const zeroCount = Math.ceil(rowCount / lowBase);
25
+ const highBitCount = zeroCount + runCount;
26
+ const lowBytes = Math.ceil(runCount * lowBits / 8);
27
+ const highBytes = Math.ceil(highBitCount / 8);
28
+ const sampleCount = Math.ceil(zeroCount / SAMPLE_STEP);
29
+ const highOffset = HEADER_BYTES + lowBytes;
30
+ const samplesOffset = highOffset + highBytes;
31
+ const idsOffset = samplesOffset + sampleCount * 4;
32
+ const bytes = new Uint8Array(idsOffset + runCount * idWidth);
33
+ const data = new DataView(bytes.buffer);
34
+ data.setUint32(0, runCount, true);
35
+ data.setUint8(4, lowBits);
36
+ data.setUint8(5, SAMPLE_SHIFT);
37
+ data.setUint8(6, idWidth);
38
+ for (let index = 0; index < runCount; index++) {
39
+ const start = starts[index] ?? 0;
40
+ writeBits(bytes, HEADER_BYTES, index * lowBits, lowBits, start % lowBase);
41
+ const highBit = Math.floor(start / lowBase) + index;
42
+ const highByte = highOffset + (highBit >>> 3);
43
+ bytes[highByte] = (bytes[highByte] ?? 0) | (1 << (highBit & 7));
44
+ writePackedInteger(bytes, idsOffset + index * idWidth, ids[index] ?? 0, idWidth);
45
+ }
46
+ let zeroIndex = 0;
47
+ for (let bit = 0; bit < highBitCount; bit++) {
48
+ if (((bytes[highOffset + (bit >>> 3)] ?? 0) & (1 << (bit & 7))) === 0) {
49
+ if (zeroIndex % SAMPLE_STEP === 0) {
50
+ data.setUint32(samplesOffset + (zeroIndex >>> SAMPLE_SHIFT) * 4, bit, true);
51
+ }
52
+ zeroIndex++;
53
+ }
54
+ }
55
+ return bytes;
56
+ }
57
+ /** Reads locations after the file has passed integrity verification. */
58
+ export function readBairroRunsLayout(data, region, rowCount, idWidth) {
59
+ const runCount = data.getUint32(region.offset, true);
60
+ const lowBits = data.getUint8(region.offset + 4);
61
+ const zeroCount = Math.ceil(rowCount / 2 ** lowBits);
62
+ const highBitCount = zeroCount + runCount;
63
+ const lowOffset = region.offset + HEADER_BYTES;
64
+ const highOffset = lowOffset + Math.ceil(runCount * lowBits / 8);
65
+ const samplesOffset = highOffset + Math.ceil(highBitCount / 8);
66
+ const idsOffset = samplesOffset + Math.ceil(zeroCount / SAMPLE_STEP) * 4;
67
+ return { highBitCount, highOffset, idWidth, idsOffset, lowBits, lowOffset, runCount, samplesOffset, zeroCount };
68
+ }
69
+ /** Validates the complete encoded run index during generation. */
70
+ export function parseBairroRuns(data, region, rowCount, idWidth, bairroCount) {
71
+ if (region.length < HEADER_BYTES) {
72
+ throw new DneBinaryDatabaseFormatError('Binary neighborhood runs are truncated');
73
+ }
74
+ const runCount = data.getUint32(region.offset, true);
75
+ const lowBits = data.getUint8(region.offset + 4);
76
+ if (runCount < 1 || runCount > rowCount || lowBits > 31
77
+ || data.getUint8(region.offset + 5) !== SAMPLE_SHIFT
78
+ || data.getUint8(region.offset + 6) !== idWidth
79
+ || data.getUint8(region.offset + 7) !== 0) {
80
+ throw new DneBinaryDatabaseFormatError('Invalid binary neighborhood run header');
81
+ }
82
+ const lowBase = 2 ** lowBits;
83
+ const zeroCount = Math.ceil(rowCount / lowBase);
84
+ const highBitCount = zeroCount + runCount;
85
+ const lowBytes = Math.ceil(runCount * lowBits / 8);
86
+ const highBytes = Math.ceil(highBitCount / 8);
87
+ const sampleCount = Math.ceil(zeroCount / SAMPLE_STEP);
88
+ const lowOffset = region.offset + HEADER_BYTES;
89
+ const highOffset = lowOffset + lowBytes;
90
+ const samplesOffset = highOffset + highBytes;
91
+ const idsOffset = samplesOffset + sampleCount * 4;
92
+ if (idsOffset + runCount * idWidth !== region.offset + region.length) {
93
+ throw new DneBinaryDatabaseFormatError('Invalid binary neighborhood run length');
94
+ }
95
+ let zeros = 0;
96
+ let runs = 0;
97
+ let previousStart = -1;
98
+ let previousId = -1;
99
+ for (let bit = 0; bit < highBitCount; bit++) {
100
+ const one = (data.getUint8(highOffset + (bit >>> 3)) & (1 << (bit & 7))) !== 0;
101
+ if (!one) {
102
+ if (zeros >= zeroCount) {
103
+ throw new DneBinaryDatabaseFormatError('Invalid binary neighborhood run bitmap');
104
+ }
105
+ if (zeros % SAMPLE_STEP === 0 && data.getUint32(samplesOffset + (zeros >>> SAMPLE_SHIFT) * 4, true) !== bit) {
106
+ throw new DneBinaryDatabaseFormatError('Invalid binary neighborhood run samples');
107
+ }
108
+ zeros++;
109
+ continue;
110
+ }
111
+ if (runs >= runCount) {
112
+ throw new DneBinaryDatabaseFormatError('Invalid binary neighborhood run bitmap');
113
+ }
114
+ const low = readBits(data, lowOffset, runs * lowBits, lowBits);
115
+ const start = zeros * lowBase + low;
116
+ const id = readPackedInteger(data, idsOffset + runs * idWidth, idWidth);
117
+ if ((runs === 0 && start !== 0) || start <= previousStart || start >= rowCount || id > bairroCount || id === previousId) {
118
+ throw new DneBinaryDatabaseFormatError('Invalid binary neighborhood run');
119
+ }
120
+ previousStart = start;
121
+ previousId = id;
122
+ runs++;
123
+ }
124
+ if (highBitCount % 8 !== 0) {
125
+ const paddingMask = 0xff << (highBitCount & 7);
126
+ if ((data.getUint8(highOffset + (highBitCount >>> 3)) & paddingMask) !== 0) {
127
+ throw new DneBinaryDatabaseFormatError('Invalid binary neighborhood run padding');
128
+ }
129
+ }
130
+ return { highBitCount, highOffset, idWidth, idsOffset, lowBits, lowOffset, runCount, samplesOffset, zeroCount };
131
+ }
132
+ /** Finds the run containing a row using the Elias–Fano high bucket and its packed low values. */
133
+ export function readBairroRunIndex(data, runs, row) {
134
+ const lowBase = 2 ** runs.lowBits;
135
+ const high = Math.floor(row / lowBase);
136
+ const end = selectZero(data, runs, high) - high;
137
+ const start = high === 0 ? 0 : selectZero(data, runs, high - 1) - (high - 1);
138
+ const wantedLow = row % lowBase;
139
+ let low = start;
140
+ let upper = end;
141
+ while (low < upper) {
142
+ const middle = low + ((upper - low) >>> 1);
143
+ const value = readBits(data, runs.lowOffset, middle * runs.lowBits, runs.lowBits);
144
+ if (value <= wantedLow) {
145
+ low = middle + 1;
146
+ }
147
+ else {
148
+ upper = middle;
149
+ }
150
+ }
151
+ const runIndex = low - 1;
152
+ return readPackedInteger(data, runs.idsOffset + runIndex * runs.idWidth, runs.idWidth);
153
+ }
154
+ function selectZero(data, runs, zeroIndex) {
155
+ const sampleIndex = zeroIndex >>> SAMPLE_SHIFT;
156
+ let bit = data.getUint32(runs.samplesOffset + sampleIndex * 4, true);
157
+ let remaining = zeroIndex - sampleIndex * SAMPLE_STEP;
158
+ if (remaining === 0) {
159
+ return bit;
160
+ }
161
+ bit++;
162
+ while (remaining > 0) {
163
+ const withinByte = bit & 7;
164
+ const available = 8 - withinByte;
165
+ const mask = (1 << available) - 1;
166
+ const zeroBits = (~(data.getUint8(runs.highOffset + (bit >>> 3)) >>> withinByte)) & mask;
167
+ const count = popcount[zeroBits] ?? 0;
168
+ if (count >= remaining) {
169
+ for (let offset = 0; remaining > 0; offset++) {
170
+ if (zeroBits & (1 << offset)) {
171
+ remaining--;
172
+ }
173
+ bit++;
174
+ }
175
+ }
176
+ else {
177
+ remaining -= count;
178
+ bit += available;
179
+ }
180
+ }
181
+ return bit - 1;
182
+ }
183
+ function readBits(data, byteOffset, bitOffset, count) {
184
+ let value = 0;
185
+ for (let bit = 0; bit < count; bit++) {
186
+ const position = bitOffset + bit;
187
+ if (data.getUint8(byteOffset + (position >>> 3)) & (1 << (position & 7))) {
188
+ value += 2 ** bit;
189
+ }
190
+ }
191
+ return value;
192
+ }
193
+ function writeBits(bytes, byteOffset, bitOffset, count, value) {
194
+ for (let bit = 0; bit < count; bit++) {
195
+ if (Math.floor(value / 2 ** bit) % 2) {
196
+ const position = bitOffset + bit;
197
+ const target = byteOffset + (position >>> 3);
198
+ bytes[target] = (bytes[target] ?? 0) | (1 << (position & 7));
199
+ }
200
+ }
201
+ }
202
+ //# sourceMappingURL=bairro-runs.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"bairro-runs.js","sourceRoot":"","sources":["../src/bairro-runs.ts"],"names":[],"mappings":"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"}
@@ -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"}