amondar-libs/js-state-flow

A lightweight TypeScript package for working with U.S. state codes and names.

It provides:

• Fast in-memory lookups for state code/name conversions
• Prebuilt regex fragments for validation/parsing
• Support for custom vocabularies via plain objects or enums

Requirements

• Node.js ^18.x or higher (ESM support)

Installation

npm install @amondar-libs/js-us-flow

Quick Start

import { StateFlow } from '@amondar-libs/js-us-flow';

StateFlow.getAbbreviation('New York');   // "NY"
StateFlow.getName('ny');          // "New York"

// Regex fragments
const cityRegex = StateFlow.getCityRegex();
const regex = new RegExp('^' + cityRegex + '$');
regex.test('Los Angeles, CA'); // true

Core Concepts

There can be only one

This package is developed with one principle in mind:

• any search/mapping response is based on lowercase keys and normalized values.
• keys are lowercase for searching, and values are normalized for display.

Default Vocabulary

By default, all methods use the internal State enum, which contains 51 U.S. states.

Custom Vocabulary

Most methods accept a final argument (vocabulary) which can be any object or enum. This allows reuse of the same helpers with your own custom dataset.

API Reference

getAbbreviations(vocabulary = State): string[]

Returns all vocabulary keys (state abbreviations by default), e.g. ['AL', 'AZ', ..., 'WY'].

const codes = StateFlow.getAbbreviations();

getCount(vocabulary = State): number

Returns total number of items in the vocabulary.

const count = StateFlow.getCount(); // 51, including Hawaii, Alaska and District of Columbia

getNames(vocabulary = State): string[]

Returns all vocabulary values (state names by default), e.g. ['Alabama', 'New York', ...].

const names = StateFlow.getNames();

getAbbreviationsRegex(vocabulary = State): string

Returns a pipe-separated regex fragment of codes, e.g. AL|AZ|AR|....

const codeRegex = StateFlow.getAbbreviationsRegex();

getNamesRegex(vocabulary = State): string

Returns a pipe-separated regex fragment of names, e.g. Alabama|Arizona|....

const labelRegex = StateFlow.getNamesRegex();

getAbbreviationByNameMap(vocabulary = State): Record<string, string>

Returns a map of normalized snake_case names to abbreviations. Examples:

• new_york => NY
• west_virginia => WV

const map = StateFlow.getAbbreviationByNameMap();

getNameByAbbreviationMap(vocabulary = State): Record<string, string>

Returns a map of lowercase abbreviations to human-readable names. Examples:

• ny => New York
• al => Alabama

const map = StateFlow.getNameByAbbreviationMap();

getAbbreviation(name: string, lower: boolean = false, vocabulary = State): string | null

Converts a full state name to its short code. Behavior:

• Input is normalized (trimmed, squished, snake_cased)
• Returns null if state name is unknown
• Optional lowercase output

StateFlow.getAbbreviation('New York');         // "NY"
StateFlow.getAbbreviation('  New   York  ');   // "NY"
StateFlow.getAbbreviation('New York', true);   // "ny"
StateFlow.getAbbreviation('NY');               // null

getName(short: string, lower: boolean = false, vocabulary = State): string | null

Converts a short code to full state name. Behavior:

• Code lookup is case-insensitive
• Returns null if code is unknown
• Optional lowercase output

StateFlow.getName('NY');        // "New York"
StateFlow.getName('ny');        // "New York"
StateFlow.getName('NY', true);  // "new york"
StateFlow.getName('XX');        // null

getCityRegex(maxCityName: number = 30, defaultCity: string | null = null, vocabulary = State): string

Builds a regex fragment for values like:

• City, ST (code)
• City, State Name (label) Supports:
• Optional whitespace after comma
• Configurable max city length (maxCityName)
• Optional exact fallback city (defaultCity)

const regex = StateFlow.getCityRegex();
const pattern = new RegExp('^' + regex + '$');
pattern.test('New York, NY');       // true
pattern.test('New York, New York'); // true
pattern.test('Invalid City, XX');   // false

const regexWithDefault = StateFlow.getCityRegex(30, 'Anywhere');
const patternWithDefault = new RegExp('^' + regexWithDefault + '$');
patternWithDefault.test('Anywhere'); // true

getOriginRegex(maxCityName: number = 30, vocabulary = State): string

Builds a regex fragment that matches:

• City, ST
• City, State Name
• Standalone state code
• Standalone state label

const regex = StateFlow.getOriginRegex();
const pattern = new RegExp('^' + regex + '$');
pattern.test('NY');            // true
pattern.test('New York, NY');  // true
pattern.test('XX');            // false

search(query: string, vocabulary = State): Record<string, string>

Searches states by abbreviation fragment and returns matched pairs as:

• key: lowercase abbreviation
• value: full state name Behavior:
• Query is normalized (trimmed + lowercased)
• Empty/whitespace-only query returns an empty object
• Matches if query is contained in name or equals full abbreviation

// Search all with "n" in name.
StateFlow.search('n');
// {
//   nc: 'North Carolina',
//   ny: 'New York',
//   tn: 'Tennessee',
//   ...
// }

StateFlow.search('  NY  ');
// { ny: 'New York' }

StateFlow.search('   ');
// {}

getRandom(vocabulary = State): { abbreviation: string, name: string }

Returns one random item from vocabulary as an object:

• abbreviation: uppercase abbreviation
• name: full state name

const random = StateFlow.getRandom();
// {
//   abbreviation: 'NY',
//   name: 'New York',
// }

normalizeNameKey(name: string): string

Normalizes a name for use as a lookup key. Behavior:

• Trims whitespace
• Squishes multiple spaces into a single space (handles special whitespace like \u3164 and \u1160)
• Converts to lowercase
• Replaces spaces and hyphens with underscores

StateFlow.normalizeNameKey('  New   York  '); // "new_york"
StateFlow.normalizeNameKey('West-Virginia');  // "west_virginia"

Using a Custom Vocabulary

You can use any object or enum as a vocabulary.

enum Region {
    NORTH = 'N',
    SOUTH = 'S'
}

const codes = StateFlow.getAbbreviations(Region); // ['NORTH', 'SOUTH']
const names = StateFlow.getNames(Region);         // ['N', 'S']
const name = StateFlow.getName('north', false, Region); // 'N'

Caching Notes

This package caches computed arrays/regex strings in static Map properties within the StateFlow class.

• Improves repeated lookup performance.
• Cache is cleared when the application restarts.
• Fully compatible with modern JavaScript environments (Node.js, Browser, etc.).

Testing

Run tests with npm:

npm test

License

MIT