@mailwoman/core 3.0.0 → 4.1.0

package/out/resolver/resolve.js

@@ -20,6 +20,38 @@ import { DEFAULT_PLACETYPE_MAP, } from "./types.js";
 export function createWofResolver(backend) {
     return new WofResolver(backend);
 }
+/**
+ * Pick the completion locality when an admin maps to several coincident same-name candidates
+ * (#405). Population is the PRIMARY signal — the principal city is the populous one, and it can sit
+ * FARTHER from the admin centroid than a tiny same-name hamlet (the Niigata case from #403).
+ * Nearest centroid breaks a population tie; a genuine tie (same population AND distance) ABSTAINS
+ * rather than guess.
+ */
+function pickCompletion(candidates) {
+    if (candidates.length === 0)
+        return null;
+    if (candidates.length === 1)
+        return candidates[0];
+    const ranked = [...candidates].sort((a, b) => b.population - a.population || a.distanceKm - b.distanceKm);
+    const [first, second] = ranked;
+    if (first.population === second.population && first.distanceKm === second.distanceKm)
+        return null;
+    return first;
+}
+/**
+ * Find the first postcode value anywhere in the tree (a one-shot pre-scan; postcode and locality
+ * are siblings, so the top-down walk wouldn't otherwise let the locality lookup see it).
+ */
+function firstPostcodeValue(roots) {
+    const stack = [...roots];
+    while (stack.length > 0) {
+        const n = stack.pop();
+        if (n.tag === "postcode" && n.value.trim().length > 0)
+            return n.value.trim();
+        stack.push(...n.children);
+    }
+    return undefined;
+}
 class WofResolver {
     #backend;
     constructor(backend) {
@@ -33,23 +65,86 @@ class WofResolver {
             placetypeMap: opts.placetypeMap ?? DEFAULT_PLACETYPE_MAP,
             minWinningScore: opts.minWinningScore ?? 0,
             candidatesPerLookup: opts.candidatesPerLookup ?? 5,
+            defaultCountry: opts.defaultCountry,
+            parentFallback: opts.parentFallback ?? true,
+            postcode: firstPostcodeValue(tree.roots),
+            anchorPosterior: opts.anchorPosterior,
+            anchorWeight: opts.anchorWeight ?? 2.0,
+            // Default-ON (#402): completion only fires for a dual-role region whose locality the parser
+            // dropped, and no-ops entirely when the backend has no relation (the browser WASM resolver, or
+            // a gazetteer without `coincident_roles`). Pass `hierarchyCompletion: false` to opt out.
+            // `cityStateFallback` is the #387 alias that #405 generalized — still honored.
+            hierarchyCompletion: opts.hierarchyCompletion ?? opts.cityStateFallback ?? true,
+            includeAncestors: opts.includeAncestors ?? false,
+            localityNodePresent: false,
+            resolvedRegion: null,
+            resolvedRegionNode: null,
         };
         const newRoots = [];
         for (const root of tree.roots) {
             newRoots.push(await this.#walk(root, /* parentResolved */ null, state));
         }
+        // Dual-role hierarchy completion (#405/#415). Only when enabled, a region resolved, and the parser
+        // emitted NO locality — record the dropped locality as a SECONDARY ROLE (an interpretation) on the
+        // resolved region node, from the backend's precomputed coincident-roles relation (#403). One node,
+        // one span, two roles — no synthesized sibling. See ResolveOpts.hierarchyCompletion.
+        if (state.hierarchyCompletion && state.resolvedRegion && state.resolvedRegionNode && !state.localityNodePresent) {
+            this.#completeRegionRole(state.resolvedRegion, state.resolvedRegionNode);
+        }
         return { raw: tree.raw, roots: newRoots };
     }
+    /**
+     * Record a dropped dual-role locality as a `locality` INTERPRETATION on the resolved region node
+     * (#415, generalizes #405's synthesized node). Consults `coincidentLocalitiesFor(regionId)` (O(1)
+     * map lookup — no distance math, no backend query), picks the principal city
+     * ({@link pickCompletion}: population-primary, distance tiebreak, abstain on a genuine tie), and
+     * appends an interpretation to `regionNode.interpretations`. No-op when the backend has no
+     * relation, the region isn't a dual-role place, or it abstains. The region node's primary role
+     * stays `region`; the locality rides alongside.
+     */
+    #completeRegionRole(region, regionNode) {
+        if (typeof region.id !== "number" || !this.#backend.coincidentLocalitiesFor)
+            return;
+        const loc = pickCompletion(this.#backend.coincidentLocalitiesFor(region.id));
+        if (!loc)
+            return;
+        const interpretation = {
+            tag: "locality",
+            placeId: `wof:${loc.id}`,
+            sourceId: `${loc.placetype}:${loc.id}`,
+            lat: loc.lat,
+            lon: loc.lon,
+            confidence: 0,
+            metadata: { relationship_type: loc.relationshipType, resolver_completed: true, resolver_name: loc.name },
+        };
+        regionNode.interpretations = [...(regionNode.interpretations ?? []), interpretation];
+    }
     async #walk(node, parentResolved, state) {
         // Always clone — never mutate input nodes.
         const decorated = { ...node, children: [] };
         const placetype = state.placetypeMap[node.tag];
+        // Track locality presence for hierarchy completion (#405): completion must NOT fire if the parser
+        // already emitted a locality node (even one that failed to resolve) — it only fills a genuine
+        // gap. Cheap and always-on; only consulted when hierarchyCompletion is set.
+        if (placetype === "locality")
+            state.localityNodePresent = true;
         let resolved = null;
         if (placetype && state.lookupsRemaining > 0 && node.value.trim().length > 0) {
             const picked = await this.#lookupAndPick(node, placetype, parentResolved, state);
             if (picked) {
                 resolved = picked.top;
                 decorateNode(decorated, picked.top, picked.alternatives);
+                // Lineage attachment (#404): stamp the resolved place's ancestor chain onto metadata. Opt-in
+                // + only when the backend supplies it, so the default stays byte-identical (no extra query).
+                if (state.includeAncestors && this.#backend.ancestors) {
+                    decorated.metadata = { ...(decorated.metadata ?? {}), ancestors: this.#backend.ancestors(picked.top.id) };
+                }
+                // Capture the first resolved region (place + node) for hierarchy completion — the locality
+                // interpretation is pushed onto this node in the post-walk pass.
+                if (placetype === "region" && state.resolvedRegion === null) {
+                    state.resolvedRegion = picked.top;
+                    state.resolvedRegionNode = decorated;
+                }
             }
         }
         const carryParent = resolved ?? parentResolved;
@@ -65,17 +160,34 @@ class WofResolver {
             placetype,
             limit: state.candidatesPerLookup,
         };
-        // Pass the inherited parent constraint to the backend when available — both `parentId` and
-        // `country` are valid narrowing hints depending on what the parent resolved to.
-        if (parentResolved) {
-            if (typeof parentResolved.id === "number")
-                query.parentId = parentResolved.id;
-            if (parentResolved.country)
-                query.country = parentResolved.country;
-        }
+        // Pass the inherited parent constraint to the backend when available — `parentId` scopes to
+        // the resolved parent's descendants. For `country`: a resolved parent's country wins, else
+        // fall back to the caller's `defaultCountry`. Without this top-level hint a bare "IL" over a
+        // multi-country gazetteer fuzzy-matches a foreign place (e.g. a French region) — see the
+        // Direction-C resolver eval.
+        if (parentResolved && typeof parentResolved.id === "number")
+            query.parentId = parentResolved.id;
+        const country = parentResolved?.country ?? state.defaultCountry;
+        if (country)
+            query.country = country;
+        // Coordinate-first: hand the sibling postcode to locality lookups so the backend can inject
+        // postcode-proximal candidates the name-match would miss. Only for locality (the placetype both
+        // `locality` and `dependent_locality` map to); other placetypes ignore it.
+        if (placetype === "locality" && state.postcode)
+            query.postcode = state.postcode;
         let candidates;
         try {
             candidates = await this.#backend.findPlace(query);
+            // Parent soft-gating: `parentId` is a HARD descendant filter in the backend, which wrongly
+            // zeroes the result when the parent resolved wrong OR the gazetteer hierarchy is incomplete
+            // (a real locality whose `ancestors` chain is missing its region). Rather than turn a
+            // resolvable node into an unresolved one, retry once WITHOUT the parent constraint — we
+            // prefer a parent-scoped hit but never sacrifice recall. The country constraint is kept, so
+            // this still can't wander to a foreign place. Same logical resolution → no extra budget.
+            if (candidates.length === 0 && state.parentFallback && query.parentId !== undefined) {
+                delete query.parentId;
+                candidates = await this.#backend.findPlace(query);
+            }
         }
         catch {
             // Defensive: a backend failure should not abort the whole tree walk. Leave the node with
@@ -84,10 +196,40 @@ class WofResolver {
         }
         if (candidates.length === 0)
             return null;
-        const top = candidates[0];
+        // Postcode-anchor re-rank (#369): when a country posterior is supplied (from the address's
+        // postcode), boost candidates by `anchorWeight * posterior[candidate.country]` and re-sort, so a
+        // postcode that pins the country pulls the right-country place over a higher-BM25 foreign namesake
+        // (the "Berlin DE vs Berlin US" class the #59 harness measured). No-op when `anchorPosterior` is
+        // undefined (the default) → byte-identical resolution.
+        //
+        // Applied to BOTH region and locality — the two placetypes that suffer cross-country namesake/
+        // abbreviation collisions a country posterior can break. The region case is the one #447's window
+        // fix couldn't reach: a bare 2-letter abbreviation is genuinely shared across countries ("VT" is
+        // both Vermont and Viterbo; "ME" both Maine and Messina), so with no country signal the score
+        // picks the wrong one — and because resolveTree resolves region FIRST and inherits its country
+        // down, a wrong region poisons the locality too. The postcode posterior breaks the tie at the
+        // region, and the right country then flows to the locality. (Country/macroregion/county are
+        // excluded: they don't exhibit this collision class and carry country via `parentId` when nested.)
+        //
+        // Tier-SAFE ordering: the candidate's exact-match flag is the PRIMARY key, so the country pin
+        // never crosses the exact/partial boundary. WITHIN a tier, `score + anchorWeight * posterior`
+        // applies the (soft) country boost. So a confident US postcode keeps the US EXACT region
+        // ("ME" → Maine) ahead of a more-populous US PARTIAL match (Missouri) AND, within the exact
+        // tier, ahead of a foreign exact match (Messina IT); a soft posterior still blends with score.
+        // (A plain additive re-rank loses the tier — it isn't encoded in `score` — and flips
+        // "ME" → Missouri / "PA" → Alabama. Backends that don't set `exactMatch` degrade to additive.)
+        const anchorEligible = placetype === "region" || placetype === "locality";
+        let ranked = candidates;
+        if (state.anchorPosterior && anchorEligible && candidates.length > 1) {
+            const post = state.anchorPosterior;
+            const w = state.anchorWeight;
+            ranked = [...candidates].sort((a, b) => Number(b.exactMatch ?? false) - Number(a.exactMatch ?? false) ||
+                b.score + w * (post[b.country] ?? 0) - (a.score + w * (post[a.country] ?? 0)));
+        }
+        const top = ranked[0];
         if (top.score < state.minWinningScore)
             return null;
-        return { top, alternatives: candidates.slice(1) };
+        return { top, alternatives: ranked.slice(1) };
     }
 }
 /**
@@ -111,6 +253,16 @@ function decorateNode(node, resolved, alternatives) {
     node.lat = resolved.lat;
     node.lon = resolved.lon;
     node.placeId = `wof:${resolved.id}`; // v1: only WOF resolvers; the URI scheme stays this simple
+    // Record the resolver's ranking score AND the resolved place's CANONICAL name. The name is the
+    // gazetteer's truth for the place we picked — distinct from `node.value` (the raw input span). It
+    // lets consumers display the canonical name and lets the end-to-end eval check the resolver chose
+    // the right PLACE (gazetteer-name vs ground-truth) rather than merely echoing the parser's text.
+    node.metadata = { ...(node.metadata ?? {}), resolver_score: resolved.score, resolver_name: resolved.name };
+    // The postcode/locality conflict flag (the falsehood differentiator): the postcode pointed to a
+    // geographically different place than the parsed city name. Surface it so callers can warn rather
+    // than silently trust the resolved point.
+    if (resolved.mismatch)
+        node.metadata["postcode_city_mismatch"] = true;
     if (alternatives.length > 0) {
         node.alternatives = alternatives;
     }

package/out/resolver/resolve.js.map

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

package/out/resolver/types.d.ts

@@ -38,6 +38,22 @@ export interface ResolvedPlace {
      * defined; callers should treat as ordinal.
      */
     score: number;
+    /**
+     * Set by the backend when this candidate is an EXACT name/alias match for the query (vs a partial
+     * token match). The postcode-anchor re-rank (#369) uses it as the PRIMARY key so a country
+     * posterior can pin the country WITHOUT crossing the exact-match tier: "ME" under a confident US
+     * posterior stays Maine (US exact) rather than promoting the more-populous Missouri (US partial),
+     * and still beats Messina (IT exact) on the posterior WITHIN the exact tier. Absent → treated as
+     * non-exact (backends that don't tier omit it; the re-rank degrades to a plain score+posterior).
+     */
+    exactMatch?: boolean;
+    /**
+     * Set when the resolver detected that the address's postcode and its parsed locality name point
+     * to geographically different places (a transposed / wrong-for-the-city postcode). Surfaced onto
+     * the resolved node's metadata as `postcode_city_mismatch` so callers can lower confidence or
+     * flag the conflict instead of silently mislocating.
+     */
+    mismatch?: boolean;
 }
 /**
  * Pull-based contract for a single resolver query. The resolver knows nothing about `AddressTree` —
@@ -52,8 +68,52 @@ export interface ResolverBackend {
         placetype?: string | string[];
         country?: string;
         parentId?: number | string;
+        /**
+         * Sibling postcode string, when the address carries one. A coordinate-first backend uses it to
+         * inject postcode-proximal locality candidates (the postcode→locality table) and soft-score
+         * them against the parsed name — recovering localities the name-match alone misses. Backends
+         * without postcode support ignore it.
+         */
+        postcode?: string;
         limit?: number;
     }): Promise<ResolvedPlace[]>;
