@mailwoman/resolver-wof-sqlite 8.1.0 → 8.2.0

package/candidate-lookup.ts

@@ -38,9 +38,13 @@ import { normalizeLocalityForKey, stripLocalityQualifier } from "./street-normal
 import type { FindPlaceQuery, PlaceCandidate, PlaceLookup, WOFPlacetype } from "./types.ts"
 
 export interface WOFCandidateTableLookupOpts {
-	/** Path to a `candidate.db` built by `build-candidate.ts`. Opened read-only. */
+	/**
+	 * Path to a `candidate.db` built by `build-candidate.ts`. Opened read-only.
+	 */
 	databasePath?: string
-	/** Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`. */
+	/**
+	 * Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`.
+	 */
 	database?: DatabaseSync
 }
 
@@ -92,7 +96,7 @@ const FUZZY_MIN = 0.34
  *    ("Los Angeles" over La, Ghana — gap 1.6; "Las Vegas" over Vegas, Cuba — gap 2.4) while a near-tie coincidental
  *    collision defers to the primary (Cancún over Changchun — gap 0.7).
  */
-const PRIMARY_PREFERENCE_LOG10 = 1.0
+const PRIMARY_PREFERENCE_LOG10 = 1
 
 /**
  * Over-fetch cap for {@link rankByPrimaryPreference}: the candidate rows for one `name_key` (all same-name places
@@ -102,7 +106,9 @@ const PRIMARY_PREFERENCE_LOG10 = 1.0
  */
 const RERANK_FETCH = 64
 
