@mailwoman/tiger 8.0.0 → 8.2.0

package/state.ts

@@ -6,7 +6,7 @@
 
 import type { GeoFeature, MultiPolygonLiteral } from "@mailwoman/spatial"
 
-import { GeoIDPart } from "./geoid.ts"
+import type { GeoIDPart } from "./geoid.ts"
 import type { TIGERTabulatedBlockProperties } from "./tabulation-block.ts"
 
 //#region FIPS Codes
@@ -21,157 +21,259 @@ import type { TIGERTabulatedBlockProperties } from "./tabulation-block.ts"
  * @see {@linkcode AdminLevel1Code} for a combined set of states and territories.
  */
 export const FIPSStateCode = {
-	/** @title Alabama */
+	/**
+	 * @title Alabama
+	 */
 	AL: "01",
 
-	/** @title Alaska */
+	/**
+	 * @title Alaska
+	 */
 	AK: "02",
 
-	/** @title Arizona */
+	/**
+	 * @title Arizona
+	 */
 	AZ: "04",
 
-	/** @title Arkansas */
+	/**
+	 * @title Arkansas
+	 */
 	AR: "05",
 
-	/** @title California */
+	/**
+	 * @title California
+	 */
 	CA: "06",
 
-	/** @title Colorado */
+	/**
+	 * @title Colorado
+	 */
 	CO: "08",
 
-	/** @title Connecticut */
+	/**
+	 * @title Connecticut
+	 */
 	CT: "09",
 
-	/** @title Delaware */
+	/**
+	 * @title Delaware
+	 */
 	DE: "10",
 
-	/** @title District Of Columbia */
+	/**
+	 * @title District Of Columbia
+	 */
 	DC: "11",
 
-	/** @title Florida */
+	/**
+	 * @title Florida
+	 */
 	FL: "12",
 
-	/** @title Georgia */
+	/**
+	 * @title Georgia
+	 */
 	GA: "13",
 
-	/** @title Hawaii */
+	/**
+	 * @title Hawaii
+	 */
 	HI: "15",
 
-	/** @title Idaho */
+	/**
+	 * @title Idaho
+	 */
 	ID: "16",
 
-	/** @title Illinois */
+	/**
+	 * @title Illinois
+	 */
 	IL: "17",
 
-	/** @title Indiana */
+	/**
+	 * @title Indiana
+	 */
 	IN: "18",
 
-	/** @title Iowa */
+	/**
+	 * @title Iowa
+	 */
 	IA: "19",
 
-	/** @title Kansas */
+	/**
+	 * @title Kansas
+	 */
 	KS: "20",
 
-	/** @title Kentucky */
+	/**
+	 * @title Kentucky
+	 */
 	KY: "21",
 
-	/** @title Louisiana */
+	/**
+	 * @title Louisiana
+	 */
 	LA: "22",
 
-	/** @title Maine */
+	/**
+	 * @title Maine
+	 */
 	ME: "23",
 
-	/** @title Maryland */
+	/**
+	 * @title Maryland
+	 */
 	MD: "24",
 
-	/** @title Massachusetts */
+	/**
+	 * @title Massachusetts
+	 */
 	MA: "25",
 
-	/** @title Michigan */
+	/**
+	 * @title Michigan
+	 */
 	MI: "26",
 
-	/** @title Minnesota */
+	/**
+	 * @title Minnesota
+	 */
 	MN: "27",
 
-	/** @title Mississippi */
+	/**
+	 * @title Mississippi
+	 */
 	MS: "28",
 
-	/** @title Missouri */
+	/**
+	 * @title Missouri
+	 */
 	MO: "29",
 
-	/** @title Montana */
+	/**
+	 * @title Montana
+	 */
 	MT: "30",
 
-	/** @title Nebraska */
+	/**
+	 * @title Nebraska
+	 */
 	NE: "31",
 
-	/** @title Nevada */
+	/**
+	 * @title Nevada
+	 */
 	NV: "32",
 
-	/** @title New Hampshire */
+	/**
+	 * @title New Hampshire
+	 */
 	NH: "33",
 
-	/** @title New Jersey */
+	/**
+	 * @title New Jersey
+	 */
 	NJ: "34",
 
-	/** @title New Mexico */
+	/**
+	 * @title New Mexico
+	 */
 	NM: "35",
 
-	/** @title New York */
+	/**
+	 * @title New York
+	 */
 	NY: "36",
 
-	/** @title North Carolina */
+	/**
+	 * @title North Carolina
+	 */
 	NC: "37",
 
-	/** @title North Dakota */
+	/**
+	 * @title North Dakota
+	 */
 	ND: "38",
 
-	/** @title Ohio */
+	/**
+	 * @title Ohio
+	 */
 	OH: "39",
 
-	/** @title Oklahoma */
+	/**
+	 * @title Oklahoma
+	 */
 	OK: "40",
 
-	/** @title Oregon */
+	/**
+	 * @title Oregon
+	 */
 	OR: "41",
 
-	/** @title Pennsylvania */
+	/**
+	 * @title Pennsylvania
+	 */
 	PA: "42",
 
-	/** @title Rhode Island */
+	/**
+	 * @title Rhode Island
+	 */
 	RI: "44",
 
-	/** @title South Carolina */
+	/**
+	 * @title South Carolina
+	 */
 	SC: "45",
 
-	/** @title South Dakota */
+	/**
+	 * @title South Dakota
+	 */
 	SD: "46",
 
-	/** @title Tennessee */
+	/**
+	 * @title Tennessee
+	 */
 	TN: "47",
 
-	/** @title Texas */
+	/**
+	 * @title Texas
+	 */
 	TX: "48",
 
-	/** @title Utah */
+	/**
+	 * @title Utah
+	 */
 	UT: "49",
 
-	/** @title Vermont */
+	/**
+	 * @title Vermont
+	 */
 	VT: "50",
 
-	/** @title Virginia */
+	/**
+	 * @title Virginia
+	 */
 	VA: "51",
 
-	/** @title Washington */
+	/**
+	 * @title Washington
+	 */
 	WA: "53",
 
-	/** @title West Virginia */
+	/**
+	 * @title West Virginia
+	 */
 	WV: "54",
 
-	/** @title Wisconsin */
+	/**
+	 * @title Wisconsin
+	 */
 	WI: "55",
 
-	/** @title Wyoming */
+	/**
+	 * @title Wyoming
+	 */
 	WY: "56",
 } as const
 
