@mailwoman/tiger 10.0.0 → 10.2.0

package/lib/{sdk/schema.ts → schema.ts}

@@ -2,18 +2,20 @@
  * @copyright Sister Software.
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   TIGER SQLite schema, as a string so it loads in both `tsx` source mode and the compiled CLI
- *   (`tsc` doesn't copy `.sql` assets into `out/`). Geometry is GeoJSON text — NOT SpatiaLite. The
- *   prior SpatiaLite path (`load_extension` of a hardcoded macOS dylib + WKB `GEOM` columns) never
- *   loaded on Linux; plain text keeps the build dependency-free and `node:sqlite`-native (read it
- *   back with `JSON.parse`).
  */
 
 import { sql, type Kysely } from "kysely"
 
+/**
+ * Re-exports Kysely's `Generated` column marker alongside the table types,
+ * so schema consumers need not import Kysely for it.
+ */
 export { type Generated } from "kysely"
 
+/**
+ * The Kysely row type for `tabblock20`, one row per 2020 Census tabulation block
+ * with its geography codes, counts and geometry.
+ */
 export interface TIGERBlockTable {
 	GEOID: string
 	state_code: string
@@ -31,9 +33,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`.
+ * The Kysely row type for `pl_block`, one row per tabulation block from the 2020 P.L.
+ * 94-171 tables P2 and H1, keyed on the same `GEOID` as {@link TIGERBlockTable}.
+ * The eight race and ethnicity columns partition `pop_total`.
  */
 export interface PLBlockTable {
 	GEOID: string
@@ -46,22 +48,27 @@ export interface PLBlockTable {
 	nhpi: number
 	other: number
 	multi: number
+
 	/**
-	 * P.L. 94-171 table H1 — total housing units in the block.
+	 * Total housing units in the block, from P.L. 94-171 table H1.
 	 */
 	housing_units: number
+
 	/**
-	 * H1 occupied. `occupied + vacant === housing_units` by construction; the reader refuses a row where it is not.
+	 * Occupied housing units from table H1.
+	 *
+	 * `occupied + vacant` always equals `housing_units`, because the reader refuses any row where it does not.
 	 */
 	occupied: number
+
 	/**
-	 * H1 vacant.
+	 * Vacant housing units from table H1.
 	 */
 	vacant: number
 }
 
 /**
- * Kysely row type for `tiger_streets` (ADDRFEAT — named street segments + ZIPs, per county).
+ * Kysely row type for `tiger_streets` (addrfeat — street segments with names and ZIPs, per county).
  */
 export interface TIGERStreetTable {
 	linearid: string
@@ -72,7 +79,7 @@ export interface TIGERStreetTable {
 }
 
 /**
- * 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
@@ -84,7 +91,7 @@ export interface TIGERPlaceTable {
 }
 
 /**
- * The TIGER database schema, for `new DatabaseClient<TIGERDatabase>(...)`.
+ * The tiger database schema, for `new DatabaseClient<TIGERDatabase>(...)`.
  */
 export interface TIGERDatabase {
 	tabblock20: TIGERBlockTable
@@ -94,36 +101,16 @@ export interface TIGERDatabase {
 }
 
 /**
- * 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,
- * and PRAGMA has no Kysely builder). The consumer execs this, then calls {@link initializeTIGERSchema} for the tables +
- * indexes.
+ * The build-tuning pragmas to execute before {@link initializeTIGERSchema},
+ * since `page_size` and `auto_vacuum` take effect only on an empty database.
  */
-export const TIGER_PRAGMAS = /* sql */ `
+export const TIGER_PRAGMAS = `
 PRAGMA auto_vacuum = INCREMENTAL;
 PRAGMA page_size = 4096;
 PRAGMA cache_size = 10000;
 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.
- *
- * 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.
- */
-/**
- * Refuse a `pl_block` built before the H1 columns existed. `createTable(...).ifNotExists()` leaves an older table as it
- * is, and the next load would fail on the first insert with a message about a column, not about the cause. The table is
- * derived (the redistricting command reloads it state by state), so the remedy is a rebuild: drop it and re-run
- * `mailwoman tiger redistricting` for each state you hold. Databases are never patched in place.
- */
 async function assertPLBlockShape(db: Kysely<TIGERDatabase>): Promise<void> {
 	const columns = await sql<{ name: string }>`select name from pragma_table_info('pl_block')`.execute(db)
 	const names = new Set(columns.rows.map((row) => row.name))
@@ -137,6 +124,12 @@ async function assertPLBlockShape(db: Kysely<TIGERDatabase>): Promise<void> {
 	}
 }
 
+/**
+ * Creates the TIGER tables and indexes if they do not exist.
+ *
+ * It throws when an existing `pl_block` lacks the H1 housing columns,
+ * because that derived table must be dropped and reloaded.
+ */
 export async function initializeTIGERSchema(db: Kysely<TIGERDatabase>): Promise<void> {
 	await db.schema
 		.createTable("us_state")
@@ -175,8 +168,6 @@ export async function initializeTIGERSchema(db: Kysely<TIGERDatabase>): Promise<
 		.addColumn("geometry", "text", (c) => c.notNull())
 		.execute()
 
-	// 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
@@ -211,8 +202,7 @@ export async function initializeTIGERSchema(db: Kysely<TIGERDatabase>): Promise<
 		.addColumn("housing_units", "integer", (c) => c.notNull())
 		.addColumn("occupied", "integer", (c) => c.notNull())
 		.addColumn("vacant", "integer", (c) => c.notNull())
-		// pl_block is small (no geometry) and always probed by its GEOID PK (1:1 join to tabblock20), so
-		// cluster it WITHOUT ROWID — one B-tree probe per join, no separate rowid + PK-index pair.
+
 		.modifyEnd(sql`without rowid`)
 		.execute()
 

package/lib/state.ts

@@ -9,7 +9,7 @@ import type { GeoFeature, MultiPolygonLiteral } from "@mailwoman/spatial"
 import type { GeoIDPart } from "#geoid"
 import type { TIGERTabulatedBlockProperties } from "#tabulation-block"
 
-//#region FIPS Codes
+// #region FIPS Codes
 
 /**
  * FIPS codes for US States.
@@ -365,7 +365,7 @@ export const AdminLevel1CodeToAbbreviation = {
 /**
  * Type-predicate to determine if a given string is a valid state FIPS code.
  */
-export function isStateFIPSCode(code: string | null | undefined): code is FIPSStateCode {
+export function isStateFIPSCode(code: string | null): code is FIPSStateCode {
 	if (!code || typeof code !== "string") return false
 
 	return Object.hasOwn(FIPSStateCodeToAbbreviation, code)
@@ -374,7 +374,7 @@ export function isStateFIPSCode(code: string | null | undefined): code is FIPSSt
 /**
  * Type-predicate to determine if a given string is a valid territory FIPS code.
  */
-export function isTerritoryFIPSCode(code: string | null | undefined): code is FIPSTerritoryCode {
+export function isTerritoryFIPSCode(code: string | null): code is FIPSTerritoryCode {
 	if (!code || typeof code !== "string") return false
 
 	return Object.hasOwn(FIPSTerritoryCodeToAbbreviation, code)
@@ -385,13 +385,13 @@ export function isTerritoryFIPSCode(code: string | null | undefined): code is FI
  *
  * This includes both states and territories.
  */
-export function isAdminLevel1FIPSCode(code: string | null | undefined): code is AdminLevel1Code {
+export function isAdminLevel1FIPSCode(code: string | null): code is AdminLevel1Code {
 	return isStateFIPSCode(code) || isTerritoryFIPSCode(code)
 }
 
-//#endregion
+// #endregion
 
-//#region State Abbreviation
+// #region State Abbreviation
 
 /**
  * Two-letter abbreviations of a US states.
@@ -457,7 +457,8 @@ 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.
+ * Postal abbreviations for US territories, kept apart from the states
+ * so callers can include or exclude them.
  */
 export const TerritoryAbbreviation = {
 	"American Samoa": "AS",
@@ -480,16 +481,16 @@ 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.
+ * Every admin-level-1 postal abbreviation — the fifty states, DC and the territories together.
  */
 export const AdminLevel1Abbreviation = {
 	...StateAbbreviation,
 	...TerritoryAbbreviation,
 } as const
 
-//#endregion
+// #endregion
 
-//#region State Name
+// #region State Name
 
 /**
  * US State abbreviations to their full names.
@@ -558,13 +559,13 @@ export const StateName = {
 
 export type StateName = (typeof StateName)[keyof typeof StateName]
 
-//#endregion
+// #endregion
 
-//#region State Utilities
+// #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.
@@ -576,7 +577,8 @@ 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.
@@ -588,7 +590,8 @@ 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.
@@ -631,17 +634,17 @@ export interface StateDetails {
 	 */
 	FIPSCode: string
 	/**
-	 * The ANSI code for the state or territory.
+	 * The ansi code for the state or territory.
 	 *
-	 * @title ANSI Code
+	 * @title ansi Code
 	 */
 	ANSICode: string
 }
 
 /**
- * A US state as defined by the Census Bureau's TIGER system.
+ * A US state as defined by the Census Bureau's tiger system.
  *
- * @title Census TIGER State
+ * @title Census tiger State
  * @public
  */
 export interface TIGERState {
@@ -667,8 +670,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
 	 */
@@ -677,4 +680,4 @@ export interface TIGERState {
 
 export type TIGERStateFeature = GeoFeature<MultiPolygonLiteral, TIGERTabulatedBlockProperties>
 
-//#endregion
+// #endregion

package/lib/tabulation-block.ts

@@ -10,7 +10,7 @@ import type { TIGERProperty, TIGERPropertyRecord } from "#constants"
 import type { GeoIDPart, FIPSBlockGeoID, ParsedGeoIDBlockLevel } from "#geoid"
 
 /**
- * The properties of a tabulated block from the TIGER/Line dataset.
+ * The properties of a tabulated block from the tiger/Line dataset.
  */
 export type TIGERTabulatedBlockProperties = Pick<
 	TIGERPropertyRecord<FIPSBlockGeoID>,
@@ -47,7 +47,7 @@ export interface TIGERBlockFeatureCollection {
 }
 
 /**
- * A tabulated block from the TIGER/Line dataset.
+ * A tabulated block from the tiger/Line dataset.
  *
  * @public
  */
@@ -60,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/lib/tract.ts

@@ -10,7 +10,7 @@ import type { TIGERProperty, TIGERPropertyRecord } from "#constants"
 import type { FIPSTractGeoID, GeoIDPart, ParsedGeoIDTractLevel } from "#geoid"
 
 /**
- * @title TIGER Tract
+ * @title tiger Tract
  * @public
  */
 export interface TIGERTract extends ParsedGeoIDTractLevel {
@@ -22,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
 	 */

package/out/block-group.d.ts

@@ -8,7 +8,7 @@ import type { TIGERFunctionalStatus } from "#functional-status";
 import type { LegalStatisticalAreaDescription } from "#legal-statistical-area";
 import type { AdminLevel1Code } from "#state";
 /**
- * @title TIGER Block Group
+ * @title tiger Block Group
  * @public
  */
 export interface TIGERBlockGroup {
@@ -32,16 +32,16 @@ export interface TIGERBlockGroup {
      */
     COUSUBFP: string;
     /**
-     * @title County Subdivision GNIS Code
+     * @title County Subdivision gnis Code
      *
      * @minLength 8
      * @maxLength 8
      * @pattern ^\d{8}$
-     * @see {@link https://www.usgs.gov/us-board-on-geographic-names/domestic-names | USGS: Domestic Names}
+     * @see {@link https://www.usgs.gov/us-board-on-geographic-names/domestic-names | usgs: Domestic Names}
      */
     COUSUBNS: string;
     /**
-     * @title Block Group GEOID
+     * @title Block Group geoid
      *
      * @minLength 10
      * @maxLength 10
@@ -49,7 +49,7 @@ export interface TIGERBlockGroup {
      */
     GEOID: string;
     /**
-     * Fully Qualified GEOID as used in CEDSCI and other systems.
+     * Fully Qualified geoid as used in cedsci and other systems.
      *
      * @title Fully Qualified Geographic Identifier
      * @minLength 19
@@ -78,9 +78,9 @@ export interface TIGERBlockGroup {
      */
     CLASSFP: TIGERClassCode;
     /**
-     * MAF/TIGER Feature Class Code.
+     * MAF/tiger Feature Class Code.
      *
-     * @title MAF/TIGER Feature Class Code
+     * @title MAF/tiger Feature Class Code
      *
      * @minLength 5
      * @maxLength 5