@mailwoman/tiger 4.16.1 → 5.0.0

package/package.json

@@ -1,7 +1,16 @@
 {
   "name": "@mailwoman/tiger",
-  "version": "4.16.1",
+  "version": "5.0.0",
   "description": "US Census TIGER/Line data processing and analysis.",
+  "keywords": [
+    "census",
+    "geospatial",
+    "tiger"
+  ],
+  "homepage": "https://github.com/sister-software/mailwoman",
+  "bugs": {
+    "url": "https://github.com/sister-software/mailwoman/issues"
+  },
   "license": "AGPL-3.0-only",
   "contributors": [
     {
@@ -14,13 +23,6 @@
     "url": "https://github.com/sister-software/mailwoman.git",
     "directory": "tiger"
   },
-  "bugs": {
-    "url": "https://github.com/sister-software/mailwoman/issues"
-  },
-  "homepage": "https://github.com/sister-software/mailwoman",
-  "scripts": {
-    "test": "node ./out/sdk/TIGERService.test.js"
-  },
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
@@ -29,9 +31,15 @@
     "./sdk": "./out/sdk/index.js",
     ".": "./out/index.js"
   },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node ./out/sdk/TIGERService.test.js"
+  },
   "dependencies": {
-    "@mailwoman/core": "4.16.1",
-    "@mailwoman/spatial": "4.16.1",
+    "@mailwoman/core": "5.0.0",
+    "@mailwoman/spatial": "5.0.0",
     "@turf/boolean-contains": "^7.3.5",
     "kysely": "^0.29.2",
     "shapefile-parser": "^1.0.3",
@@ -39,13 +47,5 @@
   },
   "engines": {
     "node": ">=24.18.0"
-  },
-  "keywords": [
-    "census",
-    "tiger",
-    "geospatial"
-  ],
-  "publishConfig": {
-    "access": "public"
   }
 }

package/sdk/fetch.ts

@@ -24,8 +24,6 @@
  *   inserts. Re-running a state replaces its rows.
  */
 
-import { DatabaseClient } from "@mailwoman/core/kysley/client"
-import { mailwomanDataRoot } from "@mailwoman/core/utils"
 import { spawn } from "node:child_process"
 import { createWriteStream, existsSync } from "node:fs"
 import { mkdir, rename } from "node:fs/promises"
@@ -34,6 +32,10 @@ import { createInterface } from "node:readline"
 import { DatabaseSync } from "node:sqlite"
 import { Readable } from "node:stream"
 import { pipeline } from "node:stream/promises"
+
+import { DatabaseClient } from "@mailwoman/core/kysley/client"
+import { mailwomanDataRoot } from "@mailwoman/core/utils"
+
 import type { TIGERBlockTable, TIGERDatabase, TIGERPlaceTable, TIGERStreetTable } from "./schema.js"
 import { initializeTIGERSchema, TIGER_PRAGMAS } from "./schema.js"
 
@@ -41,8 +43,7 @@ const CENSUS_HOST = "https://www2.census.gov"
 const DEFAULT_DATA_ROOT = mailwomanDataRoot()
 
 /**
- * Supported TIGER levels. `tabblock20` is per state + carries geometry; `place`/`addrfeat` are
- * attribute-only.
+ * Supported TIGER levels. `tabblock20` is per state + carries geometry; `place`/`addrfeat` are attribute-only.
  */
 export type TIGERFetchLevel = "tabblock20" | "place" | "addrfeat"
 
