@mailwoman/resolver-wof-sqlite 10.7.0 → 10.8.0

package/lib/fst/binary-matcher.ts

@@ -0,0 +1,379 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   An FST matcher that answers from the serialized binary in place.
+ *
+ *   {@link FSTMatcher} holds one `Map` per state and one object per place entry. For a national gazetteer those
+ *   objects take several times the size of the file. This matcher keeps the file's bytes and two typed-array hash tables: one from
+ *   an edge token to its string index, and one from a (state, string index) pair to the edge's target state. Place
+ *   entries are decoded when a query reaches their state.
+ */
+
+import type { AncestrieMatch } from "@mailwoman/ancestrie"
+import { hashFNV1a } from "@mailwoman/core/coarse-placer/fnv-hash"
+
+import {
+	EDGE_ENTRY_SIZE,
+	ENCYCLOPEDIC_OFFSET,
+	FST_FORMAT_VERSION,
+	FST_MAGIC_BYTES,
+	HEADER_SIZE,
+	LEGACY_PLACE_ENTRY_SIZE,
+	NARROW_STATE_ENTRY_SIZE,
+	PLACE_FLAG_HAS_ENCYCLOPEDIC,
+	PLACETYPE_ORDER,
+	SPLIT_PLACE_ENTRY_SIZE,
+	VERSION_TWO_SCORE_SPLIT,
+	VERSION_WIDE_STATE_COUNTERS,
+	WIDE_STATE_ENTRY_SIZE,
+} from "#fst/format"
+import { normalizeTokens } from "#fst/matcher"
+import type { FSTContinuation, FSTQueryResult, PlaceEntry } from "#fst/types"
+
+const EMPTY_SLOT = -1
+
+/**
+ * Returns the smallest power of two at least twice `count`, so each open-addressing
+ * table stays at most half full.
+ */
+function tableCapacity(count: number): number {
+	let capacity = 16
+
+	while (capacity < count * 2) {
+		capacity *= 2
+	}
+
+	return capacity
+}
+
+/**
+ * Mixes a state and a string index into one 32-bit hash.
+ */
+function edgeHash(stateID: number, stringIndex: number): number {
+	let h = Math.imul(stateID ^ 0x9e_37_79_b9, 0x85_eb_ca_6b) ^ Math.imul(stringIndex ^ 0xc2_b2_ae_35, 0x27_d4_eb_2f)
+
+	h ^= h >>> 15
+
+	return Math.imul(h, 0x2c_1b_3c_6d) >>> 0
+}
+
+/**
+ * Reads an FST binary in the format `serializeFST` writes, versions 1 through
+ * {@link FST_FORMAT_VERSION}, without decoding it into objects.
+ */
+export class BinaryFSTMatcher {
+	readonly stateCount: number
+	readonly #view: DataView
+	readonly #bytes: Uint8Array
+	readonly #decoder = new TextDecoder("utf-8")
+	readonly #version: number
+	readonly #isWide: boolean
+	readonly #isSplit: boolean
+	readonly #hasAmbiguity: boolean
+	readonly #stateEntrySize: number
+	readonly #placeEntrySize: number
+	readonly #stringDataStart: number
+	readonly #stateTableStart: number
+	readonly #edgeTableStart: number
+	readonly #placeTableStart: number
+	readonly #stringOffsets: Uint32Array
+	readonly #tokenSlots: Int32Array
+	readonly #edgeSlotState: Int32Array
+	readonly #edgeSlotString: Uint32Array
+	readonly #edgeSlotTarget: Uint32Array
+	#placeCount: number | null = null
+
+	constructor(input: ArrayBuffer | Uint8Array) {
+		const bytes = input instanceof ArrayBuffer ? new Uint8Array(input) : input
+		const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+
+		if (bytes.byteLength < HEADER_SIZE) throw new Error("FST buffer too small for header")
+
+		if (FST_MAGIC_BYTES.some((byte, index) => bytes[index] !== byte)) {
+			throw new Error("FST magic mismatch")
+		}
+
+		const version = view.getUint16(4, true)
+
+		if (version < 1 || version > FST_FORMAT_VERSION) {
+			throw new Error(`FST version ${version} unsupported (expected 1..${FST_FORMAT_VERSION})`)
+		}
+
+		this.#bytes = bytes
+		this.#view = view
+		this.#version = version
+		this.#isWide = version >= VERSION_WIDE_STATE_COUNTERS
+		this.#isSplit = version >= VERSION_TWO_SCORE_SPLIT
+		// Flags bit 0, as `serializeFST` writes it: place rows include surface-ambiguity data.
+		this.#hasAmbiguity = (view.getUint16(6, true) & 1) === 1
+		this.#stateEntrySize = this.#isWide ? WIDE_STATE_ENTRY_SIZE : NARROW_STATE_ENTRY_SIZE
+		// Version 5 grew the place entry by the encyclopedic float.
+		this.#placeEntrySize = this.#isSplit ? SPLIT_PLACE_ENTRY_SIZE : LEGACY_PLACE_ENTRY_SIZE
+
+		const stateCount = view.getUint32(8, true)
+		const edgeCount = view.getUint32(12, true)
+		const stringCount = view.getUint32(20, true)
+		const stringBytes = view.getUint32(24, true)
+
+		this.stateCount = stateCount
+		this.#stringOffsets = new Uint32Array(stringCount + 1)
+
+		for (let index = 0; index <= stringCount; index++) {
+			this.#stringOffsets[index] = view.getUint32(HEADER_SIZE + index * 4, true)
+		}
+
+		this.#stringDataStart = HEADER_SIZE + (stringCount + 1) * 4
+		this.#stateTableStart = this.#stringDataStart + stringBytes
+		this.#edgeTableStart = this.#stateTableStart + stateCount * this.#stateEntrySize
+		this.#placeTableStart = this.#edgeTableStart + edgeCount * EDGE_ENTRY_SIZE
+
+		this.#tokenSlots = new Int32Array(tableCapacity(stringCount)).fill(EMPTY_SLOT)
+
+		const edgeCapacity = tableCapacity(edgeCount)
+
+		this.#edgeSlotState = new Int32Array(edgeCapacity).fill(EMPTY_SLOT)
+		this.#edgeSlotString = new Uint32Array(edgeCapacity)
+		this.#edgeSlotTarget = new Uint32Array(edgeCapacity)
+
+		const indexedTokens = new Uint8Array(stringCount)
+
+		for (let stateID = 0; stateID < stateCount; stateID++) {
+			const { edgeStart, edgeCount: stateEdgeCount } = this.#stateEntry(stateID)
+
+			for (let edge = 0; edge < stateEdgeCount; edge++) {
+				const entry = this.#edgeTableStart + (edgeStart + edge) * EDGE_ENTRY_SIZE
+				const stringIndex = view.getUint32(entry, true)
+
+				if (!indexedTokens[stringIndex]) {
+					indexedTokens[stringIndex] = 1
+					this.#indexToken(stringIndex)
+				}
+
+				this.#indexEdge(stateID, stringIndex, view.getUint32(entry + 4, true))
+			}
+		}
+	}
+
+	/**
+	 * The number of place entries over all states.
+	 */
+	get placeCount(): number {
+		if (this.#placeCount === null) {
+			let count = 0
+
+			for (let stateID = 0; stateID < this.stateCount; stateID++) {
+				count += this.#stateEntry(stateID).placeCount
+			}
+
+			this.#placeCount = count
+		}
+
+		return this.#placeCount
+	}
+
+	get nodeCount(): number {
+		return this.stateCount
+	}
+
+	walk(tokens: string[]): AncestrieMatch | null {
+		let stateID = 0
+
+		for (const token of tokens) {
+			if (stateID >= this.stateCount) return null
+
+			const next = this.#target(stateID, token)
+
+			// No edge enters the root.
+			// A target of 0 therefore marks a missing edge.
+			if (!next) return null
+			stateID = next
+		}
+
+		return { stateID, accepted: this.#stateEntry(stateID).placeCount > 0, depth: tokens.length }
+	}
+
+	walkFrom(prev: Pick<AncestrieMatch, "stateID" | "depth">, token: string): AncestrieMatch | null {
+		if (prev.stateID >= this.stateCount) return null
+
+		const next = this.#target(prev.stateID, token)
+
+		if (!next) return null
+
+		return { stateID: next, accepted: this.#stateEntry(next).placeCount > 0, depth: prev.depth + 1 }
+	}
+
+	accepting(stateID: number): PlaceEntry[] {
+		if (stateID < 0 || stateID >= this.stateCount) return []
+
+		const { placeStart, placeCount } = this.#stateEntry(stateID)
+		const places: PlaceEntry[] = new Array(placeCount)
+
+		for (let index = 0; index < placeCount; index++) {
+			places[index] = this.#placeAt(placeStart + index)
+		}
+
+		return places
+	}
+
+	continuations(stateID: number): FSTContinuation[] {
+		if (stateID < 0 || stateID >= this.stateCount) return []
+
+		const { edgeStart, edgeCount } = this.#stateEntry(stateID)
+		const result: FSTContinuation[] = []
+
+		for (let edge = 0; edge < edgeCount; edge++) {
+			const entry = this.#edgeTableStart + (edgeStart + edge) * EDGE_ENTRY_SIZE
+			const targetState = this.#view.getUint32(entry + 4, true)
+
+			result.push({
+				token: this.#string(this.#view.getUint32(entry, true)),
+				targetState,
+				acceptingCount: this.#stateEntry(targetState).placeCount,
+			})
+		}
+
+		return result
+	}
+
+	query(text: string): FSTQueryResult {
+		const tokens = normalizeTokens(text)
+		let stateID = 0
+		let depth = 0
+
+		for (const token of tokens) {
+			const next = this.#target(stateID, token)
+
+			if (!next) break
+			stateID = next
+
+			depth++
+		}
+
+		return {
+			path: tokens.slice(0, depth),
+			stateID,
+			accepting: this.accepting(stateID),
+			continuations: this.continuations(stateID),
+		}
+	}
+
+	#stateEntry(stateID: number): { edgeStart: number; placeStart: number; edgeCount: number; placeCount: number } {
+		const entry = this.#stateTableStart + stateID * this.#stateEntrySize
+		const view = this.#view
+
+		return {
+			edgeStart: view.getUint32(entry, true),
+			placeStart: view.getUint32(entry + 4, true),
+			edgeCount: this.#isWide ? view.getUint32(entry + 8, true) : view.getUint16(entry + 8, true),
+			placeCount: this.#isWide ? view.getUint32(entry + 12, true) : view.getUint16(entry + 10, true),
+		}
+	}
+
+	#string(stringIndex: number): string {
+		const start = this.#stringDataStart + this.#stringOffsets[stringIndex]!
+		const end = this.#stringDataStart + this.#stringOffsets[stringIndex + 1]!
+
+		return this.#decoder.decode(this.#bytes.subarray(start, end))
+	}
+
+	#indexToken(stringIndex: number): void {
+		const mask = this.#tokenSlots.length - 1
+		let slot = hashFNV1a(this.#string(stringIndex)) & mask
+
+		while (this.#tokenSlots[slot] !== EMPTY_SLOT) {
+			slot = (slot + 1) & mask
+		}
+
+		this.#tokenSlots[slot] = stringIndex
+	}
+
+	/**
+	 * Returns the string index of `token` among the edge tokens, or -1 when no edge has that token.
+	 */
+	#tokenIndex(token: string): number {
+		const mask = this.#tokenSlots.length - 1
+		let slot = hashFNV1a(token) & mask
+
+		for (;;) {
+			const stringIndex = this.#tokenSlots[slot]!
+
+			if (stringIndex === EMPTY_SLOT) return -1
+
+			if (this.#string(stringIndex) === token) return stringIndex
+			slot = (slot + 1) & mask
+		}
+	}
+
+	#indexEdge(stateID: number, stringIndex: number, target: number): void {
+		const mask = this.#edgeSlotState.length - 1
+		let slot = edgeHash(stateID, stringIndex) & mask
+
+		for (;;) {
+			const occupant = this.#edgeSlotState[slot]!
+
+			if (occupant === EMPTY_SLOT || (occupant === stateID && this.#edgeSlotString[slot] === stringIndex)) break
+			slot = (slot + 1) & mask
+		}
+
+		// A repeated (state, token) pair keeps its last target, as `Map.set` does in the object deserializer.
+		this.#edgeSlotState[slot] = stateID
+		this.#edgeSlotString[slot] = stringIndex
+		this.#edgeSlotTarget[slot] = target
+	}
+
+	/**
+	 * Returns the state the edge labeled `token` leads to from `stateID`, or 0 when there is no such edge.
+	 */
+	#target(stateID: number, token: string): number {
+		const stringIndex = this.#tokenIndex(token)
+
+		if (stringIndex < 0) return 0
+
+		const mask = this.#edgeSlotState.length - 1
+		let slot = edgeHash(stateID, stringIndex) & mask
+
+		for (;;) {
+			const occupant = this.#edgeSlotState[slot]!
+
+			if (occupant === EMPTY_SLOT) return 0
+
+			if (occupant === stateID && this.#edgeSlotString[slot] === stringIndex) return this.#edgeSlotTarget[slot]!
+			slot = (slot + 1) & mask
+		}
+	}
+
+	#placeAt(placeIndex: number): PlaceEntry {
+		const view = this.#view
+		const entry = this.#placeTableStart + placeIndex * this.#placeEntrySize
+		const chainLength = view.getUint8(entry + 5)
+		const parentChain: number[] = new Array(chainLength)
+
+		for (let index = 0; index < chainLength; index++) {
+			parentChain[index] = view.getUint32(entry + 24 + index * 4, true)
+		}
+
+		// Version 1 stored a raw population u32 here, and later versions store the referential score.
+		// `deserializeFST` explains why a version 1 value converts to the referential score this way.
+		const referential =
+			this.#version >= 2
+				? view.getFloat32(entry + 12, true)
+				: Math.min(1, Math.log2(1 + view.getUint32(entry + 12, true) / 1000) / 14)
+
+		const hasEncyclopedic =
+			this.#isSplit && (view.getUint8(entry + 7) & PLACE_FLAG_HAS_ENCYCLOPEDIC) === PLACE_FLAG_HAS_ENCYCLOPEDIC
+
+		return {
+			wofID: view.getUint32(entry, true),
+			placetype: PLACETYPE_ORDER[view.getUint8(entry + 4)] ?? "locality",
+			name: this.#string(view.getUint32(entry + 8, true)),
+			referential,
+			lat: view.getFloat32(entry + 16, true),
+			lon: view.getFloat32(entry + 20, true),
+			parentChain,
+			crossCountryBranches: this.#hasAmbiguity ? view.getUint8(entry + 6) : null,
+			encyclopedic: hasEncyclopedic ? view.getFloat32(entry + ENCYCLOPEDIC_OFFSET, true) : null,
+		}
+	}
+}

