@mailwoman/tiger 9.0.0 → 9.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailwoman/tiger",
-  "version": "9.0.0",
+  "version": "9.2.0",
   "description": "US Census TIGER/Line data processing and analysis.",
   "keywords": [
     "census",
@@ -21,7 +21,7 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/sister-software/mailwoman.git",
-    "directory": "tiger"
+    "directory": "packages/tiger"
   },
   "files": [
     "out/",
@@ -33,9 +33,16 @@
     "!*.test.tsx",
     "!**/*.test.ts",
     "!**/*.test.tsx",
-    "!__snapshots__/"
+    "!__snapshots__/",
+    "!test/**"
   ],
   "type": "module",
+  "imports": {
+    "#index": {
+      "types": "./out/index.d.ts",
+      "default": "./out/index.js"
+    }
+  },
   "exports": {
     "./package.json": "./package.json",
     "./sdk": {
@@ -67,18 +74,23 @@
         "types": "./out/index.d.ts",
         "default": "./out/index.js"
       }
+    },
+    "imports": {
+      "#index": {
+        "types": "./out/index.d.ts",
+        "default": "./out/index.js"
+      }
     }
   },
   "scripts": {
     "test": "node ./out/sdk/TIGERService.test.js"
   },
   "dependencies": {
-    "@mailwoman/core": "9.0.0",
-    "@mailwoman/spatial": "9.0.0",
+    "@mailwoman/core": "9.2.0",
+    "@mailwoman/spatial": "9.2.0",
     "@turf/boolean-contains": "^7.3.5",
     "kysely": "^0.29.4",
-    "shapefile-parser": "^1.0.3",
-    "spliterator": "^6.0.1",
+    "spliterator": "^6.2.0",
     "type-fest": "^5.8.0"
   },
   "devDependencies": {

package/sdk/download.ts

@@ -14,45 +14,25 @@
  *   never holds it: a web stream piped to a write stream.
  */
 
-import { spawn } from "node:child_process"
 import { createWriteStream, existsSync } from "node:fs"
 import { rename } from "node:fs/promises"
 import { Readable } from "node:stream"
 import { pipeline } from "node:stream/promises"
 
-/**
- * Run a command and resolve its stdout, rejecting with the captured stderr on a non-zero exit.
- *
- * Used for the `unzip -tq` integrity probe below — a shelled-out check rather than a library one because the archives
- * are large and `unzip -t` streams them without materializing the contents.
- */
-export function runCapture(cmd: string, args: string[]): Promise<string> {
-	return new Promise((resolve, reject) => {
-		const child = spawn(cmd, args)
-		let out = ""
-		let err = ""
-		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)}`))
-		)
-	})
-}
+import { verifyZipIntegrity } from "@mailwoman/core/fs/zip"
 
 /**
  * Download `url` to `dest` unless a VALID copy is already there. Returns `true` when the cache was reused, `false` when
  * a download happened.
  *
- * "Valid" means `unzip -tq` passes — an existence check alone is not enough, because an interrupted download leaves a
- * plausible-looking file that fails only much later, inside ogr2ogr. Writes to a `.tmp` sibling and renames, so `dest`
- * is never a partial archive.
+ * "Valid" means every member's CRC-32 checks out — an existence check alone is not enough, because an interrupted
+ * download leaves a plausible-looking file that fails only much later, inside ogr2ogr. Writes to a `.tmp` sibling and
+ * renames, so `dest` is never a partial archive.
  */
 export async function downloadIfNeeded(url: string, dest: string): Promise<boolean> {
 	if (existsSync(dest)) {
 		try {
-			await runCapture("unzip", ["-tq", dest])
+			await verifyZipIntegrity(dest)
 
 			return true
 		} catch {

package/sdk/fetch.ts

@@ -25,19 +25,18 @@
  */
 
 import { spawn } from "node:child_process"
-import { createWriteStream, existsSync } from "node:fs"
-import { mkdir, rename } from "node:fs/promises"
+import { mkdir } from "node:fs/promises"
 import { dirname, join } from "node:path"
 import { DatabaseSync } from "node:sqlite"
-import { Readable } from "node:stream"
-import { pipeline } from "node:stream/promises"
 
+import { APIClient, pluckResponseData } from "@mailwoman/core/api"
+import { extractZipEntries } from "@mailwoman/core/fs/zip"
 import { DatabaseClient } from "@mailwoman/core/kysley/client"
 import { tryParsingJSON } from "@mailwoman/core/objects"
 import { mailwomanDataRoot } from "@mailwoman/core/utils"
 import { TextSpliterator } from "spliterator"
 
-import { downloadIfNeeded, runCapture } from "./download.ts"
+import { downloadIfNeeded } from "./download.ts"
 import type { TIGERBlockTable, TIGERDatabase, TIGERPlaceTable, TIGERStreetTable } from "./schema.ts"
 import { initializeTIGERSchema, TIGER_PRAGMAS } from "./schema.ts"
 
@@ -175,10 +174,11 @@ function buildRow(level: TIGERFetchLevel, p: Record<string, unknown>, geometry:
  * 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" })
+	// The LISTING only — a small HTML index. The per-county archives below stay on raw `fetch`, streaming to disk.
+	const html = await new APIClient({ displayName: "tiger-listing", retry: true })
+		.fetch<string>({ url: `${CENSUS_HOST}/geo/tiger/TIGER${vintage}/ADDRFEAT/`, responseType: "text" })
+		.then(pluckResponseData)
 
-	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>()
 
@@ -221,6 +221,11 @@ export async function* fetchTIGER(options: FetchTIGEROptions): AsyncGenerator<Fe
 	const kdb = new DatabaseClient<TIGERDatabase>({ database: db })
 	await initializeTIGERSchema(kdb)
 
+	/**
+	 * `level` picks the table AND the row shape, but nothing ties them at the type level: {@link buildRow} returns the
+	 * union and Kysely needs the arm's concrete row. The narrowings below are sound only because `buildRow` switches on
+	 * the SAME `level` — keep the two switches in step, or a row shape reaches the wrong table.
+	 */
 	const insertBatch = async (rows: Row[]): Promise<void> => {
 		if (level === "tabblock20") {
 			await kdb
@@ -270,7 +275,7 @@ export async function* fetchTIGER(options: FetchTIGEROptions): AsyncGenerator<Fe
 			const cached = await downloadIfNeeded(url, zipPath)
 			yield { phase: "download", file: zipName, cached }
 
-			await runCapture("unzip", ["-o", "-q", zipPath, "-d", cacheDir])
+			await extractZipEntries(zipPath, cacheDir)
 			const layer = `tl_${vintage}_${unit}_${level}`
 			const shpPath = join(cacheDir, layer + ".shp")
 			yield { phase: "extract", file: layer + ".shp" }

package/sdk/redistricting.ts

@@ -16,20 +16,17 @@
  *   https://www2.census.gov/programs-surveys/decennial/2020/data/01-Redistricting_File--PL_94-171/
  */
 
-import { spawn } from "node:child_process"
-import { createWriteStream, existsSync } from "node:fs"
-import { mkdir, rename } from "node:fs/promises"
+import { mkdir } from "node:fs/promises"
 import { dirname, join } from "node:path"
 import { DatabaseSync } from "node:sqlite"
-import { Readable } from "node:stream"
-import { pipeline } from "node:stream/promises"
 
+import { extractZipEntries } from "@mailwoman/core/fs/zip"
 import { DatabaseClient } from "@mailwoman/core/kysley/client"
 import { mailwomanDataRoot } from "@mailwoman/core/utils"
 import { TextSpliterator } from "spliterator"
 
 import { AdminLevel1CodeToAbbreviation, StateName, type AdminLevel1Code } from "../state.ts"
-import { downloadIfNeeded, runCapture } from "./download.ts"
+import { downloadIfNeeded } from "./download.ts"
 import { initializeTIGERSchema, TIGER_PRAGMAS, type PLBlockTable, type TIGERDatabase } from "./schema.ts"
 
 const REDISTRICTING_BASE =
@@ -148,7 +145,7 @@ export async function* fetchRedistricting(
 	const cached = await downloadIfNeeded(url, zipPath)
 	yield { phase: "download", file: zipName, cached }
 
-	await runCapture("unzip", ["-o", "-q", zipPath, "-d", cacheDir])
+	await extractZipEntries(zipPath, cacheDir)
 	const geoPath = join(cacheDir, `${fileAbbr}geo${vintage}.pl`)
 	const seg1Path = join(cacheDir, `${fileAbbr}00001${vintage}.pl`)
 	yield { phase: "extract", file: `${fileAbbr}geo${vintage}.pl` }

package/sdk/state/TIGERTabulatedBlockEntity.ts

@@ -5,7 +5,8 @@
  */
 
 import { smartSnakeCase } from "@mailwoman/core"
-import { TIGERProperty } from "@mailwoman/tiger"
+
+import { TIGERProperty } from "#index"
 
 /**
  * Default column selections for TIGER tabulated block entities.

package/sdk/state/TIGERTractEntity.ts

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

package/sdk/state/block-operations.ts

@@ -6,6 +6,7 @@
 
 import type { GeometryLiteral, MultiPolygonLiteral } from "@mailwoman/spatial"
 import { wellKnownGeometryToGeoJSON } from "@mailwoman/spatial/sdk"
+
 import type {
 	FIPSStateCode,
 	FIPSBlockGeoID,
@@ -13,7 +14,7 @@ import type {
 	TIGERBlockFeature,
 	TIGERBlockFeatureCollection,
 	TIGERTabulatedBlockProperties,
-} from "@mailwoman/tiger"
+} from "#index"
 
 export interface StateBlockIntersectionCriteria {
 	stateCode: FIPSStateCode

package/tools/index.ts

@@ -3,11 +3,7 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   TIGER operator tools — the `run()`-style modules behind `mailwoman tiger race-dots` /
- *   `race-dots-map` (see the 2026-07-09 scripts→Pastel spec). No argv, no `process.exit`: commands
- *   own parsing, rendering, and exit codes. Heavy deps (`@turf/boolean-contains`,
- *   `@protomaps/basemaps`) are lazy-imported inside their entry fns. NOT `sdk/` — that submodule
- *   means data acquisition.
+ *   TIGER operator tool exports.
  */
 
 export * from "./race-dots.ts"

package/tools/race-dots-map.ts

@@ -19,6 +19,8 @@
 
 import { writeFileSync } from "node:fs"
 
+import { tempRootPath } from "@mailwoman/core/utils"
+
 /**
  * Options for {@linkcode raceDotsMap}.
  */
@@ -104,7 +106,7 @@ export async function raceDotsMap(
 	report?: (line: string) => void
 ): Promise<RaceDotsMapResult> {
 	const PMTILES_URL = options.pmtilesURL || "http://localhost:8899/race-dots-oc.pmtiles"
-	const OUT = options.out || "/tmp/race-dots-oc.html"
+	const OUT = options.out || tempRootPath("race-dots-oc.html")
 	const PER = options.per ?? 5
 	const PER_PHRASE = PER === 1 ? "one dot is one person" : `one dot ≈ ${PER} people`
 	const TITLE = options.title || `Race in Orange County, CA — ${PER_PHRASE} (2020 Census)`

package/tools/race-dots.ts

@@ -25,7 +25,7 @@ import { createWriteStream } from "node:fs"
 import { DatabaseSync } from "node:sqlite"
 
 import { tryParsingJSON } from "@mailwoman/core/objects"
-import { dataRootPath } from "@mailwoman/core/utils"
+import { dataRootPath, tempRootPath } from "@mailwoman/core/utils"
 
 /**
  * Attempts to place a dot inside its polygon by rejection sampling before giving up on it.
@@ -112,7 +112,7 @@ export async function raceDots(
 	report?: (line: string) => void
 ): Promise<RaceDotsResult> {
 	const DB = options.db || dataRootPath("tiger", "tiger-oc.db")
-	const OUT = options.out || "/tmp/race-dots.ndjson"
+	const OUT = options.out || tempRootPath("race-dots.ndjson")
 	const PER = options.per ?? 10 // people represented by one dot
 	const LAYER = options.layer || "dots"
 

package/tools/serve-range.ts

@@ -15,6 +15,8 @@ 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"
 
+import { mailwomanTempRoot } from "@mailwoman/core/utils"
+
 /**
  * Options for {@linkcode serveWithRangeSupport}.
  */
@@ -55,7 +57,7 @@ export function serveWithRangeSupport(
 	options: ServeRangeOptions = {},
 	report?: (line: string) => void
 ): Promise<RangeServer> {
-	const dir = options.dir || "/tmp"
+	const dir = options.dir || mailwomanTempRoot()
 	const port = options.port ?? 8899
 
 	const server = createServer((req: IncomingMessage, res: ServerResponse) => {