@@ -194,19 +296,29 @@ export const FIPSTerritoryCode = {
 	 */
 	JA: "74",
 
-	/** @title American Samoa */
+	/**
+	 * @title American Samoa
+	 */
 	AS: "60",
 
-	/** @title Guam */
+	/**
+	 * @title Guam
+	 */
 	GU: "66",
 
-	/** @title Northern Mariana Islands */
+	/**
+	 * @title Northern Mariana Islands
+	 */
 	MP: "69",
 
-	/** @title Puerto Rico */
+	/**
+	 * @title Puerto Rico
+	 */
 	PR: "72",
 
-	/** @title Virgin Islands */
+	/**
+	 * @title Virgin Islands
+	 */
 	VI: "78",
 } as const
 
@@ -344,6 +456,9 @@ export const StateAbbreviation = {
 
 export type StateAbbreviation = (typeof StateAbbreviation)[keyof typeof StateAbbreviation]
 
+/**
+ * Postal abbreviations for US territories, kept apart from the states so callers can include or exclude them.
+ */
 export const TerritoryAbbreviation = {
 	"American Samoa": "AS",
 	"Johnston Atoll": "JA",
@@ -364,6 +479,9 @@ export type TerritoryAbbreviation = (typeof TerritoryAbbreviation)[keyof typeof
  */
 export type AdminLevel1Abbreviation = StateAbbreviation | TerritoryAbbreviation
 
+/**
+ * Every admin-level-1 postal abbreviation — the fifty states, DC, and the territories together.
+ */
 export const AdminLevel1Abbreviation = {
 	...StateAbbreviation,
 	...TerritoryAbbreviation,

package/tabulation-block.ts

@@ -4,10 +4,10 @@
  * @author Teffen Ellis, et al.
  */
 
-import { type MultiPolygonLiteral } from "@mailwoman/spatial"
+import type { MultiPolygonLiteral } from "@mailwoman/spatial"
 
-import { TIGERProperty, type TIGERPropertyRecord } from "./constants.ts"
-import { GeoIDPart, type FIPSBlockGeoID, type ParsedGeoIDBlockLevel } from "./geoid.ts"
+import type { TIGERProperty, TIGERPropertyRecord } from "./constants.ts"
+import type { GeoIDPart, FIPSBlockGeoID, ParsedGeoIDBlockLevel } from "./geoid.ts"
 
 /**
  * The properties of a tabulated block from the TIGER/Line dataset.

package/tools/race-dots-map.ts

@@ -19,25 +19,43 @@
 
 import { writeFileSync } from "node:fs"
 
-/** Options for {@linkcode raceDotsMap}. */
+/**
+ * Options for {@linkcode raceDotsMap}.
+ */
 export interface RaceDotsMapOptions {
-	/** Dots tileset URL the page reads client-side. Default `http://localhost:8899/race-dots-oc.pmtiles`. */
+	/**
+	 * Dots tileset URL the page reads client-side. Default `http://localhost:8899/race-dots-oc.pmtiles`.
+	 */
 	pmtilesURL?: string
-	/** Output HTML path. Default `/tmp/race-dots-oc.html`. */
+	/**
+	 * Output HTML path. Default `/tmp/race-dots-oc.html`.
+	 */
 	out?: string
-	/** People represented by one dot (title/legend copy only). Default 5. */
+	/**
+	 * People represented by one dot (title/legend copy only). Default 5.
+	 */
 	per?: number
-	/** Page title. Default derives from `per`. */
+	/**
+	 * Page title. Default derives from `per`.
+	 */
 	title?: string
-	/** Initial map center longitude. Default -117.83 (Orange County, CA). */
+	/**
+	 * Initial map center longitude. Default -117.83 (Orange County, CA).
+	 */
 	lng?: number
-	/** Initial map center latitude. Default 33.68. */
+	/**
+	 * Initial map center latitude. Default 33.68.
+	 */
 	lat?: number
-	/** Initial map zoom. Default 9.4. */
+	/**
+	 * Initial map zoom. Default 9.4.
+	 */
 	zoom?: number
 }
 
-/** Result of {@linkcode raceDotsMap}. */
+/**
+ * Result of {@linkcode raceDotsMap}.
+ */
 export interface RaceDotsMapResult {
 	outPath: string
 	pmtilesURL: string
@@ -53,7 +71,9 @@ const BASEMAP_TILEJSON_URL = "https://tiles.sister.software/basemap-v4.json"
 const GLYPHS_URL = "https://protomaps.github.io/basemaps-assets/fonts/{fontstack}/{range}.pbf"
 const SPRITE_URL = "https://protomaps.github.io/basemaps-assets/sprites/v4/light"
 
-// Cooper Center "Racial Dot Map" palette, by `pl_block`/P2 category.
+/**
+ * Cooper Center "Racial Dot Map" palette, by `pl_block`/P2 category.
+ */
 const CATEGORY_COLOR: Record<string, string> = {
 	white: "#1f78b4", // blue
 	black: "#33a02c", // green
@@ -64,6 +84,7 @@ const CATEGORY_COLOR: Record<string, string> = {
 	other: "#b15928", // brown
 	multi: "#9e9e9e", // grey
 }
+
 const CATEGORY_LABEL: Record<string, string> = {
 	white: "White (non-Hispanic)",
 	black: "Black (non-Hispanic)",
@@ -75,7 +96,9 @@ const CATEGORY_LABEL: Record<string, string> = {
 	multi: "Two or more races",
 }
 
-/** Race-dots MapLibre page writer — see the module doc. */
+/**
+ * Race-dots MapLibre page writer — see the module doc.
+ */
 export async function raceDotsMap(
 	options: RaceDotsMapOptions = {},
 	report?: (line: string) => void
@@ -97,6 +120,7 @@ export async function raceDotsMap(
 	for (const [cat, color] of Object.entries(CATEGORY_COLOR)) {
 		colorMatch.push(cat, color)
 	}
+
 	colorMatch.push("#9e9e9e")
 
 	const style = {

package/tools/race-dots.ts

@@ -26,32 +26,54 @@ import { DatabaseSync } from "node:sqlite"
 
 import { dataRootPath } from "@mailwoman/core/utils"
 
-/** Options for {@linkcode raceDots}. */
+/**
+ * Attempts to place a dot inside its polygon by rejection sampling before giving up on it.
+ */
+const MAX_PLACEMENT_TRIES = 60
+
+/**
+ * Options for {@linkcode raceDots}.
+ */
 export interface RaceDotsOptions {
-	/** TIGER SQLite DB (`tabblock20` ⋈ `pl_block`). Default `$MAILWOMAN_DATA_ROOT/tiger/tiger-oc.db`. */
+	/**
+	 * TIGER SQLite DB (`tabblock20` ⋈ `pl_block`). Default `$MAILWOMAN_DATA_ROOT/tiger/tiger-oc.db`.
+	 */
 	db?: string
-	/** Output NDJSON path. Default `/tmp/race-dots.ndjson`. */
+	/**
+	 * Output NDJSON path. Default `/tmp/race-dots.ndjson`.
+	 */
 	out?: string
-	/** People represented by one dot. Default 10. */
+	/**
+	 * People represented by one dot. Default 10.
+	 */
 	per?: number
-	/** Tippecanoe layer name. Default `dots`. */
+	/**
+	 * Tippecanoe layer name. Default `dots`.
+	 */
 	layer?: string
 }
 
-/** Result of {@linkcode raceDots}. */
+/**
+ * Result of {@linkcode raceDots}.
+ */
 export interface RaceDotsResult {
 	outPath: string
 	dots: number
 	skipped: number
 	blocks: number
-	/** Dots emitted per P2 category. */
+	/**
+	 * Dots emitted per P2 category.
+	 */
 	totals: Record<string, number>
 }
 
-// The eight P2 categories (columns in pl_block) that partition each block's population.
+/**
+ * The eight P2 categories (columns in pl_block) that partition each block's population.
+ */
 const CATEGORIES = ["hispanic", "white", "black", "asian", "aian", "nhpi", "other", "multi"] as const
 
 type Ring = number[][]
+
 type PolygonCoords = Ring[]
 
 function bbox(rings: PolygonCoords): [number, number, number, number] {
@@ -81,7 +103,9 @@ function bbox(rings: PolygonCoords): [number, number, number, number] {
 	return [minX, minY, maxX, maxY]
 }
 
-/** Race-by-dot-density NDJSON builder — see the module doc. */
+/**
+ * Race-by-dot-density NDJSON builder — see the module doc.
+ */
 export async function raceDots(
 	options: RaceDotsOptions = {},
 	report?: (line: string) => void
@@ -103,15 +127,18 @@ export async function raceDots(
 		while (pick < polys.length - 1 && (r -= areas[pick]!) > 0) {
 			pick++
 		}
+
 		const poly = polys[pick]!
+
 		const polyFeature = {
 			type: "Feature" as const,
 			geometry: { type: "Polygon" as const, coordinates: poly },
 			properties: {},
 		}
+
 		const [minX, minY, maxX, maxY] = bbox(poly)
 
-		for (let tries = 0; tries < 60; tries++) {
+		for (let tries = 0; tries < MAX_PLACEMENT_TRIES; tries++) {
 			const x = minX + Math.random() * (maxX - minX)
 			const y = minY + Math.random() * (maxY - minY)
 			const pt = { type: "Feature" as const, geometry: { type: "Point" as const, coordinates: [x, y] }, properties: {} }
@@ -123,6 +150,7 @@ export async function raceDots(
 	}
 
 	const db = new DatabaseSync(DB, { readOnly: true })
+
 	const rows = db
 		.prepare(
 			`SELECT b.geometry AS geometry, ${CATEGORIES.map((c) => `p.${c} AS ${c}`).join(", ")}
@@ -130,10 +158,12 @@ export async function raceDots(
 			 WHERE p.pop_total > 0`
 		)
 		.all() as Array<{ geometry: string } & Record<(typeof CATEGORIES)[number], number>>
+
 	db.close()
 
 	const out = createWriteStream(OUT)
 	const totals = new Map<string, number>()
+
 	let dots = 0,
 		skipped = 0
 
@@ -145,13 +175,16 @@ export async function raceDots(
 		} catch {
 			continue
 		}
+
 		const polys: PolygonCoords[] =
 			geom.type === "Polygon" ? [geom.coordinates as PolygonCoords] : (geom.coordinates as PolygonCoords[])
+
 		const areas = polys.map((p) => {
 			const [a, b, c, d] = bbox(p)
 
 			return Math.max((c - a) * (d - b), 1e-12)
 		})
+
 		const totalArea = areas.reduce((s, a) => s + a, 0)
 
 		for (const cat of CATEGORIES) {
@@ -166,8 +199,10 @@ export async function raceDots(
 
 				if (!pt) {
 					skipped++
+
 					continue
 				}
+
 				out.write(
 					JSON.stringify({
 						type: "Feature",
@@ -176,6 +211,7 @@ export async function raceDots(
 						geometry: { type: "Point", coordinates: [Math.round(pt[0] * 1e5) / 1e5, Math.round(pt[1] * 1e5) / 1e5] },
 					}) + "\n"
 				)
+
 				dots++
 				totals.set(cat, (totals.get(cat) ?? 0) + 1)
 			}
@@ -183,10 +219,14 @@ export async function raceDots(
 	}
 
 	out.end()
-	await new Promise<void>((resolve) => out.on("finish", () => resolve()))
+
+	await new Promise<void>((resolve) => {
+		out.on("finish", () => resolve())
+	})
+
 	report?.(`[done] ${dots} dots from ${rows.length} blocks (1 dot ≈ ${PER} people); ${skipped} skipped`)
 
-	for (const [cat, n] of [...totals.entries()].sort((a, b) => b[1] - a[1])) {
+	for (const [cat, n] of [...totals.entries()].toSorted((a, b) => b[1] - a[1])) {
 		report?.(`  ${n.toString().padStart(7)}  ${cat}`)
 	}
 

package/tools/serve-range.ts

@@ -15,15 +15,23 @@ import { createReadStream, statSync, type Stats } from "node:fs"
 import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http"
 import { extname, join, normalize } from "node:path"
 
-/** Options for {@linkcode serveWithRangeSupport}. */
+/**
+ * Options for {@linkcode serveWithRangeSupport}.
+ */
 export interface ServeRangeOptions {
-	/** Directory to serve. Default `/tmp`. */
+	/**
+	 * Directory to serve. Default `/tmp`.
+	 */
 	dir?: string
-	/** Port to listen on. Default 8899. */
+	/**
+	 * Port to listen on. Default 8899.
+	 */
 	port?: number
 }
 
-/** A running range-capable static server, resolved once listening. */
+/**
+ * A running range-capable static server, resolved once listening.
+ */
 export interface RangeServer {
 	dir: string
 	port: number
@@ -62,6 +70,7 @@ export function serveWithRangeSupport(
 
 			return res.end("not found")
 		}
+
 		const type = TYPES[extname(path)] || "application/octet-stream"
 		const base = { "Content-Type": type, "Accept-Ranges": "bytes", "Access-Control-Allow-Origin": "*" }
 		const range = req.headers.range
@@ -70,11 +79,13 @@ export function serveWithRangeSupport(
 		if (m) {
 			const start = Number(m[1])
 			const end = m[2] ? Number(m[2]) : st.size - 1
+
 			res.writeHead(206, {
 				...base,
 				"Content-Range": `bytes ${start}-${end}/${st.size}`,
 				"Content-Length": end - start + 1,
 			})
+
 			createReadStream(path, { start, end }).pipe(res)
 		} else {
 			res.writeHead(200, { ...base, "Content-Length": st.size })
@@ -84,6 +95,7 @@ export function serveWithRangeSupport(
 
 	return new Promise<RangeServer>((resolve, reject) => {
 		server.once("error", reject)
+
 		server.listen(port, () => {
 			report?.(`range server: ${dir} on http://localhost:${port}`)
 			resolve({ dir, port, server, close: () => server.close() })