@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.
Files changed (44) hide show
  1. package/README.md +215 -13
  2. package/data/dne.bin +0 -0
  3. package/dist/bairro.d.ts +27 -0
  4. package/dist/bairro.js +9 -0
  5. package/dist/bairro.js.map +1 -0
  6. package/dist/binary-db-errors.d.ts +56 -0
  7. package/dist/binary-db-errors.js +68 -0
  8. package/dist/binary-db-errors.js.map +1 -0
  9. package/dist/binary-db-format.d.ts +192 -0
  10. package/dist/binary-db-format.js +250 -0
  11. package/dist/binary-db-format.js.map +1 -0
  12. package/dist/binary-db-reader.d.ts +114 -0
  13. package/dist/binary-db-reader.js +700 -0
  14. package/dist/binary-db-reader.js.map +1 -0
  15. package/dist/cep.d.ts +50 -0
  16. package/dist/cep.js +184 -0
  17. package/dist/cep.js.map +1 -0
  18. package/dist/errors.d.ts +14 -0
  19. package/dist/errors.js +21 -0
  20. package/dist/errors.js.map +1 -0
  21. package/dist/index.js +55 -33
  22. package/dist/index.js.map +29 -16
  23. package/dist/library.d.ts +10 -0
  24. package/dist/library.js +8 -0
  25. package/dist/library.js.map +1 -0
  26. package/dist/schema.d.ts +88 -0
  27. package/dist/schema.js +233 -0
  28. package/dist/schema.js.map +1 -0
  29. package/dist/settings.d.ts +34 -0
  30. package/dist/settings.js +35 -0
  31. package/dist/settings.js.map +1 -0
  32. package/dist/sqlite-db-errors.d.ts +40 -0
  33. package/dist/sqlite-db-errors.js +54 -0
  34. package/dist/sqlite-db-errors.js.map +1 -0
  35. package/dist/sqlite-db-reader.d.ts +130 -0
  36. package/dist/sqlite-db-reader.js +307 -0
  37. package/dist/sqlite-db-reader.js.map +1 -0
  38. package/dist/sqlite-db-schema.d.ts +49 -0
  39. package/dist/sqlite-db-schema.js +115 -0
  40. package/dist/sqlite-db-schema.js.map +1 -0
  41. package/dist/types.d.ts +90 -0
  42. package/dist/types.js +49 -0
  43. package/dist/types.js.map +1 -0
  44. package/package.json +17 -4
