@ferrybig/cgeodata-reader 0.0.0-stage → 0.1.1

package/dist/reader.js

@@ -0,0 +1,1132 @@
+import { ByteBudgetCache } from "./cache.js";
+import { cellBoundingBox, chunkBoundingBox, } from "./cellBounds.js";
+import { MAX_SUPPORTED_DEPTH, parseChunk } from "./chunk.js";
+import { readHeaderAndDirectory } from "./container.js";
+import { CGeoDataError, CGeoDataFormatError, CGeoDataIndexMismatchError, CGeoDataUnsupportedError, } from "./errors.js";
+import { inflateBlock, streamInflater } from "./inflate.js";
+import { computeLocateCell, decodeLocateEntry, LocateIndex, locateEntryWidth, } from "./locateIndex.js";
+import { mortonDecode, mortonEncode, shiftRight } from "./morton.js";
+import { largestIndexWithPrefixAtMost, parsePlaceTable, readNameBlock, resolveIdentifier, } from "./placeTable.js";
+import { compareAreaRelevance, compareRelevance, contextQuality, foldDiacritics, parseQualifiedQuery, placeMatchQuality, prepareNeedle, regionRankArea, } from "./relevance.js";
+import { RELEVANCE_AREA, RELEVANCE_PLAIN, SearchIndex } from "./searchIndex.js";
+import { toSource } from "./source.js";
+import { TurnQueue } from "./turns.js";
+/** `OpenOptions.cacheBytes` when not given. */
+export const DEFAULT_CACHE_BYTES = 64 * 2 ** 20;
+/**
+ * A CGEODATA file opened for reading: answers which country, region and
+ * city a point lies in (`query`, `lookup`), what a place is called and
+ * where it sits in the hierarchy (`place`, `placeIds`), which places
+ * match a name (`search`), and where a place is (`locate`).
+ *
+ * Opening reads only the header, directory and place counts; each lookup
+ * reads and decodes the one chunk its point lies in, which then stays
+ * cached (`OpenOptions.cacheBytes`).
+ *
+ * @example
+ * ```ts
+ * // Node.js
+ * import { openFile } from "@ferrybig/cgeodata-reader/node";
+ * const reader = await openFile("world.bin");
+ *
+ * // Anywhere else
+ * import { CGeoDataReader } from "@ferrybig/cgeodata-reader";
+ * const reader = await CGeoDataReader.open(await (await fetch(url)).arrayBuffer());
+ *
+ * const { city, region, country } = await reader.query(52.0799, 4.3113);
+ * city?.internationalName; // "The Hague"
+ * ```
+ */
+export class CGeoDataReader {
+    /** Decoded chunks (keyed by chunk index) and name blocks (keyed by
+     * `-1 - blockIndex`) under one byte budget. */
+    cache;
+    /** Loads in flight, under the same keys as `cache`, so concurrent
+     * lookups in one chunk decode it once. */
+    loading = new Map();
+    /** The chunk the last lookup used, held outside `cache`: lookups close
+     * together (a tile's samples) mostly land in the same chunk, and this
+     * answers those without touching the LRU's bookkeeping. */
+    lastChunkIndex = -1;
+    lastChunk;
+    /** Decodes take turns, one per macrotask; see `TurnQueue`. */
+    decodes = new TurnQueue();
+    /** The full-precision cell of the point `gridCell()` last placed; read
+     * right after, in the same synchronous run. */
+    gx = 0;
+    gy = 0;
+    search_;
+    locate_;
+    /** Rank areas of the regions searches have matched so far (Appendix
+     * B.5.1), -1 where not yet known, for the area bytes they came from. */
+    rankAreas;
+    placeTableChecksumPromise;
+    prefixChecksumPromise;
+    source;
+    inflater;
+    /** The file's header (Section 5), including its `attribution`. */
+    header;
+    /** The file's directory (Section 6): where each chunk is. */
+    directory;
+    placeTable;
+    constructor(source, header, directory, placeTable, cacheBytes, options) {
+        this.cache = new ByteBudgetCache(cacheBytes);
+        this.source = source;
+        this.inflater = options.inflater ?? streamInflater;
+        this.header = header;
+        this.directory = directory;
+        this.placeTable = placeTable;
+        this.search_ = pendingSlot(options.searchIndex);
+        this.locate_ = pendingSlot(options.locateIndex);
+    }
+    /**
+     * Opens a CGEODATA file: reads and validates its header, directory and
+     * the uncompressed part of its place table (Sections 5-7.2), and
+     * nothing else -- chunks and names are read on first use. The reader
+     * takes ownership of `input`, if it's a `ByteSource`: `close()` closes
+     * it, as does a failed open.
+     */
+    static async open(input, options = {}) {
+        const { cacheBytes = DEFAULT_CACHE_BYTES } = options;
+        if (!(cacheBytes >= 0)) {
+            throw new RangeError(`cacheBytes must be a non-negative number, not ${cacheBytes}`);
+        }
+        const source = toSource(input);
+        try {
+            const { header, directory } = await readHeaderAndDirectory(source);
+            if (header.maxDepth > MAX_SUPPORTED_DEPTH) {
+                throw new CGeoDataUnsupportedError(`max_depth ${header.maxDepth} is past the ${MAX_SUPPORTED_DEPTH} this reader supports: rebuild the file with a bigger chunk grid instead`);
+            }
+            const placeTable = await parsePlaceTable(source, directory.placeTableStart, directory.placeTableLength, header.keyframeExp);
+            return new CGeoDataReader(source, header, directory, placeTable, cacheBytes, options);
+        }
+        catch (error) {
+            await source.close?.();
+            throw error;
+        }
+    }
+    /** Closes the source, and any index this reader opened itself. */
+    async close() {
+        await this.useSearchIndex(undefined);
+        await this.useLocateIndex(undefined);
+        this.cache.clear();
+        this.lastChunk = undefined;
+        this.lastChunkIndex = -1;
+        await this.source.close?.();
+    }
+    /** How many countries, regions and cities the file has. */
+    get placeCounts() {
+        const { countryCount, totalRegions, totalCities } = this.placeTable;
+        return {
+            countries: countryCount,
+            regions: totalRegions,
+            cities: totalCities,
+        };
+    }
+    /**
+     * The country, region and city a point lies in: Section 9's lookup
+     * procedure (`lookup()`) with the names resolved (`place()`). Rejects
+     * with a `RangeError` for a latitude outside [-90, 90) or a longitude
+     * outside [-180, 180).
+     *
+     * @example
+     * ```ts
+     * const result = await reader.query(35.6762, 139.6503);
+     * result.city?.localName;         // "杉並区"
+     * result.city?.internationalName; // "Suginami"
+     * result.country?.internationalName; // "Japan"
+     * ```
+     */
+    async query(lat, lon) {
+        const result = await this.lookup(lat, lon);
+        if (result.placeId === null) {
+            return { ...result, country: null, region: null, city: null };
+        }
+        const { country, region, city } = await this.place(result.placeId);
+        return { ...result, country, region, city };
+    }
+    /**
+     * Section 9's lookup procedure: the place a point lies in, as an id, and
+     * the cell the answer holds for. Reads and decodes the point's chunk if
+     * it isn't cached; resolve the id with `place()` or `placeIds()`.
+     */
+    async lookup(lat, lon) {
+        const chunkIndex = this.gridCell(lat, lon);
+        let chunk = this.loadedChunk(chunkIndex);
+        if (chunk === undefined) {
+            chunk = await this.loadChunk(chunkIndex, true);
+            this.gridCell(lat, lon); // another lookup may have run meanwhile
+        }
+        return this.resolve(chunkIndex, chunk);
+    }
+    /**
+     * `lookup()` answered from memory only: the same result when the
+     * point's chunk is already decoded, undefined when answering would
+     * need a read. For callers doing many lookups close together, which
+     * mostly hit the same few chunks:
+     *
+     * ```ts
+     * const result = reader.lookupCached(lat, lon) ?? (await reader.lookup(lat, lon));
+     * ```
+     *
+     * waits only for the lookups that actually read something.
+     */
+    lookupCached(lat, lon) {
+        const chunkIndex = this.gridCell(lat, lon);
+        const chunk = this.loadedChunk(chunkIndex);
+        return chunk === undefined ? undefined : this.resolve(chunkIndex, chunk);
+    }
+    /** The index of the chunk a point lies in (Section 6.1). */
+    chunkIndexAt(lat, lon) {
+        return this.gridCell(lat, lon);
+    }
+    /** Validates a point and places it on the full-precision grid
+     * (`this.gx`, `this.gy`), returning its chunk's index. */
+    gridCell(lat, lon) {
+        if (!(lat >= -90 && lat < 90)) {
+            throw new RangeError(`latitude ${lat} is outside the valid range [-90, 90)`);
+        }
+        if (!(lon >= -180 && lon < 180)) {
+            throw new RangeError(`longitude ${lon} is outside the valid range [-180, 180)`);
+        }
+        const { width: W, height: H, maxDepth: D } = this.header;
+        const NX = W * 2 ** D;
+        const NY = H * 2 ** D;
+        const gx = Math.floor(((lon + 180) / 360) * NX);
+        const gy = Math.floor(((lat + 90) / 180) * NY);
+        this.gx = Math.min(Math.max(gx, 0), NX - 1);
+        this.gy = Math.min(Math.max(gy, 0), NY - 1);
+        return Math.floor(this.gy / 2 ** D) * W + Math.floor(this.gx / 2 ** D);
+    }
+    /** Section 9 steps 5-8 for the point `gridCell()` just placed, in its
+     * (decoded, or null for empty) chunk. */
+    resolve(chunkIndex, chunk) {
+        const { width: W, height: H, maxDepth: D } = this.header;
+        const cellsPerChunkSide = 2 ** D;
+        const c = chunkIndex % W;
+        const r = Math.floor(chunkIndex / W);
+        const x = this.gx - c * cellsPerChunkSide;
+        const y = this.gy - r * cellsPerChunkSide;
+        const chunkBox = chunkBoundingBox(c, r, W, H);
+        if (!chunk)
+            return unknownResult(chunkBox, chunkIndex); // whole chunk is empty
+        const q = mortonEncode(x, y, D);
+        const j = bisectRightMinusOne(chunk.codes, q);
+        // Neither of these two "no record covers this" cases can recover the
+        // gap's true extent without redoing the encoder's own subdivision
+        // work, so fall back to the single finest cell around the query point.
+        if (j < 0)
+            return unknownResult(cellBoundingBox(chunkBox, x, y, D), chunkIndex);
+        const depth = chunk.depths[j];
+        const shift = 2 * (D - depth);
+        const code = chunk.codes[j];
+        if (shiftRight(q, shift) !== shiftRight(code, shift)) {
+            // gap between records
+            return unknownResult(cellBoundingBox(chunkBox, x, y, D), chunkIndex);
+        }
+        // A real record matched: recover its exact cell (Section 8.1) for a
+        // tight, correct bounding box, whether or not it resolves to a place.
+        const matchedCellBox = this.recordBoundingBox(chunkBox, code, depth);
+        const k = chunk.paletteIndices[j];
+        if (k === 0)
+            return unknownResult(matchedCellBox, chunkIndex);
+        return {
+            placeId: chunk.palette[k - 1],
+            boundingBox: matchedCellBox,
+            chunkIndex,
+        };
+    }
+    /** The names of one place by global id, without resolving its ancestors.
+     * Cheaper than `place()` when only the names are needed. */
+    async placeNames(id) {
+        this.checkPlaceId(id);
+        return this.loadedNames(id) ?? (await this.loadNames(id));
+    }
+    /** FNV-1a 64-bit hash of the place table bytes, as defined by
+     * binary-format.md Section B.6. Used to bind a search index to its source. */
+    placeTableChecksum() {
+        this.placeTableChecksumPromise ??= (async () => {
+            const { placeTableStart, placeTableLength } = this.directory;
+            return fnv1a64(await this.source.read(placeTableStart, placeTableLength));
+        })();
+        return this.placeTableChecksumPromise;
+    }
+    /** FNV-1a 64-bit hash of everything before the first chunk -- header,
+     * directory and place table -- as defined by binary-format.md Section
+     * C.4. Binds a locate index to its source: the chunk lengths it covers
+     * change whenever the chunks do. */
+    prefixChecksum() {
+        this.prefixChecksumPromise ??= (async () => {
+            const { placeTableStart, placeTableLength } = this.directory;
+            return fnv1a64(await this.source.read(0, placeTableStart + placeTableLength));
+        })();
+        return this.prefixChecksumPromise;
+    }
+    /**
+     * Attaches a text search index (Appendix B, built by `buildSearchIndex`
+     * / `cgeodata build-search-index`) so `search()` only checks the places
+     * the index says could match instead of every place. Results are
+     * identical with or without it -- only the speed differs.
+     *
+     * Takes the index's file (as for `open()`; read on demand) or an open
+     * `SearchIndex` (which the caller keeps ownership of), or undefined to
+     * search without one. Replaces `OpenOptions.searchIndex`. Rejects with
+     * a `CGeoDataIndexMismatchError` if it was built from a different file.
+     */
+    async useSearchIndex(index) {
+        await this.attach(this.search_, index, SearchIndex.open, (opened) => this.checkSearchIndex(opened));
+    }
+    /** Whether `search()` will use an index. Reads (and validates) the one
+     * from `OpenOptions.searchIndex` if that hasn't happened yet. */
+    async hasSearchIndex() {
+        return (await this.activeSearchIndex()) !== undefined;
+    }
+    /** The attached search index, opening `OpenOptions.searchIndex` on
+     * first use. One that's there but unusable (stale, corrupt) rejects on
+     * every call rather than silently falling back to a linear scan. */
+    activeSearchIndex() {
+        return this.activate(this.search_, "search", (index) => this.useSearchIndex(index));
+    }
+    async checkSearchIndex(index) {
+        // An index ranked by area depends on the chunks too (Section B.8).
+        const checksum = index.relevanceRule === RELEVANCE_AREA
+            ? await this.prefixChecksum()
+            : await this.placeTableChecksum();
+        if (index.sourceChecksum !== checksum) {
+            throw new CGeoDataIndexMismatchError("search index was built from a different .bin file (checksum mismatch); rebuild it with build-search-index");
+        }
+        if (index.placeCount !== this.placeTable.totalPlaces) {
+            throw new CGeoDataIndexMismatchError(`search index covers ${index.placeCount} places, but this file has ${this.placeTable.totalPlaces}`);
+        }
+    }
+    /**
+     * Attaches a locate index (Appendix C, built by `buildLocateIndex` /
+     * `cgeodata build-locate-index`) so `locate()` reads one entry instead
+     * of scanning every chunk. Results are identical with or without it --
+     * only the speed differs -- except that its areas also let a sorted
+     * `search()` rank equal matches by size (`SearchOptions.areaTieBreak`).
+     *
+     * Takes the index's file (as for `open()`; read on demand) or an open
+     * `LocateIndex` (which the caller keeps ownership of), or undefined to
+     * locate without one. Replaces `OpenOptions.locateIndex`. Rejects with
+     * a `CGeoDataIndexMismatchError` if it was built from a different file.
+     */
+    async useLocateIndex(index) {
+        await this.attach(this.locate_, index, LocateIndex.open, (opened) => this.checkLocateIndex(opened));
+    }
+    /** Whether `locate()` will use an index. Reads (and validates) the one
+     * from `OpenOptions.locateIndex` if that hasn't happened yet. */
+    async hasLocateIndex() {
+        return (await this.activeLocateIndex()) !== undefined;
+    }
+    /** The attached locate index, opening `OpenOptions.locateIndex` on
+     * first use. One that's there but unusable (stale, corrupt) rejects on
+     * every call rather than silently falling back to a chunk scan. */
+    activeLocateIndex() {
+        return this.activate(this.locate_, "locate", (index) => this.useLocateIndex(index));
+    }
+    async checkLocateIndex(index) {
+        if (index.sourceChecksum !== (await this.prefixChecksum())) {
+            throw new CGeoDataIndexMismatchError("locate index was built from a different .bin file (checksum mismatch); rebuild it with build-locate-index");
+        }
+        const { totalPlaces } = this.placeTable;
+        if (index.placeCount !== totalPlaces) {
+            throw new CGeoDataIndexMismatchError(`locate index covers ${index.placeCount} places, but this file has ${totalPlaces}`);
+        }
+        const expectedWidth = locateEntryWidth(this.header);
+        if (index.entryWidth !== expectedWidth) {
+            throw new CGeoDataIndexMismatchError(`locate index has ${index.entryWidth}-byte entries, but this file's grid needs ${expectedWidth}`);
+        }
+    }
+    /** `useSearchIndex`/`useLocateIndex`, for either slot. */
+    async attach(slot, index, open, check) {
+        slot.pending = undefined;
+        if (slot.owned)
+            await slot.index?.close();
+        slot.index = undefined;
+        slot.owned = false;
+        if (index === undefined)
+            return;
+        const owned = !(index instanceof SearchIndex || index instanceof LocateIndex);
+        const opened = owned ? await open(index) : index;
+        try {
+            await check(opened);
+        }
+        catch (error) {
+            if (owned)
+                await opened.close();
+            throw error;
+        }
+        slot.index = opened;
+        slot.owned = owned;
+    }
+    /** The slot's index, trying its pending one first. */
+    activate(slot, what, use) {
+        if (slot.pending === undefined)
+            return Promise.resolve(slot.index);
+        slot.activating ??= this.tryPending(slot, what, use).finally(() => {
+            slot.activating = undefined;
+        });
+        return slot.activating;
+    }
+    async tryPending(slot, what, use) {
+        const pending = slot.pending;
+        let input;
+        try {
+            input = await pending();
+            if (input === undefined)
+                slot.pending = undefined;
+            else
+                await use(input);
+        }
+        catch (error) {
+            slot.pending = pending; // `use` cleared it; try again next time
+            const name = indexName(input);
+            throw name === undefined
+                ? error
+                : withContext(error, `${name}: `, ` (or delete it to ${what} without an index)`);
+        }
+        return slot.index;
+    }
+    /** Resolves one place id (Section 7.5) to its names and ancestors. */
+    async place(id) {
+        const loaded = this.loadedPlace(id);
+        if (loaded)
+            return loaded;
+        const ids = this.placeIds(id);
+        await Promise.all([ids.country, ids.region, ids.city].map((globalId) => globalId === null || this.loadedNames(globalId)
+            ? undefined
+            : this.loadNames(globalId)));
+        // Loaded, though not necessarily still cached: rebuild from the
+        // blocks if the budget already let one go.
+        return this.loadedPlace(id) ?? this.placeFrom(ids, id);
+    }
+    /** `place()` when every name it needs is cached, else undefined. */
+    loadedPlace(id) {
+        const ids = this.placeIds(id);
+        const country = this.loadedNames(ids.country);
+        if (!country)
+            return undefined;
+        let region;
+        if (ids.region !== null) {
+            region = this.loadedNames(ids.region);
+            if (!region)
+                return undefined;
+        }
+        let city;
+        if (ids.city !== null) {
+            city = this.loadedNames(ids.city);
+            if (!city)
+                return undefined;
+        }
+        return assemblePlace(id, ids, country, region, city);
+    }
+    /** `place()` loading each name block in turn, for when the cache is
+     * too small to hold them all at once. */
+    async placeFrom(ids, id) {
+        const country = await this.loadNames(ids.country);
+        const region = ids.region === null ? undefined : await this.loadNames(ids.region);
+        const city = ids.city === null ? undefined : await this.loadNames(ids.city);
+        return assemblePlace(id, ids, country, region, city);
+    }
+    /** `place()` without the names: the place's level and the global ids
+     * of it and its ancestors, from the place table's counts alone, so no
+     * name block is read -- and so synchronous. */
+    placeIds(id) {
+        const resolved = resolveIdentifier(this.placeTable, id);
+        const C = this.placeTable.countryCount;
+        const R = this.placeTable.totalRegions;
+        return {
+            level: resolved.level,
+            country: resolved.countryId,
+            region: "regionId" in resolved ? C + resolved.regionId : null,
+            city: resolved.level === "city" ? C + R + resolved.cityId : null,
+        };
+    }
+    /** How many places sit directly under `id`: a country's regions, a
+     * region's cities, always 0 for a city. From the place table's counts
+     * alone, like `placeIds()`, so no name block is read and it is
+     * synchronous: `childCount(region) === 0` finds a region with no city
+     * mapped to it. */
+    childCount(id) {
+        this.checkPlaceId(id);
+        const { countryCount: C, totalRegions: R } = this.placeTable;
+        const { regionCountryPrefix, cityRegionPrefix } = this.placeTable;
+        if (id < C)
+            return regionCountryPrefix[id + 1] - regionCountryPrefix[id];
+        if (id < C + R) {
+            const region = id - C;
+            return cityRegionPrefix[region + 1] - cityRegionPrefix[region];
+        }
+        return 0;
+    }
+    /**
+     * Walks the place hierarchy in id order (countries, then regions, then
+     * cities), optionally restricted to one level and/or one ancestor. Each
+     * level's ids for a given parent are contiguous (Section 7.5), so a
+     * filtered walk only touches the ids it yields.
+     */
+    async *places(filter = {}) {
+        for (const level of LEVELS) {
+            if (filter.level !== undefined && filter.level !== level)
+                continue;
+            const [start, end] = this.idRange(level, filter);
+            for (let id = start; id < end; id++)
+                yield this.loadedPlace(id) ?? (await this.place(id));
+        }
+    }
+    /**
+     * Diacritic- and case-insensitive substring match against every name of
+     * every place (all levels unless filtered) -- Section B.5's "matches":
+     * the folded form (`foldDiacritics`) of a name contains the folded form
+     * of the query. Without a search index this is a plain linear scan over
+     * the name blocks; with one (`useSearchIndex()`), only the places the
+     * index can't rule out are compared. Same results either way.
+     *
+     * A text with commas also reads as a place and the places it lies in
+     * (Appendix B.13): "Paris, Texas" finds a place named "Paris, Texas"
+     * and every "Paris" whose region or country matches "Texas";
+     * "Springfield, Illinois, United States" narrows by both. Each part
+     * after a comma has to match a different ancestor, nearest first.
+     *
+     * @example
+     * ```ts
+     * for await (const place of reader.search("munchen", { sort: true, limit: 20 }))
+     * 	console.log(place.internationalName, place.country.internationalName);
+     * // Munich Germany
+     * // Grafing bei München Germany
+     * // ...
+     * ```
+     */
+    async *search(text, options = {}) {
+        if (options.sort) {
+            yield* this.searchRanked(text, options);
+            return;
+        }
+        let remaining = options.limit ?? Infinity;
+        if (remaining <= 0)
+            return;
+        const query = await this.prepareQuery(text, await this.activeSearchIndex());
+        for (const level of LEVELS) {
+            if (options.level !== undefined && options.level !== level)
+                continue;
+            for (const id of this.searchScope(level, options, query.candidates)) {
+                // Match on the bare names first; resolving parents is only worth
+                // doing for the few that hit.
+                if (!(await this.matchQuery(id, level, query)))
+                    continue;
+                yield this.loadedPlace(id) ?? (await this.place(id));
+                if (--remaining <= 0)
+                    return;
+            }
+        }
+    }
+    /** The `sort: true` path of `search()`: scores every match in relevance
+     * order (Appendix B.5, or B.5.1 when ranking by area; `relevance.ts`),
+     * then yields the best first. `limit` is applied after sorting, not
+     * during the scan -- the top match can turn up anywhere in id order. */
+    async *searchRanked(text, options) {
+        const areas = await this.searchAreas(options.areaTieBreak ?? "auto");
+        const compare = areas ? compareAreaRelevance : compareRelevance;
+        const needle = foldDiacritics(text);
+        const index = await this.activeSearchIndex();
+        // The table is keyed, and was scored, by each key's own folded form
+        // (Section B.6) -- the same needle a live query would use only when
+        // the query itself already equals its folded form, i.e. has no
+        // diacritic of its own to fold away. A query that does (`ë`, say)
+        // would need `nameMatchQuality`'s exact-spelling bonus evaluated
+        // against ITS OWN raw spelling, not the plain, diacritic-free key
+        // ("e") the table was built from -- those can legitimately disagree
+        // (an accented query can give a different field its spelling bonus
+        // than the plain key would). Falling back to the live scan for such
+        // a query is the only way to keep index and no-index results equal.
+        // So is one ranked by a different order than the table was built
+        // with, and one with a comma, which the table knows nothing about.
+        const shortQuery = index !== undefined &&
+            index.relevanceRule === (areas ? RELEVANCE_AREA : RELEVANCE_PLAIN) &&
+            options.limit !== undefined &&
+            options.limit <= index.topCount &&
+            options.level === undefined &&
+            options.country === undefined &&
+            options.region === undefined &&
+            !text.includes(",") &&
+            needle === text.toLowerCase()
+            ? await index.shortQuery(text)
+            : undefined;
+        if (shortQuery) {
+            // The table already holds the answer (Appendix B.9 step 1); only
+            // confirm each place really matches, so a corrupt table can't add
+            // a wrong result.
+            let remaining = options.limit ?? Infinity;
+            for (const id of shortQuery) {
+                if (remaining <= 0)
+                    return;
+                const names = this.loadedNames(id) ?? (await this.loadNames(id));
+                if (!names.some((name) => foldDiacritics(name).includes(needle)))
+                    continue;
+                yield this.loadedPlace(id) ?? (await this.place(id));
+                remaining--;
+            }
+            return;
+        }
+        const query = await this.prepareQuery(text, index);
+        const scored = [];
+        for (const level of LEVELS) {
+            if (options.level !== undefined && options.level !== level)
+                continue;
+            for (const id of this.searchScope(level, options, query.candidates)) {
+                const match = await this.matchQuery(id, level, query, compare);
+                if (match)
+                    scored.push(match);
+            }
+        }
+        if (areas) {
+            for (const match of scored)
+                match.rankArea = await this.rankArea(match.id, match.level, areas);
+        }
+        scored.sort(compare);
+        let remaining = options.limit ?? Infinity;
+        for (const { id } of scored) {
+            if (remaining-- <= 0)
+                return;
+            yield this.loadedPlace(id) ?? (await this.place(id));
+        }
+    }
+    /** `text`'s readings (Appendix B.13) as needles, and the places a search
+     * index says could match any of them (ascending), or undefined when
+     * there's no index or it can't narrow one of the readings down. */
+    async prepareQuery(text, index) {
+        const parsed = parseQualifiedQuery(text);
+        const readings = parsed.map(({ head, contexts }) => ({
+            head: prepareNeedle(head),
+            contexts: contexts.map(prepareNeedle),
+        }));
+        if (!index)
+            return { readings, candidates: undefined };
+        let candidates = [];
+        for (const { head } of parsed) {
+            const found = await index.candidates(head);
+            if (!found)
+                return { readings, candidates: undefined };
+            candidates =
+                candidates.length === 0 ? found : unionSorted(candidates, found);
+        }
+        return { readings, candidates };
+    }
+    /** Whether place `id` matches any reading of `query`. With `compare`,
+     * instead the best-ranked way it does (by that order), or undefined;
+     * `rankArea` is left at 0 for the caller to fill in. */
+    async matchQuery(id, level, query, compare) {
+        const names = this.loadedNames(id) ?? (await this.loadNames(id));
+        let best;
+        let ancestors;
+        for (const { head, contexts } of query.readings) {
+            let quality;
+            if (compare) {
+                quality = placeMatchQuality(names, head);
+                if (quality === 0)
+                    continue;
+            }
+            else {
+                if (!names.some((name) => foldDiacritics(name).includes(head.folded)))
+                    continue;
+                quality = 0;
+            }
+            let context = 0;
+            if (contexts.length > 0) {
+                ancestors ??= await this.ancestorNames(id);
+                context = contextQuality(contexts, ancestors);
+                if (context === 0)
+                    continue;
+            }
+            const match = {
+                id,
+                level,
+                quality,
+                contextQuality: context,
+                rankArea: 0,
+            };
+            if (!compare)
+                return match;
+            if (!best || compare(match, best) < 0)
+                best = match;
+        }
+        return best;
+    }
+    /** The names of place `id`'s ancestors, nearest first: a city's region
+     * and country, a region's country, nothing for a country. */
+    async ancestorNames(id) {
+        const ids = this.placeIds(id);
+        const ancestors = [];
+        if (ids.level === "city")
+            ancestors.push(ids.region);
+        if (ids.level !== "country")
+            ancestors.push(ids.country);
+        const names = [];
+        for (const ancestor of ancestors)
+            names.push(this.loadedNames(ancestor) ?? (await this.loadNames(ancestor)));
+        return names;
+    }
+    /** `areaTieBreak` resolved to the area bytes to rank by, or undefined
+     * for Appendix B.5's plain order. */
+    async searchAreas(mode) {
+        if (mode === false)
+            return undefined;
+        const areas = await this.placeAreas();
+        if (!areas && mode === true) {
+            throw new CGeoDataError("areaTieBreak: true ranks by the areas in a locate index, and none is attached; build one with build-locate-index");
+        }
+        return areas;
+    }
+    /**
+     * The area byte (binary-format.md Section C.3) of every place, by id --
+     * the size of the place and everything under it, on a log scale, a
+     * quarter of a doubling per step -- read from the attached locate index
+     * (`useLocateIndex()`), or undefined without one. What
+     * `search({ sort: true })` breaks ties with (`SearchOptions.areaTieBreak`).
+     * Read once and then kept; the array is shared, so don't modify it.
+     */
+    async placeAreas() {
+        return (await this.activeLocateIndex())?.areas();
+    }
+    /** Place `id`'s rank area (Appendix B.5.1, `regionRankArea`): its area
+     * byte, except for a region with a city of the same local name. That
+     * takes reading the region's city names, so it's worked out only for
+     * the regions a search actually matched, once each. */
+    async rankArea(id, level, areas) {
+        if (level !== "region")
+            return areas[id];
+        const C = this.placeTable.countryCount;
+        if (this.rankAreas?.areas !== areas) {
+            this.rankAreas = {
+                areas,
+                regions: new Int16Array(this.placeTable.totalRegions).fill(-1),
+            };
+        }
+        const { regions } = this.rankAreas;
+        const cached = regions[id - C];
+        if (cached >= 0)
+            return cached;
+        const own = this.loadedNames(id) ?? (await this.loadNames(id));
+        const [lo, hi] = this.idRange("city", { region: id });
+        const cities = [];
+        for (let city = lo; city < hi; city++) {
+            const names = this.loadedNames(city) ?? (await this.loadNames(city));
+            cities.push({ localName: names[0] ?? "", area: areas[city] });
+        }
+        const value = regionRankArea(own[0] ?? "", areas[id], cities);
+        regions[id - C] = value;
+        return value;
+    }
+    /** The ids (ascending) of `level` under the filter that `search()` has
+     * to check: the whole `idRange`, or, when a search index narrowed the
+     * query to `candidates` (ascending), just those within it. */
+    *searchScope(level, filter, candidates) {
+        const [start, end] = this.idRange(level, filter);
+        if (!candidates) {
+            for (let id = start; id < end; id++)
+                yield id;
+            return;
+        }
+        for (let i = lowerBound(candidates, start); i < candidates.length; i++) {
+            const id = candidates[i];
+            if (id >= end)
+                return;
+            yield id;
+        }
+    }
+    /** The parsed records of one chunk (Section 8), or undefined when the
+     * chunk is empty. Cached like lookups, unless `cache` is false: a
+     * one-pass walk over every chunk should skip the cache, so it doesn't
+     * evict everything lookups had cached for chunks it only visits once. */
+    async chunk(index, { cache = true } = {}) {
+        if (!Number.isInteger(index) ||
+            index < 0 ||
+            index >= this.directory.chunkLengths.length) {
+            throw new RangeError(`chunk index ${index} is out of range for this file (0 <= index < ${this.directory.chunkLengths.length})`);
+        }
+        const loaded = this.loadedChunk(index);
+        return ((loaded === undefined ? await this.loadChunk(index, cache) : loaded) ??
+            undefined);
+    }
+    /** The lat/lon extent of a chunk (Section 6.1). */
+    chunkBoundingBox(index) {
+        const { width, height } = this.header;
+        return chunkBoundingBox(index % width, Math.floor(index / width), width, height);
+    }
+    /**
+     * A representative lat/lon for a place id: the centre of the place's
+     * representative cell (binary-format.md Section C.3), a cell near the
+     * middle of the place's area -- its own cells plus those of every place
+     * under it -- that is guaranteed to lie in that area, so `query()` at
+     * the returned point resolves to the place or one of its descendants.
+     *
+     * @example
+     * ```ts
+     * const position = await reader.locate(place.id);
+     * if (position) map.setView([position.lat, position.lon]);
+     * ```
+     *
+     * Null if neither the place nor anything under it has any cells -- and
+     * that happens to real places, not only to broken files: a place
+     * smaller than the file's finest cell (a tiny island, an enclave, a
+     * boundary sliver) loses every cell to its neighbours. On a worldwide
+     * build that's about 0.15% of places, every one of them still found
+     * by `search()`; drop them from results that need a position rather
+     * than defaulting to a coordinate.
+     *
+     * With a locate index (`useLocateIndex()`) this reads one entry;
+     * without one it scans every chunk. Same result either way.
+     */
+    async locate(id) {
+        this.checkPlaceId(id);
+        const index = await this.activeLocateIndex();
+        let found;
+        if (index) {
+            const cell = decodeLocateEntry(await index.entry(id), this.header);
+            found = cell && { cell, area: await index.area(id) };
+        }
+        else {
+            found = await computeLocateCell(this, id);
+        }
+        if (!found)
+            return null;
+        const { cell, area } = found;
+        const box = this.recordBoundingBox(this.chunkBoundingBox(cell.chunkIndex), cell.code, cell.depth);
+        const { width, height, maxDepth } = this.header;
+        const cellDegrees = (360 / (width * 2 ** maxDepth)) * (180 / (height * 2 ** maxDepth));
+        return {
+            lat: (box.minLat + box.maxLat) / 2,
+            lon: (box.minLon + box.maxLon) / 2,
+            boundingBox: box,
+            // The middle of the byte's range, 2^((area - 1) / 4) up to
+            // 2^(area / 4) cells, on the same log scale.
+            area: area === 0 ? 0 : 2 ** ((area - 0.5) / 4) * cellDegrees,
+        };
+    }
+    /**
+     * The ids of place `id` and of every place under it, as half-open
+     * ranges: `[id, id + 1]` first, then for a country its regions and
+     * their cities, for a region its cities. Each level's children are
+     * contiguous (Section 7.1), so this is at most three ranges.
+     */
+    subtreeIdRanges(id) {
+        const resolved = resolveIdentifier(this.placeTable, id);
+        const ranges = [[id, id + 1]];
+        if (resolved.level === "country") {
+            ranges.push(this.idRange("region", { country: id }));
+            ranges.push(this.idRange("city", { country: id }));
+        }
+        else if (resolved.level === "region") {
+            ranges.push(this.idRange("city", { region: id }));
+        }
+        return ranges;
+    }
+    /** One chunk's records with their cells and places resolved -- what a
+     * lookup in that chunk can answer with, laid out for inspection. */
+    async *chunkRecords(index) {
+        const chunk = await this.chunk(index);
+        if (!chunk)
+            return;
+        const chunkBox = this.chunkBoundingBox(index);
+        for (let j = 0; j < chunk.codes.length; j++) {
+            const code = chunk.codes[j];
+            const depth = chunk.depths[j];
+            const k = chunk.paletteIndices[j];
+            const placeId = k === 0 ? undefined : chunk.palette[k - 1];
+            yield {
+                code,
+                depth,
+                boundingBox: this.recordBoundingBox(chunkBox, code, depth),
+                place: placeId === undefined
+                    ? null
+                    : (this.loadedPlace(placeId) ?? (await this.place(placeId))),
+            };
+        }
+    }
+    recordBoundingBox(chunkBox, code, depth) {
+        const D = this.header.maxDepth;
+        const { x: fullX, y: fullY } = mortonDecode(code, D);
+        return cellBoundingBox(chunkBox, shiftRight(fullX, D - depth), shiftRight(fullY, D - depth), depth);
+    }
+    /** The half-open global id range of `level` under the filter's
+     * narrowest ancestor, via the Section 7.5 prefix arrays. */
+    idRange(level, filter) {
+        const { countryCount: C, totalRegions: R, totalPlaces, regionCountryPrefix, cityRegionPrefix, } = this.placeTable;
+        let { country } = filter;
+        const { region } = filter;
+        if (country !== undefined)
+            checkId(country, 0, C, "country");
+        if (region !== undefined) {
+            checkId(region, C, C + R, "region");
+            const owner = largestIndexWithPrefixAtMost(regionCountryPrefix, region - C);
+            if (country !== undefined && country !== owner)
+                return [0, 0]; // region isn't in that country
+            country = owner;
+        }
+        // Region-local index range under the narrowest ancestor, then the
+        // level's own ids from there.
+        const regionLo = region !== undefined
+            ? region - C
+            : country !== undefined
+                ? regionCountryPrefix[country]
+                : 0;
+        const regionHi = region !== undefined
+            ? region - C + 1
+            : country !== undefined
+                ? regionCountryPrefix[country + 1]
+                : R;
+        switch (level) {
+            case "country":
+                return country !== undefined ? [country, country + 1] : [0, C];
+            case "region":
+                return [C + regionLo, C + regionHi];
+            case "city":
+                return [
+                    Math.min(C + R + cityRegionPrefix[regionLo], totalPlaces),
+                    Math.min(C + R + cityRegionPrefix[regionHi], totalPlaces),
+                ];
+        }
+    }
+    checkPlaceId(id) {
+        const { totalPlaces } = this.placeTable;
+        if (!Number.isInteger(id) || id < 0 || id >= totalPlaces) {
+            throw new RangeError(`${id} is not a place id for this file (0 <= id < ${totalPlaces})`);
+        }
+    }
+    /** A chunk without reading anything: its records when decoded and
+     * cached, null when it's empty, undefined when it would need a read. */
+    loadedChunk(index) {
+        if (this.directory.chunkLengths[index] === 0)
+            return null;
+        if (index === this.lastChunkIndex)
+            return this.lastChunk;
+        const cached = this.cache.get(index);
+        if (cached) {
+            this.lastChunkIndex = index;
+            this.lastChunk = cached;
+        }
+        return cached;
+    }
+    /** Reads and decodes a chunk, sharing one decode among concurrent
+     * callers. */
+    loadChunk(index, cache) {
+        if (!cache)
+            return this.decodeChunk(index);
+        const inFlight = this.loading.get(index);
+        if (inFlight)
+            return inFlight;
+        const load = this.decodeChunk(index)
+            .then((chunk) => {
+            this.cache.set(index, chunk, chunkBytes(chunk));
+            this.lastChunkIndex = index;
+            this.lastChunk = chunk;
+            return chunk;
+        })
+            .finally(() => this.loading.delete(index));
+        this.loading.set(index, load);
+        return load;
+    }
+    async decodeChunk(index) {
+        const compressed = await this.source.read(this.directory.chunkOffsets[index], this.directory.chunkLengths[index]);
+        return this.decodes.run(async () => this.checkPalette(index, parseChunk(
+        // Version 2 chunks are range coded, not zlib (Section 8.7).
+        this.header.version >= 2
+            ? compressed
+            : await inflateBlock(this.inflater, compressed), this.header.maxDepth, this.header.version)));
+    }
+    checkPalette(index, chunk) {
+        // Section 11: "every palette entry [MUST be] less than N".
+        // `parseChunk` can't check that -- it has no place table -- and this
+        // is the one place that has both, so a corrupt palette fails here
+        // with a format error naming the chunk, instead of surfacing much
+        // later as an out-of-range place id (`chunkRecords`) or as a bare
+        // TypeError on an undefined lookup (`buildLocateIndex`'s
+        // `countryOf[placeId]`).
+        const { totalPlaces } = this.placeTable;
+        for (const placeId of chunk.palette) {
+            if (placeId >= totalPlaces) {
+                throw new CGeoDataFormatError(`chunk ${index}'s palette references place ${placeId}, beyond this file's ${totalPlaces} places`);
+            }
+        }
+        return chunk;
+    }
+    /** A place's names when its name block is cached, else undefined. */
+    loadedNames(globalId) {
+        const blockIndex = Math.floor(globalId / this.nameBlockSize);
+        const block = this.cache.get(-1 - blockIndex);
+        return block && this.entryOf(block, blockIndex, globalId);
+    }
+    /** Reads and decodes a place's name block (sharing one read among
+     * concurrent callers), and returns its names. */
+    async loadNames(globalId) {
+        const blockIndex = Math.floor(globalId / this.nameBlockSize);
+        const key = -1 - blockIndex;
+        let load = this.loading.get(key);
+        if (!load) {
+            load = readNameBlock(this.source, this.placeTable, blockIndex, this.inflater, (work) => this.decodes.run(work))
+                .then((block) => {
+                this.cache.set(key, block, nameBlockBytes(block));
+                return block;
+            })
+                .finally(() => this.loading.delete(key));
+            this.loading.set(key, load);
+        }
+        return this.entryOf(await load, blockIndex, globalId);
+    }
+    get nameBlockSize() {
+        const { keyframeExp, totalPlaces } = this.placeTable;
+        return keyframeExp === 0 ? totalPlaces : 2 ** keyframeExp;
+    }
+    entryOf(block, blockIndex, globalId) {
+        const entry = block[globalId - blockIndex * this.nameBlockSize];
+        if (!entry)
+            throw new CGeoDataFormatError(`name block ${blockIndex} ended before reaching place ${globalId}`);
+        return entry;
+    }
+}
+const LEVELS = ["country", "region", "city"];
+function pendingSlot(option) {
+    return {
+        index: undefined,
+        owned: false,
+        activating: undefined,
+        pending: option === undefined
+            ? undefined
+            : typeof option === "function"
+                ? option
+                : () => Promise.resolve(option),
+    };
+}
+/** What an index's errors are prefixed with, if anything names it. */
+function indexName(input) {
+    const name = input?.name;
+    return typeof name === "string" ? name : undefined;
+}
+function assemblePlace(id, ids, country, region, city) {
+    const countryRef = placeRef(ids.country, country);
+    const regionRef = ids.region === null ? null : placeRef(ids.region, region);
+    const cityRef = ids.city === null ? null : placeRef(ids.city, city);
+    const own = cityRef ?? regionRef ?? countryRef;
+    return {
+        id,
+        localName: own.localName,
+        internationalName: own.internationalName,
+        names: own.names,
+        level: ids.level,
+        country: countryRef,
+        region: regionRef,
+        city: cityRef,
+    };
+}
+function placeRef(id, names) {
+    const localName = names[0] ?? "";
+    return {
+        id,
+        localName,
+        internationalName: names[1] || localName,
+        names,
+    };
+}
+/** A decoded chunk's size, for the cache budget. */
+function chunkBytes(chunk) {
+    return (chunk.codes.byteLength +
+        chunk.depths.byteLength +
+        chunk.paletteIndices.byteLength +
+        chunk.palette.length * 8);
+}
+/** A rough size of a decoded name block, for the cache budget: two bytes
+ * per character (V8's worst case), plus per-string and per-array
+ * overhead. */
+function nameBlockBytes(block) {
+    let bytes = 0;
+    for (const entry of block) {
+        bytes += 32;
+        for (const name of entry)
+            bytes += 24 + 2 * name.length;
+    }
+    return bytes;
+}
+function checkId(id, lo, hi, what) {
+    if (!Number.isInteger(id) || id < lo || id >= hi) {
+        throw new RangeError(`${id} is not a ${what} id for this file (${what} ids are ${lo} <= id < ${hi})`);
+    }
+}
+/** `error` with `prefix` and `suffix` added to its message, keeping its
+ * class -- so a stale index next to the file still throws a
+ * `CGeoDataIndexMismatchError`, and says which file it was. */
+function withContext(error, prefix, suffix) {
+    if (!(error instanceof Error))
+        return error;
+    const message = `${prefix}${error.message}${suffix}`;
+    if (error.stack)
+        error.stack = error.stack.replace(error.message, message);
+    error.message = message;
+    return error;
+}
+function unknownResult(boundingBox, chunkIndex) {
+    return { placeId: null, boundingBox, chunkIndex };
+}
+/** The union of two ascending id lists, ascending, without duplicates. */
+function unionSorted(a, b) {
+    const out = [];
+    let i = 0;
+    let j = 0;
+    while (i < a.length || j < b.length) {
+        const x = i < a.length ? a[i] : Infinity;
+        const y = j < b.length ? b[j] : Infinity;
+        out.push(Math.min(x, y));
+        if (x <= y)
+            i++;
+        if (y <= x)
+            j++;
+    }
+    return out;
+}
+/** The first index of the ascending `sorted` whose value is >= `value`. */
+function lowerBound(sorted, value) {
+    let lo = 0;
+    let hi = sorted.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (sorted[mid] < value)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}
+/** bisect_right(sorted, value) - 1, per Section 9 step 6. */
+function bisectRightMinusOne(sorted, value) {
+    let lo = 0;
+    let hi = sorted.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (sorted[mid] <= value)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo - 1;
+}
+/** FNV-1a 64-bit hash per binary-format.md Section B.6.
+ * offset_basis = 0xcbf29ce484222325, prime = 0x100000001b3.
+ *
+ * Done in two 32-bit halves rather than with BigInt, which costs ~100ms
+ * on a world-sized place table: prime = 2^40 + 0x1b3, so
+ * h * prime mod 2^64 = h * 0x1b3 + (lo << 40), and every intermediate
+ * below stays under 2^53. */
+function fnv1a64(data) {
+    let hi = 0xcbf29ce4;
+    let lo = 0x84222325;
+    for (let i = 0; i < data.length; i++) {
+        lo ^= data[i];
+        const loProduct = (lo >>> 0) * 0x1b3;
+        hi =
+            (hi * 0x1b3 + Math.floor(loProduct / 0x100000000) + ((lo << 8) >>> 0)) >>>
+                0;
+        lo = loProduct >>> 0;
+    }
+    return (BigInt(hi) << 32n) | BigInt(lo);
+}
+//# sourceMappingURL=reader.js.map