+    /**
+     * The dual-role locality (or localities) coincident with an admin place id, from the precomputed
+     * coincident-roles relation (#403). Drives {@link ResolveOpts.hierarchyCompletion}: when the parse
+     * drops the locality of a city-state / capital-seat region, the resolver completes it from here
+     * instead of re-querying. OPTIONAL — backends without the relation omit it, and completion
+     * no-ops. Synchronous: it's an in-memory map lookup once the relation is loaded.
+     */
+    coincidentLocalitiesFor?(adminId: number | string): CoincidentLocality[];
+    /**
+     * The ancestor lineage of a resolved place — its containment chain (county → region → country),
+     * nearest-first. Backs {@link ResolveOpts.includeAncestors} (#404): the Pelias/Nominatim
+     * "always-attach-the-hierarchy" enrichment. OPTIONAL — backends without it omit it, and the
+     * attachment is skipped. Synchronous: a memoized read of the gazetteer's `ancestors` table.
+     */
+    ancestors?(id: number | string): Ancestor[];
+}
+/** One link in a resolved place's containment lineage ({@link ResolverBackend.ancestors}, #404). */
+export interface Ancestor {
+    id: number | string;
+    placetype: string;
+    name: string;
+}
+/**
+ * A dual-role locality returned by {@link ResolverBackend.coincidentLocalitiesFor} — a resolved
+ * place (so it can decorate a node directly) plus the relation metadata the completion step
+ * disambiguates on.
+ */
+export interface CoincidentLocality extends ResolvedPlace {
+    /**
+     * `city-state` / `capital-seat` / `consolidated-county` — surfaced as
+     * `metadata.relationship_type`.
+     */
+    relationshipType: string;
+    /** Locality population (0 when unknown) — the PRIMARY disambiguator when an admin has several. */
+    population: number;
+    /** Centroid distance (km) admin↔locality from the relation — the population tiebreak. */
+    distanceKm: number;
 }
 /**
  * Options for `resolveTree`. All optional with sensible defaults.
@@ -75,6 +135,22 @@ export interface ResolveOpts {
      * candidate after post-scoring, but the backend may benefit from over-fetching for ranking.
      */
     candidatesPerLookup?: number;
