@konstit/dne 0.1.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +85 -352
- package/dist/address-search-index.d.ts +34 -0
- package/dist/address-search-index.js +326 -0
- package/dist/address-search-index.js.map +1 -0
- package/dist/address-search-pool-errors.d.ts +15 -0
- package/dist/address-search-pool-errors.js +25 -0
- package/dist/address-search-pool-errors.js.map +1 -0
- package/dist/address-search-pool.d.ts +40 -0
- package/dist/address-search-pool.js +215 -0
- package/dist/address-search-pool.js.map +1 -0
- package/dist/address-search-rank.d.ts +5 -0
- package/dist/address-search-rank.js +89 -0
- package/dist/address-search-rank.js.map +1 -0
- package/dist/address-search-text.d.ts +6 -0
- package/dist/address-search-text.js +16 -0
- package/dist/address-search-text.js.map +1 -0
- package/dist/address-search-worker-runtime.d.ts +41 -0
- package/dist/address-search-worker-runtime.js +38 -0
- package/dist/address-search-worker-runtime.js.map +1 -0
- package/dist/address-search-worker-source.d.ts +2 -0
- package/dist/address-search-worker-source.js +5 -0
- package/dist/address-search-worker-source.js.map +1 -0
- package/dist/address-search.d.ts +31 -0
- package/dist/address-search.js +152 -0
- package/dist/address-search.js.map +1 -0
- package/dist/bairro-runs.d.ts +20 -0
- package/dist/bairro-runs.js +202 -0
- package/dist/bairro-runs.js.map +1 -0
- package/dist/binary-db-errors.d.ts +1 -1
- package/dist/binary-db-errors.js +1 -1
- package/dist/binary-db-errors.js.map +1 -1
- package/dist/binary-db-format.d.ts +10 -2
- package/dist/binary-db-format.js +9 -1
- package/dist/binary-db-format.js.map +1 -1
- package/dist/binary-db-integrity.d.ts +4 -0
- package/dist/binary-db-integrity.js +20 -0
- package/dist/binary-db-integrity.js.map +1 -0
- package/dist/binary-db-reader.d.ts +46 -28
- package/dist/binary-db-reader.js +237 -360
- package/dist/binary-db-reader.js.map +1 -1
- package/dist/binary-db-validator.d.ts +13 -0
- package/dist/binary-db-validator.js +709 -0
- package/dist/binary-db-validator.js.map +1 -0
- package/dist/chunks/dynamic-completion-wbp85hh9-cytdw6ns.js +7 -0
- package/dist/chunks/dynamic-completion-wbp85hh9-cytdw6ns.js.map +10 -0
- package/dist/chunks/index-338dn00y.js +18 -0
- package/dist/chunks/index-338dn00y.js.map +10 -0
- package/dist/expand.d.ts +8 -0
- package/dist/expand.js +1484 -0
- package/dist/expand.js.map +1 -0
- package/dist/fsst.d.ts +18 -0
- package/dist/fsst.js +117 -0
- package/dist/fsst.js.map +1 -0
- package/dist/index.js +48 -48
- package/dist/index.js.map +30 -18
- package/dist/library.d.ts +9 -2
- package/dist/library.js +9 -2
- package/dist/library.js.map +1 -1
- package/dist/locality-runs.d.ts +18 -0
- package/dist/locality-runs.js +108 -0
- package/dist/locality-runs.js.map +1 -0
- package/dist/packed-bits.d.ts +6 -0
- package/dist/packed-bits.js +41 -0
- package/dist/packed-bits.js.map +1 -0
- package/dist/settings.d.ts +0 -2
- package/dist/settings.js +0 -2
- package/dist/settings.js.map +1 -1
- package/dist/shared-file.d.ts +2 -0
- package/dist/shared-file.js +35 -0
- package/dist/shared-file.js.map +1 -0
- package/dist/sqlite-db-reader.d.ts +13 -4
- package/dist/sqlite-db-reader.js +39 -17
- package/dist/sqlite-db-reader.js.map +1 -1
- package/dist/types.d.ts +29 -4
- package/dist/types.js +73 -4
- package/dist/types.js.map +1 -1
- package/package.json +13 -10
- package/data/dne.bin +0 -0
- package/dist/chunks/dynamic-completion-403da357-4jc4w04x.js +0 -7
- package/dist/chunks/dynamic-completion-403da357-4jc4w04x.js.map +0 -10
- package/dist/chunks/index-s0h4vdva.js +0 -17
- package/dist/chunks/index-s0h4vdva.js.map +0 -10
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { type DneBairro, type DneFaixaCep } from './bairro.ts';
|
|
2
|
-
import { type DneRow, type LoadMetadata } from './types.ts';
|
|
2
|
+
import { type DneRow, type LoadMetadata, type UF } from './types.ts';
|
|
3
3
|
/** Error classes and discriminants used by this module's public operations. */
|
|
4
4
|
export { DneBinaryDatabaseClosedError, DneBinaryDatabaseError, type DneBinaryDatabaseErrorCode, DneBinaryDatabaseFormatError, DneBinaryDatabaseIOError, DneBinaryDatabaseVersionError, } from './binary-db-errors.ts';
|
|
5
5
|
/** Header size and format version accepted by this reader. */
|
|
@@ -14,55 +14,73 @@ export type { DneBairro, DneFaixaCep } from './bairro.ts';
|
|
|
14
14
|
*/
|
|
15
15
|
export declare function isBinaryDatabase(path: string): Promise<boolean>;
|
|
16
16
|
/**
|
|
17
|
-
* Provides synchronous, read-only CEP lookups over a
|
|
17
|
+
* Provides synchronous, read-only CEP lookups over a physical or embedded DNE binary database.
|
|
18
18
|
*
|
|
19
|
-
* Construction
|
|
20
|
-
*
|
|
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
|
+
* The database is loaded as a snapshot at construction. Call `close()` when finished.
|
|
21
22
|
* All operational errors extend {@link DneBinaryDatabaseError}; invalid or absent CEPs return `undefined`.
|
|
22
23
|
*/
|
|
23
|
-
export declare class DneBinaryDatabaseReader {
|
|
24
|
+
export declare class DneBinaryDatabaseReader implements Disposable {
|
|
24
25
|
private bairroCache;
|
|
25
26
|
private data;
|
|
26
27
|
private decodeScratch;
|
|
27
28
|
private dictionaries;
|
|
28
29
|
private bairros;
|
|
30
|
+
private bairroRuns;
|
|
31
|
+
private localityRuns;
|
|
32
|
+
private logradouroIdBits;
|
|
29
33
|
private header;
|
|
30
|
-
private
|
|
31
|
-
private metadataValue;
|
|
34
|
+
private bytes;
|
|
35
|
+
private readonly metadataValue;
|
|
32
36
|
private municipalityCache;
|
|
33
37
|
/**
|
|
34
|
-
*
|
|
35
|
-
* @param databasePath -
|
|
36
|
-
* @throws {DneBinaryDatabaseIOError} If the file cannot be
|
|
38
|
+
* Reads and verifies a complete binary database from a physical file or embedded asset.
|
|
39
|
+
* @param databasePath - Path to an existing binary database.
|
|
40
|
+
* @throws {DneBinaryDatabaseIOError} If the file cannot be resolved or read.
|
|
37
41
|
* @throws {DneBinaryDatabaseVersionError} If the declared format version is unsupported.
|
|
38
|
-
* @throws {DneBinaryDatabaseFormatError} If the header,
|
|
42
|
+
* @throws {DneBinaryDatabaseFormatError} If the minimum header, file size, or SHA-256 checksum is invalid.
|
|
39
43
|
*/
|
|
40
|
-
constructor(databasePath
|
|
44
|
+
constructor(databasePath: string);
|
|
41
45
|
/**
|
|
42
|
-
* Releases this reader's references to the
|
|
43
|
-
* Repeated calls are safe. Bun controls when the
|
|
44
|
-
*
|
|
46
|
+
* Releases this reader's references to the database bytes and decoded caches.
|
|
47
|
+
* Repeated calls are safe. Bun controls when the bytes are reclaimed by garbage collection.
|
|
48
|
+
* Metadata and row count remain available after closing.
|
|
45
49
|
*/
|
|
46
50
|
close(): void;
|
|
51
|
+
/** Calls close() when a using declaration leaves its scope. Repeated calls are safe. */
|
|
52
|
+
[Symbol.dispose](): void;
|
|
47
53
|
/**
|
|
48
54
|
* Returns the load metadata parsed when the reader was constructed.
|
|
49
|
-
* @returns The cached metadata object
|
|
55
|
+
* @returns The cached, frozen metadata object. Available after `close()`.
|
|
50
56
|
*/
|
|
51
|
-
metadata(): LoadMetadata
|
|
57
|
+
metadata(): Readonly<LoadMetadata>;
|
|
52
58
|
/**
|
|
53
59
|
* Looks up a CEP and decodes its address, including the originating locality indicators.
|
|
54
60
|
* @param cep - Eight ASCII digits or the form `NNNNN-NNN`; surrounding whitespace is not accepted.
|
|
55
61
|
* @returns An address with an eight-digit CEP, or `undefined` when the input is invalid or absent from the database.
|
|
56
62
|
* @throws {DneBinaryDatabaseClosedError} If called after `close()`, including for invalid CEP input.
|
|
57
|
-
* @throws {DneBinaryDatabaseFormatError} If the lookup encounters invalid indexes or record data.
|
|
58
63
|
*/
|
|
59
64
|
queryCep(cep: string): DneRow | undefined;
|
|
65
|
+
/**
|
|
66
|
+
* Resolves a municipality's name and UF by its IBGE code.
|
|
67
|
+
* @param municipioCodIbge - Seven-digit IBGE municipality code represented as an integer.
|
|
68
|
+
* @returns The municipality and UF, or undefined for an invalid or unknown code.
|
|
69
|
+
* @throws {DneBinaryDatabaseClosedError} If the reader is closed, including for invalid input.
|
|
70
|
+
*/
|
|
71
|
+
queryMunicipality(municipioCodIbge: number): Pick<DneRow, 'municipio' | 'uf'> | undefined;
|
|
72
|
+
/**
|
|
73
|
+
* Lists the IBGE municipality codes stored for a federative unit.
|
|
74
|
+
* @param uf - Canonical uppercase Brazilian state abbreviation.
|
|
75
|
+
* @returns Unique codes in ascending order, or an empty array for an invalid or absent UF.
|
|
76
|
+
* @throws {DneBinaryDatabaseClosedError} If the reader is closed, including for invalid input.
|
|
77
|
+
*/
|
|
78
|
+
queryMunicipalityCodesByUf(uf: UF): number[];
|
|
60
79
|
/**
|
|
61
80
|
* Reads a neighborhood by its original DNE identifier, independent of duplicate names.
|
|
62
81
|
* @param neighborhoodId - Positive `BAI_NU` identifier.
|
|
63
82
|
* @returns The neighborhood, or undefined for an invalid or unknown identifier.
|
|
64
83
|
* @throws {DneBinaryDatabaseClosedError} If the reader is closed, including for invalid input.
|
|
65
|
-
* @throws {DneBinaryDatabaseFormatError} If an index, record, or string cannot be decoded.
|
|
66
84
|
*/
|
|
67
85
|
queryNeighborhood(neighborhoodId: number): DneBairro | undefined;
|
|
68
86
|
/**
|
|
@@ -70,7 +88,6 @@ export declare class DneBinaryDatabaseReader {
|
|
|
70
88
|
* @param cep - Eight ASCII digits or `NNNNN-NNN`.
|
|
71
89
|
* @returns The neighborhood, or undefined for an invalid, unknown, or neighborhood-free CEP.
|
|
72
90
|
* @throws {DneBinaryDatabaseClosedError} If the reader is closed, including for invalid input.
|
|
73
|
-
* @throws {DneBinaryDatabaseFormatError} If the CEP or neighborhood data is invalid.
|
|
74
91
|
*/
|
|
75
92
|
queryNeighborhoodByCep(cep: string): DneBairro | undefined;
|
|
76
93
|
/**
|
|
@@ -78,7 +95,6 @@ export declare class DneBinaryDatabaseReader {
|
|
|
78
95
|
* @param neighborhoodId - Positive `BAI_NU` identifier.
|
|
79
96
|
* @returns Intervals sorted by lower and upper bounds, or an empty array for an invalid, unknown, or rangeless neighborhood.
|
|
80
97
|
* @throws {DneBinaryDatabaseClosedError} If the reader is closed, including for invalid input.
|
|
81
|
-
* @throws {DneBinaryDatabaseFormatError} If the interval directory or bounds are invalid.
|
|
82
98
|
*/
|
|
83
99
|
queryNeighborhoodCepRanges(neighborhoodId: number): DneFaixaCep[];
|
|
84
100
|
/**
|
|
@@ -86,7 +102,11 @@ export declare class DneBinaryDatabaseReader {
|
|
|
86
102
|
* @returns The row count recorded at construction; available after `close()`.
|
|
87
103
|
*/
|
|
88
104
|
rowCount(): number;
|
|
89
|
-
|
|
105
|
+
/** Returns the verified database SHA-256 used to bind optional indexes to this snapshot. */
|
|
106
|
+
checksum(): string;
|
|
107
|
+
/** Streams addresses in CEP order. Advancing the iterator after close() throws. */
|
|
108
|
+
entries(): IterableIterator<DneRow>;
|
|
109
|
+
private assertOpen;
|
|
90
110
|
private findCepIndex;
|
|
91
111
|
private findNeighborhoodIndex;
|
|
92
112
|
private readNeighborhoodIndex;
|
|
@@ -100,15 +120,13 @@ export declare class DneBinaryDatabaseReader {
|
|
|
100
120
|
private readPacked10;
|
|
101
121
|
private readPackedInteger;
|
|
102
122
|
private readUint32;
|
|
103
|
-
private requireData;
|
|
104
|
-
private requireMapped;
|
|
105
123
|
}
|
|
106
124
|
/**
|
|
107
125
|
* Opens a binary database, reads its load metadata, and closes the temporary reader.
|
|
108
126
|
* @param path - Path to an existing binary database file.
|
|
109
|
-
* @returns
|
|
110
|
-
* @throws {DneBinaryDatabaseIOError} If the file cannot be
|
|
127
|
+
* @returns Frozen metadata parsed from the file at open time.
|
|
128
|
+
* @throws {DneBinaryDatabaseIOError} If the file cannot be read.
|
|
111
129
|
* @throws {DneBinaryDatabaseVersionError} If the binary version is unsupported.
|
|
112
|
-
* @throws {DneBinaryDatabaseFormatError} If the file
|
|
130
|
+
* @throws {DneBinaryDatabaseFormatError} If the minimum header, file size, or SHA-256 checksum is invalid.
|
|
113
131
|
*/
|
|
114
|
-
export declare function readBinaryDatabaseMetadata(path: string): Promise<LoadMetadata
|
|
132
|
+
export declare function readBinaryDatabaseMetadata(path: string): Promise<Readonly<LoadMetadata>>;
|