-/** A candidate row annotated with the {@link rankByPrimaryPreference} effective rank + the exact-tier demotion flag. */
+/**
+ * A candidate row annotated with the {@link rankByPrimaryPreference} effective rank + the exact-tier demotion flag.
+ */
 export type RankedRow<R> = R & {
 	/**
 	 * `neg_rank` plus the bounded cross-country alias penalty — the value the row is ORDERED by, and the base the emitted
@@ -144,10 +150,12 @@ export function rankByPrimaryPreference<R extends Pick<CandidateRow, "neg_rank"
 	}
 
 	const topCountry = topPrimary?.country_id
+
 	// A cross-country alias (different country than the top primary) is penalized; it is DEMOTED when even after — i.e.
 	// the penalty leaves its effective rank behind the primary's raw rank (it lost the bounded population contest).
 	const isCrossCountryAlias = (r: R): boolean =>
 		topCountry !== undefined && r.is_primary !== 1 && r.country_id !== topCountry
+
 	const annotate = (r: R): RankedRow<R> => {
 		const penalized = isCrossCountryAlias(r)
 		const effectiveNegRank = r.neg_rank + (penalized ? delta : 0)
@@ -159,6 +167,7 @@ export function rankByPrimaryPreference<R extends Pick<CandidateRow, "neg_rank"
 		rows
 			.map((r, i) => ({ row: annotate(r), i }))
 			// Effective rank ASC; ties keep population order, then original index (stable).
+			// oxlint-disable-next-line unicorn/no-array-sort -- sorts a freshly-built array; toSorted would double-allocate on a hot path
 			.sort((a, b) => a.row.effectiveNegRank - b.row.effectiveNegRank || a.row.neg_rank - b.row.neg_rank || a.i - b.i)
 			.slice(0, limit)
 			.map((x) => x.row)
@@ -260,6 +269,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 			this.#ftsProbe = this.#db.prepare(
 				`SELECT name_key FROM ${CANDIDATE_FTS_TABLE} WHERE ${CANDIDATE_FTS_TABLE} MATCH ? ORDER BY bm25(${CANDIDATE_FTS_TABLE}) LIMIT ?`
 			)
+
 			this.#nameKeyExistsProbe = this.#db.prepare("SELECT 1 FROM candidate WHERE name_key = ? LIMIT 1")
 		}
 
@@ -269,7 +279,9 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 		this.artifactCoverage = readGazetteerCoverageManifest(this.#db)
 	}
 
-	/** Does this query want a locality-tier place? Postal-city aliases (#741) are all localities. */
+	/**
+	 * Does this query want a locality-tier place? Postal-city aliases (#741) are all localities.
+	 */
 	#wantsLocality(placetype: FindPlaceQuery["placetype"]): boolean {
 		if (!placetype) return true
 		const want = Array.isArray(placetype) ? placetype : [placetype]
@@ -286,8 +298,9 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 		// form at build (the GeoNames fold normalizes '624 66' → '62466'), so a postcode-typed query
 		// strips internal whitespace before keying. Postcode-only — locality names keep their spaces.
 		if ([query.placetype].flat().includes("postalcode")) {
-			text = text.replace(/\s+/g, "")
+			text = text.replaceAll(/\s+/g, "")
 		}
+
 		const nameKey = normalizeLocalityForKey(text)
 
 		if (!nameKey) return []
@@ -337,11 +350,12 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 			// Shared placetype-equivalence expansion (a `locality` query must also reach borough /
 			// localadmin). `postalcode` maps to no admin placetype here → empty → no rows.
 			const want = Array.isArray(query.placetype) ? query.placetype : [query.placetype]
+
 			const ids = expandPlacetypeFilter(want as readonly string[])
 				.map((t) => this.#placetypeToID.get(t))
 				.filter((v): v is number => v !== undefined)
 
-			if (ids.length === 0) return []
+			if (!ids.length) return []
 			filters.push(`placetype_id IN (${ids.map(() => "?").join(",")})`)
 			filterParams.push(...ids)
 		}
@@ -360,7 +374,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 		// Kept OUT of the shared `filters` so a region MISS falls back to the unscoped cascade below: a
 		// country/non-region parent (no `region_id` match), a `region_id=0` row (place with no region
 		// ancestor), or a wrong parent degrades to today's behavior — never worse, recall-safe by construction.
-		const regionParentID = query.parentID ? query.parentID : undefined
+		const regionParentID = query.parentID || undefined
 
 		const probe = (nk: string, regionID: number | undefined): Array<RankedRow<CandidateRow>> => {
 			const conds = ["name_key = ?", ...filters]
@@ -379,6 +393,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 			const sql =
 				"SELECT spr_id, name, country_id, placetype_id, latitude, longitude, min_lat, min_lon, max_lat, max_lon, neg_rank, is_primary " +
 				`FROM candidate WHERE ${conds.join(" AND ")} ORDER BY neg_rank ASC LIMIT ?`
+
 			const fetched = this.#db.prepare(sql).all(...params, Math.max(limit, RERANK_FETCH)) as unknown as CandidateRow[]
 
 			return rankByPrimaryPreference(fetched, limit)
@@ -390,7 +405,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 		const cascade = (regionID: number | undefined): Array<RankedRow<CandidateRow>> => {
 			let rows = probe(nameKey, regionID)
 
-			if (rows.length === 0) {
+			if (!rows.length) {
 				// Query-side qualifier-strip fallback: an OA locality with a qualifier the gazetteer's
 				// canonical name omits ("Lenk im Simmental" → "Lenk", "Roche VD"). Tried ONLY on an exact
 				// miss; the cascade's region bbox disambiguates any base-name ambiguity.
@@ -412,15 +427,18 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 			// — fuzzing it scrapes an unrelated same-filter place ("Vienna, Austria" misrouted to IT would
 			// pull a tiny Italian name_key near Siena) and masks the cascade's country-agnostic retry that
 			// correctly lands population-first Vienna AT. The exact/strip probes already covered the real name.
-			if (rows.length === 0 && this.#ftsProbe && this.#nameKeyExistsProbe && !this.#nameKeyExistsProbe.get(nameKey)) {
+			if (!rows.length && this.#ftsProbe && this.#nameKeyExistsProbe && !this.#nameKeyExistsProbe.get(nameKey)) {
 				const match = ftsTrigramQuery(nameKey)
 
 				if (match) {
 					const hits = this.#ftsProbe.all(match, FUZZY_FETCH) as unknown as Array<{ name_key: string }>
+
 					const ranked = hits
 						.map((h) => ({ nk: String(h.name_key), s: trigramJaccard(nameKey, String(h.name_key)) }))
 						.filter((h) => h.s >= FUZZY_MIN)
+						// oxlint-disable-next-line unicorn/no-array-sort -- sorts a freshly-built array; toSorted would double-allocate on a hot path
 						.sort((a, b) => b.s - a.s)
+
 					const seen = new Set<string>()
 
 					for (const h of ranked) {
@@ -430,6 +448,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 
 						if (rows.length >= limit) break
 					}
+
 					rows = rows.slice(0, limit)
 				}
 			}
@@ -442,7 +461,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 		// Region-scope fallback: if scoping to the parent region found nothing across the whole cascade, retry
 		// unscoped so a place with no in-region row (missing ancestry, or a country/non-region parent) still
 		// resolves exactly as it does today. Only when a region scope was actually applied.
-		if (rows.length === 0 && regionParentID !== undefined) {
+		if (!rows.length && regionParentID !== undefined) {
 			rows = cascade(undefined)
 		}
 
@@ -492,9 +511,9 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 		// log10(population + 1), so popTerm is the server formula read straight off it. Constants MIRROR
 		// lookup.ts's DEFAULT_WEIGHTS (biasBoost 4, populationBoost 4, populationScaleLog10 6,
 		// proximityScaleKm 100) — the #861 server↔demo parity contract; keep them in lockstep.
-		if (query.bias && query.bias.length > 0) {
-			const BIAS_BOOST = 4.0
-			const POP_BOOST = 4.0
+		if (query.bias && query.bias.length) {
+			const BIAS_BOOST = 4
+			const POP_BOOST = 4
 			const POP_SCALE_LOG10 = 6
 			// SHARPER than lookup.ts's 100 km on purpose: this backend's `score` is log-population ALONE
 			// (no bm25 document term), so the population signal is weaker relative to the bias and the
@@ -503,6 +522,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 			// candidates the user is actually LOOKING at — an in-view namesake still wins (Dublin, OH from
 			// an Ohio view), a distant one no longer does (Paris stays FR from a Michigan view).
 			const PROX_SCALE_KM = 30
+
 			const combinedProminence = (c: PlaceCandidate): number => {
 				// Population base is the PENALIZED `prominence` (set above = -effectiveNegRank), not raw `score`, so
 				// the cross-country primary preference carries into the bias-weighted order too — a coincidental
@@ -524,6 +544,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 
 				return popTerm + proxTerm
 			}
+
 			// Persist the combined value into `prominence` so the resolver walk's `prominence ?? score` sort (and any
 			// other node consumer) honors the bias order — then sort. Stable within equal prominence (preserves the
 			// population order the B-tree already gave).
@@ -533,6 +554,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 
 					return { c, i, p: c.prominence }
 				})
+				// oxlint-disable-next-line unicorn/no-array-sort -- sorts a freshly-built array; toSorted would double-allocate on a hot path
 				.sort((a, b) => b.p - a.p || a.i - b.i)
 				.forEach((x, j) => (candidates[j] = x.c))
 		}

package/candidate-schema.ts

@@ -23,19 +23,29 @@ import { sql, type Kysely } from "kysely"
  * level (a postcode shard row may lack a bbox).
  */
 export interface CandidateTable {
-	/** The shared {@link normalizeLocalityForKey} of the name/alias — the probe key. */
+	/**
+	 * The shared {@link normalizeLocalityForKey} of the name/alias — the probe key.
+	 */
 	name_key: string
-	/** Small int from {@link CountryCodeTable} (shrinks the clustered key). */
+	/**
+	 * Small int from {@link CountryCodeTable} (shrinks the clustered key).
+	 */
 	country_id: number
-	/** The place's region-tier ancestor id, or 0 (carried for the future region 2-step). */
+	/**
+	 * The place's region-tier ancestor id, or 0 (carried for the future region 2-step).
+	 */
 	region_id: number
-	/** Small int from {@link PlacetypeCodeTable}. */
+	/**
+	 * Small int from {@link PlacetypeCodeTable}.
+	 */
 	placetype_id: number
 	/**
 	 * `-log10(population + 1)` — ASC order = highest-population first. 0 for postcodes (no population).
 	 */
 	neg_rank: number
-	/** WOF id of the place this row resolves to. */
+	/**
+	 * WOF id of the place this row resolves to.
+	 */
 	spr_id: number
 	name: string | null
 	latitude: number | null
@@ -45,27 +55,39 @@ export interface CandidateTable {
 	max_lat: number | null
 	max_lon: number | null
 	population: number | null
-	/** 1 when the row is the place's canonical name (vs an alias/abbrev). */
+	/**
+	 * 1 when the row is the place's canonical name (vs an alias/abbrev).
+	 */
 	is_primary: number | null
 }
 
-/** `(id → ISO country code)` dictionary. */
+/**
+ * `(id → ISO country code)` dictionary.
+ */
 export interface CountryCodeTable {
 	id: number
 	code: string
 }
 
-/** `(id → placetype)` dictionary. */
+/**
+ * `(id → placetype)` dictionary.
+ */
 export interface PlacetypeCodeTable {
 	id: number
 	placetype: string
 }
 
-/** The candidate database schema for `new DatabaseClient<CandidateDatabase>(...)`. */
+/**
+ * The candidate database schema for `new DatabaseClient<CandidateDatabase>(...)`.
+ */
 export interface CandidateDatabase {
-	/** The clustered `WITHOUT ROWID` lookup table the reader probes. */
+	/**
+	 * The clustered `WITHOUT ROWID` lookup table the reader probes.
+	 */
 	candidate: CandidateTable
-	/** Transient staging table (same columns); dropped once `candidate` is materialized. */
+	/**
+	 * Transient staging table (same columns); dropped once `candidate` is materialized.
+	 */
 	cand_stage: CandidateTable
 	country_codes: CountryCodeTable
 	placetype_codes: PlacetypeCodeTable
@@ -105,11 +127,13 @@ export async function createCandidateStagingTables(db: Kysely<CandidateDatabase>
 		.addColumn("id", "integer", (c) => c.primaryKey())
 		.addColumn("code", "text", (c) => c.unique())
 		.execute()
+
 	await db.schema
 		.createTable("placetype_codes")
 		.addColumn("id", "integer", (c) => c.primaryKey())
 		.addColumn("placetype", "text", (c) => c.unique())
 		.execute()
+
 	await db.schema
 		.createTable("cand_stage")
 		.addColumn("name_key", "text")

package/coincident-roles.ts

@@ -42,9 +42,15 @@ import type { DatabaseSync } from "node:sqlite"
 
 import { haversineKm } from "@mailwoman/spatial"
 
+/**
+ * Table of places that hold more than one admin role — a locality that is also its county seat. Written by the
+ * gazetteer build, read by the resolver when a coincident locality has to be chosen.
+ */
 export const COINCIDENT_ROLES_TABLE = "coincident_roles"
 
-/** A place that plays multiple admin roles — one row of the relation, keyed by `admin_id`. */
+/**
+ * A place that plays multiple admin roles — one row of the relation, keyed by `admin_id`.
+ */
 export interface CoincidentRole {
 	localityID: number
 	relationshipType: "city-state" | "capital-seat" | "consolidated-county"
@@ -54,13 +60,17 @@ export interface CoincidentRole {
 }
 
 export interface BuildCoincidentRolesOpts {
-	/** Drop + rebuild the table if it already exists. Default true (the build is cheap + idempotent). */
+	/**
+	 * Drop + rebuild the table if it already exists. Default true (the build is cheap + idempotent).
+	 */
 	drop?: boolean
 	/**
 	 * Relative tolerance: a pair is kept when centroid distance ≤ `toleranceFraction × bbox-diagonal`. Default 0.15.
 	 */
 	toleranceFraction?: number
-	/** Floor (km) under the relative tolerance, so small-bbox city-states still qualify. Default 12. */
+	/**
+	 * Floor (km) under the relative tolerance, so small-bbox city-states still qualify. Default 12.
+	 */
 	minToleranceKm?: number
 	/**
 	 * Centroid distance (km) below which a region-tier pair is classed `city-state` (metadata only). Default 2.
@@ -115,7 +125,9 @@ export function buildCoincidentRoles(
 		onProgress("dropping", COINCIDENT_ROLES_TABLE)
 		db.exec(`DROP TABLE ${COINCIDENT_ROLES_TABLE}`)
 	}
+
 	onProgress("creating", COINCIDENT_ROLES_TABLE)
+
 	// Raw DDL by design: this is a sync builder consumed by a sync CLI (build-coincident-roles-cli) and
 	// 6 sync unit tests, so routing one table through async Kysely would cascade async through all of
 	// them for no real gain. See AGENTS.md "Database / inline SQL". (The SELECT + INSERT loop below are
@@ -133,6 +145,7 @@ export function buildCoincidentRoles(
 	`)
 
 	onProgress("scanning")
+
 	// Admin (region/county tier) ⋈ same-name DESCENDANT locality. `place_population` is optional (LEFT
 	// JOIN → 0 when absent). The relative-tolerance filter + relationship classification happen in JS so
 	// the SQL stays a plain join. `spr` exposes the bbox columns we need for the diagonal.
@@ -153,11 +166,13 @@ export function buildCoincidentRoles(
 		.all() as unknown as CandidateRow[]
 
 	onProgress("filtering", `${candidates.length} candidates`)
+
 	const insert = db.prepare(
 		`INSERT OR REPLACE INTO ${COINCIDENT_ROLES_TABLE}
 			(admin_id, locality_id, relationship_type, admin_placetype, distance_km, locality_population)
 			VALUES (?, ?, ?, ?, ?, ?)`
 	)
+
 	const byCountry: Record<string, number> = {}
 	let rowCount = 0
 	db.exec("BEGIN")
@@ -176,14 +191,17 @@ export function buildCoincidentRoles(
 			// dominated by French cantons / JP counties that don't hit the parser-drops-locality failure.
 			const relationshipType = dist <= cityStateMaxKm ? "city-state" : "capital-seat"
 			insert.run(c.admin_id, c.locality_id, relationshipType, c.admin_placetype, dist, c.pop)
+
 			rowCount++
 			byCountry[c.country] = (byCountry[c.country] ?? 0) + 1
 		}
+
 		db.exec("COMMIT")
-	} catch (err) {
+	} catch (error) {
 		db.exec("ROLLBACK")
-		throw err
+		throw error
 	}
+
 	db.exec(`CREATE INDEX IF NOT EXISTS coincident_roles_by_admin ON ${COINCIDENT_ROLES_TABLE} (admin_id)`)
 
 	onProgress("done", `${rowCount} coincident-role rows`)
@@ -191,7 +209,9 @@ export function buildCoincidentRoles(
 	return { created: true, rowCount, byCountry, durationMs: Date.now() - start }
 }
 
-/** True iff the relation table exists. Used by the resolver to decide whether completion can run. */
+/**
+ * True iff the relation table exists. Used by the resolver to decide whether completion can run.
+ */
 export function coincidentRolesExists(db: DatabaseSync): boolean {
 	return tableExists(db, COINCIDENT_ROLES_TABLE)
 }
@@ -205,6 +225,7 @@ export function loadCoincidentRoles(db: DatabaseSync): Map<number, CoincidentRol
 	const map = new Map<number, CoincidentRole[]>()
 
 	if (!coincidentRolesExists(db)) return map
+
 	const rows = db
 		.prepare(
 			`SELECT admin_id, locality_id, relationship_type, admin_placetype, distance_km, locality_population
@@ -227,6 +248,7 @@ export function loadCoincidentRoles(db: DatabaseSync): Map<number, CoincidentRol
 			distanceKm: r.distance_km,
 			population: r.locality_population,
 		}
+
 		const list = map.get(r.admin_id)
 
 		if (list) {

package/convention.ts

@@ -38,7 +38,9 @@ export interface ScoringWeights {
  * `tokenNormalization`, etc.
  */
 export interface Convention {
-	/** Ordered strategy names the dispatcher runs; the first to return a non-null result wins. */
+	/**
+	 * Ordered strategy names the dispatcher runs; the first to return a non-null result wins.
+	 */
 	candidateStrategies?: string[]
 	/**
 	 * Weights for `postcode_area_resolution`'s soft-score. Partial — a layer may nudge one weight and inherit the rest

package/coverage-manifest-schema.ts

@@ -35,45 +35,74 @@ import { sql, type Kysely } from "kysely"
 
 import { hasTable } from "./sqlite-utils.ts"
 
-/** One country's hard-filter coverage measurement — the storage form of {@link CountryCoverageFact}. */
+/**
+ * One country's hard-filter coverage measurement — the storage form of {@link CountryCoverageFact}.
+ */
 export interface CountryCoverageTable {
-	/** ISO 3166-1 alpha-2, uppercase (PK). */
+	/**
+	 * ISO 3166-1 alpha-2, uppercase (PK).
+	 */
 	country: string
-	/** 0/1 — the promote-gate verdict (a verdict column, NOT re-derived from the rate; see the fact type's docstring). */
+	/**
+	 * 0/1 — the promote-gate verdict (a verdict column, NOT re-derived from the rate; see the fact type's docstring).
+	 */
 	hard_filter_safe: number
-	/** Measured hard-resolve rate 0..1 on the panel named in `source`; NULL when the receipt recorded none. */
+	/**
+	 * Measured hard-resolve rate 0..1 on the panel named in `source`; NULL when the receipt recorded none.
+	 */
 	hard_resolve_rate: number | null
-	/** Panel size behind `hard_resolve_rate`; NULL when unrecorded. */
+	/**
+	 * Panel size behind `hard_resolve_rate`; NULL when unrecorded.
+	 */
 	sample_size: number | null
-	/** ISO-8601 date of the measurement / promote gate. */
+	/**
+	 * ISO-8601 date of the measurement / promote gate.
+	 */
 	measured_at: string
-	/** The receipt: which panel/gate produced this row. */
+	/**
+	 * The receipt: which panel/gate produced this row.
+	 */
 	source: string
 }
 
-/** One country's coarse guard-B bounding box — the storage form of {@link CountryBBoxFact}. */
+/**
+ * One country's coarse guard-B bounding box — the storage form of {@link CountryBBoxFact}.
+ */
 export interface CountryBBoxTable {
-	/** ISO 3166-1 alpha-2, uppercase (PK). */
+	/**
+	 * ISO 3166-1 alpha-2, uppercase (PK).
+	 */
 	country: string
 	lat_min: number
 	lat_max: number
 	lon_min: number
 	lon_max: number
-	/** Provenance of the box (harness + date). */
+	/**
+	 * Provenance of the box (harness + date).
+	 */
 	source: string
 }
 
-/** The coverage-manifest schema for `new DatabaseClient<GazetteerCoverageDatabase>(...)`. */
+/**
+ * The coverage-manifest schema for `new DatabaseClient<GazetteerCoverageDatabase>(...)`.
+ */
 export interface GazetteerCoverageDatabase {
 	country_coverage: CountryCoverageTable
 	country_bbox: CountryBBoxTable
 }
 
-/** Table names the lookup probes (existence-gated, so a candidate.db built before the manifest is byte-stable). */
+/**
+ * Table names the lookup probes (existence-gated, so a candidate.db built before the manifest is byte-stable).
+ */
 export const COUNTRY_COVERAGE_TABLE = "country_coverage"
+/**
+ * Table of per-country bounding boxes, used to reject a placement that fell outside its own country.
+ */
 export const COUNTRY_BBOX_TABLE = "country_bbox"
 
-/** Create `country_coverage` — a handful of small PK-probed rows, the WITHOUT ROWID sweet spot. */
+/**
+ * Create `country_coverage` — a handful of small PK-probed rows, the WITHOUT ROWID sweet spot.
+ */
 export async function createCountryCoverageTable(db: Kysely<GazetteerCoverageDatabase>): Promise<void> {
 	await db.schema
 		.createTable(COUNTRY_COVERAGE_TABLE)
@@ -89,7 +118,9 @@ export async function createCountryCoverageTable(db: Kysely<GazetteerCoverageDat
 		.execute()
 }
 
-/** Create `country_bbox` — same shape discipline as {@link createCountryCoverageTable}. */
+/**
+ * Create `country_bbox` — same shape discipline as {@link createCountryCoverageTable}.
+ */
 export async function createCountryBBoxTable(db: Kysely<GazetteerCoverageDatabase>): Promise<void> {
 	await db.schema
 		.createTable(COUNTRY_BBOX_TABLE)
@@ -115,7 +146,7 @@ export async function writeGazetteerCoverageManifest(
 	await createCountryCoverageTable(db)
 	await createCountryBBoxTable(db)
 
-	if (facts.coverage.length > 0) {
+	if (facts.coverage.length) {
 		await db
 			.insertInto(COUNTRY_COVERAGE_TABLE)
 			.values(
@@ -131,7 +162,7 @@ export async function writeGazetteerCoverageManifest(
 			.execute()
 	}
 
-	if (facts.bboxes.length > 0) {
+	if (facts.bboxes.length) {
 		await db
 			.insertInto(COUNTRY_BBOX_TABLE)
 			.values(
@@ -171,6 +202,7 @@ export function readGazetteerCoverageManifest(db: DatabaseSync): GazetteerArtifa
 
 		for (const row of rows) {
 			const country = String(row.country).toUpperCase()
+
 			countryCoverage.set(country, {
 				country,
 				hardFilterSafe: Number(row.hard_filter_safe) !== 0,
@@ -191,6 +223,7 @@ export function readGazetteerCoverageManifest(db: DatabaseSync): GazetteerArtifa
 
 		for (const row of rows) {
 			const country = String(row.country).toUpperCase()
+
 			countryBBoxes.set(country, {
 				country,
 				latMin: Number(row.lat_min),

package/fst-autocomplete.ts

@@ -17,7 +17,8 @@
  *       needs; without it "new yor" returns nothing useful. (#587)
  */
 
-import { FSTMatcher, normalizeTokens } from "./fst-matcher.ts"
+import type { FSTMatcher } from "./fst-matcher.ts"
+import { normalizeTokens } from "./fst-matcher.ts"
 import type { PlaceEntry } from "./fst-types.ts"
 
 export interface AutocompleteResult {
@@ -54,7 +55,9 @@ interface BfsItem {
 	tokens: string[]
 }
 
-/** Max accepting entries collected per BFS branch — keeps one dense branch from starving the search. */
+/**
+ * Max accepting entries collected per BFS branch — keeps one dense branch from starving the search.
+ */
 const PER_BRANCH = 4
 
 /**
@@ -63,7 +66,7 @@ const PER_BRANCH = 4
 function topByImportance(entries: readonly PlaceEntry[], k: number): PlaceEntry[] {
 	if (entries.length <= k) return [...entries]
 
-	return [...entries].sort((a, b) => b.importance - a.importance).slice(0, k)
+	return [...entries].toSorted((a, b) => b.importance - a.importance).slice(0, k)
 }
 
 /**
@@ -74,13 +77,13 @@ export function autocomplete(fst: FSTMatcher, query: string, opts: AutocompleteO
 	const maxExpansionDepth = opts.maxExpansionDepth ?? 2
 	const normalizedTokens = normalizeTokens(query)
 
-	if (normalizedTokens.length === 0) {
+	if (!normalizedTokens.length) {
 		return { query, normalizedTokens: [], depth: 0, suggestions: [] }
 	}
 
 	const seen = new Map<number, AutocompleteSuggestion>()
 	const queue: BfsItem[] = []
-	let depth = 0
+	let depth: number
 
 	const match = fst.walk(normalizedTokens)
 
@@ -98,12 +101,13 @@ export function autocomplete(fst: FSTMatcher, query: string, opts: AutocompleteO
 	} else {
 		// PARTIAL last token — walk the complete prefix, complete the partial by prefix-filtering edges.
 		const complete = normalizedTokens.slice(0, -1)
-		const partial = normalizedTokens[normalizedTokens.length - 1]!
-		const prefixState = complete.length === 0 ? 0 : (fst.walk(complete)?.stateID ?? undefined)
+		const partial = normalizedTokens.at(-1)!
+		const prefixState = !complete.length ? 0 : (fst.walk(complete)?.stateID ?? undefined)
 
 		if (prefixState === undefined) {
 			return { query, normalizedTokens, depth: 0, suggestions: [] }
 		}
+
 		depth = complete.length
 
 		for (const cont of fst.continuations(prefixState)) {
@@ -113,6 +117,7 @@ export function autocomplete(fst: FSTMatcher, query: string, opts: AutocompleteO
 			for (const entry of topByImportance(fst.accepting(cont.targetState), PER_BRANCH)) {
 				addSuggestion(seen, entry, complete.length + 1, [cont.token])
 			}
+
 			// BFS a little past it too (multi-token completions: "new yor" → "New York Mills").
 			queue.push({ stateID: cont.targetState, depth: 1, tokens: [cont.token] })
 		}
@@ -122,7 +127,7 @@ export function autocomplete(fst: FSTMatcher, query: string, opts: AutocompleteO
 	// branch contributes only its top PER_BRANCH places: a state like "new london" has dozens of
 	// accepting entries and would otherwise blow the budget before the BFS ever reaches "new york"
 	// (the "new" state has 311 continuations). Per-branch capping keeps the search broad. (#587)
-	while (queue.length > 0 && seen.size < maxSuggestions * 4) {
+	while (queue.length && seen.size < maxSuggestions * 4) {
 		const item = queue.shift()!
 
 		if (item.depth > maxExpansionDepth) continue
@@ -138,7 +143,7 @@ export function autocomplete(fst: FSTMatcher, query: string, opts: AutocompleteO
 		}
 	}
 
-	let suggestions = [...seen.values()].sort((a, b) => b.importance - a.importance)
+	let suggestions = [...seen.values()].toSorted((a, b) => b.importance - a.importance)
 
 	if (opts.dedupeByName) {
 		suggestions = dedupeByName(suggestions)
@@ -156,6 +161,7 @@ function addSuggestion(
 	const existing = seen.get(entry.wofID)
 
 	if (existing && existing.matchDepth <= matchDepth) return
+
 	seen.set(entry.wofID, {
 		name: entry.name,
 		placetype: entry.placetype,