+    /**
+     * Default ISO-3166 alpha-2 country to constrain top-level lookups to, when no resolved parent has
+     * supplied a country yet. Without it, a bare component over a multi-country gazetteer (e.g. "IL")
+     * can fuzzy-match a foreign place. Callers should set this from the detected locale (the
+     * pipeline's locale-gate). A resolved parent's country still overrides it deeper in the tree.
+     */
+    defaultCountry?: string;
+    /**
+     * When a resolved parent constrains a child lookup (`parentId` is passed to the backend as a hard
+     * descendant filter) and that filtered lookup returns NOTHING, retry the lookup once without the
+     * parent constraint. Guards against an incomplete gazetteer hierarchy (a real locality whose
+     * ancestor chain is missing its region) or a mis-resolved parent silently turning a resolvable
+     * node unresolved. The country constraint is retained on the retry, so resolution still can't
+     * wander cross-border. Default true. Set false to measure the strict-parent baseline.
+     */
+    parentFallback?: boolean;
     /**
      * Override the default ComponentTag → resolver-placetype mapping. When set, this map FULLY
      * REPLACES `DEFAULT_PLACETYPE_MAP` — start from the default by spreading it (`{
@@ -89,6 +165,55 @@ export interface ResolveOpts {
      * break when locale-aware resolvers land in 4.4+.
      */
     locale?: string;
