@isodb/us-states

Typed reference data for U.S. states, the District of Columbia, and U.S. territories.

Provides immutable datasets and convenient lookup utilities for common state identifiers such as USPS codes, names, and FIPS codes.

Part of the isodb project, providing typed reference datasets for developers.

Features

• Includes all 50 U.S. states
• Includes the District of Columbia
• Includes permanently inhabited U.S. territories
• Zero dependencies
• Immutable datasets
• Fully typed with TypeScript
• Lazy lookup indexes
• Tree-shakeable API

Installation

npm install @isodb/us-states

Usage

Import the dataset

import { states } from '@isodb/us-states';
console.log( states.length );

Lookup by USPS code

Finds a state by its USPS postal abbreviation:

import { byCode } from '@isodb/us-states';

const california = byCode( 'CA' );
console.log( california?.capital );

Lookup by name

Finds a state by its official English name:

import { byName } from '@isodb/us-states';
const texas = byName( 'Texas' );

Lookup by FIPS code

Finds a state by its FIPS code:

import { byFIPS } from '@isodb/us-states';
const alaska = byFIPS( '02' );

Filter the dataset

Filters states using the specified predicate:

import { filter } from '@isodb/us-states';
const westernStates = filter( state => state.region === 'West' );

Using the lookup service

import { lookup } from '@isodb/us-states';

lookup.byCode( 'CA' );
lookup.byName( 'California' );
lookup.byFIPS( '06' );

lookup.codes;
lookup.names;
lookup.fips;

Default export

import usStates from '@isodb/us-states';

usStates.byCode( 'NY' );
usStates.states;

Dataset

Each entry contains the following information:

| Property | Description | |----------|-------------| | code | USPS postal abbreviation | | name | Official English name | | capital | Capital city | | region | U.S. Census region | | division | U.S. Census division | | fips | Federal Information Processing Standard (FIPS) code | | type | Administrative type (state, district, or territory) |

Included territories

In addition to the 50 U.S. states, the dataset includes:

• District of Columbia (DC)
• American Samoa (AS)
• Guam (GU)
• Northern Mariana Islands (MP)
• Puerto Rico (PR)
• U.S. Virgin Islands (VI)

License

This project is licensed under the MIT License - see the LICENSE file for details.
© Copyright 2026 Paul Köhler (komed3).