@mailwoman/tiger 10.0.0 → 10.2.0

package/lib/constants.ts

@@ -22,7 +22,7 @@ import type { FIPSStateCode } from "#state"
 /**
  * A code indicating the classification of the block, i.e. urban or rural.
  *
- * @title TIGER Geographic Classification
+ * @title tiger Geographic Classification
  *
  * @minLength 1
  * @maxLength 1
@@ -54,7 +54,7 @@ export const LandWaterBlockType = {
 export type LandWaterBlockType = (typeof LandWaterBlockType)[keyof typeof LandWaterBlockType]
 
 /**
- * @title TIGER Property
+ * @title tiger Property
  */
 export const TIGERProperty = {
 	/**
@@ -106,7 +106,7 @@ export const TIGERProperty = {
 	 */
 	LegalStatisticalAreaDescription: "legal_statistical_area_description",
 	/**
-	 * @title MAF/TIGER Feature Class Code
+	 * @title MAF/tiger Feature Class Code
 	 */
 	ClassCode: "class_code",
 } as const
@@ -175,7 +175,8 @@ export interface TIGERPropertyRecord<GeoID extends string = string> {
 	/**
 	 * A code indicating a specific urban area, such as a specific city, or a specific region of cities.
 	 *
-	 * For example, 23824 references Detroit, MI. 63217 references the region of New York City, Jersey City, and Newark.
+	 * For example, 23824 references Detroit, MI. 63217 references the region of
+	 * New York City, Jersey City and Newark.
 	 *
 	 * @title Urban Area Code
 	 * @minLength 5
@@ -204,7 +205,7 @@ export interface TIGERPropertyRecord<GeoID extends string = string> {
 	/**
 	 * The tabulated block's housing unit count.
 	 *
-	 * Note: This is the number of housing units in the block, not the number of people.
+	 * Note: This is the number of housing units in the block rather than the number of people.
 	 *
 	 * @type {integer}
 	 * @title Housing Units
@@ -227,7 +228,7 @@ export interface TIGERPropertyRecord<GeoID extends string = string> {
 	[TIGERProperty.LegalStatisticalAreaDescription]: LegalStatisticalAreaDescription
 
 	/**
-	 * @title MAF/TIGER Feature Class Code
+	 * @title MAF/tiger Feature Class Code
 	 */
 	[TIGERProperty.ClassCode]: TIGERClassCode
 

package/lib/county/subdivision.ts

@@ -12,7 +12,7 @@ import type { AdminLevel1Code } from "#state"
 /**
  * Census Geographic subdivision of a county.
  *
- * @title TIGER County Subdivision
+ * @title tiger County Subdivision
  * @public
  */
 export interface TIGERCountySubdivision {
@@ -39,16 +39,16 @@ export interface TIGERCountySubdivision {
 	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
 	/**
-	 * Concatenation of current state FIPS code, county FIPS code, and county subdivision FIPS code.
+	 * Concatenation of current state FIPS code, county FIPS code and county subdivision FIPS code.
 	 *
 	 * @title County Sub-division Identifier
 	 * @minLength 10
@@ -59,7 +59,7 @@ export interface TIGERCountySubdivision {
 	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
@@ -92,9 +92,9 @@ export interface TIGERCountySubdivision {
 	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

package/lib/{county/index.ts → county.ts}

@@ -10,7 +10,7 @@ import type { LegalStatisticalAreaDescription } from "#legal-statistical-area"
 import type { AdminLevel1Code } from "#state"
 
 /**
- * @title TIGER County
+ * @title tiger County
  * @public
  */
 export interface TIGERCounty {
@@ -28,17 +28,17 @@ export interface TIGERCounty {
 	COUNTYFP: string
 
 	/**
-	 * @title County GNIS Code
+	 * @title County 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}
 	 */
 	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
@@ -71,9 +71,9 @@ export interface TIGERCounty {
 	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
@@ -132,6 +132,6 @@ export interface TIGERCounty {
 }
 
 /**
- * Brand symbol marking a value as a TIGER county record, so a bare object cannot be passed as one.
+ * Brand symbol marking a value as a tiger county record, so a bare object cannot be passed as one.
  */
 export const TIGERCountySymbol = Symbol.for("TIGERCounty")

package/lib/files.ts

@@ -3,15 +3,15 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   TIGER Census data utilities.
+ *   tiger Census data utilities.
  */
 
 import type { AdminLevel1Code } from "#state"
 
-//#region Constants
+// #region Constants
 
 /**
- * Census TIGER levels for geographic data.
+ * Census tiger levels for geographic data.
  *
  * @category Census
  */
@@ -27,7 +27,7 @@ export const TIGERLevel = {
 export type TIGERLevel = (typeof TIGERLevel)[keyof typeof TIGERLevel]
 
 /**
- * File extension for TIGER data files.
+ * File extension for tiger data files.
  *
  * @category Census
  */
@@ -45,11 +45,13 @@ export const TIGERFileExtension = {
 	 */
 	Attributes: ".dbf",
 	/**
-	 * Coordinate system information. Describes the projection of the geographic data.
+	 * Coordinate system information.
+	 *
+	 * Describes the projection of the geographic data.
 	 */
 	Projection: ".prj",
 	/**
-	 * Federal Geographic Data Committee (FGDC) metadata.
+	 * Federal Geographic Data Committee (fgdc) metadata.
 	 */
 	FGDCMetadata: ".shp.xml",
 	/**
@@ -72,7 +74,7 @@ export const TIGERFileExtension = {
 export type TIGERFileExtension = (typeof TIGERFileExtension)[keyof typeof TIGERFileExtension]
 
 /**
- * Order of TIGER levels for processing, from largest to smallest.
+ * Order of tiger levels for processing, from largest to smallest.
  */
 export const TIGERLevelOrder = [
 	TIGERLevel.State,
@@ -83,7 +85,7 @@ export const TIGERLevelOrder = [
 ] as const satisfies TIGERLevel[]
 
 /**
- * The current TIGER vintage.
+ * The current tiger vintage.
  *
  * @category Census
  * @internal
@@ -92,12 +94,27 @@ export const TIGERCurrentVintage = 2023
 
 export type TIGERCurrentVintage = typeof TIGERCurrentVintage
 
-//#endregion
+/**
+ * Parses a TIGER release tag such as `TIGER2023` into its vintage year.
+ *
+ * @throws Error when the tag is not `TIGER` followed by a four-digit year.
+ */
+export function parseTIGERRelease(release: string): number {
+	const match = /^TIGER(\d{4})$/.exec(release)
+
+	if (!match) {
+		throw new Error(`A TIGER release tag looks like TIGER${TIGERCurrentVintage}, but got "${release}".`)
+	}
+
+	return Number(match[1])
+}
+
+// #endregion
 
-//#region File Name Generation
+// #region File Name Generation
 
 /**
- * Type-helper for TIGER feature geometry file names.
+ * Type-helper for tiger feature geometry file names.
  *
  * @category Census
  */
@@ -109,7 +126,7 @@ export type TIGERStateLevelFileName<
 > = `tl_${Vintage}_${SFC}_${Level}${FileExtension}`
 
 /**
- * Template function to generate a TIGER file name.
+ * Template function to generate a tiger file name.
  */
 export function TIGERStateLevelFileName<
 	SFC extends AdminLevel1Code,
@@ -134,7 +151,7 @@ export type TIGERStateLevelZIPPath<
 > = `/geo/tiger/TIGER${Vintage}/${Uppercase<Level>}/${TIGERStateLevelFileName<SFC, Level, typeof TIGERFileExtension.Zip, Vintage>}`
 
 /**
- * Template function to generate a TIGER ZIP file path.
+ * Template function to generate a tiger ZIP file path.
  */
 export function TIGERStateLevelZIPPath<
 	SFC extends AdminLevel1Code,
@@ -154,7 +171,7 @@ export function TIGERStateLevelZIPPath<
 }
 
 /**
- * Template function to generate a TIGER ZIP file path.
+ * Template function to generate a tiger ZIP file path.
  */
 export function TIGERNationZIPPath<Vintage extends number = TIGERCurrentVintage>(
 	vintage: Vintage = TIGERCurrentVintage as Vintage
@@ -163,17 +180,17 @@ export function TIGERNationZIPPath<Vintage extends number = TIGERCurrentVintage>
 
 	const path = `/geo/tiger/TIGER${vintage}/STATE/${fileName}` as const
 
-	// https://www2.census.gov/geo/tiger/TIGER2023/STATE/tl_2023_us_state.zip
+	// https://www2.census.gov/geo/tiger/TIGER2023/state/tl_2023_us_state.zip
 
 	return path
 }
 
-//#endregion
+// #endregion
 
-//#region Manifests
+// #region Manifests
 
 /**
- * A TIGER manifest for a specific state at a specific level of detail.
+ * A tiger manifest for a specific state at a specific level of detail.
  *
  * @category Census
  */
@@ -231,7 +248,7 @@ export function TIGERLevelManifest<
 }
 
 /**
- * A full TIGER manifest for a specific state.
+ * A full tiger manifest for a specific state.
  */
 export interface TIGERStateManifest<SFC extends AdminLevel1Code, Vintage extends number = TIGERCurrentVintage> {
 	Tract: TIGERLevelManifest<SFC, typeof TIGERLevel.Tract, Vintage>
@@ -261,4 +278,4 @@ export function TIGERStateManifest<SFC extends AdminLevel1Code, Vintage extends
 	return manifest as TIGERStateManifest<SFC, Vintage>
 }
 
-//#endregion
+// #endregion

package/lib/functional-status.ts

@@ -7,16 +7,18 @@
 /**
  * A code indicating the functional status of a governmental unit.
  *
- * @title TIGER Functional Status
+ * @title tiger Functional Status
  */
 export const TIGERFunctionalStatus = {
 	/**
-	 * Active government providing primary general-purpose functions. Active entity (federally recognized entities only).
+	 * Active government providing primary general-purpose functions.
+	 *
+	 * Active entity (federally recognized entities only).
 	 */
 	ActiveGovernment: "A",
 	/**
-	 * Active government that is partially consolidated with another government but with separate officials providing
-	 * primary general-purpose functions.
+	 * Active government that is partially consolidated with another government
+	 * but with separate officials providing primary general-purpose functions.
 	 */
 	PartiallyConsolidatedActiveGovernment: "B",
 	/**

package/lib/geoid.ts

@@ -8,13 +8,13 @@ import type { Tagged } from "type-fest"
 
 import type { AdminLevel1Code, FIPSStateCode } from "#state"
 
-//#region Tagged FIPS types
+// #region Tagged FIPS types
 
 /**
  * A 4-digit number assigned by the Census to uniquely identify a block.
  *
  * ```txt
- * (State Code)━━┳┓   ┏┳┳┳┳┳━━(Tract Code)
+ * (State Code)━━┳┓ ┏┳┳┳┳┳━━(Tract Code)
  *               482012231001050
  *                 ┗╋┛      ┗┻┻┻━(Block Code)
  *            (County Code)
@@ -36,7 +36,7 @@ export type FIPSBlockCode = Tagged<string, "FIPSBlockCode">
  * A 15-digit number assigned by the Census to uniquely identify a block.
  *
  * ```txt
- * (State Code)━━┳┓   ┏┳┳┳┳┳━━(Tract Code)
+ * (State Code)━━┳┓ ┏┳┳┳┳┳━━(Tract Code)
  *               482012231001050
  *                 ┗╋┛      ┗┻┻┻━(Block Code)
  *            (County Code)
@@ -57,7 +57,7 @@ export type FIPSBlockGeoID = Tagged<string, "FIPSBlockGeoID">
  * A 1-digit number assigned by the Census to uniquely identify a block group.
  *
  * ```txt
- * (State Code)━━┳┓   ┏┳┳┳┳┳━━(Tract Code)
+ * (State Code)━━┳┓ ┏┳┳┳┳┳━━(Tract Code)
  *               060133740002###
  *                 ┗╋┛      ┗━(Block Group Code)
  *            (County Code)
@@ -79,7 +79,7 @@ export type FIPSBlockGroupCode = Tagged<string, "FIPSBlockGroupCode">
  * A 6-digit number assigned by the Census to uniquely identify a tract.
  *
  * ```txt
- * (State Code)━━┳┓   ┏┳┳┳┳┳━━(Tract Code)
+ * (State Code)━━┳┓ ┏┳┳┳┳┳━━(Tract Code)
  *               06013374000####
  *                 ┗╋┛
  *            (County Code)
@@ -101,7 +101,7 @@ export type FIPSTractCode = Tagged<string, "FIPSTractCode">
  * An 11-digit number assigned by the Census to uniquely identify a tract.
  *
  * ```txt
- * (State Code)━━┳┓   ┏┳┳┳┳┳━━(Tract Code)
+ * (State Code)━━┳┓ ┏┳┳┳┳┳━━(Tract Code)
  *               06013374000####
  *                 ┗╋┛
  *            (County Code)
@@ -122,7 +122,7 @@ export type FIPSTractGeoID = Tagged<string, "FIPSTractGeoID">
  * A 5-digit number assigned by the Census to uniquely identify a county sub-division.
  *
  * ```txt
- * (State Code)━━┳┓   ┏┳┳┳┳━━(County Sub-Division Code)
+ * (State Code)━━┳┓ ┏┳┳┳┳━━(County Sub-Division Code)
  *               0601337400#####
  *                 ┗╋┛
  *            (County Code)
@@ -201,9 +201,9 @@ export type FIPSPlaceCode = Tagged<string, "FIPSPlaceCode">
  */
 export type FIPSCongressionalDistrictCode = Tagged<string, "FIPSConressionalDistrictCode">
 
-//#endregion
+// #endregion
 
-//#region GeoID Parsing Setup
+// #region GeoID Parsing Setup
 
 /**
  * A part of a GeoID to it's respective name.
@@ -238,15 +238,21 @@ export const GeoIDPart = {
 	 */
 	Place: "place_code",
 	/**
-	 * The tract code part of a GeoID. The third most granular part.
+	 * The tract code part of a GeoID.
+	 *
+	 * The third most granular part.
 	 */
 	Tract: "tract_code",
 	/**
-	 * The block group code part of a GeoID. The second most granular part.
+	 * The block group code part of a GeoID.
+	 *
+	 * The second most granular part.
 	 */
 	BlockGroup: "block_group_code",
 	/**
-	 * The block code part of a GeoID. The most granular part.
+	 * The block code part of a GeoID.
+	 *
+	 * The most granular part.
 	 */
 	Block: "block_code",
 } as const
@@ -254,7 +260,7 @@ export const GeoIDPart = {
 export type GeoIDPart = (typeof GeoIDPart)[keyof typeof GeoIDPart]
 
 /**
- * Mapping of GeoID parts to their respective FIPS codes types.
+ * This interface maps each `GeoID` part to its corresponding FIPS code type.
  *
  * @internal
  */
@@ -288,7 +294,9 @@ export const GeoIDPartLength = {
 } as const satisfies Record<GeoIDPart, number>
 
 /**
- * A GeoID parsed to the block level. The most granular level.
+ * A GeoID parsed to the block level.
+ *
+ * The most granular level.
  *
  * @title Parsed GeoID Block Level
  * @public
@@ -305,7 +313,9 @@ export interface ParsedGeoIDBlockLevel {
 }
 
 /**
- * A GeoID parsed to the block group level. The second most granular level.
+ * A GeoID parsed to the block group level.
+ *
+ * The second most granular level.
  *
  * @internal
  */
@@ -319,7 +329,9 @@ export interface ParsedGeoIDBlockGroupLevel {
 }
 
 /**
- * A GeoID parsed to the tract level. The third most granular level.
+ * A GeoID parsed to the tract level.
+ *
+ * The third most granular level.
  *
  * @internal
  */
@@ -340,7 +352,9 @@ export interface ParsedGeoIDTractLevel {
 export type ParsedGeoIDPartial = Partial<Record<GeoIDPart, string>>
 
 /**
- * A GeoID parsed to the county-subdivision level. The fourth most granular level.
+ * A GeoID parsed to the county-subdivision level.
+ *
+ * The fourth most granular level.
  *
  * @internal
  */
@@ -354,7 +368,9 @@ export interface ParsedGeoIDCountySubDivisionLevel {
 }
 
 /**
- * A GeoID parsed to the county level. The fifth most granular level.
+ * A GeoID parsed to the county level.
+ *
+ * The fifth most granular level.
  *
  * @internal
  */
@@ -368,7 +384,9 @@ export interface ParsedGeoIDCountyLevel {
 }
 
 /**
- * A GeoID parsed to the state level. The least granular level.
+ * A GeoID parsed to the state level.
+ *
+ * The least granular level.
  *
  * @internal
  */
@@ -401,9 +419,9 @@ export class GeoIDParsingError extends Error {
 	}
 }
 
-//#endregion
+// #endregion
 
-//#region GeoID Input Matchers
+// #region GeoID Input Matchers
 
 export class GeoIDInputMatcher<T extends GeoIDPart[] = GeoIDPart[]> {
 	public pattern: RegExp
@@ -526,9 +544,9 @@ export function isGeoIDComponent<T extends GeoIDPart>(component: T, input: unkno
 	return matcher.test(input)
 }
 
-//#endregion
+// #endregion
 
-//#region GeoID Parsing
+// #region GeoID Parsing
 
 /**
  * GeoID input matchers sorted by length in descending order, such that the most specific matchers are first.
@@ -625,9 +643,9 @@ export function parseGeoID(input: unknown): ParsedGeoID | null {
 	return null
 }
 
-//#endregion
+// #endregion
 
-//#region GeoID Formatting
+// #region GeoID Formatting
 
 /**
  * Format a parsed block GeoID back into a string.
@@ -682,4 +700,4 @@ export function formatGeoID(input: unknown): string | null {
 	return null
 }
 
-//#endregion
+// #endregion

package/lib/index.ts

@@ -8,7 +8,7 @@ export * from "#block-group"
 export * from "#class-code"
 export * from "#constants"
 export * from "#county/subdivision"
-export * from "#county/index"
+export * from "#county"
 export * from "#files"
 export * from "#functional-status"
 export * from "#geoid"

package/lib/legal-statistical-area.ts

@@ -7,10 +7,11 @@
 /**
  * Describes the particular typology for each geographic entity.
  *
- * For legal entities, the LSAD reflects the term that appears in legal documentation pertaining to the entity, such as
- * a treaty, charter, legislation, resolution, or ordinance.
+ * For legal entities, the lsad reflects the term that appears in legal documentation
+ * pertaining to the entity, such as a treaty, charter, legislation, resolution, or ordinance.
  *
- * For statistical entities, the LSAD is the term assigned by the Census Bureau or other agency defining the entity.
+ * For statistical entities, the lsad is the term assigned by the Census Bureau
+ * or other agency defining the entity.
  *
  * @title Legal/Statistical Area Description
  */
@@ -35,7 +36,7 @@ export const LegalStatisticalAreaDescription = {
 	 * - State or Equivalent Feature
 	 * - Tribal Subdivision
 	 * - Unified School District
-	 * - Voting District
+	 * - A Voting District
 	 */
 	Other: "00",
 	/**
@@ -95,7 +96,8 @@ export const LegalStatisticalAreaDescription = {
 	 */
 	CensusSubDistrict: "24",
 	/**
-	 * Consolidated City, County or Equivalent Feature, County Subdivision, Economic Census Place, Incorporated Place.
+	 * Consolidated City, County or Equivalent Feature, County Subdivision,
+	 * Economic Census Place, Incorporated Place.
 	 */
 	City: "25",
 	CountySuffixCountySubdivision: "26",