@@ -65,8 +66,7 @@ export interface FetchTIGEROptions {
 	/** 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).
+	 * Output SQLite path. Default `<dataRoot>/tiger/tiger.db` (the name the corpus `tiger` adapter reads).
 	 */
 	outPath?: string
 	/** Download cache + default output root. */
@@ -91,6 +91,7 @@ export interface FetchTIGERResult {
 /** The isp-nexus column map for `tabblock20`. Geometry rides along implicitly. */
 function blockSelectSQL(layer: string, county?: string): string {
 	const where = county ? ` WHERE COUNTYFP20 = '${county}'` : ""
+
 	return (
 		`SELECT GEOID20 AS GEOID, STATEFP20 AS state_code, COUNTYFP20 AS county_code, ` +
 		`SUBSTR(GEOID20, 6, 6) AS tract_code, ` +
@@ -171,6 +172,7 @@ async function downloadIfNeeded(url: string, dest: string): Promise<boolean> {
 	if (existsSync(dest)) {
 		try {
 			await runCapture("unzip", ["-tq", dest])
+
 			return true
 		} catch {
 			// corrupt cache — re-download
@@ -178,26 +180,30 @@ async function downloadIfNeeded(url: string, dest: string): Promise<boolean> {
 	}
 	const tmp = dest + ".tmp"
 	const res = await fetch(url, { redirect: "follow" })
+
 	if (!res.ok || !res.body) throw new Error(`HTTP ${res.status} fetching ${url}`)
 	await pipeline(Readable.fromWeb(res.body as Parameters<typeof Readable.fromWeb>[0]), createWriteStream(tmp))
 	await rename(tmp, dest)
+
 	return false
 }
 
 /** 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" })
+
 	if (!res.ok) throw new Error(`HTTP ${res.status} listing ADDRFEAT for vintage ${vintage}`)
 	const html = await res.text()
 	const re = new RegExp(`tl_${vintage}_${state}(\\d{3})_addrfeat\\.zip`, "g")
 	const counties = new Set<string>()
+
 	for (let m = re.exec(html); m; m = re.exec(html)) counties.add(m[1]!)
+
 	return [...counties].sort()
 }
 
 /**
- * Fetch one state's TIGER data at `level` into a SQLite DB. Yields progress; returns the final
- * tally.
+ * Fetch one state's TIGER data at `level` into a SQLite DB. Yields progress; returns the final tally.
  */
 export async function* fetchTIGER(options: FetchTIGEROptions): AsyncGenerator<FetchTIGEREvent, FetchTIGERResult> {
 	const level = options.level ?? "tabblock20"
@@ -218,6 +224,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) {
 		throw new Error(`No ADDRFEAT counties found for state ${state} vintage ${vintage}`)
 	}
@@ -296,14 +303,18 @@ export async function* fetchTIGER(options: FetchTIGEROptions): AsyncGenerator<Fe
 			for await (const line of createInterface({ input: child.stdout, crlfDelay: Infinity })) {
 				if (!line) continue
 				let feat: { properties?: Record<string, unknown>; geometry?: unknown }
+
 				try {
 					feat = JSON.parse(line)
 				} catch {
 					continue
 				}
+
 				if (!feat.properties) continue
+
 				if (level === "tabblock20" && !feat.geometry) continue
 				batch.push(buildRow(level, feat.properties, feat.geometry, state))
+
 				if (batch.length >= batchSize) {
 					await flush()
 					yield { phase: "load", inserted, total: 0 }
@@ -312,11 +323,13 @@ export async function* fetchTIGER(options: FetchTIGEROptions): AsyncGenerator<Fe
 			await flush()
 
 			const code = await exited
+
 			if (code !== 0) throw new Error(`ogr2ogr exited ${code} on ${layer}: ${stderr.slice(0, 500)}`)
 			yield { phase: "load", inserted, total: 0 }
 		}
 
 		db.exec("PRAGMA wal_checkpoint(TRUNCATE);")
+
 		return { outPath, table, inserted }
 	} finally {
 		await kdb.destroy()

package/sdk/redistricting.ts

@@ -16,8 +16,6 @@
  *   https://www2.census.gov/programs-surveys/decennial/2020/data/01-Redistricting_File--PL_94-171/
  */
 
-import { DatabaseClient } from "@mailwoman/core/kysley/client"
-import { mailwomanDataRoot } from "@mailwoman/core/utils"
 import { spawn } from "node:child_process"
 import { createReadStream, createWriteStream, existsSync } from "node:fs"
 import { mkdir, rename } from "node:fs/promises"
@@ -26,6 +24,10 @@ import { createInterface } from "node:readline"
 import { DatabaseSync } from "node:sqlite"
 import { Readable } from "node:stream"
 import { pipeline } from "node:stream/promises"
+
+import { DatabaseClient } from "@mailwoman/core/kysley/client"
+import { mailwomanDataRoot } from "@mailwoman/core/utils"
+
 import { AdminLevel1CodeToAbbreviation, StateName, type AdminLevel1Code } from "../state.js"
 import { initializeTIGERSchema, TIGER_PRAGMAS, type PLBlockTable, type TIGERDatabase } from "./schema.js"
 
@@ -100,6 +102,7 @@ async function downloadIfNeeded(url: string, dest: string): Promise<boolean> {
 	if (existsSync(dest)) {
 		try {
 			await runCapture("unzip", ["-tq", dest])
+
 			return true
 		} catch {
 			// corrupt cache — re-download
@@ -107,9 +110,11 @@ async function downloadIfNeeded(url: string, dest: string): Promise<boolean> {
 	}
 	const tmp = dest + ".tmp"
 	const res = await fetch(url, { redirect: "follow" })
+
 	if (!res.ok || !res.body) throw new Error(`HTTP ${res.status} fetching ${url}`)
 	await pipeline(Readable.fromWeb(res.body as Parameters<typeof Readable.fromWeb>[0]), createWriteStream(tmp))
 	await rename(tmp, dest)
+
 	return false
 }
 
@@ -120,8 +125,7 @@ async function eachLine(path: string, fn: (line: string) => void): Promise<void>
 }
 
 /**
- * Fetch one state's P.L. 94-171 block race counts into `pl_block`. Yields progress; returns the
- * tally.
+ * Fetch one state's P.L. 94-171 block race counts into `pl_block`. Yields progress; returns the tally.
  */
 export async function* fetchRedistricting(
 	options: FetchRedistrictingOptions
@@ -132,6 +136,7 @@ export async function* fetchRedistricting(
 	const state = options.stateFIPS
 
 	const abbr = AdminLevel1CodeToAbbreviation[state as AdminLevel1Code]
+
 	if (!abbr) throw new Error(`Unknown state FIPS "${state}"`)
 	const stateName = StateName[abbr as keyof typeof StateName]
 	const dirName = stateName.replace(/ /g, "_")
@@ -160,8 +165,10 @@ export async function* fetchRedistricting(
 	const logToGeoid = new Map<string, string>()
 	await eachLine(geoPath, (line) => {
 		const f = line.split("|")
+
 		if (f[GEO_SUMLEV] !== "750") return
 		const geoid = f[GEO_GEOCODE] ?? ""
+
 		if (!geoid.startsWith(prefix)) return
 		logToGeoid.set(f[GEO_LOGRECNO] ?? "", geoid)
 	})
@@ -195,6 +202,7 @@ export async function* fetchRedistricting(
 			if (!line) continue
 			const f = line.split("|")
 			const geoid = logToGeoid.get(f[SEG_LOGRECNO] ?? "")
+
 			if (!geoid) continue
 			batch.push({
 				GEOID: geoid,
@@ -208,6 +216,7 @@ export async function* fetchRedistricting(
 				other: Number(f[CATEGORY_INDEX.other] ?? 0),
 				multi: Number(f[CATEGORY_INDEX.multi] ?? 0),
 			})
+
 			if (batch.length >= batchSize) {
 				await flush()
 				yield { phase: "load", inserted, total }
@@ -217,6 +226,7 @@ export async function* fetchRedistricting(
 
 		yield { phase: "load", inserted, total }
 		db.exec("PRAGMA wal_checkpoint(TRUNCATE);")
+
 		return { outPath, table: "pl_block", inserted }
 	} finally {
 		await kdb.destroy()

package/sdk/schema.ts

@@ -30,9 +30,9 @@ export interface TIGERBlockTable {
 }
 
 /**
- * Kysely row type for `pl_block` — Census 2020 P.L. 94-171 table P2 (Hispanic-or-Latino by race),
- * one row per tabulation block, keyed on the same 15-char `GEOID` as {@link TIGERBlockTable}. The
- * eight category columns partition `pop_total`.
+ * Kysely row type for `pl_block` — Census 2020 P.L. 94-171 table P2 (Hispanic-or-Latino by race), one row per
+ * tabulation block, keyed on the same 15-char `GEOID` as {@link TIGERBlockTable}. The eight category columns partition
+ * `pop_total`.
  */
 export interface PLBlockTable {
 	GEOID: string
@@ -78,9 +78,9 @@ export interface TIGERDatabase {
 export type { Generated }
 
 /**
- * Build-tuning PRAGMAs, run raw before any table is created (`page_size`/`auto_vacuum` only take
- * effect on an empty DB, and PRAGMA has no Kysely builder). The consumer execs this, then calls
- * {@link initializeTIGERSchema} for the tables + indexes.
+ * Build-tuning PRAGMAs, run raw before any table is created (`page_size`/`auto_vacuum` only take effect on an empty DB,
+ * and PRAGMA has no Kysely builder). The consumer execs this, then calls {@link initializeTIGERSchema} for the tables +
+ * indexes.
  */
 export const TIGER_PRAGMAS = /* sql */ `
 PRAGMA auto_vacuum = INCREMENTAL;
@@ -90,13 +90,13 @@ PRAGMA journal_mode = WAL;
 `
 
 /**
- * Create the TIGER tables + indexes via the Kysely schema-builder (the house idiom). Idempotent
- * (`IF NOT EXISTS`). Pass a {@link DatabaseClient} (or any `Kysely`) over the TIGER DB; run
- * {@link TIGER_PRAGMAS} first. `us_state`/`tract` aren't in {@link TIGERDatabase} (created here but
- * not queried via Kysely) — `createTable` takes any table name, so that's fine.
+ * Create the TIGER tables + indexes via the Kysely schema-builder (the house idiom). Idempotent (`IF NOT EXISTS`). Pass
+ * a {@link DatabaseClient} (or any `Kysely`) over the TIGER DB; run {@link TIGER_PRAGMAS} first. `us_state`/`tract`
+ * aren't in {@link TIGERDatabase} (created here but not queried via Kysely) — `createTable` takes any table name, so
+ * that's fine.
  *
- * The `text(N)` length hints in the prior raw DDL were documentary only (SQLite uses TEXT affinity
- * regardless); the lengths live on the {@link TIGERBlockTable} interface instead.
+ * The `text(N)` length hints in the prior raw DDL were documentary only (SQLite uses TEXT affinity regardless); the
+ * lengths live on the {@link TIGERBlockTable} interface instead.
  */
 export async function initializeTIGERSchema(db: Kysely<TIGERDatabase>): Promise<void> {
 	await db.schema

package/sdk/state/block-operations.ts

@@ -51,8 +51,7 @@ export function parseTIGERBlockFromRow({ serializedGeometry, ...properties }: TI
 }
 
 /**
- * Given a collection of rows from the TIGER tabulated block table, parses them into a GeoJSON
- * feature collection.
+ * Given a collection of rows from the TIGER tabulated block table, parses them into a GeoJSON feature collection.
  *
  * @internal
  */

package/state.ts

@@ -5,6 +5,7 @@
  */
 
 import type { GeoFeature, MultiPolygonLiteral } from "@mailwoman/spatial"
+
 import { GeoIDPart } from "./geoid.js"
 import type { TIGERTabulatedBlockProperties } from "./tabulation-block.js"
 
@@ -180,10 +181,10 @@ export enum FIPSStateCode {
  * @category FIPS
  * @category Territories
  * @category Census
- * @see {@linkcode FIPSStateCode} for states.
- * @see {@linkcode AdminLevel1Code} for a combined set of states and territories.
  * @minLength 2
  * @maxLength 2
+ * @see {@linkcode FIPSStateCode} for states.
+ * @see {@linkcode AdminLevel1Code} for a combined set of states and territories.
  */
 export enum FIPSTerritoryCode {
 	/**
@@ -214,11 +215,11 @@ export enum FIPSTerritoryCode {
  * @category States
  * @category Territories
  * @category Census
- * @see {@linkcode FIPSStateCode} for states.
- * @see {@linkcode FIPSTerritoryCode} for territories.
  * @minLength 2
  * @maxLength 2
  * @public
+ * @see {@linkcode FIPSStateCode} for states.
+ * @see {@linkcode FIPSTerritoryCode} for territories.
  */
 export const AdminLevel1Code = {
 	...FIPSStateCode,
@@ -434,8 +435,8 @@ export enum StateName {
 //#region State Utilities
 
 /**
- * Predicate for checking if a string is a proper abbreviation for a US State or territory, rather
- * than a random 2-letter string.
+ * Predicate for checking if a string is a proper abbreviation for a US State or territory, rather than a random
+ * 2-letter string.
  *
  * @see {@link isStateAbbreviation} for a specific check for US States.
  * @see {@link isStateTerritoryAbbreviation} for a specific check for US Territories.
@@ -447,8 +448,7 @@ export function isStateLevelAbbreviation(input: unknown): input is AdminLevel1Ab
 }
 
 /**
- * Predicate for checking if a string is a proper abbreviation for a US State, rather than a random
- * 2-letter string.
+ * Predicate for checking if a string is a proper abbreviation for a US State, rather than a random 2-letter string.
  *
  * @see {@link isStateLevelAbbreviation} for a general check for US States and Territories.
  * @see {@link isStateTerritoryAbbreviation} for a specific check for US Territories.
@@ -460,8 +460,7 @@ export function isStateAbbreviation(input: unknown): input is StateAbbreviation
 }
 
 /**
- * Predicate for checking if a string is a proper abbreviation for a US Territory, rather than a
- * random 2-letter string.
+ * Predicate for checking if a string is a proper abbreviation for a US Territory, rather than a random 2-letter string.
  *
  * @see {@link isStateLevelAbbreviation} for a general check for US States and Territories.
  * @see {@link isStateAbbreviation} for a specific check for US States.
@@ -540,8 +539,8 @@ export interface TIGERState {
 	[GeoIDPart.State]: AdminLevel1Code
 
 	/**
-	 * The geometry of the tabulated block, typically a polygon, but may be a multi-polygon for blocks
-	 * with holes, or islands.
+	 * The geometry of the tabulated block, typically a polygon, but may be a multi-polygon for blocks with holes, or
+	 * islands.
 	 *
 	 * @title Geometry
 	 */

package/tabulation-block.ts

@@ -5,6 +5,7 @@
  */
 
 import { type MultiPolygonLiteral } from "@mailwoman/spatial"
+
 import { TIGERProperty, type TIGERPropertyRecord } from "./constants.js"
 import { GeoIDPart, type FIPSBlockGeoID, type ParsedGeoIDBlockLevel } from "./geoid.js"
 
@@ -59,8 +60,8 @@ export interface TIGERTabulatedBlock extends ParsedGeoIDBlockLevel, TIGERTabulat
 	GEOID: FIPSBlockGeoID
 
 	/**
-	 * The geometry of the tabulated block, typically a polygon, but may be a multi-polygon for blocks
-	 * with holes, or islands.
+	 * The geometry of the tabulated block, typically a polygon, but may be a multi-polygon for blocks with holes, or
+	 * islands.
 	 *
 	 * @title Geometry
 	 */

package/tract.ts

@@ -5,6 +5,7 @@
  */
 
 import { type GeoFeature, type MultiPolygonLiteral } from "@mailwoman/spatial"
+
 import { TIGERProperty, type TIGERPropertyRecord } from "./constants.js"
 import type { FIPSTractGeoID, GeoIDPart, ParsedGeoIDTractLevel } from "./geoid.js"
 
@@ -21,8 +22,8 @@ export interface TIGERTract extends ParsedGeoIDTractLevel {
 	GEOID: FIPSTractGeoID
 
 	/**
-	 * The geometry of the tabulated block, typically a polygon, but may be a multi-polygon for blocks
-	 * with holes, or islands.
+	 * The geometry of the tabulated block, typically a polygon, but may be a multi-polygon for blocks with holes, or
+	 * islands.
 	 *
 	 * @title Geometry
 	 */