+    /**
+     * Optional postcode-anchor country posterior (#369) — a `{ countryCode: probability }` map
+     * derived from the address's postcode (e.g. `@mailwoman/neural`'s `extractPostcodeAnchors`). When
+     * provided, LOCALITY candidates are re-ranked by `score + anchorWeight *
+     * posterior[candidate.country]` before the top is picked, so a postcode that pins the country can
+     * pull the right-country place over a higher-BM25 foreign namesake (the "Berlin DE vs Berlin US"
+     * class the #59 anchor→resolver harness measured). OFF by default — omit it and resolution is
+     * byte-identical. Country signal only, so it touches locality lookups only; admin parents already
+     * carry country via `parentId`.
+     */
+    anchorPosterior?: Record<string, number>;
+    /**
+     * Weight on the anchor's country posterior in the locality re-rank (#369). Default 2.0 (the value
+     * the harness swept). Only consulted when `anchorPosterior` is set.
+     */
+    anchorWeight?: number;
+    /**
+     * Recover the dropped locality in a DUAL-ROLE-place address (#405, epic #402). Many places occupy
+     * multiple admin tiers under one name — city-states (Berlin/Hamburg/Bremen = city == state),
+     * capital-seat provinces (Milano, Madrid), UK unitary authorities — and in the
+     * international-order layout `…, Berlin, Berlin <PC>` the parser labels one token the region and
+     * drops the locality entirely, leaving a region but no locality (955/1500 Berlin rows resolved to
+     * nothing on v0.9.4).
+     *
+     * When this is on AND a region resolved AND the tree has NO locality node, the resolver consults
+     * the backend's precomputed coincident-roles relation
+     * ({@link ResolverBackend.coincidentLocalitiesFor}, #403) for a same-name coincident locality and
+     * synthesizes a node from it. The relation is the gazetteer's own structure (same name +
+     * descendant + centroid-coincidence, derived at build time), so the runtime is an O(1) membership
+     * lookup — no magic distance constant. When an admin maps to several same-name localities, the
+     * most populous wins (the principal city), nearest-centroid breaks a population tie, and a
+     * genuine tie ABSTAINS (no completion) rather than guess. The synthesized node carries
+     * `metadata.resolver_synthesized = true` (+ `relationship_type`) — it has no span in the raw
+     * input. ON by default (#402): it only fires for a dual-role region whose locality the parser
+     * dropped, and no-ops entirely when the backend has no relation (the browser WASM resolver, or a
+     * gazetteer without the `coincident_roles` table). Pass `false` to opt out.
+     */
+    hierarchyCompletion?: boolean;
+    /** @deprecated Renamed to {@link hierarchyCompletion} (#405 generalized #387). Still honored. */
+    cityStateFallback?: boolean;
+    /**
+     * Attach each resolved node's ancestor lineage (#404) — the containment chain (county → region →
+     * country) the backend's {@link ResolverBackend.ancestors} returns — onto `metadata.ancestors`.
+     * The Pelias/Nominatim "always-attach-the-hierarchy" enrichment, so a consumer gets the full
+     * admin ladder from a single resolved place. OFF by default: omit it and resolution is
+     * byte-identical (and there's no extra query). Only attaches to nodes the resolver actually
+     * resolved.
+     */
+    includeAncestors?: boolean;
 }
 /**
  * Mapping from mailwoman's address-component tags to the resolver's placetype taxonomy. Components

package/out/resolver/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../resolver/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAEpE;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC7B,wDAAwD;IACxD,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;IACnB,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAA;IACZ,0FAA0F;IAC1F,SAAS,EAAE,MAAM,CAAA;IACjB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAA;IACf,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAA;IACX,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAA;IACX,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAC3B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;CACb;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC/B,SAAS,CAAC,KAAK,EAAE;QAChB,IAAI,EAAE,MAAM,CAAA;QACZ,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;QAC7B,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;QAC1B,KAAK,CAAC,EAAE,MAAM,CAAA;KACd,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAA;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAA;AAEhE,eAAO,MAAM,qBAAqB,EAAE,YAUnC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACxB,WAAW,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;CACxE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../resolver/types.ts"],"names":[],"mappings":"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"}

package/out/resolver/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../resolver/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAmGH,MAAM,CAAC,MAAM,qBAAqB,GAAiB;IAClD,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,QAAQ;IAChB,QAAQ,EAAE,UAAU;IACpB,kBAAkB,EAAE,UAAU;IAC9B,SAAS,EAAE,QAAQ;IACnB,0FAA0F;IAC1F,6FAA6F;IAC7F,2FAA2F;IAC3F,QAAQ,EAAE,YAAY;CACtB,CAAA"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../resolver/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAkOH,MAAM,CAAC,MAAM,qBAAqB,GAAiB;IAClD,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,QAAQ;IAChB,QAAQ,EAAE,UAAU;IACpB,kBAAkB,EAAE,UAAU;IAC9B,SAAS,EAAE,QAAQ;IACnB,0FAA0F;IAC1F,6FAA6F;IAC7F,2FAA2F;IAC3F,QAAQ,EAAE,YAAY;CACtB,CAAA"}

package/out/resources/whosonfirst/PlacetypeDataSource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PlacetypeDataSource.d.ts","sourceRoot":"","sources":["../../../resources/whosonfirst/PlacetypeDataSource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACN,kBAAkB,EAClB,KAAK,mBAAmB,EAGxB,MAAM,qCAAqC,CAAA;AAC5C,OAAO,EAAgB,KAAK,mBAAmB,EAAsB,MAAM,aAAa,CAAA;AACxF,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,SAAS,CAAA;AAE3D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAA;AAEtE,MAAM,WAAW,0BAA0B,CAC1C,CAAC,SAAS,oBAAoB,GAAG,oBAAoB,EACrD,CAAC,SAAS,mBAAmB,GAAG,kBAAkB,GAAG,mBAAmB;IAExE,SAAS,EAAE,CAAC,CAAA;IACZ,YAAY,EAAE,CAAC,CAAA;IACf,aAAa,EAAE,eAAe,CAAA;CAC9B;AAED,MAAM,WAAW,eAAe;IAC/B;;OAEG;IACH,EAAE,EAAE,MAAM,CAAA;IACV;;OAEG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;OAEG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB;;OAEG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB;;OAEG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB;;OAEG;IACH,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB;;OAEG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CACpB;AAED;;GAEG;AACH,qBAAa,mBAAoB,YAAW,UAAU;;WAGvC,UAAU,CAAC,CAAC,SAAS,oBAAoB,EAAE,CAAC,SAAS,mBAAmB,GAAG,kBAAkB,EAAE,EAC5G,SAAS,EACT,YAAY,EACZ,aAAa,GACb,EAAE,IAAI,CAAC,0BAA0B,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,WAAW,GAAG,cAAc,GAAG,eAAe,CAAC,GASxE,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;IAGtC,aAAa,IAAI,IAAI;IAkBrB,cAAc,IAAI,IAAI;gBAejB,YAAY,EAAE,eAAe,EAAE,SAAS,CAAC,EAAE,mBAAmB;IAYnE,CAAC,MAAM,CAAC,OAAO,CAAC;IAIvB;;OAEG;IAEI,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,cAAc,CAAC,eAAe,CAAC;IAgBhF;;;;OAIG;IACU,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;CA+B3D"}
+{"version":3,"file":"PlacetypeDataSource.d.ts","sourceRoot":"","sources":["../../../resources/whosonfirst/PlacetypeDataSource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACN,kBAAkB,EAClB,KAAK,mBAAmB,EAGxB,MAAM,qCAAqC,CAAA;AAC5C,OAAO,EAAgB,KAAK,mBAAmB,EAAsB,MAAM,aAAa,CAAA;AACxF,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,SAAS,CAAA;AAE3D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAA;AAEtE,MAAM,WAAW,0BAA0B,CAC1C,CAAC,SAAS,oBAAoB,GAAG,oBAAoB,EACrD,CAAC,SAAS,mBAAmB,GAAG,kBAAkB,GAAG,mBAAmB;IAExE,SAAS,EAAE,CAAC,CAAA;IACZ,YAAY,EAAE,CAAC,CAAA;IACf,aAAa,EAAE,eAAe,CAAA;CAC9B;AAED,MAAM,WAAW,eAAe;IAC/B;;OAEG;IACH,EAAE,EAAE,MAAM,CAAA;IACV;;OAEG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;OAEG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB;;OAEG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB;;OAEG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB;;OAEG;IACH,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB;;OAEG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CACpB;AAED;;GAEG;AACH,qBAAa,mBAAoB,YAAW,UAAU;;WAGvC,UAAU,CAAC,CAAC,SAAS,oBAAoB,EAAE,CAAC,SAAS,mBAAmB,GAAG,kBAAkB,EAAE,EAC5G,SAAS,EACT,YAAY,EACZ,aAAa,GACb,EAAE,IAAI,CAAC,0BAA0B,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,WAAW,GAAG,cAAc,GAAG,eAAe,CAAC,GASxE,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;IAGtC,aAAa,IAAI,IAAI;IAkBrB,cAAc,IAAI,IAAI;gBAejB,YAAY,EAAE,eAAe,EAAE,SAAS,CAAC,EAAE,mBAAmB;IAcnE,CAAC,MAAM,CAAC,OAAO,CAAC;IAIvB;;OAEG;IAEI,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,cAAc,CAAC,eAAe,CAAC;IAgBhF;;;;OAIG;IACU,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;CA+B3D"}

package/out/resources/whosonfirst/PlacetypeDataSource.js

@@ -50,7 +50,9 @@ export class PlacetypeDataSource {
 		`);
     }
     constructor(databasePath, dbOptions) {
-        this.#db = new DatabaseSync(databasePath.toString(), dbOptions);
+        this.#db = dbOptions
+            ? new DatabaseSync(databasePath.toString(), dbOptions)
+            : new DatabaseSync(databasePath.toString());
         // node:sqlite has no .pragma() helper; pragmas are executed as plain SQL.
         this.#db.exec("PRAGMA busy_timeout = 10000");
         this.#db.exec("PRAGMA journal_mode = WAL");

package/out/resources/whosonfirst/PlacetypeDataSource.js.map

@@ -1 +1 @@
-{"version":3,"file":"PlacetypeDataSource.js","sourceRoot":"","sources":["../../../resources/whosonfirst/PlacetypeDataSource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACN,kBAAkB,EAElB,eAAe,EACf,qBAAqB,GACrB,MAAM,qCAAqC,CAAA;AAC5C,OAAO,EAAE,YAAY,EAAgD,MAAM,aAAa,CAAA;AACxF,OAAO,EAAE,WAAW,EAAwB,MAAM,SAAS,CAAA;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAmDrD;;GAEG;AACH,MAAM,OAAO,mBAAmB;IAC/B,GAAG,CAAc;IAEV,MAAM,CAAC,UAAU,CAAqF,EAC5G,SAAS,EACT,YAAY,EACZ,aAAa,GAC2E;QACxF,MAAM,sBAAsB,GAAG,qBAAqB,CAAC,YAAY,CAAC;YACjE,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,YAAY,CAAC;YACnC,CAAC,CAAC,YAAY,CAAA;QAEf,OAAO,WAAW,CAAC,IAAI,CACtB,aAAa,EACb,SAAS,EACT,GAAG,sBAAsB,KAAK,CACa,CAAA;IAC7C,CAAC;IAEM,aAAa;QACnB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC;;;;;;;;;;;;;;GAcvB,CAAC,CAAA;IACH,CAAC;IAEM,cAAc;QACpB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC;;;;;;;;;;;GAWvB,CAAC,CAAA;IACH,CAAC;IAED,YAAY,YAA6B,EAAE,SAA+B;QACzE,IAAI,CAAC,GAAG,GAAG,IAAI,YAAY,CAAC,YAAY,CAAC,QAAQ,EAAE,EAAE,SAAS,CAAC,CAAA;QAE/D,0EAA0E;QAC1E,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAA;QAC5C,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAA;QAC1C,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAA;QAEzC,IAAI,CAAC,aAAa,EAAE,CAAA;QACpB,uBAAuB;IACxB,CAAC;IAEM,CAAC,MAAM,CAAC,OAAO,CAAC;QACtB,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAA;IACjB,CAAC;IAED;;OAEG;IAEI,IAAI,CAAC,QAAkC;QAC7C,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC;;;WAGpC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC;aAC3B,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,OAAO,GAAG,EAAE,CAAC;aAChC,IAAI,CAAC,MAAM,CAAC;GACd,CAAC,CAAA;QAEF,4FAA4F;QAC5F,2DAA2D;QAC3D,OAAO,QAAQ,CAAC,IAAI,CACnB,SAAS,CAAC,OAAO,CAAC,QAAoD,CAAC,CACzB,CAAA;IAChD,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,MAAM,CAAC,MAAuB;QAC1C,MAAM,OAAO,GAAG,GAAG,EAAE;YACpB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC;;;;;;;;;;;;;;;;;;;;;;IAsB5C,CAAC,CAAA;YAEF,SAAS,CAAC,GAAG,CAAC,MAAkD,CAAC,CAAA;QAClE,CAAC,CAAA;QAED,MAAM,cAAc,CAAC,CAAC,EAAE,OAAO,CAAC,CAAA;IACjC,CAAC;CACD"}
+{"version":3,"file":"PlacetypeDataSource.js","sourceRoot":"","sources":["../../../resources/whosonfirst/PlacetypeDataSource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACN,kBAAkB,EAElB,eAAe,EACf,qBAAqB,GACrB,MAAM,qCAAqC,CAAA;AAC5C,OAAO,EAAE,YAAY,EAAgD,MAAM,aAAa,CAAA;AACxF,OAAO,EAAE,WAAW,EAAwB,MAAM,SAAS,CAAA;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAmDrD;;GAEG;AACH,MAAM,OAAO,mBAAmB;IAC/B,GAAG,CAAc;IAEV,MAAM,CAAC,UAAU,CAAqF,EAC5G,SAAS,EACT,YAAY,EACZ,aAAa,GAC2E;QACxF,MAAM,sBAAsB,GAAG,qBAAqB,CAAC,YAAY,CAAC;YACjE,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,YAAY,CAAC;YACnC,CAAC,CAAC,YAAY,CAAA;QAEf,OAAO,WAAW,CAAC,IAAI,CACtB,aAAa,EACb,SAAS,EACT,GAAG,sBAAsB,KAAK,CACa,CAAA;IAC7C,CAAC;IAEM,aAAa;QACnB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC;;;;;;;;;;;;;;GAcvB,CAAC,CAAA;IACH,CAAC;IAEM,cAAc;QACpB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC;;;;;;;;;;;GAWvB,CAAC,CAAA;IACH,CAAC;IAED,YAAY,YAA6B,EAAE,SAA+B;QACzE,IAAI,CAAC,GAAG,GAAG,SAAS;YACnB,CAAC,CAAC,IAAI,YAAY,CAAC,YAAY,CAAC,QAAQ,EAAE,EAAE,SAAS,CAAC;YACtD,CAAC,CAAC,IAAI,YAAY,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC,CAAA;QAE5C,0EAA0E;QAC1E,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAA;QAC5C,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAA;QAC1C,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAA;QAEzC,IAAI,CAAC,aAAa,EAAE,CAAA;QACpB,uBAAuB;IACxB,CAAC;IAEM,CAAC,MAAM,CAAC,OAAO,CAAC;QACtB,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAA;IACjB,CAAC;IAED;;OAEG;IAEI,IAAI,CAAC,QAAkC;QAC7C,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC;;;WAGpC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC;aAC3B,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,OAAO,GAAG,EAAE,CAAC;aAChC,IAAI,CAAC,MAAM,CAAC;GACd,CAAC,CAAA;QAEF,4FAA4F;QAC5F,2DAA2D;QAC3D,OAAO,QAAQ,CAAC,IAAI,CACnB,SAAS,CAAC,OAAO,CAAC,QAAoD,CAAC,CACzB,CAAA;IAChD,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,MAAM,CAAC,MAAuB;QAC1C,MAAM,OAAO,GAAG,GAAG,EAAE;YACpB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC;;;;;;;;;;;;;;;;;;;;;;IAsB5C,CAAC,CAAA;YAEF,SAAS,CAAC,GAAG,CAAC,MAAkD,CAAC,CAAA;QAClE,CAAC,CAAA;QAED,MAAM,cAAc,CAAC,CAAC,EAAE,OAAO,CAAC,CAAA;IACjC,CAAC;CACD"}

package/out/resources/whosonfirst/placetypes/graph.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+import type { PlacetypeRole } from "./definition.js";
+import { Placetype } from "./Placetype.js";
+/**
+ * A single node in a placetype graph. One entry per unique placetype name.
+ */
+export interface PlacetypeGraphNode {
+    name: string;
+    /** Brooklyn Integers ID. */
+    id: number;
+    role: PlacetypeRole;
+}
+/**
+ * A directed parent → child edge. Field names match d3-force / react-flow / cytoscape conventions
+ * so the graph drops straight into common viewers.
+ */
+export interface PlacetypeGraphLink {
+    source: string;
+    target: string;
+}
+/**
+ * Node-link projection of the placetype DAG rooted at a given placetype. Each node and each
+ * (parent, child) edge appears exactly once — see {@linkcode generatePlacetypeGraph} for why this is
+ * the preferred shape when the root has many shared descendants (e.g. `planet`).
+ */
+export interface PlacetypeGraph {
+    root: string;
+    nodes: PlacetypeGraphNode[];
+    links: PlacetypeGraphLink[];
+}
+/**
+ * Build a node-link graph of a placetype and its descendants, optionally filtered by role.
+ *
+ * Unlike {@linkcode generatePlacetypeTree}, this emits each node and each (parent, child) edge
+ * exactly once. WOF placetypes form a DAG with heavy descendant sharing (e.g. `installation` is a
+ * leaf reachable from many parents); projecting that DAG to a nested tree duplicates every shared
+ * subtree under every parent path and blows up exponentially for roots like `planet` (~165 MB for
+ * the full hierarchy). The graph shape stays O(nodes + edges) regardless.
+ *
+ * Output is well-suited for d3-force, react-flow, cytoscape, and any other HTML graph viewer.
+ */
+export declare function generatePlacetypeGraph(placetype: Placetype, roles?: Iterable<PlacetypeRole> | null): PlacetypeGraph;
+//# sourceMappingURL=graph.d.ts.map

