@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

package/out/extracts.d.ts

@@ -1,33 +1,29 @@
+import { type PathBuilderLike } from "path-ts";
 /**
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Multi-extract support for `WOFSQLitePlaceLookup` — opens multiple WOF SQLite distributions on one
- *   connection via `ATTACH DATABASE`, and routes queries to the right extract based on placetype.
+ *   Multi-extract support for `WOFSQLitePlaceLookup`. It opens multiple WOF SQLite distributions
+ *   on one connection with `attach database`. It routes queries by placetype.
  *
- *   ## The FTS5 syntax rule that drove this design
- *
- *   The naive `SELECT … FROM pc.place_search WHERE pc.place_search MATCH ?` fails — SQLite parses the
- *   schema-qualified table on the left of MATCH as "column place_search of table pc". Discovered in
- *   the spike at PR review time; documented as `_EXTRACT_RULE.md` should it ever bite again.
- *
- *   The working form: schema-qualified in FROM, bare table name in MATCH:
+ *   SQLite parses a schema-qualified table on the left of `match` as "column place_search of table
+ *   pc", so the working form is schema-qualified in `from` and a bare table name in `match`:
  *
  *   ```sql
- *   SELECT … FROM pc.place_search WHERE place_search MATCH ?
+ *   select … from pc.place_search where place_search match ?
  * ```
  *
- *   Identical table names across attached extracts (which is what we have — every extract ships its own
- *   `place_search` + `place_bbox`) are fine because the bare-name MATCH resolves against FROM
- *   scope.
+ *   Identical table names across attached extracts are fine, because the bare-name `match` resolves
+ *   against `from` scope. Every extract ships its own `place_search` and `place_bbox`.
  */
 /**
- * Derive a SQL-safe schema name from a WOF distribution filename. Used by `ATTACH DATABASE … AS <name>` so each extract
- * gets a stable, predictable handle.
+ * Derive a SQL-safe schema name from a WOF distribution filename.
  *
- * Convention strips the `whosonfirst-data-` prefix and the `-latest.db` (or just `.db`) suffix, then replaces `-` with
- * `_` for SQL identifier safety.
+ * Used by `attach database … AS <name>` so each extract gets a stable, predictable handle.
+ *
+ * Convention strips the `whosonfirst-data-` prefix and the `-latest.db` (or just `.db`)
+ * suffix, then replaces `-` with `_` for SQL identifier safety.
  *
  * Examples:
  *
@@ -36,32 +32,42 @@
  * - `whosonfirst-data-admin-latest.db` → `admin`
  * - `my-custom.db` → `my_custom`
  *
- * Callers can override the derived name explicitly via `ExtractConfig.schemaName` when the filename doesn't follow WOF
- * convention.
+ * Callers can override the derived name explicitly via `ExtractConfig.schemaName`
+ * when the filename doesn't follow WOF convention.
  */
