@mailwoman/tiger 8.0.0 → 8.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailwoman/tiger",
-  "version": "8.0.0",
+  "version": "8.2.0",
   "description": "US Census TIGER/Line data processing and analysis.",
   "keywords": [
     "census",
@@ -73,8 +73,8 @@
     "test": "node ./out/sdk/TIGERService.test.js"
   },
   "dependencies": {
-    "@mailwoman/core": "8.0.0",
-    "@mailwoman/spatial": "8.0.0",
+    "@mailwoman/core": "8.2.0",
+    "@mailwoman/spatial": "8.2.0",
     "@turf/boolean-contains": "^7.3.5",
     "kysely": "^0.29.4",
     "shapefile-parser": "^1.0.3",

package/sdk/fetch.ts

@@ -52,6 +52,7 @@ const LEVEL_DIR: Record<TIGERFetchLevel, string> = {
 	place: "PLACE",
 	addrfeat: "ADDRFEAT",
 }
+
 const LEVEL_TABLE: Record<TIGERFetchLevel, keyof TIGERDatabase> = {
 	tabblock20: "tabblock20",
 	place: "tiger_places",
@@ -59,21 +60,33 @@ const LEVEL_TABLE: Record<TIGERFetchLevel, keyof TIGERDatabase> = {
 }
 
 export interface FetchTIGEROptions {
-	/** Two-digit state FIPS, e.g. `"06"`. */
+	/**
+	 * Two-digit state FIPS, e.g. `"06"`.
+	 */
 	stateFIPS: string
-	/** TIGER level. Default `tabblock20`. */
+	/**
+	 * TIGER level. Default `tabblock20`.
+	 */
 	level?: TIGERFetchLevel
-	/** Vintage. Default 2020 for blocks (matches the 2020 P.L.), 2024 for place/addrfeat (current). */
+	/**
+	 * Vintage. Default 2020 for blocks (matches the 2020 P.L.), 2024 for place/addrfeat (current).
+	 */
 	vintage?: number
 	/**
 	 * Output SQLite path. Default `<dataRoot>/tiger/tiger.db` (the name the corpus `tiger` adapter reads).
 	 */
 	outPath?: string
-	/** Download cache + default output root. */
+	/**
+	 * Download cache + default output root.
+	 */
 	dataRoot?: string
-	/** Optional three-digit county FIPS filter (blocks only — addrfeat is already per-county). */
+	/**
+	 * Optional three-digit county FIPS filter (blocks only — addrfeat is already per-county).
+	 */
 	county?: string
-	/** Rows per insert. Default 1000. */
+	/**
+	 * Rows per insert. Default 1000.
+	 */
 	batchSize?: number
 }
 
@@ -88,7 +101,9 @@ export interface FetchTIGERResult {
 	inserted: number
 }
 
-/** The isp-nexus column map for `tabblock20`. Geometry rides along implicitly. */
+/**
+ * The isp-nexus column map for `tabblock20`. Geometry rides along implicitly.
+ */
 function blockSelectSQL(layer: string, county?: string): string {
 	const where = county ? ` WHERE COUNTYFP20 = '${county}'` : ""
 
@@ -162,6 +177,7 @@ function runCapture(cmd: string, args: string[]): Promise<string> {
 		child.stdout.on("data", (d) => (out += d))
 		child.stderr.on("data", (d) => (err += d))
 		child.on("error", reject)
+
 		child.on("close", (code) =>
 			code === 0 ? resolve(out) : reject(new Error(`${cmd} exited ${code}: ${err.slice(0, 500)}`))
 		)
@@ -178,6 +194,7 @@ async function downloadIfNeeded(url: string, dest: string): Promise<boolean> {
 			// corrupt cache — re-download
 		}
 	}
+
 	const tmp = dest + ".tmp"
 	const res = await fetch(url, { redirect: "follow" })
 
@@ -188,7 +205,9 @@ async function downloadIfNeeded(url: string, dest: string): Promise<boolean> {
 	return false
 }
 
-/** Scrape the ADDRFEAT directory listing for a state's county FIPS codes. */
+/**
+ * Scrape the ADDRFEAT directory listing for a state's county FIPS codes.
+ */
 async function discoverCounties(state: string, vintage: number): Promise<string[]> {
 	const res = await fetch(`${CENSUS_HOST}/geo/tiger/TIGER${vintage}/ADDRFEAT/`, { redirect: "follow" })
 
@@ -201,7 +220,7 @@ async function discoverCounties(state: string, vintage: number): Promise<string[
 		counties.add(m[1]!)
 	}
 
-	return [...counties].sort()
+	return [...counties].toSorted()
 }
 
 /**
@@ -227,7 +246,7 @@ export async function* fetchTIGER(options: FetchTIGEROptions): AsyncGenerator<Fe
 	// Source units: one (per-state) for block/place; one per county for addrfeat.
 	const geoCodes = level === "addrfeat" ? await discoverCounties(state, vintage) : [""]
 
-	if (level === "addrfeat" && geoCodes.length === 0) {
+	if (level === "addrfeat" && !geoCodes.length) {
 		throw new Error(`No ADDRFEAT counties found for state ${state} vintage ${vintage}`)
 	}
 
@@ -267,6 +286,7 @@ export async function* fetchTIGER(options: FetchTIGEROptions): AsyncGenerator<Fe
 
 		let inserted = 0
 		let batch: Row[] = []
+
 		const flush = async () => {
 			if (!batch.length) return
 			const rows = batch
@@ -303,9 +323,13 @@ export async function* fetchTIGER(options: FetchTIGEROptions): AsyncGenerator<Fe
 				],
 				{ stdio: ["ignore", "pipe", "pipe"] }
 			)
+
 			let stderr = ""
 			child.stderr.on("data", (d) => (stderr += d))
-			const exited = new Promise<number>((resolve) => child.on("close", (code) => resolve(code ?? 0)))
+
+			const exited = new Promise<number>((resolve) => {
+				child.on("close", (code) => resolve(code ?? 0))
+			})
 
 			// GeoJSONSeq is line-delimited; keep the per-line `JSON.parse` in a try/catch so a malformed
 			// record is tolerated (skipped), not thrown.
@@ -329,6 +353,7 @@ export async function* fetchTIGER(options: FetchTIGEROptions): AsyncGenerator<Fe
 					yield { phase: "load", inserted, total: 0 }
 				}
 			}
+
 			await flush()
 
 			const code = await exited

package/sdk/redistricting.ts

@@ -33,18 +33,26 @@ import { initializeTIGERSchema, TIGER_PRAGMAS, type PLBlockTable, type TIGERData
 
 const REDISTRICTING_BASE =
 	"https://www2.census.gov/programs-surveys/decennial/2020/data/01-Redistricting_File--PL_94-171"
+
 const DEFAULT_DATA_ROOT = mailwomanDataRoot()
 
-// P.L. 94-171 (2020) pipe-delimited field offsets (0-based).
-// Geographic header: …|SUMLEV(2)|…|LOGRECNO(7)|GEOID(8)|GEOCODE(9)|… — GEOCODE is the bare 15-char
-// block FIPS (matches TIGER GEOID20); SUMLEV 750 = tabulation block.
+/**
+ * P.L. 94-171 (2020) pipe-delimited field offsets (0-based). Geographic header:
+ * …|SUMLEV(2)|…|LOGRECNO(7)|GEOID(8)|GEOCODE(9)|… — GEOCODE is the bare 15-char block FIPS (matches TIGER GEOID20);
+ * SUMLEV 750 = tabulation block.
+ */
 const GEO_SUMLEV = 2
 const GEO_LOGRECNO = 7
 const GEO_GEOCODE = 9
-// Segment 1: FILEID|STUSAB|CHARITER|CIFSN|LOGRECNO(4)| P1×71 | P2×73. P0020001 is at index 76.
+/**
+ * Segment 1: FILEID|STUSAB|CHARITER|CIFSN|LOGRECNO(4)| P1×71 | P2×73. P0020001 is at index 76.
+ */
 const SEG_LOGRECNO = 4
 const P2 = (fieldNo: number) => 76 + (fieldNo - 1)
-// The eight P2 categories that partition the total (P0020001), in `pl_block` column order.
+
+/**
+ * The eight P2 categories that partition the total (P0020001), in `pl_block` column order.
+ */
 const CATEGORY_INDEX = {
 	pop_total: P2(1),
 	hispanic: P2(2), // Hispanic or Latino (any race)
@@ -58,17 +66,29 @@ const CATEGORY_INDEX = {
 } as const
 
 export interface FetchRedistrictingOptions {
-	/** Two-digit state FIPS, e.g. `"06"`. */
+	/**
+	 * Two-digit state FIPS, e.g. `"06"`.
+	 */
 	stateFIPS: string
-	/** Decennial vintage. Default 2020 (the only P.L. 94-171 release this parses). */
+	/**
+	 * Decennial vintage. Default 2020 (the only P.L. 94-171 release this parses).
+	 */
 	vintage?: number
-	/** Output SQLite path. Default `<dataRoot>/tiger/tiger.db` (same DB as `fetchTIGER`). */
+	/**
+	 * Output SQLite path. Default `<dataRoot>/tiger/tiger.db` (same DB as `fetchTIGER`).
+	 */
 	outPath?: string
-	/** Download cache + default output root. */
+	/**
+	 * Download cache + default output root.
+	 */
 	dataRoot?: string
-	/** Optional three-digit county FIPS filter, e.g. `"059"`. */
+	/**
+	 * Optional three-digit county FIPS filter, e.g. `"059"`.
+	 */
 	county?: string
-	/** Rows per insert. Default 2000. */
+	/**
+	 * Rows per insert. Default 2000.
+	 */
 	batchSize?: number
 }
 
@@ -92,6 +112,7 @@ function runCapture(cmd: string, args: string[]): Promise<string> {
 		child.stdout.on("data", (d) => (out += d))
 		child.stderr.on("data", (d) => (err += d))
 		child.on("error", reject)
+
 		child.on("close", (code) =>
 			code === 0 ? resolve(out) : reject(new Error(`${cmd} exited ${code}: ${err.slice(0, 500)}`))
 		)
@@ -108,6 +129,7 @@ async function downloadIfNeeded(url: string, dest: string): Promise<boolean> {
 			// corrupt cache — re-download
 		}
 	}
+
 	const tmp = dest + ".tmp"
 	const res = await fetch(url, { redirect: "follow" })
 
@@ -145,7 +167,7 @@ export async function* fetchRedistricting(
 
 	if (!abbr) throw new Error(`Unknown state FIPS "${state}"`)
 	const stateName = StateName[abbr as keyof typeof StateName]
-	const dirName = stateName.replace(/ /g, "_")
+	const dirName = stateName.replaceAll(" ", "_")
 	const fileAbbr = abbr.toLowerCase()
 
 	const cacheDir = join(dataRoot, "census", "redistricting", String(vintage), state)
@@ -169,6 +191,7 @@ export async function* fetchRedistricting(
 	// Pass 1: header → LOGRECNO → GEOID for the blocks we want.
 	const prefix = options.county ? state + options.county : state
 	const logToGeoid = new Map<string, string>()
+
 	await eachLine(geoPath, (line) => {
 		const f = line.split("|")
 
@@ -178,6 +201,7 @@ export async function* fetchRedistricting(
 		if (!geoid.startsWith(prefix)) return
 		logToGeoid.set(f[GEO_LOGRECNO] ?? "", geoid)
 	})
+
 	const total = logToGeoid.size
 	yield { phase: "header", blocks: total }
 
@@ -195,6 +219,7 @@ export async function* fetchRedistricting(
 
 		let inserted = 0
 		let batch: PLBlockTable[] = []
+
 		const flush = async () => {
 			if (!batch.length) return
 			const rows = batch
@@ -210,6 +235,7 @@ export async function* fetchRedistricting(
 			const geoid = logToGeoid.get(f[SEG_LOGRECNO] ?? "")
 
 			if (!geoid) continue
+
 			batch.push({
 				GEOID: geoid,
 				pop_total: Number(f[CATEGORY_INDEX.pop_total] ?? 0),
@@ -228,6 +254,7 @@ export async function* fetchRedistricting(
 				yield { phase: "load", inserted, total }
 			}
 		}
+
 		await flush()
 
 		yield { phase: "load", inserted, total }

package/sdk/schema.ts

@@ -10,9 +10,10 @@
  *   back with `JSON.parse`).
  */
 
-import { sql, type Generated, type Kysely } from "kysely"
+import { sql, type Kysely } from "kysely"
+
+export { type Generated } from "kysely"
 
-/** Kysely row type for `tabblock20`. Geometry is a GeoJSON string. */
 export interface TIGERBlockTable {
 	GEOID: string
 	state_code: string
@@ -47,7 +48,9 @@ export interface PLBlockTable {
 	multi: number
 }
 
-/** Kysely row type for `tiger_streets` (ADDRFEAT — named street segments + ZIPs, per county). */
+/**
+ * Kysely row type for `tiger_streets` (ADDRFEAT — named street segments + ZIPs, per county).
+ */
 export interface TIGERStreetTable {
 	linearid: string
 	fullname: string
@@ -56,7 +59,9 @@ export interface TIGERStreetTable {
 	statefp: string
 }
 
-/** Kysely row type for `tiger_places` (PLACE — incorporated/census places, per state). */
+/**
+ * Kysely row type for `tiger_places` (PLACE — incorporated/census places, per state).
+ */
 export interface TIGERPlaceTable {
 	geoid: string
 	name: string
@@ -66,7 +71,9 @@ export interface TIGERPlaceTable {
 	classfp: string | null
 }
 
-/** The TIGER database schema, for `new DatabaseClient<TIGERDatabase>(...)`. */
+/**
+ * The TIGER database schema, for `new DatabaseClient<TIGERDatabase>(...)`.
+ */
 export interface TIGERDatabase {
 	tabblock20: TIGERBlockTable
 	pl_block: PLBlockTable
@@ -74,8 +81,9 @@ export interface TIGERDatabase {
 	tiger_places: TIGERPlaceTable
 }
 
-/** Marker so callers can opt into `Generated` columns later without importing kysely here. */
-export type { Generated }
+/**
+ * Marker so callers can opt into `Generated` columns later without importing kysely here.
+ */
 
 /**
  * Build-tuning PRAGMAs, run raw before any table is created (`page_size`/`auto_vacuum` only take effect on an empty DB,
@@ -139,18 +147,21 @@ export async function initializeTIGERSchema(db: Kysely<TIGERDatabase>): Promise<
 	// No index on GEOID alone — it's the PRIMARY KEY, which already carries a unique index. The prior
 	// schema's idx_tabblock20_geoid duplicated that for nothing (double insert cost, double footprint).
 	await db.schema.createIndex("idx_tabblock20_state_code").ifNotExists().on("tabblock20").column("state_code").execute()
+
 	await db.schema
 		.createIndex("idx_tabblock20_state_county")
 		.ifNotExists()
 		.on("tabblock20")
 		.columns(["state_code", "county_code"])
 		.execute()
+
 	await db.schema
 		.createIndex("idx_tabblock20_state_county_tract")
 		.ifNotExists()
 		.on("tabblock20")
 		.columns(["state_code", "county_code", "tract_code"])
 		.execute()
+
 	await db.schema.createIndex("idx_tabblock20_population").ifNotExists().on("tabblock20").column("population").execute()
 
 	await db.schema
@@ -180,7 +191,9 @@ export async function initializeTIGERSchema(db: Kysely<TIGERDatabase>): Promise<
 		.addColumn("zipr", "text")
 		.addColumn("statefp", "text", (c) => c.notNull())
 		.execute()
+
 	await db.schema.createIndex("idx_tiger_streets_statefp").ifNotExists().on("tiger_streets").column("statefp").execute()
+
 	await db.schema
 		.createIndex("idx_tiger_streets_linearid")
 		.ifNotExists()
@@ -198,6 +211,7 @@ export async function initializeTIGERSchema(db: Kysely<TIGERDatabase>): Promise<
 		.addColumn("namelsad", "text")
 		.addColumn("classfp", "text")
 		.execute()
+
 	await db.schema.createIndex("idx_tiger_places_statefp").ifNotExists().on("tiger_places").column("statefp").execute()
 	await db.schema.createIndex("idx_tiger_places_geoid").ifNotExists().on("tiger_places").column("geoid").execute()
 }

package/sdk/state/TIGERTractEntity.ts

@@ -4,7 +4,7 @@
  * @author Teffen Ellis, et al.
  */
 
-import { AdminLevel1Code, type FIPSCountyCode, type FIPSTractCode } from "@mailwoman/tiger"
+import type { AdminLevel1Code, FIPSCountyCode, FIPSTractCode } from "@mailwoman/tiger"
 
 /**
  * @internal

package/sdk/state/block-operations.ts

@@ -6,13 +6,13 @@
 
 import type { GeometryLiteral, MultiPolygonLiteral } from "@mailwoman/spatial"
 import { wellKnownGeometryToGeoJSON } from "@mailwoman/spatial/sdk"
-import {
+import type {
 	FIPSStateCode,
-	type FIPSBlockGeoID,
-	type FIPSTractCode,
-	type TIGERBlockFeature,
-	type TIGERBlockFeatureCollection,
-	type TIGERTabulatedBlockProperties,
+	FIPSBlockGeoID,
+	FIPSTractCode,
+	TIGERBlockFeature,
+	TIGERBlockFeatureCollection,
+	TIGERTabulatedBlockProperties,
 } from "@mailwoman/tiger"
 
 export interface StateBlockIntersectionCriteria {
@@ -57,6 +57,7 @@ export function parseTIGERBlockFromRow({ serializedGeometry, ...properties }: TI
  */
 export function parseTIGERBlockFeatureCollectionFromRows(rows: TIGERBlockRow[]): TIGERBlockFeatureCollection {
 	const features = rows.map(parseTIGERBlockFromRow)
+
 	const featureCollection: TIGERBlockFeatureCollection = {
 		type: "FeatureCollection",
 		features,