package/out/resources/whosonfirst/placetypes/graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../../../resources/whosonfirst/placetypes/graph.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE1C;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,4BAA4B;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,aAAa,CAAA;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAClC,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACd;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,kBAAkB,EAAE,CAAA;IAC3B,KAAK,EAAE,kBAAkB,EAAE,CAAA;CAC3B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,IAAI,GAAG,cAAc,CAsCnH"}

package/out/resources/whosonfirst/placetypes/graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.js","sourceRoot":"","sources":["../../../../resources/whosonfirst/placetypes/graph.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAgC1C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,sBAAsB,CAAC,SAAoB,EAAE,KAAsC;IAClG,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IAE7C,MAAM,KAAK,GAAG,IAAI,GAAG,EAA8B,CAAA;IACnD,MAAM,KAAK,GAAyB,EAAE,CAAA;IACtC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAA;IACnC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAA;IAEhC,MAAM,OAAO,GAAG,CAAC,CAAY,EAAQ,EAAE;QACtC,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;YAAE,OAAM;QAC7B,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAA;IAC5D,CAAC,CAAA;IAED,MAAM,IAAI,GAAG,CAAC,IAAe,EAAQ,EAAE;QACtC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAErB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC;YAChD,OAAO,CAAC,KAAK,CAAC,CAAA;YAEd,MAAM,OAAO,GAAG,GAAG,IAAI,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,EAAE,CAAA;YAC5C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC7B,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;gBACtB,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAA;YACtD,CAAC;YAED,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;gBAAE,SAAQ;YACpC,IAAI,CAAC,KAAK,CAAC,CAAA;QACZ,CAAC;IACF,CAAC,CAAA;IAED,OAAO,CAAC,SAAS,CAAC,CAAA;IAClB,IAAI,CAAC,SAAS,CAAC,CAAA;IAEf,OAAO;QACN,IAAI,EAAE,SAAS,CAAC,IAAI;QACpB,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QACjC,KAAK;KACL,CAAA;AACF,CAAC"}