-export declare function deriveSchemaName(path: string): string;
+export declare function deriveSchemaName(path: PathBuilderLike): string;
 /**
- * Per-extract configuration. The simple form is just a path string — the schema name is derived from it. The object
- * form lets callers override the derived schema name (useful when a filename doesn't follow WOF convention) or attach
- * an extra hint about which placetypes route here.
+ * Per-extract configuration.
+ *
+ * The simple form is just a path string.
+ * The schema name is derived from it.
+ *
+ * The object form lets callers override the derived schema name (useful when a filename
+ * doesn't follow WOF convention) or attach an extra hint about which placetypes route here.
  */
 export interface ExtractConfig {
-    path: string;
+    path: PathBuilderLike;
     /**
-     * Override the auto-derived schema name. Useful when the filename doesn't match WOF convention or when you want a
-     * memorable handle. Must be a valid SQLite identifier — `[a-zA-Z_][a-zA-Z0-9_]*`.
+     * Override the auto-derived schema name.
+     *
+     * Useful when the filename does not match WOF convention or when you want a memorable handle.
+     * Must be a valid SQLite identifier matching `[a-zA-Z_][a-zA-Z0-9_]*`.
      */
     schemaName?: string;
     /**
-     * Optional explicit list of placetypes this extract serves. When set, queries against any listed placetype are routed
-     * to this extract. When omitted, routing falls back to a name-match heuristic: a extract whose `schemaName` contains
-     * the placetype as a substring (e.g. `postalcode_us` for `postalcode` queries) is preferred for that placetype.
+     * Optional explicit list of placetypes this extract serves.
+     *
+     * When set, queries against any listed placetype are routed to this extract.
+     * When omitted, routing falls back to a name-match heuristic: an extract whose `schemaName`
+     * contains the placetype as a substring (e.g. `postalcode_us` for `postalcode` queries)
+     * is preferred for that placetype.
      */
     placetypes?: readonly string[];
 }
 /**
- * Resolved post-derivation: paired path + chosen schema name + (possibly empty) placetypes hint. Used internally by
- * `WOFSQLitePlaceLookup` so the routing logic operates on uniform structures.
+ * Resolved post-derivation: paired path + chosen schema name + (possibly empty) placetypes hint.
+ *
+ * Used internally by `WOFSQLitePlaceLookup` so the routing logic operates on uniform structures.
  */
 export interface ResolvedExtract {
     path: string;
@@ -69,41 +75,46 @@ export interface ResolvedExtract {
     placetypes: readonly string[];
 }
 /**
- * Normalize the user-provided `databasePath` opt (which may be a single string, an array of strings, or an array of
- * `ExtractConfig` objects) into a uniform `ResolvedExtract[]`.
+ * Normalize the user-provided `databasePath` opt (which may be a single string, an array
+ * of strings, or an array of `ExtractConfig` objects) into a uniform `ResolvedExtract[]`.
  *
- * The first extract becomes `main` regardless of its derived schema name — that's the SQLite convention. Subsequent
- * extracts keep their derived (or override) schema name.
+ * The first extract becomes `main` regardless of its derived schema name, following SQLite convention.
+ * Subsequent extracts keep their derived or overridden schema name.
  */
-export declare function resolveExtracts(input: string | ReadonlyArray<string | ExtractConfig>): ResolvedExtract[];
+export declare function resolveExtracts(input: PathBuilderLike | ReadonlyArray<PathBuilderLike | ExtractConfig>): ResolvedExtract[];
+/**
+ * All placetype-matching extracts, in routing order (the country-aware pick chooses among these).
+ *
+ * Used by the bias path: a country-less postcode query with proximity hints fans out across
+ * every matching extract and merges, because single-extract routing would hide the cross-country
+ * ambiguity the hints exist to resolve ("48026" lives in postalcode-us and postalcode-intl).
+ */
+export declare function pickExtractsForPlacetype(extracts: ResolvedExtract[], placetype: string | undefined): ResolvedExtract[];
 /**
  * Pick the extract to route a query to given the requested placetype(s).
  *
- * Routing rules, in order:
+ * The resolver applies these routing rules in order:
  *
  * 1. If any extract has explicit `placetypes` that includes the requested placetype, use it.
- * 2. Otherwise, if a non-main extract's `schemaName` matches the placetype (e.g. `postalcode_us` matches `postalcode`),
- *    use it.
+ * 2. Otherwise, if a non-main extract's `schemaName` matches the placetype
+ *    (e.g. `postalcode_us` matches `postalcode`), use it.
  * 3. Otherwise, fall back to `main`.
  *
- * This deliberately doesn't UNION across extracts — BM25 scores aren't comparable across separately- indexed corpora,
- * and the typical mailwoman query has a single placetype anyway. If a caller needs cross-extract results they can issue
- * two `findPlace` calls.
- */
-/**
- * All placetype-matching extracts, in routing order (the country-aware pick chooses among these). Used by the bias
- * path: a country-less postcode query with proximity hints fans out across every matching extract and merges, because
- * single-extract routing would hide the cross-country ambiguity the hints exist to resolve ("48026" lives in
- * postalcode-us AND postalcode-intl).
+ * This deliberately does not union across extracts.
+ * BM25 scores are not comparable across separately indexed corpora.
+ * A typical mailwoman query has one placetype.
+ *
+ * Callers that need cross-extract results can issue two `findPlace` calls.
  */
-export declare function pickExtractsForPlacetype(extracts: ResolvedExtract[], placetype: string | undefined): ResolvedExtract[];
-export declare function pickExtractForPlacetype(extracts: ResolvedExtract[], placetype: string | undefined, opts?: {
+export declare function pickExtractForPlacetype(extracts: ResolvedExtract[], placetype: string | null, opts?: {
     /**
-     * #920: the query's country constraint, when the caller has one. With MULTIPLE extracts matching a placetype
-     * (postalcode-us + postalcode-geonames-tail), first-match routing sent every postcode query to the first extract
-     * and starved the rest — a FI postcode could never reach the tail extract. When `country` is given and a matching
-     * extract's probed country set contains it, that extract wins; extracts without the country are skipped; the
-     * placetype-match order remains the tiebreak when no extract claims the country (or none was probed).
+     * The query's country constraint, when the caller has one.
+     *
+     * When `country` is given and a matching extract's probed country set contains it, that extract wins.
+     * Extracts without the country are skipped.
+     *
+     * The placetype-match order remains the tiebreak when no extract claims
+     * the country (or none was probed).
      */
     country?: string;
     /**

package/out/extracts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extracts.d.ts","sourceRoot":"","sources":["../lib/extracts.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAYrD;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;CAC7B;AAOD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,GAAG,aAAa,CAAC,GAAG,eAAe,EAAE,CA0CxG;AAED;;;;;;;;;;;;;GAaG;AACH;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACvC,QAAQ,EAAE,eAAe,EAAE,EAC3B,SAAS,EAAE,MAAM,GAAG,SAAS,GAC3B,eAAe,EAAE,CAuBnB;AAED,wBAAgB,uBAAuB,CACtC,QAAQ,EAAE,eAAe,EAAE,EAC3B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,IAAI,CAAC,EAAE;IACN;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,iBAAiB,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAA;CAC5D,GACC,eAAe,CAmCjB"}
+{"version":3,"file":"extracts.d.ts","sourceRoot":"","sources":["../lib/extracts.ts"],"names":[],"mappings":"AACA,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,SAAS,CAAA;AAErE;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAY9D;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,eAAe,CAAA;IACrB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;CAC7B;AAgBD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC9B,KAAK,EAAE,eAAe,GAAG,aAAa,CAAC,eAAe,GAAG,aAAa,CAAC,GACrE,eAAe,EAAE,CA2CnB;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACvC,QAAQ,EAAE,eAAe,EAAE,EAC3B,SAAS,EAAE,MAAM,GAAG,SAAS,GAC3B,eAAe,EAAE,CAuBnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CACtC,QAAQ,EAAE,eAAe,EAAE,EAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,IAAI,CAAC,EAAE;IACN;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,iBAAiB,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAA;CAC5D,GACC,eAAe,CAmCjB"}

package/out/extracts.js

@@ -1,34 +1,30 @@
-import { basename } from "path-ts";
+import { stringifyJSON } from "@mailwoman/core/json";
+import { basename, PathBuilder } from "path-ts";
 /**
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Multi-extract support for `WOFSQLitePlaceLookup` — opens multiple WOF SQLite distributions on one
- *   connection via `ATTACH DATABASE`, and routes queries to the right extract based on placetype.
+ *   Multi-extract support for `WOFSQLitePlaceLookup`. It opens multiple WOF SQLite distributions
+ *   on one connection with `attach database`. It routes queries by placetype.
  *
- *   ## The FTS5 syntax rule that drove this design
- *
- *   The naive `SELECT … FROM pc.place_search WHERE pc.place_search MATCH ?` fails — SQLite parses the
- *   schema-qualified table on the left of MATCH as "column place_search of table pc". Discovered in
- *   the spike at PR review time; documented as `_EXTRACT_RULE.md` should it ever bite again.
- *
- *   The working form: schema-qualified in FROM, bare table name in MATCH:
+ *   SQLite parses a schema-qualified table on the left of `match` as "column place_search of table
+ *   pc", so the working form is schema-qualified in `from` and a bare table name in `match`:
  *
  *   ```sql
- *   SELECT … FROM pc.place_search WHERE place_search MATCH ?
+ *   select … from pc.place_search where place_search match ?
  * ```
  *
- *   Identical table names across attached extracts (which is what we have — every extract ships its own
- *   `place_search` + `place_bbox`) are fine because the bare-name MATCH resolves against FROM
- *   scope.
+ *   Identical table names across attached extracts are fine, because the bare-name `match` resolves
+ *   against `from` scope. Every extract ships its own `place_search` and `place_bbox`.
  */
 /**
- * Derive a SQL-safe schema name from a WOF distribution filename. Used by `ATTACH DATABASE … AS <name>` so each extract
- * gets a stable, predictable handle.
+ * Derive a SQL-safe schema name from a WOF distribution filename.
+ *
+ * Used by `attach database … AS <name>` so each extract gets a stable, predictable handle.
  *
- * Convention strips the `whosonfirst-data-` prefix and the `-latest.db` (or just `.db`) suffix, then replaces `-` with
- * `_` for SQL identifier safety.
+ * Convention strips the `whosonfirst-data-` prefix and the `-latest.db` (or just `.db`)
+ * suffix, then replaces `-` with `_` for SQL identifier safety.
  *
  * Examples:
  *
@@ -37,56 +33,65 @@ import { basename } from "path-ts";
  * - `whosonfirst-data-admin-latest.db` → `admin`
  * - `my-custom.db` → `my_custom`
  *
- * Callers can override the derived name explicitly via `ExtractConfig.schemaName` when the filename doesn't follow WOF
- * convention.
+ * Callers can override the derived name explicitly via `ExtractConfig.schemaName`
+ * when the filename doesn't follow WOF convention.
  */
 export function deriveSchemaName(path) {
-    const stem = basename(path)
+    const stem = basename(path.toString())
         .replace(/^whosonfirst-data-/u, "")
         .replace(/-latest\.db$/u, "")
         .replace(/\.db$/u, "")
         .replaceAll(/[^a-zA-Z0-9_]/g, "_");
     if (!stem) {
-        throw new Error(`deriveSchemaName: could not derive a SQL schema name from path ${JSON.stringify(path)}`);
+        throw new Error(`deriveSchemaName: could not derive a SQL schema name from path ${stringifyJSON(path)}`);
     }
     return stem;
 }
 /**
- * SQLite identifier regex — `[A-Za-z_][A-Za-z0-9_]*`.
+ * SQLite identifier regex matching `[A-Za-z_][A-Za-z0-9_]*`.
  */
 const SQLITE_IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/u;
 /**
- * Normalize the user-provided `databasePath` opt (which may be a single string, an array of strings, or an array of
- * `ExtractConfig` objects) into a uniform `ResolvedExtract[]`.
+ * Whether a `databasePath` entry is a path or an {@link ExtractConfig}.
+ *
+ * A builder is a `String` object, so `typeof` by itself reads it as an object.
+ */
+function isPathBuilderLike(value) {
+    return typeof value === "string" || value instanceof PathBuilder;
+}
+/**
+ * Normalize the user-provided `databasePath` opt (which may be a single string, an array
+ * of strings, or an array of `ExtractConfig` objects) into a uniform `ResolvedExtract[]`.
  *
- * The first extract becomes `main` regardless of its derived schema name — that's the SQLite convention. Subsequent
- * extracts keep their derived (or override) schema name.
+ * The first extract becomes `main` regardless of its derived schema name, following SQLite convention.
+ * Subsequent extracts keep their derived or overridden schema name.
  */
 export function resolveExtracts(input) {
-    const list = typeof input === "string" ? [input] : input;
+    const list = isPathBuilderLike(input) ? [input] : input;
     if (!list.length)
         throw new Error("resolveExtracts: at least one extract is required");
     const seen = new Set();
     const out = [];
     for (let i = 0; i < list.length; i++) {
         const entry = list[i];
-        const cfg = typeof entry === "string" ? { path: entry } : entry;
+        const cfg = isPathBuilderLike(entry) ? { path: entry } : entry;
         const derived = cfg.schemaName ?? deriveSchemaName(cfg.path);
         if (!SQLITE_IDENT_RE.test(derived)) {
-            throw new Error(`resolveExtracts: schema name ${JSON.stringify(derived)} is not a valid SQLite identifier ` +
-                `(derived from path ${JSON.stringify(cfg.path)}). Pass an explicit ` +
+            throw new Error(`resolveExtracts: schema name ${stringifyJSON(derived)} is not a valid SQLite identifier ` +
+                `(derived from path ${stringifyJSON(cfg.path)}). Pass an explicit ` +
                 `{ path, schemaName } to override.`);
         }
-        // The first extract is always main per SQLite semantics — its derived name is informational
-        // only. Subsequent extracts must have unique non-main names.
+        // SQLite always treats the first extract as main.
+        // Its derived name is informational only.
+        // Subsequent extracts must have unique non-main names.
         const schemaName = i === 0 ? "main" : derived;
         if (i > 0 && (schemaName === "main" || seen.has(schemaName))) {
-            throw new Error(`resolveExtracts: schema name ${JSON.stringify(schemaName)} collides ` +
+            throw new Error(`resolveExtracts: schema name ${stringifyJSON(schemaName)} collides ` +
                 `(either with "main" or another extract). Pass an explicit { path, schemaName }.`);
         }
         seen.add(schemaName);
         out.push({
-            path: cfg.path,
+            path: cfg.path.toString(),
             schemaName,
             placetypes: cfg.placetypes ?? [],
         });
@@ -94,24 +99,11 @@ export function resolveExtracts(input) {
     return out;
 }
 /**
- * Pick the extract to route a query to given the requested placetype(s).
- *
- * Routing rules, in order:
- *
- * 1. If any extract has explicit `placetypes` that includes the requested placetype, use it.
- * 2. Otherwise, if a non-main extract's `schemaName` matches the placetype (e.g. `postalcode_us` matches `postalcode`),
- *    use it.
- * 3. Otherwise, fall back to `main`.
+ * All placetype-matching extracts, in routing order (the country-aware pick chooses among these).
  *
- * This deliberately doesn't UNION across extracts — BM25 scores aren't comparable across separately- indexed corpora,
- * and the typical mailwoman query has a single placetype anyway. If a caller needs cross-extract results they can issue
- * two `findPlace` calls.
- */
-/**
- * All placetype-matching extracts, in routing order (the country-aware pick chooses among these). Used by the bias
- * path: a country-less postcode query with proximity hints fans out across every matching extract and merges, because
- * single-extract routing would hide the cross-country ambiguity the hints exist to resolve ("48026" lives in
- * postalcode-us AND postalcode-intl).
+ * Used by the bias path: a country-less postcode query with proximity hints fans out across
+ * every matching extract and merges, because single-extract routing would hide the cross-country
+ * ambiguity the hints exist to resolve ("48026" lives in postalcode-us and postalcode-intl).
  */
 export function pickExtractsForPlacetype(extracts, placetype) {
     if (!placetype)
@@ -133,6 +125,22 @@ export function pickExtractsForPlacetype(extracts, placetype) {
     }
     return matches.length ? matches : [extracts[0]];
 }
+/**
+ * Pick the extract to route a query to given the requested placetype(s).
+ *
+ * The resolver applies these routing rules in order:
+ *
+ * 1. If any extract has explicit `placetypes` that includes the requested placetype, use it.
+ * 2. Otherwise, if a non-main extract's `schemaName` matches the placetype
+ *    (e.g. `postalcode_us` matches `postalcode`), use it.
+ * 3. Otherwise, fall back to `main`.
+ *
+ * This deliberately does not union across extracts.
+ * BM25 scores are not comparable across separately indexed corpora.
+ * A typical mailwoman query has one placetype.
+ *
+ * Callers that need cross-extract results can issue two `findPlace` calls.
+ */
 export function pickExtractForPlacetype(extracts, placetype, opts) {
     if (!placetype)
         return extracts[0];
@@ -145,9 +153,9 @@ export function pickExtractForPlacetype(extracts, placetype, opts) {
     for (const s of extracts) {
         if (s.schemaName === "main" || matches.includes(s))
             continue;
-        // Substring match: `postalcode_us` matches `postalcode`. Conservative — requires the
-        // placetype to appear at a word boundary in the schema name to avoid false hits like
-        // `region` matching `arboregion`.
+        // A substring match lets `postalcode_us` match `postalcode`.
+        // Conservative, requiring the placetype at a word boundary in the schema name
+        // to avoid false hits like `region` matching `arboregion`.
         if (s.schemaName === placetype ||
             s.schemaName.startsWith(`${placetype}_`) ||
             s.schemaName.endsWith(`_${placetype}`)) {

package/out/extracts.js.map

@@ -1 +1 @@
-{"version":3,"file":"extracts.js","sourceRoot":"","sources":["../lib/extracts.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"extracts.js","sourceRoot":"","sources":["../lib/extracts.ts"],"names":[],"mappings":"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"}

package/out/fst/autocomplete.d.ts

@@ -3,18 +3,18 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   FST-based autocomplete — mailwoman vocabulary over `@mailwoman/ancestrie`'s generic algorithm
- *   (#1728 phase 2). The #587 behavior — prefix walk + BFS expansion, partial-last-token completion,
- *   per-branch capping, dedupe — lives in ancestrie's `autocomplete`; this module contributes only
- *   the storage adapter ({@link FSTMatcher} → `AncestrieReaderLike`) and the mapping back to
- *   mailwoman's suggestion shape (name, placetype, referential/encyclopedic, WOF ids).
+ *   FST-based autocomplete, mailwoman vocabulary over `@mailwoman/ancestrie`'s generic algorithm.
+ *   The prefix walk, BFS expansion, partial-last-token completion, per-branch capping and dedupe
+ *   live in ancestrie's `autocomplete`. This module contributes only the storage adapter
+ *   ({@link FSTMatcher} → `AncestrieReaderLike`) and the mapping back to mailwoman's suggestion
+ *   shape (name, placetype, referential and encyclopedic scores, WOF ids).
  *
- *   THE BYTES DO NOT MIGRATE. The shipped artifacts are `FST\0` v1–v5 (`fst-serialize.ts`), not
- *   ancestrie's `ANCT`: ancestrie entries are id-keyed with one record per id, while an FST place row
- *   is per-(surface, place) — `crossCountryBranches` is a property of the SURFACE, so the same wofID
- *   legitimately carries different values under different aliases and cannot be represented id-keyed.
- *   The matcher, both deserializers, and the serializer therefore stay here; what migrated is the
- *   ALGORITHM, which is the half that drifts (the #861 share-the-function rule).
+ *   The bytes do not migrate. The shipped artifacts are `FST\0` v1 to v5 (`fst-serialize.ts`), and
+ *   ancestrie's entries are id-keyed with one record per id. An FST place row is per-(surface,
+ *   place), because `crossCountryBranches` is a property of the surface, so the same wofID
+ *   legitimately has different values under different aliases, so it cannot use IDs as keys.
+ *   The matcher, both deserializers and serializer stay here. The algorithm is the
+ *   half that migrated.
  */
 import type { FSTMatcher } from "#fst/matcher";
 export interface AutocompleteResult {
@@ -27,16 +27,20 @@ export interface AutocompleteSuggestion {
     name: string;
     placetype: string;
     /**
-     * The REFERENTIAL likelihood the suggestion is ranked by (ROAD_TO_V9 §2). Autocomplete answers "which place does the
-     * user mean", so it ranks referentially like everything else; encyclopedic importance rides along on
-     * {@link AutocompleteSuggestion.encyclopedic} for display and never enters the order.
+     * The referential likelihood the suggestion is ranked by (ROAD_TO_V9 §2).
+     *
+     * Autocomplete answers "which place does the user mean", so it ranks referentially like everything else.
+     * Encyclopedic importance appears in {@link AutocompleteSuggestion.encyclopedic}
+     * for display and never enters the order.
      */
     referential: number;
     /**
-     * Encyclopedic (Wikipedia) importance, when the FST artifact carries one for this place. `undefined` = no article, or
-     * a pre-v5 binary — never 0.
+     * Encyclopedic (Wikipedia) importance, when the FST artifact stores one for this place.
+     *
+     * `undefined` means no article, or a pre-v5 binary.
+     * It is never 0.
      */
-    encyclopedic?: number;
+    encyclopedic: number | null;
     wofID: number;
     parentChain: number[];
     matchDepth: number;
@@ -46,14 +50,18 @@ export interface AutocompleteOpts {
     maxSuggestions?: number;
     maxExpansionDepth?: number;
     /**
-     * Collapse same-name suggestions to the single highest-referential one. Off by default (the CLI surfaces distinct
-     * same-name places — New York the city vs the county); a typeahead wants it ON so the dropdown isn't four "New
-     * London"s. (#587)
+     * Collapse same-name suggestions to the single highest-referential one.
+     *
+     * Off by default, because the CLI surfaces distinct same-name places such as
+     * New York the city and New York the county.
+     * A typeahead wants it on so the dropdown does not show four "New London"s.
      */
     dedupeByName?: boolean;
 }
 /**
- * Autocomplete from the current prefix. Returns suggestions ranked referential-descending.
+ * Autocomplete from the current prefix.
+ *
+ * @returns Suggestions ranked referential-descending.
  */
 export declare function autocomplete(fst: FSTMatcher, query: string, opts?: AutocompleteOpts): AutocompleteResult;
 //# sourceMappingURL=autocomplete.d.ts.map

package/out/fst/autocomplete.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"autocomplete.d.ts","sourceRoot":"","sources":["../../lib/fst/autocomplete.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAWH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAI9C,MAAM,WAAW,kBAAkB;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,gBAAgB,EAAE,MAAM,EAAE,CAAA;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,sBAAsB,EAAE,CAAA;CACrC;AAED,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB,gBAAgB,EAAE,MAAM,EAAE,CAAA;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAChC,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACtB;AAyED;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,gBAAqB,GAAG,kBAAkB,CA+B5G"}
+{"version":3,"file":"autocomplete.d.ts","sourceRoot":"","sources":["../../lib/fst/autocomplete.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAWH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAI9C,MAAM,WAAW,kBAAkB;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,gBAAgB,EAAE,MAAM,EAAE,CAAA;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,sBAAsB,EAAE,CAAA;CACrC;AAED,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB;;;;;;OAMG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB,gBAAgB,EAAE,MAAM,EAAE,CAAA;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAChC,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACtB;AAkFD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,gBAAqB,GAAG,kBAAkB,CA+B5G"}

package/out/fst/autocomplete.js

@@ -3,29 +3,33 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   FST-based autocomplete — mailwoman vocabulary over `@mailwoman/ancestrie`'s generic algorithm
- *   (#1728 phase 2). The #587 behavior — prefix walk + BFS expansion, partial-last-token completion,
- *   per-branch capping, dedupe — lives in ancestrie's `autocomplete`; this module contributes only
- *   the storage adapter ({@link FSTMatcher} → `AncestrieReaderLike`) and the mapping back to
- *   mailwoman's suggestion shape (name, placetype, referential/encyclopedic, WOF ids).
+ *   FST-based autocomplete, mailwoman vocabulary over `@mailwoman/ancestrie`'s generic algorithm.
+ *   The prefix walk, BFS expansion, partial-last-token completion, per-branch capping and dedupe
+ *   live in ancestrie's `autocomplete`. This module contributes only the storage adapter
+ *   ({@link FSTMatcher} → `AncestrieReaderLike`) and the mapping back to mailwoman's suggestion
+ *   shape (name, placetype, referential and encyclopedic scores, WOF ids).
  *
- *   THE BYTES DO NOT MIGRATE. The shipped artifacts are `FST\0` v1–v5 (`fst-serialize.ts`), not
- *   ancestrie's `ANCT`: ancestrie entries are id-keyed with one record per id, while an FST place row
- *   is per-(surface, place) — `crossCountryBranches` is a property of the SURFACE, so the same wofID
- *   legitimately carries different values under different aliases and cannot be represented id-keyed.
- *   The matcher, both deserializers, and the serializer therefore stay here; what migrated is the
- *   ALGORITHM, which is the half that drifts (the #861 share-the-function rule).
+ *   The bytes do not migrate. The shipped artifacts are `FST\0` v1 to v5 (`fst-serialize.ts`), and
+ *   ancestrie's entries are id-keyed with one record per id. An FST place row is per-(surface,
+ *   place), because `crossCountryBranches` is a property of the surface, so the same wofID
+ *   legitimately has different values under different aliases, so it cannot use IDs as keys.
+ *   The matcher, both deserializers and serializer stay here. The algorithm is the
+ *   half that migrated.
  */
 import { autocomplete as ancestrieAutocomplete } from "@mailwoman/ancestrie";
 import { normalizeTokens } from "#fst/matcher";
 /**
- * Max accepting entries collected per BFS branch — keeps one dense branch from starving the search.
+ * Max accepting entries collected per BFS branch, keeping one dense branch from starving the search.
  */
 const PER_BRANCH = 4;
 /**
- * The top-`k` entries by REFERENTIAL likelihood (descending). Avoids sorting/allocating when `entries` is small — and
- * that shortcut is part of the observable contract: at or under `k` the INSERTION order is served, which decides
- * suggestion order among referential ties.
+ * The top-`k` entries by referential likelihood (descending).
+ *
+ * Avoids sorting or allocating when `entries` is small.
+ * That shortcut is part of the observable interface.
+ *
+ * At or under `k`, suggestions retain insertion order.
+ * That order decides suggestions among referential ties.
  */
 function topByReferential(entries, k) {
     if (entries.length <= k)
@@ -33,18 +37,22 @@ function topByReferential(entries, k) {
     return [...entries].toSorted((a, b) => b.referential - a.referential).slice(0, k);
 }
 /**
- * {@link FSTMatcher} presented through ancestrie's storage interface. Records carry the {@link PlaceEntry} itself as the
- * payload, so the entry that WINS the algorithm's shallowest-depth rule is the entry whose fields the suggestion
- * reports — a side lookup keyed on id could pick a different surface's row (`crossCountryBranches` differs per
- * surface).
+ * {@link FSTMatcher} presented through ancestrie's storage interface.
+ *
+ * Records store the {@link PlaceEntry} itself as the payload, so the entry that wins the
+ * algorithm's shallowest-depth rule is the entry whose fields the suggestion reports.
+ * A side lookup keyed on id could pick a different surface's row
+ * (`crossCountryBranches` differs per surface).
  */
 class FSTReader {
     #fst;
     /**
-     * Parent chains of the entries this reader has served, id-keyed. A place's chain is identical across its surfaces (it
-     * is place-row data), so last-write-wins is safe. The algorithm asks {@link FSTReader.ancestorsOf} only for ids it
-     * just received from {@link FSTReader.entriesAt}, so serving from this memo answers every real call without an
-     * artifact-wide id index.
+     * Parent chains of the entries this reader has served, id-keyed.
+     *
+     * A place's chain is identical across its surfaces (it is place-row data), so last-write-wins is safe.
+     * The algorithm asks {@link FSTReader.ancestorsOf} only for ids it just received
+     * from {@link FSTReader.entriesAt}, so serving from this memo answers every
+     * real call without an artifact-wide id index.
      */
     #chains = new Map();
     constructor(fst) {
@@ -54,7 +62,8 @@ class FSTReader {
         return this.#fst.walk([...tokens]);
     }
     continuations(stateID) {
-        // Insertion order, verbatim — BFS visit order under the suggestion budget depends on it.
+        // Insertion order, verbatim.
+        // BFS visit order under the suggestion budget depends on it.
         return this.#fst.continuations(stateID).map((c) => ({
             token: c.token,
             targetState: c.targetState,
@@ -79,7 +88,9 @@ class FSTReader {
     }
 }
 /**
- * Autocomplete from the current prefix. Returns suggestions ranked referential-descending.
+ * Autocomplete from the current prefix.
+ *
+ * @returns Suggestions ranked referential-descending.
  */
 export function autocomplete(fst, query, opts = {}) {
     const normalizedTokens = normalizeTokens(query);
@@ -87,7 +98,7 @@ export function autocomplete(fst, query, opts = {}) {
         ...(opts.maxSuggestions === undefined ? {} : { maxSuggestions: opts.maxSuggestions }),
         ...(opts.maxExpansionDepth === undefined ? {} : { maxExpansionDepth: opts.maxExpansionDepth }),
         perBranchLimit: PER_BRANCH,
-        // The dedupe key is the DISPLAY name, not the token path: two surfaces of one name must still collapse. (#587)
+        // The dedupe key is the display name, so two surfaces of one name still collapse.
         ...(opts.dedupeByName ? { dedupe: (s) => s.payload.name.toLowerCase() } : {}),
     });
     return {
@@ -95,13 +106,13 @@ export function autocomplete(fst, query, opts = {}) {
         normalizedTokens,
         depth: result.depth,
         suggestions: result.suggestions.map((s) => {
-            // Every record this adapter serves carries its entry; the assertion documents the invariant.
+            // Every record this adapter serves includes its entry, so the non-null assertion holds.
             const entry = s.payload;
             return {
                 name: entry.name,
                 placetype: entry.placetype,
                 referential: entry.referential,
-                ...(entry.encyclopedic === undefined ? {} : { encyclopedic: entry.encyclopedic }),
+                encyclopedic: entry.encyclopedic,
                 wofID: s.id,
                 parentChain: s.parentIDs,
                 matchDepth: s.matchDepth,