package/lib/fst/builder.ts

@@ -260,7 +260,7 @@ export async function buildFSTFromWOF(opts: BuildFSTOpts): Promise<{
 			const node = nodes[stateID]!
 			let next = node.edges.get(t)
 
-			if (next === undefined) {
+			if (!next) {
 				next = nodes.length
 				nodes.push({ edges: new Map(), places: [] })
 				node.edges.set(t, next)

package/lib/fst/deserialize-web.ts

@@ -3,155 +3,26 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Browser-compatible FST deserializer. Uses DataView + TextDecoder instead of Node's Buffer so the
- *   same binary format loads in the browser through fetch(url).then(r => r.arrayBuffer()).
+ *   Browser-compatible FST reader. Uses DataView + TextDecoder instead of Node's Buffer so the same binary format
+ *   loads in the browser and in a Cloudflare Worker through fetch(url).then(r => r.arrayBuffer()).
  *
- *   This is a read-only counterpart to fst-serialize.ts. Serialization stays Node-only because it is
- *   a build-time operation.
+ *   This is a read-only counterpart to serialize.ts. Serialization stays Node-only because it is a build-time
+ *   operation.
  */
 
 import { tryParsingJSON } from "@mailwoman/core/json"
 
-import {
-	EDGE_ENTRY_SIZE,
-	ENCYCLOPEDIC_OFFSET,
-	FST_FORMAT_VERSION,
-	FST_MAGIC_BYTES,
-	HEADER_SIZE,
-	LEGACY_PLACE_ENTRY_SIZE,
-	NARROW_STATE_ENTRY_SIZE,
-	PLACE_FLAG_HAS_ENCYCLOPEDIC,
-	PLACETYPE_ORDER,
-	SPLIT_PLACE_ENTRY_SIZE,
-	VERSION_TWO_SCORE_SPLIT,
-	VERSION_WIDE_STATE_COUNTERS,
-	VERSION_WITH_METADATA,
-	WIDE_STATE_ENTRY_SIZE,
-} from "#fst/format"
-import type { FSTNode } from "#fst/matcher"
-import { FSTMatcher } from "#fst/matcher"
-import type { FSTProvenance, PlaceEntry } from "#fst/types"
+import { BinaryFSTMatcher } from "#fst/binary-matcher"
+import { HEADER_SIZE, VERSION_WITH_METADATA } from "#fst/format"
+import type { FSTProvenance } from "#fst/types"
 
-export function deserializeFSTWeb(input: ArrayBuffer | Uint8Array): FSTMatcher {
-	const bytes = input instanceof ArrayBuffer ? new Uint8Array(input) : input
-	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
-	const decoder = new TextDecoder("utf-8")
-
-	if (bytes.byteLength < HEADER_SIZE) throw new Error("FST buffer too small for header")
-
-	if (
-		bytes[0] !== FST_MAGIC_BYTES[0] ||
-		bytes[1] !== FST_MAGIC_BYTES[1] ||
-		bytes[2] !== FST_MAGIC_BYTES[2] ||
-		bytes[3] !== FST_MAGIC_BYTES[3]
-	) {
-		throw new Error("FST magic mismatch")
-	}
-
-	const version = view.getUint16(4, true)
-
-	if (version < 1 || version > FST_FORMAT_VERSION) {
-		throw new Error(`FST version ${version} unsupported (expected 1..${FST_FORMAT_VERSION})`)
-	}
-
-	const isV2 = version >= 2
-	const isSplit = version >= VERSION_TWO_SCORE_SPLIT
-	// flags bit0 (mirrors fst-serialize.ts): place rows include surface-ambiguity data.
-	const hasAmbiguity = (view.getUint16(6, true) & 1) === 1
-
-	const stateCount = view.getUint32(8, true)
-	const edgeCount = view.getUint32(12, true)
-	const _placeCount = view.getUint32(16, true)
-	const stringCount = view.getUint32(20, true)
-	const stringBytes = view.getUint32(24, true)
-
-	let pos = HEADER_SIZE
-
-	const strOffsets = new Uint32Array(stringCount + 1)
-
-	for (let i = 0; i <= stringCount; i++) {
-		strOffsets[i] = view.getUint32(pos, true)
-		pos += 4
-	}
-
-	const strDataStart = pos
-	const strings: string[] = new Array(stringCount)
-
-	for (let i = 0; i < stringCount; i++) {
-		const start = strDataStart + strOffsets[i]!
-		const end = strDataStart + strOffsets[i + 1]!
-		strings[i] = decoder.decode(bytes.subarray(start, end))
-	}
-
-	pos += stringBytes
-
-	const stateEntrySize = version >= VERSION_WIDE_STATE_COUNTERS ? WIDE_STATE_ENTRY_SIZE : NARROW_STATE_ENTRY_SIZE
-	// v5 grew the place entry by the encyclopedic float. v4-and-below files are read at the old stride.
-	const placeEntrySize = isSplit ? SPLIT_PLACE_ENTRY_SIZE : LEGACY_PLACE_ENTRY_SIZE
-	const stateTableStart = pos
-	const edgeTableStart = stateTableStart + stateCount * stateEntrySize
-	const placeTableStart = edgeTableStart + edgeCount * EDGE_ENTRY_SIZE
-
-	const nodes: FSTNode[] = new Array(stateCount)
-
-	for (let si = 0; si < stateCount; si++) {
-		const sp = stateTableStart + si * stateEntrySize
-		const edgeStart = view.getUint32(sp, true)
-		const placeStart = view.getUint32(sp + 4, true)
-
-		const edgeCountForState =
-			version >= VERSION_WIDE_STATE_COUNTERS ? view.getUint32(sp + 8, true) : view.getUint16(sp + 8, true)
-
-		const placeCountForState =
-			version >= VERSION_WIDE_STATE_COUNTERS ? view.getUint32(sp + 12, true) : view.getUint16(sp + 10, true)
-
-		const edges = new Map<string, number>()
-
-		for (let ei = 0; ei < edgeCountForState; ei++) {
-			const ep = edgeTableStart + (edgeStart + ei) * EDGE_ENTRY_SIZE
-			const stringIdx = view.getUint32(ep, true)
-			const target = view.getUint32(ep + 4, true)
-			edges.set(strings[stringIdx]!, target)
-		}
-
-		const places: PlaceEntry[] = new Array(placeCountForState)
-
-		for (let pi = 0; pi < placeCountForState; pi++) {
-			const pp = placeTableStart + (placeStart + pi) * placeEntrySize
-			const chainLen = view.getUint8(pp + 5)
-			const parentChain: number[] = []
-
-			for (let ci = 0; ci < chainLen; ci++) {
-				parentChain.push(view.getUint32(pp + 24 + ci * 4, true))
-			}
-
-			// v1 stored a raw population u32 here. v2-v4 stored the conflated `importance`
-			// float. v5 stored the referential score.
-			// The Node deserializer explains why a v1 value is the referential score.
-			const referential = isV2
-				? view.getFloat32(pp + 12, true)
-				: Math.min(1, Math.log2(1 + view.getUint32(pp + 12, true) / 1000) / 14)
-
-			const hasEncyclopedic =
-				isSplit && (view.getUint8(pp + 7) & PLACE_FLAG_HAS_ENCYCLOPEDIC) === PLACE_FLAG_HAS_ENCYCLOPEDIC
-
-			places[pi] = {
-				wofID: view.getUint32(pp, true),
-				placetype: PLACETYPE_ORDER[view.getUint8(pp + 4)] ?? "locality",
-				name: strings[view.getUint32(pp + 8, true)]!,
-				referential,
-				lat: view.getFloat32(pp + 16, true),
-				lon: view.getFloat32(pp + 20, true),
-				parentChain,
-				crossCountryBranches: hasAmbiguity ? view.getUint8(pp + 6) : null,
-				encyclopedic: hasEncyclopedic ? view.getFloat32(pp + ENCYCLOPEDIC_OFFSET, true) : null,
-			}
-		}
-
-		nodes[si] = { edges, places }
-	}
-
-	return FSTMatcher.fromNodes(nodes)
+/**
+ * Opens an FST binary for matching, answering queries from the bytes in place.
+ *
+ * The matcher keeps a reference to `input`, so the caller must not modify it afterward.
+ */
+export function deserializeFSTWeb(input: ArrayBuffer | Uint8Array): BinaryFSTMatcher {
+	return new BinaryFSTMatcher(input)
 }
 
 export function readFSTProvenanceWeb(input: ArrayBuffer | Uint8Array): FSTProvenance | null {

package/lib/fst/matcher.ts

@@ -47,7 +47,7 @@ export class FSTMatcher {
 			if (!node) return null
 			const next = node.edges.get(token)
 
-			if (next === undefined) return null
+			if (!next) return null
 			stateID = next
 		}
 
@@ -62,7 +62,7 @@ export class FSTMatcher {
 		if (!node) return null
 		const next = node.edges.get(token)
 
-		if (next === undefined) return null
+		if (!next) return null
 		const target = this.nodes[next]!
 
 		return { stateID: next, accepted: target.places.length > 0, depth: prev.depth + 1 }
@@ -106,7 +106,7 @@ export class FSTMatcher {
 				if (!node) break
 				const next = node.edges.get(t)
 
-				if (next === undefined) break
+				if (!next) break
 				stateID = next
 
 				depth++

package/lib/fst/serialize.ts

@@ -71,7 +71,7 @@ export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): B
 	function intern(s: string): number {
 		let idx = stringMap.get(s)
 
-		if (idx === undefined) {
+		if (typeof idx !== "number") {
 			idx = strings.length
 			strings.push(s)
 			stringMap.set(s, idx)

package/lib/fst.ts

@@ -5,6 +5,7 @@
  */
 
 export * from "#fst/autocomplete"
+export * from "#fst/binary-matcher"
 export * from "#fst/builder"
 export * from "#fst/deserialize-web"
 export * from "#fst/format"

package/lib/geonames/aliases.ts

@@ -220,7 +220,7 @@ export async function ingestGeonamesAliases(
 		let refused = 0
 
 		const addAdmin = opts?.adminForCountries?.has(cc) ?? false
-		const v2File = opts?.alternateDir ? resolvePathBuilder(opts.alternateDir, `${cc}.txt`) : undefined
+		const v2File = opts?.alternateDir ? resolvePathBuilder(opts.alternateDir, `${cc}.txt`) : null
 		const readV2 = Boolean(v2File && (await pathExists(v2File)))
 
 		const wanted = new Set<number>()
@@ -242,7 +242,7 @@ export async function ingestGeonamesAliases(
 			}
 		}
 
-		const v2 = readV2 ? await parseAlternateNamesV2(v2File!, cc, wanted) : undefined
+		const v2 = readV2 ? await parseAlternateNamesV2(v2File!, cc, wanted) : null
 
 		let countryID = -1
 		const adminMap = new Map<string, number>()

package/lib/interpolation.ts

@@ -8,7 +8,8 @@
 
 import { parseJSONStrict } from "@mailwoman/core/json"
 import type { InterpolationLookup } from "@mailwoman/core/resolver"
-import { clampFraction, haversineKm, pointAlong } from "@mailwoman/spatial"
+import { haversine } from "@mailwoman/spatial/geometries/point/distance"
+import { clampFraction, pointAlong } from "@mailwoman/spatial/polyline"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
 
 import { hasTable, prepareAll, type PreparedAll } from "#sqlite-utils"
@@ -100,7 +101,7 @@ function nearestPostcodeGroup(pool: readonly SegmentRow[], near: { lat: number;
 			const [firstVertex] = parseJSONStrict<[number, number][]>(row.geometry)
 
 			if (firstVertex) {
-				km = haversineKm(near.lat, near.lon, firstVertex[1], firstVertex[0])
+				km = haversine(near.lat, near.lon, firstVertex[1], firstVertex[0])
 			}
 		} catch {
 			// Unparseable geometry: this row cannot be sited, so it cannot win the tie-break.

package/lib/lookup.ts

@@ -9,7 +9,7 @@
 import { expandPlacetypeFilter } from "@mailwoman/codex/placetype-map"
 import type { Ancestor, CoincidentLocality } from "@mailwoman/core/resolver"
 import { allRows } from "@mailwoman/core/utils"
-import { haversineKm } from "@mailwoman/spatial"
+import { haversine } from "@mailwoman/spatial/geometries/point/distance"
 import type { DatabaseClient, SQLInputValue } from "@mailwoman/sqlite/client"
 import { SQLiteLookup } from "@mailwoman/sqlite/lookup"
 import type { PathBuilderLike } from "path-ts"
@@ -81,7 +81,7 @@ export interface WOFSQLitePlaceLookupOpts {
 	 *
 	 * Absent, every alias code path is skipped and the resolver is byte-identical.
 	 */
-	postalCityAliases?: WOFPostalCityAliasLookup
+	postalCityAliases?: WOFPostalCityAliasLookup | null
 }
 
 /**
@@ -168,7 +168,7 @@ export class WOFSQLitePlaceLookup extends SQLiteLookup<WOFDatabase> implements P
 	 */
 	readonly #postalCityAliases: WOFPostalCityAliasLookup | null
 
-	constructor(opts: WOFSQLitePlaceLookupOpts, weights?: Partial<RankingWeights>) {
+	constructor(opts: WOFSQLitePlaceLookupOpts, weights?: Partial<RankingWeights> | null) {
 		if (opts.database && opts.databasePath) {
 			throw new Error("WOFSQLitePlaceLookup: pass either `database` or `databasePath`, not both")
 		}
@@ -549,7 +549,7 @@ export class WOFSQLitePlaceLookup extends SQLiteLookup<WOFDatabase> implements P
 	#countryWOFId(code: string): number | null {
 		const cached = this.#countryWOFIdCache.get(code)
 
-		if (cached !== undefined) return cached
+		if (cached) return cached
 		let id: number | null
 
 		try {
@@ -666,12 +666,12 @@ export class WOFSQLitePlaceLookup extends SQLiteLookup<WOFDatabase> implements P
 				// 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.containing - a.containing || a.dist - b.dist)[0]
 
-			const anchor = anchorRow ? merged.get(anchorRow.id) : undefined
+			const anchor = anchorRow ? merged.get(anchorRow.id) : null
 
 			if (
 				anchor &&
 				(top.id as number) !== anchorRow!.id &&
-				haversineKm(top.lat, top.lon, anchor.lat, anchor.lon) > CF_MISMATCH_KM
+				haversine(top.lat, top.lon, anchor.lat, anchor.lon) > CF_MISMATCH_KM
 			) {
 				top.mismatch = true
 			}