@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
@@ -0,0 +1,126 @@
1
+ import { type DneBairro, type DneFaixaCep } from './bairro.ts';
2
+ import { type DneRow, type LoadMetadata, type UF } from './types.ts';
3
+ /** Error classes and discriminants used by this module's public operations. */
4
+ export { DneBinaryDatabaseClosedError, DneBinaryDatabaseError, type DneBinaryDatabaseErrorCode, DneBinaryDatabaseFormatError, DneBinaryDatabaseIOError, DneBinaryDatabaseVersionError, } from './binary-db-errors.ts';
5
+ /** Header size and format version accepted by this reader. */
6
+ export { BINARY_DATABASE_HEADER_SIZE, BINARY_DATABASE_VERSION } from './binary-db-format.ts';
7
+ /** Neighborhood records and inclusive CEP intervals returned by this reader. */
8
+ export type { DneBairro, DneFaixaCep } from './bairro.ts';
9
+ /**
10
+ * Checks a file's magic bytes without validating its version or contents.
11
+ * @param path - Path to the candidate database file.
12
+ * @returns `false` for a missing file or nonmatching signature; `true` for the DNE binary signature.
13
+ * @throws {DneBinaryDatabaseIOError} If the file cannot be inspected or read.
14
+ */
15
+ export declare function isBinaryDatabase(path: string): Promise<boolean>;
16
+ /**
17
+ * Provides synchronous, read-only CEP lookups over a memory-mapped DNE binary database.
18
+ *
19
+ * Construction verifies the header and SHA-256 of bytes validated by a trusted generator.
20
+ * Queries decode directly using the invariants guaranteed at generation.
21
+ * Keep the underlying file immutable while the reader is open. Call `close()` when finished.
22
+ * All operational errors extend {@link DneBinaryDatabaseError}; invalid or absent CEPs return `undefined`.
23
+ */
24
+ export declare class DneBinaryDatabaseReader {
25
+ private bairroCache;
26
+ private data;
27
+ private decodeScratch;
28
+ private dictionaries;
29
+ private bairros;
30
+ private bairroRuns;
31
+ private localityRuns;
32
+ private logradouroIdBits;
33
+ private header;
34
+ private mapped;
35
+ private readonly metadataValue;
36
+ private municipalityCache;
37
+ /**
38
+ * Opens and verifies a binary database using Bun's memory-mapping API.
39
+ * @param databasePath - Optional path to an existing binary database. Defaults to `data/dne.bin` inside this package.
40
+ * @throws {DneBinaryDatabaseIOError} If the file cannot be mapped.
41
+ * @throws {DneBinaryDatabaseVersionError} If the declared format version is unsupported.
42
+ * @throws {DneBinaryDatabaseFormatError} If the minimum header, file size, or SHA-256 checksum is invalid.
43
+ */
44
+ constructor(databasePath?: string);
45
+ /**
46
+ * Releases this reader's references to the mapping and decoded caches.
47
+ * Repeated calls are safe. Bun controls when the mapping is reclaimed; this method does not
48
+ * guarantee immediate unmapping. Metadata and row count remain available after closing.
49
+ */
50
+ close(): void;
51
+ /**
52
+ * Returns the load metadata parsed when the reader was constructed.
53
+ * @returns The cached, frozen metadata object. Available after `close()`.
54
+ */
55
+ metadata(): Readonly<LoadMetadata>;
56
+ /**
57
+ * Looks up a CEP and decodes its address, including the originating locality indicators.
58
+ * @param cep - Eight ASCII digits or the form `NNNNN-NNN`; surrounding whitespace is not accepted.
59
+ * @returns An address with an eight-digit CEP, or `undefined` when the input is invalid or absent from the database.
60
+ * @throws {DneBinaryDatabaseClosedError} If called after `close()`, including for invalid CEP input.
61
+ */
62
+ queryCep(cep: string): DneRow | undefined;
63
+ /**
64
+ * Resolves a municipality's name and UF by its IBGE code.
65
+ * @param municipioCodIbge - Seven-digit IBGE municipality code represented as an integer.
66
+ * @returns The municipality and UF, or undefined for an invalid or unknown code.
67
+ * @throws {DneBinaryDatabaseClosedError} If the reader is closed, including for invalid input.
68
+ */
69
+ queryMunicipality(municipioCodIbge: number): Pick<DneRow, 'municipio' | 'uf'> | undefined;
70
+ /**
71
+ * Lists the IBGE municipality codes stored for a federative unit.
72
+ * @param uf - Canonical uppercase Brazilian state abbreviation.
73
+ * @returns Unique codes in ascending order, or an empty array for an invalid or absent UF.
74
+ * @throws {DneBinaryDatabaseClosedError} If the reader is closed, including for invalid input.
75
+ */
76
+ queryMunicipalityCodesByUf(uf: UF): number[];
77
+ /**
78
+ * Reads a neighborhood by its original DNE identifier, independent of duplicate names.
79
+ * @param neighborhoodId - Positive `BAI_NU` identifier.
80
+ * @returns The neighborhood, or undefined for an invalid or unknown identifier.
81
+ * @throws {DneBinaryDatabaseClosedError} If the reader is closed, including for invalid input.
82
+ */
83
+ queryNeighborhood(neighborhoodId: number): DneBairro | undefined;
84
+ /**
85
+ * Resolves the actual neighborhood of a CEP, preserving the distinction from districts and villages.
86
+ * @param cep - Eight ASCII digits or `NNNNN-NNN`.
87
+ * @returns The neighborhood, or undefined for an invalid, unknown, or neighborhood-free CEP.
88
+ * @throws {DneBinaryDatabaseClosedError} If the reader is closed, including for invalid input.
89
+ */
90
+ queryNeighborhoodByCep(cep: string): DneBairro | undefined;
91
+ /**
92
+ * Reads a neighborhood's original inclusive CEP intervals without merging gaps.
93
+ * @param neighborhoodId - Positive `BAI_NU` identifier.
94
+ * @returns Intervals sorted by lower and upper bounds, or an empty array for an invalid, unknown, or rangeless neighborhood.
95
+ * @throws {DneBinaryDatabaseClosedError} If the reader is closed, including for invalid input.
96
+ */
97
+ queryNeighborhoodCepRanges(neighborhoodId: number): DneFaixaCep[];
98
+ /**
99
+ * Returns the number of CEP records declared by the validated header.
100
+ * @returns The row count recorded at construction; available after `close()`.
101
+ */
102
+ rowCount(): number;
103
+ private assertOpen;
104
+ private findCepIndex;
105
+ private findNeighborhoodIndex;
106
+ private readNeighborhoodIndex;
107
+ private readNeighborhood;
108
+ private readRow;
109
+ private readMunicipality;
110
+ private readSparseId;
111
+ private readDictionaryString;
112
+ private readCachedDictionaryString;
113
+ private readRequiredDictionaryString;
114
+ private readPacked10;
115
+ private readPackedInteger;
116
+ private readUint32;
117
+ }
118
+ /**
119
+ * Opens a binary database, reads its load metadata, and closes the temporary reader.
120
+ * @param path - Path to an existing binary database file.
121
+ * @returns Frozen metadata parsed from the file at open time.
122
+ * @throws {DneBinaryDatabaseIOError} If the file cannot be mapped.
123
+ * @throws {DneBinaryDatabaseVersionError} If the binary version is unsupported.
124
+ * @throws {DneBinaryDatabaseFormatError} If the minimum header, file size, or SHA-256 checksum is invalid.
125
+ */
126
+ export declare function readBinaryDatabaseMetadata(path: string): Promise<Readonly<LoadMetadata>>;
@@ -0,0 +1,556 @@
1
+ import { fileURLToPath } from 'node:url';
2
+ import { readBairroRunIndex, readBairroRunsLayout, } from "./bairro-runs.js";
3
+ import { isBairroId, } from "./bairro.js";
4
+ import { DneBinaryDatabaseClosedError, DneBinaryDatabaseError, DneBinaryDatabaseFormatError, DneBinaryDatabaseIOError, DneBinaryDatabaseVersionError, } from "./binary-db-errors.js";
5
+ import { BINARY_BAIRRO_HEADER_SIZE, BINARY_DATABASE_CHECKSUM_SIZE, BINARY_DATABASE_HEADER_SIZE, BINARY_DATABASE_MAGIC as MAGIC, BINARY_DATABASE_VERSION, BINARY_SECTION_NAMES as SECTION_NAMES, CEP_SUFFIX_BITS, createPopcountTable, DICTIONARY_BLOCK_SHIFT, DICTIONARY_CODEC_FSST, hasBinaryMagic as hasMagic, integerByteWidth, readPackedInteger as readPackedIntegerFromData, SECTION_TABLE_OFFSET, SPARSE_RANK_ROWS, SPARSE_RANK_SHIFT, } from "./binary-db-format.js";
6
+ import { verifyBinaryDatabaseChecksum } from "./binary-db-integrity.js";
7
+ import { cepToU32 } from "./cep.js";
8
+ import { readTrustedFsstString } from "./fsst.js";
9
+ import { findLocalityRun, readLocalityRunsLayout, } from "./locality-runs.js";
10
+ import { integerBitWidth, readPackedBits, } from "./packed-bits.js";
11
+ import { LOCALIDADE_SITUACOES, LOCALIDADE_TIPOS, } from "./schema.js";
12
+ import { stateCodes, } from "./types.js";
13
+ /** Error classes and discriminants used by this module's public operations. */
14
+ export { DneBinaryDatabaseClosedError, DneBinaryDatabaseError, DneBinaryDatabaseFormatError, DneBinaryDatabaseIOError, DneBinaryDatabaseVersionError, } from "./binary-db-errors.js";
15
+ /** Header size and format version accepted by this reader. */
16
+ export { BINARY_DATABASE_HEADER_SIZE, BINARY_DATABASE_VERSION } from "./binary-db-format.js";
17
+ const textDecoder = new TextDecoder();
18
+ const popcount = createPopcountTable();
19
+ /**
20
+ * Checks a file's magic bytes without validating its version or contents.
21
+ * @param path - Path to the candidate database file.
22
+ * @returns `false` for a missing file or nonmatching signature; `true` for the DNE binary signature.
23
+ * @throws {DneBinaryDatabaseIOError} If the file cannot be inspected or read.
24
+ */
25
+ export async function isBinaryDatabase(path) {
26
+ try {
27
+ if (!(await Bun.file(path).exists())) {
28
+ return false;
29
+ }
30
+ const prefix = new Uint8Array(await Bun.file(path).slice(0, MAGIC.length).arrayBuffer());
31
+ return hasMagic(prefix);
32
+ }
33
+ catch (cause) {
34
+ throw new DneBinaryDatabaseIOError(path, { cause });
35
+ }
36
+ }
37
+ /**
38
+ * Provides synchronous, read-only CEP lookups over a memory-mapped DNE binary database.
39
+ *
40
+ * Construction verifies the header and SHA-256 of bytes validated by a trusted generator.
41
+ * Queries decode directly using the invariants guaranteed at generation.
42
+ * Keep the underlying file immutable while the reader is open. Call `close()` when finished.
43
+ * All operational errors extend {@link DneBinaryDatabaseError}; invalid or absent CEPs return `undefined`.
44
+ */
45
+ export class DneBinaryDatabaseReader {
46
+ bairroCache;
47
+ data;
48
+ decodeScratch = new Uint8Array(0xff);
49
+ dictionaries;
50
+ bairros;
51
+ bairroRuns;
52
+ localityRuns;
53
+ logradouroIdBits;
54
+ header;
55
+ mapped;
56
+ metadataValue;
57
+ municipalityCache;
58
+ /**
59
+ * Opens and verifies a binary database using Bun's memory-mapping API.
60
+ * @param databasePath - Optional path to an existing binary database. Defaults to `data/dne.bin` inside this package.
61
+ * @throws {DneBinaryDatabaseIOError} If the file cannot be mapped.
62
+ * @throws {DneBinaryDatabaseVersionError} If the declared format version is unsupported.
63
+ * @throws {DneBinaryDatabaseFormatError} If the minimum header, file size, or SHA-256 checksum is invalid.
64
+ */
65
+ constructor(databasePath = fileURLToPath(new URL('../data/dne.bin', import.meta.url))) {
66
+ let mapped;
67
+ try {
68
+ mapped = Bun.mmap(databasePath, { shared: false });
69
+ }
70
+ catch (cause) {
71
+ throw new DneBinaryDatabaseIOError(databasePath, { cause });
72
+ }
73
+ try {
74
+ const data = new DataView(mapped.buffer, mapped.byteOffset, mapped.byteLength);
75
+ verifyHeader(data);
76
+ verifyBinaryDatabaseChecksum(mapped);
77
+ const header = readHeader(data);
78
+ const dictionaries = readDictionaries(data, header);
79
+ const bairros = readNeighborhoods(data, header, dictionaries);
80
+ const bairroRuns = readBairroRunsLayout(data, header.sections.bairroIds, header.rowCount, bairros.idWidth);
81
+ const localityRuns = readLocalityRunsLayout(data, header.sections.municipalityIds, header.rowCount);
82
+ const metadata = parseMetadata(mapped, header.sections.metadata);
83
+ this.mapped = mapped;
84
+ this.data = data;
85
+ this.header = header;
86
+ this.dictionaries = dictionaries;
87
+ this.bairros = bairros;
88
+ this.bairroRuns = bairroRuns;
89
+ this.localityRuns = localityRuns;
90
+ this.logradouroIdBits = integerBitWidth(dictionaries.logradouro.count);
91
+ this.metadataValue = Object.freeze(metadata);
92
+ this.bairroCache = Array.from({ length: dictionaries.bairro.count + 1 });
93
+ this.municipalityCache = Array.from({ length: header.municipalityCount + 1 });
94
+ }
95
+ catch (error) {
96
+ this.mapped = null;
97
+ this.data = null;
98
+ if (error instanceof DneBinaryDatabaseError) {
99
+ throw error;
100
+ }
101
+ throw new DneBinaryDatabaseFormatError('Unable to decode binary database', { cause: error });
102
+ }
103
+ }
104
+ /**
105
+ * Releases this reader's references to the mapping and decoded caches.
106
+ * Repeated calls are safe. Bun controls when the mapping is reclaimed; this method does not
107
+ * guarantee immediate unmapping. Metadata and row count remain available after closing.
108
+ */
109
+ close() {
110
+ this.bairroCache = [];
111
+ this.data = null;
112
+ this.mapped = null;
113
+ this.municipalityCache = [];
114
+ }
115
+ /**
116
+ * Returns the load metadata parsed when the reader was constructed.
117
+ * @returns The cached, frozen metadata object. Available after `close()`.
118
+ */
119
+ metadata() {
120
+ return this.metadataValue;
121
+ }
122
+ /**
123
+ * Looks up a CEP and decodes its address, including the originating locality indicators.
124
+ * @param cep - Eight ASCII digits or the form `NNNNN-NNN`; surrounding whitespace is not accepted.
125
+ * @returns An address with an eight-digit CEP, or `undefined` when the input is invalid or absent from the database.
126
+ * @throws {DneBinaryDatabaseClosedError} If called after `close()`, including for invalid CEP input.
127
+ */
128
+ queryCep(cep) {
129
+ this.assertOpen();
130
+ const index = this.findCepIndex(cep);
131
+ return index === -1 ? undefined : this.readRow(index, cep.replace('-', ''));
132
+ }
133
+ /**
134
+ * Resolves a municipality's name and UF by its IBGE code.
135
+ * @param municipioCodIbge - Seven-digit IBGE municipality code represented as an integer.
136
+ * @returns The municipality and UF, or undefined for an invalid or unknown code.
137
+ * @throws {DneBinaryDatabaseClosedError} If the reader is closed, including for invalid input.
138
+ */
139
+ queryMunicipality(municipioCodIbge) {
140
+ this.assertOpen();
141
+ if (!Number.isInteger(municipioCodIbge) || municipioCodIbge < 1_000_000 || municipioCodIbge > 9_999_999) {
142
+ return undefined;
143
+ }
144
+ const recordWidth = 3 + this.dictionaries.municipio.idWidth + this.dictionaries.uf.idWidth;
145
+ const offset = this.header.sections.municipalities.offset;
146
+ let low = 0;
147
+ let high = this.header.municipalityCount - 1;
148
+ while (low <= high) {
149
+ const middle = low + ((high - low) >>> 1);
150
+ const code = this.readPackedInteger(offset + middle * recordWidth, 3);
151
+ if (code < municipioCodIbge) {
152
+ low = middle + 1;
153
+ }
154
+ else if (code > municipioCodIbge) {
155
+ high = middle - 1;
156
+ }
157
+ else {
158
+ const { municipio, uf } = this.readMunicipality(middle + 1);
159
+ return { municipio, uf };
160
+ }
161
+ }
162
+ return undefined;
163
+ }
164
+ /**
165
+ * Lists the IBGE municipality codes stored for a federative unit.
166
+ * @param uf - Canonical uppercase Brazilian state abbreviation.
167
+ * @returns Unique codes in ascending order, or an empty array for an invalid or absent UF.
168
+ * @throws {DneBinaryDatabaseClosedError} If the reader is closed, including for invalid input.
169
+ */
170
+ queryMunicipalityCodesByUf(uf) {
171
+ this.assertOpen();
172
+ if (!Object.hasOwn(stateCodes, uf)) {
173
+ return [];
174
+ }
175
+ const minimum = stateCodes[uf] * 100_000;
176
+ const maximum = minimum + 100_000;
177
+ const recordWidth = 3 + this.dictionaries.municipio.idWidth + this.dictionaries.uf.idWidth;
178
+ const offset = this.header.sections.municipalities.offset;
179
+ let low = 0;
180
+ let high = this.header.municipalityCount;
181
+ while (low < high) {
182
+ const middle = low + ((high - low) >>> 1);
183
+ if (this.readPackedInteger(offset + middle * recordWidth, 3) < minimum) {
184
+ low = middle + 1;
185
+ }
186
+ else {
187
+ high = middle;
188
+ }
189
+ }
190
+ const codes = [];
191
+ for (let index = low; index < this.header.municipalityCount; index++) {
192
+ const code = this.readPackedInteger(offset + index * recordWidth, 3);
193
+ if (code >= maximum) {
194
+ break;
195
+ }
196
+ codes.push(code);
197
+ }
198
+ return codes;
199
+ }
200
+ /**
201
+ * Reads a neighborhood by its original DNE identifier, independent of duplicate names.
202
+ * @param neighborhoodId - Positive `BAI_NU` identifier.
203
+ * @returns The neighborhood, or undefined for an invalid or unknown identifier.
204
+ * @throws {DneBinaryDatabaseClosedError} If the reader is closed, including for invalid input.
205
+ */
206
+ queryNeighborhood(neighborhoodId) {
207
+ this.assertOpen();
208
+ const index = this.findNeighborhoodIndex(neighborhoodId);
209
+ return index === 0 ? undefined : this.readNeighborhood(index);
210
+ }
211
+ /**
212
+ * Resolves the actual neighborhood of a CEP, preserving the distinction from districts and villages.
213
+ * @param cep - Eight ASCII digits or `NNNNN-NNN`.
214
+ * @returns The neighborhood, or undefined for an invalid, unknown, or neighborhood-free CEP.
215
+ * @throws {DneBinaryDatabaseClosedError} If the reader is closed, including for invalid input.
216
+ */
217
+ queryNeighborhoodByCep(cep) {
218
+ this.assertOpen();
219
+ const row = this.findCepIndex(cep);
220
+ if (row === -1) {
221
+ return undefined;
222
+ }
223
+ const index = this.readNeighborhoodIndex(row);
224
+ return index === 0 ? undefined : this.readNeighborhood(index);
225
+ }
226
+ /**
227
+ * Reads a neighborhood's original inclusive CEP intervals without merging gaps.
228
+ * @param neighborhoodId - Positive `BAI_NU` identifier.
229
+ * @returns Intervals sorted by lower and upper bounds, or an empty array for an invalid, unknown, or rangeless neighborhood.
230
+ * @throws {DneBinaryDatabaseClosedError} If the reader is closed, including for invalid input.
231
+ */
232
+ queryNeighborhoodCepRanges(neighborhoodId) {
233
+ this.assertOpen();
234
+ const index = this.findNeighborhoodIndex(neighborhoodId);
235
+ if (index === 0) {
236
+ return [];
237
+ }
238
+ const { bairroFaixaOffsets: offsets, bairroFaixas: ranges } = this.header.sections;
239
+ const start = this.readUint32(offsets.offset + (index - 1) * 4);
240
+ const end = this.readUint32(offsets.offset + index * 4);
241
+ const result = [];
242
+ for (let row = start; row < end; row++) {
243
+ const initial = this.readUint32(ranges.offset + row * 8);
244
+ const final = this.readUint32(ranges.offset + row * 8 + 4);
245
+ result.push({ cep_inicial: String(initial).padStart(8, '0'), cep_final: String(final).padStart(8, '0') });
246
+ }
247
+ return result;
248
+ }
249
+ /**
250
+ * Returns the number of CEP records declared by the validated header.
251
+ * @returns The row count recorded at construction; available after `close()`.
252
+ */
253
+ rowCount() {
254
+ return this.header.rowCount;
255
+ }
256
+ assertOpen() {
257
+ if (this.data === null) {
258
+ throw new DneBinaryDatabaseClosedError();
259
+ }
260
+ }
261
+ findCepIndex(cep) {
262
+ const wanted = cepToU32(cep);
263
+ if (Number.isNaN(wanted)) {
264
+ return -1;
265
+ }
266
+ const prefix = Math.floor(wanted / 1_000);
267
+ const suffix = wanted % 1_000;
268
+ const prefixRegion = this.header.sections.cepPrefixOffsets;
269
+ const width = this.header.cepPrefixOffsetWidth;
270
+ let low = this.readPackedInteger(prefixRegion.offset + prefix * width, width);
271
+ const prefixEnd = this.readPackedInteger(prefixRegion.offset + (prefix + 1) * width, width);
272
+ let high = prefixEnd;
273
+ while (low < high) {
274
+ const middle = low + ((high - low) >>> 1);
275
+ const current = this.readPacked10(middle);
276
+ if (current < suffix) {
277
+ low = middle + 1;
278
+ }
279
+ else {
280
+ high = middle;
281
+ }
282
+ }
283
+ if (low >= prefixEnd || this.readPacked10(low) !== suffix) {
284
+ return -1;
285
+ }
286
+ return low;
287
+ }
288
+ findNeighborhoodIndex(neighborhoodId) {
289
+ if (!isBairroId(neighborhoodId)) {
290
+ return 0;
291
+ }
292
+ let low = 0;
293
+ let high = this.bairros.count;
294
+ while (low < high) {
295
+ const middle = low + ((high - low) >>> 1);
296
+ const id = this.readPackedInteger(this.bairros.recordsOffset + middle * this.bairros.recordWidth, this.bairros.originalIdWidth);
297
+ if (id < neighborhoodId) {
298
+ low = middle + 1;
299
+ }
300
+ else {
301
+ high = middle;
302
+ }
303
+ }
304
+ if (low === this.bairros.count) {
305
+ return 0;
306
+ }
307
+ const id = this.readPackedInteger(this.bairros.recordsOffset + low * this.bairros.recordWidth, this.bairros.originalIdWidth);
308
+ return id === neighborhoodId ? low + 1 : 0;
309
+ }
310
+ readNeighborhoodIndex(row) {
311
+ return readBairroRunIndex(this.data, this.bairroRuns, row);
312
+ }
313
+ readNeighborhood(index) {
314
+ const { originalIdWidth, localidadeIdWidth, recordsOffset, recordWidth } = this.bairros;
315
+ let offset = recordsOffset + (index - 1) * recordWidth;
316
+ const bairro_id = this.readPackedInteger(offset, originalIdWidth);
317
+ offset += originalIdWidth;
318
+ const localidade_id = this.readPackedInteger(offset, localidadeIdWidth);
319
+ offset += localidadeIdWidth;
320
+ const nome = this.readRequiredDictionaryString(this.dictionaries.bairro, this.readPackedInteger(offset, this.dictionaries.bairro.idWidth));
321
+ offset += this.dictionaries.bairro.idWidth;
322
+ const nome_abreviado = this.readDictionaryString(this.dictionaries.bairroAbreviado, this.readPackedInteger(offset, this.dictionaries.bairroAbreviado.idWidth));
323
+ offset += this.dictionaries.bairroAbreviado.idWidth;
324
+ const uf = this.readRequiredDictionaryString(this.dictionaries.uf, this.readPackedInteger(offset, this.dictionaries.uf.idWidth));
325
+ return { bairro_id, localidade_id, nome, nome_abreviado, uf };
326
+ }
327
+ readRow(index, cep) {
328
+ const sections = this.header.sections;
329
+ const run = findLocalityRun(this.data, this.localityRuns, index);
330
+ const municipalityId = this.readPackedInteger(this.localityRuns.idsOffset + run * this.header.municipalityIdWidth, this.header.municipalityIdWidth);
331
+ const municipality = this.readMunicipality(municipalityId);
332
+ const flags = this.data.getUint8(sections.localidadeFlags.offset + run);
333
+ const situacao = LOCALIDADE_SITUACOES[flags & 3];
334
+ const tipo = LOCALIDADE_TIPOS[flags >>> 2];
335
+ const bairroIndex = this.readNeighborhoodIndex(index);
336
+ const localidadeNomeId = this.readSparseId(sections.localidadeNomeBitmap, sections.localidadeNomeRanks, sections.localidadeNomeIds, index, this.dictionaries.bairro.idWidth);
337
+ const bairroNameId = bairroIndex === 0
338
+ ? localidadeNomeId
339
+ : this.readPackedInteger(this.bairros.recordsOffset + (bairroIndex - 1) * this.bairros.recordWidth
340
+ + this.bairros.originalIdWidth + this.bairros.localidadeIdWidth, this.dictionaries.bairro.idWidth);
341
+ return {
342
+ bairro: this.readCachedDictionaryString(this.dictionaries.bairro, bairroNameId, this.bairroCache),
343
+ cep,
344
+ complemento: this.readDictionaryString(this.dictionaries.complemento, this.readSparseId(sections.complementoBitmap, sections.complementoRanks, sections.complementoIds, index, this.dictionaries.complemento.idWidth)),
345
+ localidade_situacao: situacao,
346
+ localidade_tipo: tipo,
347
+ logradouro: this.readDictionaryString(this.dictionaries.logradouro, readPackedBits(this.data, sections.logradouroIds.offset, index, this.logradouroIdBits)),
348
+ municipio: municipality.municipio,
349
+ municipio_cod_ibge: municipality.codigoIbge,
350
+ nome: this.readDictionaryString(this.dictionaries.nome, this.readSparseId(sections.nomeBitmap, sections.nomeRanks, sections.nomeIds, index, this.dictionaries.nome.idWidth)),
351
+ uf: municipality.uf,
352
+ };
353
+ }
354
+ readMunicipality(id) {
355
+ const cached = this.municipalityCache[id];
356
+ if (cached) {
357
+ return cached;
358
+ }
359
+ const recordWidth = 3 + this.dictionaries.municipio.idWidth + this.dictionaries.uf.idWidth;
360
+ const offset = this.header.sections.municipalities.offset + (id - 1) * recordWidth;
361
+ const municipioId = this.readPackedInteger(offset + 3, this.dictionaries.municipio.idWidth);
362
+ const ufId = this.readPackedInteger(offset + 3 + this.dictionaries.municipio.idWidth, this.dictionaries.uf.idWidth);
363
+ const municipality = {
364
+ codigoIbge: this.readPackedInteger(offset, 3),
365
+ municipio: this.readRequiredDictionaryString(this.dictionaries.municipio, municipioId),
366
+ uf: this.readRequiredDictionaryString(this.dictionaries.uf, ufId),
367
+ };
368
+ this.municipalityCache[id] = municipality;
369
+ return municipality;
370
+ }
371
+ readSparseId(bitmap, ranks, ids, rowIndex, idWidth) {
372
+ const mapped = this.mapped;
373
+ const bitmapByteIndex = rowIndex >>> 3;
374
+ const bitmapByte = mapped[bitmap.offset + bitmapByteIndex];
375
+ const bitIndex = rowIndex & 7;
376
+ if ((bitmapByte & (1 << bitIndex)) === 0) {
377
+ return 0;
378
+ }
379
+ const rankBlock = rowIndex >>> SPARSE_RANK_SHIFT;
380
+ let denseIndex = this.readUint32(ranks.offset + rankBlock * 4);
381
+ const blockByteOffset = rankBlock * (SPARSE_RANK_ROWS >>> 3);
382
+ for (let offset = blockByteOffset; offset < bitmapByteIndex; offset++) {
383
+ denseIndex += popcount[mapped[bitmap.offset + offset]];
384
+ }
385
+ denseIndex += popcount[bitmapByte & ((1 << bitIndex) - 1)];
386
+ return this.readPackedInteger(ids.offset + denseIndex * idWidth, idWidth);
387
+ }
388
+ readDictionaryString(dictionary, id) {
389
+ if (id === 0) {
390
+ return null;
391
+ }
392
+ const mapped = this.mapped;
393
+ if (dictionary.codec === DICTIONARY_CODEC_FSST) {
394
+ return readTrustedFsstString(mapped, this.data, dictionary, id);
395
+ }
396
+ const index = id - 1;
397
+ const block = index >>> DICTIONARY_BLOCK_SHIFT;
398
+ const blockStart = block << DICTIONARY_BLOCK_SHIFT;
399
+ const relativeOffset = this.readUint32(dictionary.blockOffsetsOffset + block * 4);
400
+ let cursor = dictionary.suffixDataOffset + relativeOffset;
401
+ const decoded = this.decodeScratch;
402
+ let previousLength = 0;
403
+ for (let currentIndex = blockStart; currentIndex <= index; currentIndex++) {
404
+ const length = mapped[dictionary.lengthsOffset + currentIndex];
405
+ const prefixLength = mapped[dictionary.prefixesOffset + currentIndex];
406
+ const suffixLength = length - prefixLength;
407
+ decoded.set(mapped.subarray(cursor, cursor + suffixLength), prefixLength);
408
+ cursor += suffixLength;
409
+ previousLength = length;
410
+ }
411
+ return textDecoder.decode(decoded.subarray(0, previousLength));
412
+ }
413
+ readCachedDictionaryString(dictionary, id, cache) {
414
+ if (id === 0) {
415
+ return null;
416
+ }
417
+ const cached = cache[id];
418
+ if (cached !== undefined) {
419
+ return cached;
420
+ }
421
+ const value = this.readRequiredDictionaryString(dictionary, id);
422
+ cache[id] = value;
423
+ return value;
424
+ }
425
+ readRequiredDictionaryString(dictionary, id) {
426
+ return this.readDictionaryString(dictionary, id);
427
+ }
428
+ readPacked10(index) {
429
+ const mapped = this.mapped;
430
+ const region = this.header.sections.cepSuffixes;
431
+ const bitOffset = index * CEP_SUFFIX_BITS;
432
+ const byteIndex = bitOffset >>> 3;
433
+ const shift = bitOffset & 7;
434
+ const absoluteOffset = region.offset + byteIndex;
435
+ const value = mapped[absoluteOffset]
436
+ | (mapped[absoluteOffset + 1] << 8)
437
+ | (mapped[absoluteOffset + 2] << 16);
438
+ return (value >>> shift) & 0x3ff;
439
+ }
440
+ readPackedInteger(offset, width) {
441
+ return readPackedIntegerFromData(this.data, offset, width);
442
+ }
443
+ readUint32(offset) {
444
+ return this.data.getUint32(offset, true);
445
+ }
446
+ }
447
+ /**
448
+ * Opens a binary database, reads its load metadata, and closes the temporary reader.
449
+ * @param path - Path to an existing binary database file.
450
+ * @returns Frozen metadata parsed from the file at open time.
451
+ * @throws {DneBinaryDatabaseIOError} If the file cannot be mapped.
452
+ * @throws {DneBinaryDatabaseVersionError} If the binary version is unsupported.
453
+ * @throws {DneBinaryDatabaseFormatError} If the minimum header, file size, or SHA-256 checksum is invalid.
454
+ */
455
+ export async function readBinaryDatabaseMetadata(path) {
456
+ const reader = new DneBinaryDatabaseReader(path);
457
+ try {
458
+ return reader.metadata();
459
+ }
460
+ finally {
461
+ reader.close();
462
+ }
463
+ }
464
+ function verifyHeader(data) {
465
+ if (data.byteLength < BINARY_DATABASE_HEADER_SIZE + BINARY_DATABASE_CHECKSUM_SIZE) {
466
+ throw new DneBinaryDatabaseFormatError('Binary database header is truncated');
467
+ }
468
+ for (let index = 0; index < MAGIC.length; index++) {
469
+ if (data.getUint8(index) !== MAGIC[index]) {
470
+ throw new DneBinaryDatabaseFormatError('Invalid binary database magic');
471
+ }
472
+ }
473
+ const version = data.getUint16(8, true);
474
+ if (version !== BINARY_DATABASE_VERSION) {
475
+ throw new DneBinaryDatabaseVersionError(version, BINARY_DATABASE_VERSION);
476
+ }
477
+ if (data.getUint16(10, true) !== BINARY_DATABASE_HEADER_SIZE) {
478
+ throw new DneBinaryDatabaseFormatError('Unsupported binary database header size');
479
+ }
480
+ if (data.getUint8(22) !== SPARSE_RANK_SHIFT || data.getUint8(23) !== DICTIONARY_BLOCK_SHIFT) {
481
+ throw new DneBinaryDatabaseFormatError('Unsupported binary database block layout');
482
+ }
483
+ if (data.getUint16(24, true) !== SECTION_NAMES.length) {
484
+ throw new DneBinaryDatabaseFormatError('Unsupported binary database section table');
485
+ }
486
+ if (data.getUint32(16, true) !== data.byteLength) {
487
+ throw new DneBinaryDatabaseFormatError(`Binary database size mismatch: header=${data.getUint32(16, true)}, actual=${data.byteLength}`);
488
+ }
489
+ }
490
+ function readHeader(data) {
491
+ const sections = {};
492
+ for (const [index, name,] of SECTION_NAMES.entries()) {
493
+ const offset = SECTION_TABLE_OFFSET + index * 8;
494
+ sections[name] = {
495
+ length: data.getUint32(offset + 4, true),
496
+ offset: data.getUint32(offset, true),
497
+ };
498
+ }
499
+ return {
500
+ cepPrefixOffsetWidth: data.getUint8(20),
501
+ fileSize: data.getUint32(16, true),
502
+ municipalityCount: data.getUint32(28, true),
503
+ municipalityIdWidth: data.getUint8(21),
504
+ rowCount: data.getUint32(12, true),
505
+ sections,
506
+ };
507
+ }
508
+ function readDictionaries(data, header) {
509
+ return {
510
+ bairro: readDictionary(data, header.sections.bairroDictionary),
511
+ bairroAbreviado: readDictionary(data, header.sections.bairroAbreviadoDictionary),
512
+ complemento: readDictionary(data, header.sections.complementoDictionary),
513
+ logradouro: readDictionary(data, header.sections.logradouroDictionary),
514
+ municipio: readDictionary(data, header.sections.municipioDictionary),
515
+ nome: readDictionary(data, header.sections.nomeDictionary),
516
+ uf: readDictionary(data, header.sections.ufDictionary),
517
+ };
518
+ }
519
+ function readDictionary(data, region) {
520
+ const count = data.getUint32(region.offset, true);
521
+ const prefixesOffset = region.offset + data.getUint32(region.offset + 16, true);
522
+ return {
523
+ blockCount: data.getUint32(region.offset + 4, true),
524
+ blockOffsetsOffset: region.offset + data.getUint32(region.offset + 8, true),
525
+ count,
526
+ codec: data.getUint8(region.offset + 30),
527
+ idWidth: data.getUint8(region.offset + 28),
528
+ lengthsOffset: region.offset + data.getUint32(region.offset + 12, true),
529
+ lengthWidth: data.getUint8(region.offset + 31) === 2 ? 2 : 1,
530
+ prefixesOffset,
531
+ region,
532
+ suffixDataLength: data.getUint32(region.offset + 24, true),
533
+ suffixDataOffset: region.offset + data.getUint32(region.offset + 20, true),
534
+ symbolsOffset: prefixesOffset + count,
535
+ };
536
+ }
537
+ function readNeighborhoods(data, header, dictionaries) {
538
+ const region = header.sections.bairros;
539
+ const count = data.getUint32(region.offset, true);
540
+ const originalIdWidth = data.getUint8(region.offset + 4);
541
+ const localidadeIdWidth = data.getUint8(region.offset + 5);
542
+ const recordWidth = originalIdWidth + localidadeIdWidth + dictionaries.bairro.idWidth
543
+ + dictionaries.bairroAbreviado.idWidth + dictionaries.uf.idWidth;
544
+ return {
545
+ count,
546
+ idWidth: integerByteWidth(count),
547
+ originalIdWidth,
548
+ localidadeIdWidth,
549
+ recordsOffset: region.offset + BINARY_BAIRRO_HEADER_SIZE,
550
+ recordWidth,
551
+ };
552
+ }
553
+ function parseMetadata(mapped, region) {
554
+ return JSON.parse(textDecoder.decode(mapped.subarray(region.offset, region.offset + region.length)));
555
+ }
556
+ //# sourceMappingURL=binary-db-reader.js.map