package/out/resources/whosonfirst/placetypes/index.d.ts

@@ -5,6 +5,8 @@
  */
 export * from "./admin.js";
 export * from "./definition.js";
+export * from "./graph.js";
 export * from "./mermaid.js";
 export * from "./Placetype.js";
+export * from "./tree.js";
 //# sourceMappingURL=index.d.ts.map

package/out/resources/whosonfirst/placetypes/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../resources/whosonfirst/placetypes/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../resources/whosonfirst/placetypes/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,WAAW,CAAA"}

package/out/resources/whosonfirst/placetypes/index.js

@@ -5,6 +5,8 @@
  */
 export * from "./admin.js";
 export * from "./definition.js";
+export * from "./graph.js";
 export * from "./mermaid.js";
 export * from "./Placetype.js";
+export * from "./tree.js";
 //# sourceMappingURL=index.js.map

package/out/resources/whosonfirst/placetypes/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../resources/whosonfirst/placetypes/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../resources/whosonfirst/placetypes/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,WAAW,CAAA"}

package/out/resources/whosonfirst/placetypes/mermaid.d.ts

@@ -3,18 +3,50 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  */
-import type { PlacetypeRole } from "./definition.js";
+import { type PlacetypeRole } from "./definition.js";
 import { Placetype } from "./Placetype.js";
 /**
- * Colors for placetype roles.
+ * Hand-tuned default colors for placetype roles. Used when no `interpolator` is passed to
+ * {@linkcode generateMermaidMarkup}. Each entry pairs a fill with a darker stroke and a text color
+ * chosen for contrast against the fill.
  */
 export declare const PlacetypeRoleColor: {
     readonly common: "#0066cc";
     readonly common_optional: "#00cc66";
     readonly optional: "#ffcc00";
 };