@@ -0,0 +1,700 @@
1
+ import { fileURLToPath } from 'node:url';
2
+ import { isBairroId, } from "./bairro.js";
3
+ import { DneBinaryDatabaseClosedError, DneBinaryDatabaseError, DneBinaryDatabaseFormatError, DneBinaryDatabaseIOError, DneBinaryDatabaseVersionError, } from "./binary-db-errors.js";
4
+ import { BINARY_BAIRRO_HEADER_SIZE, BINARY_DATABASE_HEADER_SIZE, BINARY_DATABASE_MAGIC as MAGIC, BINARY_DATABASE_VERSION, BINARY_SECTION_NAMES as SECTION_NAMES, bitmapByteLength, CEP_PREFIX_COUNT, CEP_PREFIX_OFFSETS_COUNT, CEP_SUFFIX_BITS, createPopcountTable, DICTIONARY_BLOCK_SHIFT, DICTIONARY_BLOCK_SIZE, DICTIONARY_HEADER_SIZE, hasBinaryMagic as hasMagic, integerByteWidth, maxPackedInteger, packedBitLength, readByteWidth, readPackedInteger as readPackedIntegerFromData, SECTION_TABLE_OFFSET, SPARSE_RANK_ROWS, SPARSE_RANK_SHIFT, } from "./binary-db-format.js";
5
+ import { cepToU32 } from "./cep.js";
6
+ import { LOCALIDADE_SITUACOES, LOCALIDADE_TIPOS, } from "./schema.js";
7
+ import { parseUF, } from "./types.js";
8
+ /** Error classes and discriminants used by this module's public operations. */
9
+ export { DneBinaryDatabaseClosedError, DneBinaryDatabaseError, DneBinaryDatabaseFormatError, DneBinaryDatabaseIOError, DneBinaryDatabaseVersionError, } from "./binary-db-errors.js";
10
+ /** Header size and format version accepted by this reader. */
11
+ export { BINARY_DATABASE_HEADER_SIZE, BINARY_DATABASE_VERSION } from "./binary-db-format.js";
12
+ const textDecoder = new TextDecoder();
13
+ const popcount = createPopcountTable();
14
+ /**
15
+ * Checks a file's magic bytes without validating its version or contents.
16
+ * @param path - Path to the candidate database file.
17
+ * @returns `false` for a missing file or nonmatching signature; `true` for the DNE binary signature.
18
+ * @throws {DneBinaryDatabaseIOError} If the file cannot be inspected or read.
19
+ */
20
+ export async function isBinaryDatabase(path) {
21
+ try {
22
+ if (!(await Bun.file(path).exists())) {
23
+ return false;
24
+ }
25
+ const prefix = new Uint8Array(await Bun.file(path).slice(0, MAGIC.length).arrayBuffer());
26
+ return hasMagic(prefix);
27
+ }
28
+ catch (cause) {
29
+ throw new DneBinaryDatabaseIOError(path, { cause });
30
+ }
31
+ }
32
+ /**
33
+ * Provides synchronous, read-only CEP lookups over a memory-mapped DNE binary database.
34
+ *
35
+ * Construction validates the file layout; individual records are decoded and checked on demand.
36
+ * Keep the underlying file immutable while the reader is open. Call `close()` when finished.
37
+ * All operational errors extend {@link DneBinaryDatabaseError}; invalid or absent CEPs return `undefined`.
38
+ */
39
+ export class DneBinaryDatabaseReader {
40
+ bairroCache;
41
+ data;
42
+ decodeScratch = new Uint8Array(0xff);
43
+ dictionaries;
44
+ bairros;
45
+ header;
46
+ mapped;
47
+ metadataValue;
48
+ municipalityCache;
49
+ /**
50
+ * Opens and validates a binary database using Bun's memory-mapping API.
51
+ * @param databasePath - Optional path to an existing binary database. Defaults to `data/dne.bin` inside this package.
52
+ * @throws {DneBinaryDatabaseIOError} If the file cannot be mapped.
53
+ * @throws {DneBinaryDatabaseVersionError} If the declared format version is unsupported.
54
+ * @throws {DneBinaryDatabaseFormatError} If the header, layout, dictionaries, or metadata are invalid.
55
+ */
56
+ constructor(databasePath = fileURLToPath(new URL('../data/dne.bin', import.meta.url))) {
57
+ let mapped;
58
+ try {
59
+ mapped = Bun.mmap(databasePath, { shared: false });
60
+ }
61
+ catch (cause) {
62
+ throw new DneBinaryDatabaseIOError(databasePath, { cause });
63
+ }
64
+ try {
65
+ const data = new DataView(mapped.buffer, mapped.byteOffset, mapped.byteLength);
66
+ const header = readHeader(data);
67
+ validateHeader(data, header);
68
+ const dictionaries = readDictionaries(data, header);
69
+ const bairros = readNeighborhoods(data, header, dictionaries);
70
+ validateLayout(data, header, dictionaries, bairros);
71
+ const metadata = parseMetadata(mapped, header.sections.metadata);
72
+ this.mapped = mapped;
73
+ this.data = data;
74
+ this.header = header;
75
+ this.dictionaries = dictionaries;
76
+ this.bairros = bairros;
77
+ this.metadataValue = metadata;
78
+ this.bairroCache = Array.from({ length: dictionaries.bairro.count + 1 });
79
+ this.municipalityCache = Array.from({ length: header.municipalityCount + 1 });
80
+ }
81
+ catch (error) {
82
+ this.mapped = null;
83
+ this.data = null;
84
+ if (error instanceof DneBinaryDatabaseError) {
85
+ throw error;
86
+ }
87
+ throw new DneBinaryDatabaseFormatError('Unable to decode binary database', { cause: error });
88
+ }
89
+ }
90
+ /**
91
+ * Releases this reader's references to the mapping and decoded caches.
92
+ * Repeated calls are safe. Bun controls when the mapping is reclaimed; this method does not
93
+ * guarantee immediate unmapping. Metadata and row count remain available after closing.
94
+ */
95
+ close() {
96
+ this.bairroCache = [];
97
+ this.data = null;
98
+ this.mapped = null;
99
+ this.municipalityCache = [];
100
+ }
101
+ /**
102
+ * Returns the load metadata parsed when the reader was constructed.
103
+ * @returns The cached metadata object, which callers should treat as read-only. Available after `close()`.
104
+ */
105
+ metadata() {
106
+ return this.metadataValue;
107
+ }
108
+ /**
109
+ * Looks up a CEP and decodes its address, including the originating locality indicators.
110
+ * @param cep - Eight ASCII digits or the form `NNNNN-NNN`; surrounding whitespace is not accepted.
111
+ * @returns An address with an eight-digit CEP, or `undefined` when the input is invalid or absent from the database.
112
+ * @throws {DneBinaryDatabaseClosedError} If called after `close()`, including for invalid CEP input.
113
+ * @throws {DneBinaryDatabaseFormatError} If the lookup encounters invalid indexes or record data.
114
+ */
115
+ queryCep(cep) {
116
+ return this.readSafely(() => {
117
+ const index = this.findCepIndex(cep);
118
+ return index === -1 ? undefined : this.readRow(index, cep.replace('-', ''));
119
+ });
120
+ }
121
+ /**
122
+ * Reads a neighborhood by its original DNE identifier, independent of duplicate names.
123
+ * @param neighborhoodId - Positive `BAI_NU` identifier.
124
+ * @returns The neighborhood, or undefined for an invalid or unknown identifier.
125
+ * @throws {DneBinaryDatabaseClosedError} If the reader is closed, including for invalid input.
126
+ * @throws {DneBinaryDatabaseFormatError} If an index, record, or string cannot be decoded.
127
+ */
128
+ queryNeighborhood(neighborhoodId) {
129
+ return this.readSafely(() => {
130
+ const index = this.findNeighborhoodIndex(neighborhoodId);
131
+ return index === 0 ? undefined : this.readNeighborhood(index);
132
+ });
133
+ }
134
+ /**
135
+ * Resolves the actual neighborhood of a CEP, preserving the distinction from districts and villages.
136
+ * @param cep - Eight ASCII digits or `NNNNN-NNN`.
137
+ * @returns The neighborhood, or undefined for an invalid, unknown, or neighborhood-free CEP.
138
+ * @throws {DneBinaryDatabaseClosedError} If the reader is closed, including for invalid input.
139
+ * @throws {DneBinaryDatabaseFormatError} If the CEP or neighborhood data is invalid.
140
+ */
141
+ queryNeighborhoodByCep(cep) {
142
+ return this.readSafely(() => {
143
+ const row = this.findCepIndex(cep);
144
+ if (row === -1) {
145
+ return undefined;
146
+ }
147
+ const index = this.readNeighborhoodIndex(row);
148
+ return index === 0 ? undefined : this.readNeighborhood(index);
149
+ });
150
+ }
151
+ /**
152
+ * Reads a neighborhood's original inclusive CEP intervals without merging gaps.
153
+ * @param neighborhoodId - Positive `BAI_NU` identifier.
154
+ * @returns Intervals sorted by lower and upper bounds, or an empty array for an invalid, unknown, or rangeless neighborhood.
155
+ * @throws {DneBinaryDatabaseClosedError} If the reader is closed, including for invalid input.
156
+ * @throws {DneBinaryDatabaseFormatError} If the interval directory or bounds are invalid.
157
+ */
158
+ queryNeighborhoodCepRanges(neighborhoodId) {
159
+ return this.readSafely(() => {
160
+ const index = this.findNeighborhoodIndex(neighborhoodId);
161
+ if (index === 0) {
162
+ return [];
163
+ }
164
+ const { bairroFaixaOffsets: offsets, bairroFaixas: ranges } = this.header.sections;
165
+ const start = this.readUint32(offsets.offset + (index - 1) * 4);
166
+ const end = this.readUint32(offsets.offset + index * 4);
167
+ if (start > end || end > ranges.length / 8) {
168
+ throw new DneBinaryDatabaseFormatError('Invalid binary neighborhood range offsets');
169
+ }
170
+ const result = [];
171
+ for (let row = start; row < end; row++) {
172
+ const initial = this.readUint32(ranges.offset + row * 8);
173
+ const final = this.readUint32(ranges.offset + row * 8 + 4);
174
+ if (initial > final || final > 99_999_999) {
175
+ throw new DneBinaryDatabaseFormatError('Invalid binary neighborhood CEP range');
176
+ }
177
+ result.push({ cep_inicial: String(initial).padStart(8, '0'), cep_final: String(final).padStart(8, '0') });
178
+ }
179
+ return result;
180
+ });
181
+ }
182
+ /**
183
+ * Returns the number of CEP records declared by the validated header.
184
+ * @returns The row count recorded at construction; available after `close()`.
185
+ */
186
+ rowCount() {
187
+ return this.header.rowCount;
188
+ }
189
+ readSafely(read) {
190
+ try {
191
+ this.requireData();
192
+ return read();
193
+ }
194
+ catch (error) {
195
+ if (error instanceof DneBinaryDatabaseError) {
196
+ throw error;
197
+ }
198
+ throw new DneBinaryDatabaseFormatError('Unable to decode binary database record', { cause: error });
199
+ }
200
+ }
201
+ findCepIndex(cep) {
202
+ const wanted = cepToU32(cep);
203
+ if (Number.isNaN(wanted)) {
204
+ return -1;
205
+ }
206
+ const prefix = Math.floor(wanted / 1_000);
207
+ const suffix = wanted % 1_000;
208
+ const prefixRegion = this.header.sections.cepPrefixOffsets;
209
+ const width = this.header.cepPrefixOffsetWidth;
210
+ let low = this.readPackedInteger(prefixRegion.offset + prefix * width, width);
211
+ const prefixEnd = this.readPackedInteger(prefixRegion.offset + (prefix + 1) * width, width);
212
+ let high = prefixEnd;
213
+ if (low > prefixEnd || prefixEnd > this.header.rowCount) {
214
+ throw new DneBinaryDatabaseFormatError(`Invalid binary CEP prefix range: ${prefix}`);
215
+ }
216
+ while (low < high) {
217
+ const middle = low + ((high - low) >>> 1);
218
+ const current = this.readPacked10(middle);
219
+ if (current < suffix) {
220
+ low = middle + 1;
221
+ }
222
+ else {
223
+ high = middle;
224
+ }
225
+ }
226
+ if (low >= prefixEnd || this.readPacked10(low) !== suffix) {
227
+ return -1;
228
+ }
229
+ return low;
230
+ }
231
+ findNeighborhoodIndex(neighborhoodId) {
232
+ if (!isBairroId(neighborhoodId)) {
233
+ return 0;
234
+ }
235
+ let low = 0;
236
+ let high = this.bairros.count;
237
+ while (low < high) {
238
+ const middle = low + ((high - low) >>> 1);
239
+ const id = this.readPackedInteger(this.bairros.recordsOffset + middle * this.bairros.recordWidth, this.bairros.originalIdWidth);
240
+ if (id < neighborhoodId) {
241
+ low = middle + 1;
242
+ }
243
+ else {
244
+ high = middle;
245
+ }
246
+ }
247
+ if (low === this.bairros.count) {
248
+ return 0;
249
+ }
250
+ const id = this.readPackedInteger(this.bairros.recordsOffset + low * this.bairros.recordWidth, this.bairros.originalIdWidth);
251
+ return id === neighborhoodId ? low + 1 : 0;
252
+ }
253
+ readNeighborhoodIndex(row) {
254
+ const index = this.readPackedInteger(this.header.sections.bairroIds.offset + row * this.bairros.idWidth, this.bairros.idWidth);
255
+ if (index > this.bairros.count) {
256
+ throw new DneBinaryDatabaseFormatError(`Invalid binary neighborhood index: ${index}`);
257
+ }
258
+ return index;
259
+ }
260
+ readNeighborhood(index) {
261
+ const { originalIdWidth, localidadeIdWidth, recordsOffset, recordWidth } = this.bairros;
262
+ let offset = recordsOffset + (index - 1) * recordWidth;
263
+ const bairro_id = this.readPackedInteger(offset, originalIdWidth);
264
+ offset += originalIdWidth;
265
+ const localidade_id = this.readPackedInteger(offset, localidadeIdWidth);
266
+ offset += localidadeIdWidth;
267
+ const nome = this.readRequiredDictionaryString(this.dictionaries.bairro, this.readPackedInteger(offset, this.dictionaries.bairro.idWidth), 'bairro');
268
+ offset += this.dictionaries.bairro.idWidth;
269
+ const nome_abreviado = this.readDictionaryString(this.dictionaries.bairroAbreviado, this.readPackedInteger(offset, this.dictionaries.bairroAbreviado.idWidth));
270
+ offset += this.dictionaries.bairroAbreviado.idWidth;
271
+ const uf = parseUF(this.readRequiredDictionaryString(this.dictionaries.uf, this.readPackedInteger(offset, this.dictionaries.uf.idWidth), 'uf'));
272
+ return { bairro_id, localidade_id, nome, nome_abreviado, uf };
273
+ }
274
+ readRow(index, cep) {
275
+ const sections = this.header.sections;
276
+ const municipalityId = this.readPackedInteger(sections.municipalityIds.offset + index * this.header.municipalityIdWidth, this.header.municipalityIdWidth);
277
+ if (municipalityId === 0 || municipalityId > this.header.municipalityCount) {
278
+ throw new DneBinaryDatabaseFormatError(`Invalid binary municipality id: ${municipalityId}`);
279
+ }
280
+ const municipality = this.readMunicipality(municipalityId);
281
+ const flags = this.requireData().getUint8(sections.localidadeFlags.offset + index);
282
+ const situacao = LOCALIDADE_SITUACOES[flags & 3];
283
+ const tipo = LOCALIDADE_TIPOS[flags >>> 2];
284
+ if (situacao === undefined || tipo === undefined) {
285
+ throw new DneBinaryDatabaseFormatError(`Invalid binary locality indicators: ${flags}`);
286
+ }
287
+ const bairroIndex = this.readNeighborhoodIndex(index);
288
+ const localidadeNomeId = this.readSparseId(sections.localidadeNomeBitmap, sections.localidadeNomeRanks, sections.localidadeNomeIds, index, this.dictionaries.bairro.idWidth);
289
+ if (localidadeNomeId !== 0 && (bairroIndex !== 0 || tipo === 'municipio')) {
290
+ throw new DneBinaryDatabaseFormatError('Invalid binary subordinate locality name');
291
+ }
292
+ const bairroNameId = bairroIndex === 0
293
+ ? localidadeNomeId
294
+ : this.readPackedInteger(this.bairros.recordsOffset + (bairroIndex - 1) * this.bairros.recordWidth
295
+ + this.bairros.originalIdWidth + this.bairros.localidadeIdWidth, this.dictionaries.bairro.idWidth);
296
+ if (bairroIndex !== 0 && bairroNameId === 0) {
297
+ throw new DneBinaryDatabaseFormatError('Null binary neighborhood name');
298
+ }
299
+ return {
300
+ bairro: this.readCachedDictionaryString(this.dictionaries.bairro, bairroNameId, this.bairroCache),
301
+ cep,
302
+ complemento: this.readDictionaryString(this.dictionaries.complemento, this.readSparseId(sections.complementoBitmap, sections.complementoRanks, sections.complementoIds, index, this.dictionaries.complemento.idWidth)),
303
+ localidade_situacao: situacao,
304
+ localidade_tipo: tipo,
305
+ logradouro: this.readDictionaryString(this.dictionaries.logradouro, this.readPackedInteger(sections.logradouroIds.offset + index * this.dictionaries.logradouro.idWidth, this.dictionaries.logradouro.idWidth)),
306
+ municipio: municipality.municipio,
307
+ municipio_cod_ibge: municipality.codigoIbge,
308
+ nome: this.readDictionaryString(this.dictionaries.nome, this.readSparseId(sections.nomeBitmap, sections.nomeRanks, sections.nomeIds, index, this.dictionaries.nome.idWidth)),
309
+ uf: municipality.uf,
310
+ };
311
+ }
312
+ readMunicipality(id) {
313
+ const cached = this.municipalityCache[id];
314
+ if (cached) {
315
+ return cached;
316
+ }
317
+ const recordWidth = 3 + this.dictionaries.municipio.idWidth + this.dictionaries.uf.idWidth;
318
+ const offset = this.header.sections.municipalities.offset + (id - 1) * recordWidth;
319
+ const municipioId = this.readPackedInteger(offset + 3, this.dictionaries.municipio.idWidth);
320
+ const ufId = this.readPackedInteger(offset + 3 + this.dictionaries.municipio.idWidth, this.dictionaries.uf.idWidth);
321
+ const municipality = {
322
+ codigoIbge: this.readPackedInteger(offset, 3),
323
+ municipio: this.readRequiredDictionaryString(this.dictionaries.municipio, municipioId, 'municipio'),
324
+ uf: parseUF(this.readRequiredDictionaryString(this.dictionaries.uf, ufId, 'uf')),
325
+ };
326
+ this.municipalityCache[id] = municipality;
327
+ return municipality;
328
+ }
329
+ readSparseId(bitmap, ranks, ids, rowIndex, idWidth) {
330
+ const mapped = this.requireMapped();
331
+ const bitmapByteIndex = rowIndex >>> 3;
332
+ const bitmapByte = mapped[bitmap.offset + bitmapByteIndex] ?? 0;
333
+ const bitIndex = rowIndex & 7;
334
+ if ((bitmapByte & (1 << bitIndex)) === 0) {
335
+ return 0;
336
+ }
337
+ const rankBlock = rowIndex >>> SPARSE_RANK_SHIFT;
338
+ let denseIndex = this.readUint32(ranks.offset + rankBlock * 4);
339
+ const blockByteOffset = rankBlock * (SPARSE_RANK_ROWS >>> 3);
340
+ for (let offset = blockByteOffset; offset < bitmapByteIndex; offset++) {
341
+ denseIndex += popcount[mapped[bitmap.offset + offset] ?? 0] ?? 0;
342
+ }
343
+ denseIndex += popcount[bitmapByte & ((1 << bitIndex) - 1)] ?? 0;
344
+ if ((denseIndex + 1) * idWidth > ids.length) {
345
+ throw new DneBinaryDatabaseFormatError(`Invalid binary sparse id index: ${denseIndex}`);
346
+ }
347
+ return this.readPackedInteger(ids.offset + denseIndex * idWidth, idWidth);
348
+ }
349
+ readDictionaryString(dictionary, id) {
350
+ if (id === 0) {
351
+ return null;
352
+ }
353
+ if (id > dictionary.count) {
354
+ throw new DneBinaryDatabaseFormatError(`Invalid binary string id: ${id}`);
355
+ }
356
+ const mapped = this.requireMapped();
357
+ const index = id - 1;
358
+ const block = index >>> DICTIONARY_BLOCK_SHIFT;
359
+ const blockStart = block << DICTIONARY_BLOCK_SHIFT;
360
+ const relativeOffset = this.readUint32(dictionary.blockOffsetsOffset + block * 4);
361
+ if (relativeOffset > dictionary.suffixDataLength) {
362
+ throw new DneBinaryDatabaseFormatError(`Invalid binary string block offset: ${relativeOffset}`);
363
+ }
364
+ let cursor = dictionary.suffixDataOffset + relativeOffset;
365
+ const decoded = this.decodeScratch;
366
+ let previousLength = 0;
367
+ for (let currentIndex = blockStart; currentIndex <= index; currentIndex++) {
368
+ const length = mapped[dictionary.lengthsOffset + currentIndex] ?? 0;
369
+ const prefixLength = mapped[dictionary.prefixesOffset + currentIndex] ?? 0;
370
+ if ((currentIndex === blockStart && prefixLength !== 0) || prefixLength > previousLength || prefixLength > length) {
371
+ throw new DneBinaryDatabaseFormatError(`Invalid binary front-coded string: ${id}`);
372
+ }
373
+ const suffixLength = length - prefixLength;
374
+ if (cursor < dictionary.suffixDataOffset || cursor + suffixLength > dictionary.suffixDataOffset + dictionary.suffixDataLength) {
375
+ throw new DneBinaryDatabaseFormatError(`Invalid binary string suffix: ${id}`);
376
+ }
377
+ decoded.set(mapped.subarray(cursor, cursor + suffixLength), prefixLength);
378
+ cursor += suffixLength;
379
+ previousLength = length;
380
+ }
381
+ return textDecoder.decode(decoded.subarray(0, previousLength));
382
+ }
383
+ readCachedDictionaryString(dictionary, id, cache) {
384
+ if (id === 0) {
385
+ return null;
386
+ }
387
+ const cached = cache[id];
388
+ if (cached !== undefined) {
389
+ return cached;
390
+ }
391
+ const value = this.readDictionaryString(dictionary, id);
392
+ if (value !== null) {
393
+ cache[id] = value;
394
+ }
395
+ return value;
396
+ }
397
+ readRequiredDictionaryString(dictionary, id, field) {
398
+ const value = this.readDictionaryString(dictionary, id);
399
+ if (value === null) {
400
+ throw new DneBinaryDatabaseFormatError(`Binary database has a null required field: ${field}`);
401
+ }
402
+ return value;
403
+ }
404
+ readPacked10(index) {
405
+ const mapped = this.requireMapped();
406
+ const region = this.header.sections.cepSuffixes;
407
+ const bitOffset = index * CEP_SUFFIX_BITS;
408
+ const byteIndex = bitOffset >>> 3;
409
+ const shift = bitOffset & 7;
410
+ const absoluteOffset = region.offset + byteIndex;
411
+ const value = (mapped[absoluteOffset] ?? 0)
412
+ | ((mapped[absoluteOffset + 1] ?? 0) << 8)
413
+ | ((mapped[absoluteOffset + 2] ?? 0) << 16);
414
+ return (value >>> shift) & 0x3ff;
415
+ }
416
+ readPackedInteger(offset, width) {
417
+ return readPackedIntegerFromData(this.requireData(), offset, width);
418
+ }
419
+ readUint32(offset) {
420
+ return this.requireData().getUint32(offset, true);
421
+ }
422
+ requireData() {
423
+ if (!this.data) {
424
+ throw new DneBinaryDatabaseClosedError();
425
+ }
426
+ return this.data;
427
+ }
428
+ requireMapped() {
429
+ if (!this.mapped) {
430
+ throw new DneBinaryDatabaseClosedError();
431
+ }
432
+ return this.mapped;
433
+ }
434
+ }
435
+ /**
436
+ * Opens a binary database, reads its load metadata, and closes the temporary reader.
437
+ * @param path - Path to an existing binary database file.
438
+ * @returns Metadata parsed from the file at open time.
439
+ * @throws {DneBinaryDatabaseIOError} If the file cannot be mapped.
440
+ * @throws {DneBinaryDatabaseVersionError} If the binary version is unsupported.
441
+ * @throws {DneBinaryDatabaseFormatError} If the file layout or metadata are invalid.
442
+ */
443
+ export async function readBinaryDatabaseMetadata(path) {
444
+ const reader = new DneBinaryDatabaseReader(path);
445
+ try {
446
+ return reader.metadata();
447
+ }
448
+ finally {
449
+ reader.close();
450
+ }
451
+ }
452
+ function readHeader(data) {
453
+ if (data.byteLength < BINARY_DATABASE_HEADER_SIZE) {
454
+ throw new DneBinaryDatabaseFormatError('Binary database header is truncated');
455
+ }
456
+ for (let index = 0; index < MAGIC.length; index++) {
457
+ if (data.getUint8(index) !== MAGIC[index]) {
458
+ throw new DneBinaryDatabaseFormatError('Invalid binary database magic');
459
+ }
460
+ }
461
+ const version = data.getUint16(8, true);
462
+ if (version !== BINARY_DATABASE_VERSION) {
463
+ throw new DneBinaryDatabaseVersionError(version, BINARY_DATABASE_VERSION);
464
+ }
465
+ if (data.getUint16(10, true) !== BINARY_DATABASE_HEADER_SIZE) {
466
+ throw new DneBinaryDatabaseFormatError('Unsupported binary database header size');
467
+ }
468
+ if (data.getUint8(22) !== SPARSE_RANK_SHIFT || data.getUint8(23) !== DICTIONARY_BLOCK_SHIFT) {
469
+ throw new DneBinaryDatabaseFormatError('Unsupported binary database block layout');
470
+ }
471
+ if (data.getUint16(24, true) !== SECTION_NAMES.length) {
472
+ throw new DneBinaryDatabaseFormatError('Unsupported binary database section table');
473
+ }
474
+ const sections = {};
475
+ for (const [index, name,] of SECTION_NAMES.entries()) {
476
+ const offset = SECTION_TABLE_OFFSET + index * 8;
477
+ sections[name] = {
478
+ length: data.getUint32(offset + 4, true),
479
+ offset: data.getUint32(offset, true),
480
+ };
481
+ }
482
+ return {
483
+ cepPrefixOffsetWidth: readByteWidth(data.getUint8(20), 'CEP prefix offset'),
484
+ fileSize: data.getUint32(16, true),
485
+ municipalityCount: data.getUint32(28, true),
486
+ municipalityIdWidth: readByteWidth(data.getUint8(21), 'municipality id'),
487
+ rowCount: data.getUint32(12, true),
488
+ sections,
489
+ };
490
+ }
491
+ function validateHeader(data, header) {
492
+ if (header.fileSize !== data.byteLength) {
493
+ throw new DneBinaryDatabaseFormatError(`Binary database size mismatch: header=${header.fileSize}, actual=${data.byteLength}`);
494
+ }
495
+ if (!header.rowCount || !header.municipalityCount) {
496
+ throw new DneBinaryDatabaseFormatError('Binary database must contain rows and municipalities');
497
+ }
498
+ if (header.rowCount > maxPackedInteger(header.cepPrefixOffsetWidth)) {
499
+ throw new DneBinaryDatabaseFormatError('Binary row count does not fit the CEP prefix offset width');
500
+ }
501
+ if (header.municipalityCount > maxPackedInteger(header.municipalityIdWidth)) {
502
+ throw new DneBinaryDatabaseFormatError('Binary municipality count does not fit its id width');
503
+ }
504
+ let previousEnd = BINARY_DATABASE_HEADER_SIZE;
505
+ for (const name of SECTION_NAMES) {
506
+ const region = header.sections[name];
507
+ validateRegion(data.byteLength, region, name);
508
+ if (region.offset < previousEnd) {
509
+ throw new DneBinaryDatabaseFormatError(`Binary section is out of order or overlaps: ${name}`);
510
+ }
511
+ previousEnd = region.offset + region.length;
512
+ }
513
+ if (header.sections.cepPrefixOffsets.length !== CEP_PREFIX_OFFSETS_COUNT * header.cepPrefixOffsetWidth) {
514
+ throw new DneBinaryDatabaseFormatError('Binary CEP prefix directory has an invalid length');
515
+ }
516
+ if (header.sections.cepSuffixes.length !== packedBitLength(header.rowCount, CEP_SUFFIX_BITS)) {
517
+ throw new DneBinaryDatabaseFormatError('Binary CEP suffix column has an invalid length');
518
+ }
519
+ if (header.sections.complementoBitmap.length !== bitmapByteLength(header.rowCount)
520
+ || header.sections.nomeBitmap.length !== bitmapByteLength(header.rowCount)
521
+ || header.sections.localidadeNomeBitmap.length !== bitmapByteLength(header.rowCount)) {
522
+ throw new DneBinaryDatabaseFormatError('Binary nullable bitmap has an invalid length');
523
+ }
524
+ const expectedRankLength = (Math.ceil(header.rowCount / SPARSE_RANK_ROWS) + 1) * 4;
525
+ if (header.sections.complementoRanks.length !== expectedRankLength
526
+ || header.sections.nomeRanks.length !== expectedRankLength
527
+ || header.sections.localidadeNomeRanks.length !== expectedRankLength) {
528
+ throw new DneBinaryDatabaseFormatError('Binary sparse rank index has an invalid length');
529
+ }
530
+ }
531
+ function readDictionaries(data, header) {
532
+ return {
533
+ bairro: readDictionary(data, header.sections.bairroDictionary, 'bairro'),
534
+ bairroAbreviado: readDictionary(data, header.sections.bairroAbreviadoDictionary, 'bairro abbreviation'),
535
+ complemento: readDictionary(data, header.sections.complementoDictionary, 'complemento'),
536
+ logradouro: readDictionary(data, header.sections.logradouroDictionary, 'logradouro'),
537
+ municipio: readDictionary(data, header.sections.municipioDictionary, 'municipio'),
538
+ nome: readDictionary(data, header.sections.nomeDictionary, 'nome'),
539
+ uf: readDictionary(data, header.sections.ufDictionary, 'uf'),
540
+ };
541
+ }
542
+ function readDictionary(data, region, name) {
543
+ if (region.length < DICTIONARY_HEADER_SIZE) {
544
+ throw new DneBinaryDatabaseFormatError(`Binary ${name} dictionary is truncated`);
545
+ }
546
+ const count = data.getUint32(region.offset, true);
547
+ const blockCount = data.getUint32(region.offset + 4, true);
548
+ const blockOffsetsRelative = data.getUint32(region.offset + 8, true);
549
+ const lengthsRelative = data.getUint32(region.offset + 12, true);
550
+ const prefixesRelative = data.getUint32(region.offset + 16, true);
551
+ const suffixDataRelative = data.getUint32(region.offset + 20, true);
552
+ const suffixDataLength = data.getUint32(region.offset + 24, true);
553
+ const idWidth = readByteWidth(data.getUint8(region.offset + 28), `${name} dictionary id`);
554
+ if (data.getUint8(region.offset + 29) !== DICTIONARY_BLOCK_SHIFT) {
555
+ throw new DneBinaryDatabaseFormatError(`Unsupported binary ${name} dictionary block size`);
556
+ }
557
+ if (blockCount !== Math.ceil(count / DICTIONARY_BLOCK_SIZE)) {
558
+ throw new DneBinaryDatabaseFormatError(`Binary ${name} dictionary has an invalid block count`);
559
+ }
560
+ if (count > maxPackedInteger(idWidth)) {
561
+ throw new DneBinaryDatabaseFormatError(`Binary ${name} dictionary does not fit its id width`);
562
+ }
563
+ if (blockOffsetsRelative !== DICTIONARY_HEADER_SIZE
564
+ || lengthsRelative !== blockOffsetsRelative + blockCount * 4
565
+ || prefixesRelative !== lengthsRelative + count
566
+ || suffixDataRelative !== prefixesRelative + count
567
+ || suffixDataRelative > region.length
568
+ || suffixDataLength !== region.length - suffixDataRelative) {
569
+ throw new DneBinaryDatabaseFormatError(`Binary ${name} dictionary has an invalid layout`);
570
+ }
571
+ const dictionary = {
572
+ blockCount,
573
+ blockOffsetsOffset: region.offset + blockOffsetsRelative,
574
+ count,
575
+ idWidth,
576
+ lengthsOffset: region.offset + lengthsRelative,
577
+ prefixesOffset: region.offset + prefixesRelative,
578
+ region,
579
+ suffixDataLength,
580
+ suffixDataOffset: region.offset + suffixDataRelative,
581
+ };
582
+ if (blockCount && data.getUint32(dictionary.blockOffsetsOffset, true) !== 0) {
583
+ throw new DneBinaryDatabaseFormatError(`Binary ${name} dictionary has an invalid first block offset`);
584
+ }
585
+ return dictionary;
586
+ }
587
+ function readNeighborhoods(data, header, dictionaries) {
588
+ const region = header.sections.bairros;
589
+ if (region.length < BINARY_BAIRRO_HEADER_SIZE) {
590
+ throw new DneBinaryDatabaseFormatError('Binary neighborhood table is truncated');
591
+ }
592
+ const count = data.getUint32(region.offset, true);
593
+ const originalIdWidth = readByteWidth(data.getUint8(region.offset + 4), 'original neighborhood id');
594
+ const localidadeIdWidth = readByteWidth(data.getUint8(region.offset + 5), 'original locality id');
595
+ const recordWidth = originalIdWidth + localidadeIdWidth + dictionaries.bairro.idWidth
596
+ + dictionaries.bairroAbreviado.idWidth + dictionaries.uf.idWidth;
597
+ assertRegionLength(region, BINARY_BAIRRO_HEADER_SIZE + count * recordWidth, 'neighborhood table');
598
+ const recordsOffset = region.offset + BINARY_BAIRRO_HEADER_SIZE;
599
+ let previousId = 0;
600
+ for (let index = 0; index < count; index++) {
601
+ let offset = recordsOffset + index * recordWidth;
602
+ const id = readPackedIntegerFromData(data, offset, originalIdWidth);
603
+ offset += originalIdWidth;
604
+ const localityId = readPackedIntegerFromData(data, offset, localidadeIdWidth);
605
+ offset += localidadeIdWidth;
606
+ const nameId = readPackedIntegerFromData(data, offset, dictionaries.bairro.idWidth);
607
+ offset += dictionaries.bairro.idWidth;
608
+ const abbreviationId = readPackedIntegerFromData(data, offset, dictionaries.bairroAbreviado.idWidth);
609
+ offset += dictionaries.bairroAbreviado.idWidth;
610
+ const ufId = readPackedIntegerFromData(data, offset, dictionaries.uf.idWidth);
611
+ if (id <= previousId || localityId === 0 || nameId === 0 || nameId > dictionaries.bairro.count
612
+ || abbreviationId > dictionaries.bairroAbreviado.count || ufId === 0 || ufId > dictionaries.uf.count) {
613
+ throw new DneBinaryDatabaseFormatError(`Invalid binary neighborhood record: ${index}`);
614
+ }
615
+ previousId = id;
616
+ }
617
+ return { count, idWidth: integerByteWidth(count), originalIdWidth, localidadeIdWidth, recordsOffset, recordWidth };
618
+ }
619
+ function validateNeighborhoodRanges(data, header, bairros) {
620
+ const { bairroFaixaOffsets: offsets, bairroFaixas: ranges } = header.sections;
621
+ assertRegionLength(offsets, (bairros.count + 1) * 4, 'neighborhood range offsets');
622
+ if (ranges.length % 8 !== 0 || data.getUint32(offsets.offset, true) !== 0) {
623
+ throw new DneBinaryDatabaseFormatError('Invalid binary neighborhood range layout');
624
+ }
625
+ const count = ranges.length / 8;
626
+ let start = 0;
627
+ for (let index = 0; index < bairros.count; index++) {
628
+ const end = data.getUint32(offsets.offset + (index + 1) * 4, true);
629
+ if (end < start || end > count) {
630
+ throw new DneBinaryDatabaseFormatError('Invalid binary neighborhood range offsets');
631
+ }
632
+ let previousInitial = -1;
633
+ let previousFinal = -1;
634
+ for (let row = start; row < end; row++) {
635
+ const initial = data.getUint32(ranges.offset + row * 8, true);
636
+ const final = data.getUint32(ranges.offset + row * 8 + 4, true);
637
+ if (initial > final || final > 99_999_999 || initial < previousInitial
638
+ || (initial === previousInitial && final <= previousFinal)) {
639
+ throw new DneBinaryDatabaseFormatError('Invalid binary neighborhood CEP range');
640
+ }
641
+ previousInitial = initial;
642
+ previousFinal = final;
643
+ }
644
+ start = end;
645
+ }
646
+ if (start !== count) {
647
+ throw new DneBinaryDatabaseFormatError('Unreferenced binary neighborhood CEP ranges');
648
+ }
649
+ }
650
+ function validateLayout(data, header, dictionaries, bairros) {
651
+ const sections = header.sections;
652
+ assertRegionLength(sections.localidadeFlags, header.rowCount, 'locality indicators');
653
+ assertRegionLength(sections.logradouroIds, header.rowCount * dictionaries.logradouro.idWidth, 'logradouro ids');
654
+ assertRegionLength(sections.bairroIds, header.rowCount * bairros.idWidth, 'bairro indexes');
655
+ assertRegionLength(sections.municipalityIds, header.rowCount * header.municipalityIdWidth, 'municipality ids');
656
+ const municipalityRecordWidth = 3 + dictionaries.municipio.idWidth + dictionaries.uf.idWidth;
657
+ assertRegionLength(sections.municipalities, header.municipalityCount * municipalityRecordWidth, 'municipalities');
658
+ validateSparseLayout(data, sections.complementoRanks, sections.complementoIds, dictionaries.complemento.idWidth, 'complemento');
659
+ validateSparseLayout(data, sections.nomeRanks, sections.nomeIds, dictionaries.nome.idWidth, 'nome');
660
+ validateSparseLayout(data, sections.localidadeNomeRanks, sections.localidadeNomeIds, dictionaries.bairro.idWidth, 'localidade_nome');
661
+ validateNeighborhoodRanges(data, header, bairros);
662
+ const firstPrefix = readPackedIntegerFromData(data, sections.cepPrefixOffsets.offset, header.cepPrefixOffsetWidth);
663
+ const lastPrefix = readPackedIntegerFromData(data, sections.cepPrefixOffsets.offset + CEP_PREFIX_COUNT * header.cepPrefixOffsetWidth, header.cepPrefixOffsetWidth);
664
+ if (firstPrefix !== 0 || lastPrefix !== header.rowCount) {
665
+ throw new DneBinaryDatabaseFormatError('Binary CEP prefix directory has invalid boundaries');
666
+ }
667
+ }
668
+ function validateSparseLayout(data, ranks, ids, idWidth, name) {
669
+ const denseCount = data.getUint32(ranks.offset + ranks.length - 4, true);
670
+ if (ids.length !== denseCount * idWidth) {
671
+ throw new DneBinaryDatabaseFormatError(`Binary ${name} sparse ids have an invalid length`);
672
+ }
673
+ }
674
+ function parseMetadata(mapped, region) {
675
+ const text = textDecoder.decode(mapped.subarray(region.offset, region.offset + region.length));
676
+ let parsed;
677
+ try {
678
+ parsed = JSON.parse(text);
679
+ }
680
+ catch (cause) {
681
+ throw new DneBinaryDatabaseFormatError('Binary database metadata is invalid JSON', { cause });
682
+ }
683
+ if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
684
+ throw new DneBinaryDatabaseFormatError('Binary database metadata must be an object');
685
+ }
686
+ return parsed;
687
+ }
688
+ function validateRegion(fileLength, region, name) {
689
+ if (region.offset < BINARY_DATABASE_HEADER_SIZE
690
+ || region.offset > fileLength
691
+ || region.length > fileLength - region.offset) {
692
+ throw new DneBinaryDatabaseFormatError(`Binary ${name} region is outside the file`);
693
+ }
694
+ }
695
+ function assertRegionLength(region, expected, name) {
696
+ if (region.length !== expected) {
697
+ throw new DneBinaryDatabaseFormatError(`Binary ${name} region has an invalid length`);
698
+ }
699
+ }
700
+ //# sourceMappingURL=binary-db-reader.js.map