+/**
+ * A color interpolator — compatible with d3-scale-chromatic's `interpolate*` functions (e.g.
+ * `interpolateViridis`, `interpolateTurbo`). Receives `t ∈ [0, 1]` and returns a CSS color string.
+ */
+export type InterpolateColorCallback = (t: number) => string;
+export interface GenerateMermaidMarkupOptions {
+    /** Restrict descendants to the given roles. Default: all roles. */
+    roles?: Iterable<PlacetypeRole>;
+    /**
+     * Edge color interpolator. Each edge is colored by its child node's depth from the root: `t =
+     * (childDepth - 1) / (maxDepth - 1)`. This traces a smooth gradient along any lineage path (e.g.
+     * `planet → continent → country → …`) and gives a visual cue for how deep an edge sits in the
+     * tree.
+     *
+     * Defaults to d3-scale-chromatic's `interpolateViridis` — perceptually uniform and
+     * colorblind-friendly. Node fills/strokes are _not_ affected; they always use the hand-tuned
+     * {@linkcode PlacetypeRoleColor} palette, which carries more semantic weight than a sampled
+     * gradient for only three categorical role values.
+     */
+    edgeInterpolator?: InterpolateColorCallback;
+}
 /**
  * Generate a Mermaid flowchart markup for a placetype and its descendants.
+ *
+ * The walk is a recursive `findChildren` traversal — every emitted edge is a real direct-parent →
+ * direct-child relationship. WOF placetypes form a DAG (e.g. `borough` has both `country` and
+ * `macroregion` as parents), so a child can legitimately appear on multiple edges; the `visited`
+ * set prevents the subtree below it from being re-emitted.
+ *
+ * Edges are colored by depth from the root via
+ * {@linkcode GenerateMermaidMarkupOptions.edgeInterpolator} (default: viridis), so any lineage path
+ * traces a smooth gradient down the chart. Node fills always use the hand-tuned role palette.
  */
-export declare function generateMermaidMarkup(placetype: Placetype, roles?: Iterable<PlacetypeRole>): string;
+export declare function generateMermaidMarkup(placetype: Placetype, options?: GenerateMermaidMarkupOptions): string;
 //# sourceMappingURL=mermaid.d.ts.map

package/out/resources/whosonfirst/placetypes/mermaid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mermaid.d.ts","sourceRoot":"","sources":["../../../../resources/whosonfirst/placetypes/mermaid.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE1C;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;;CAImB,CAAA;AAElD;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,MAAM,CA8BnG"}
+{"version":3,"file":"mermaid.d.ts","sourceRoot":"","sources":["../../../../resources/whosonfirst/placetypes/mermaid.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,iBAAiB,CAAA;AACpE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAa1C;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;CAImB,CAAA;AAclD;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;AAE5D,MAAM,WAAW,4BAA4B;IAC5C,mEAAmE;IACnE,KAAK,CAAC,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAA;IAC/B;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,EAAE,wBAAwB,CAAA;CAC3C;AAuCD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,GAAE,4BAAiC,GAAG,MAAM,CA+C9G"}