npm package: @mardillu/us-cities-utils
Description: A lightweight TypeScript utility library to work with US cities and ZIP codes — perfect for filters, maps, address lookups, and geolocation logic.
Author: Ezekiel Sebastine
Latest version: 1.2.7


[![Publish Package to NPM](https://github.com/mardillu/us-cities-utils/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/mardillu/us-cities-utils/actions/workflows/npm-publish.yml)
[![Publish Package to Github](https://github.com/mardillu/us-cities-utils/actions/workflows/npm-publish-github-packages.yml/badge.svg)](https://github.com/mardillu/us-cities-utils/actions/workflows/npm-publish-github-packages.yml)
[![Run Unit Tests](https://github.com/mardillu/us-cities-utils/actions/workflows/tests.yml/badge.svg)](https://github.com/mardillu/us-cities-utils/actions/workflows/tests.yml)

# US Cities & Zipcode Utilities

A lightweight TypeScript utility library to work with US cities and ZIP codes — perfect for filters, maps, address lookups, and geolocation logic.

---

## Features

- 🔍 **Get states** and cities from a normalized dataset
- 📬 Lookup city data by ZIP code
- 🗺️ Find the **nearest city** by coordinates (lat/lon)
- 🏙️ Search cities by name (fuzzy search)
- 📌 Filter cities by **state**, **county**, or ZIP
- 📦 Pure, fast, and dependency-free

---

## Installation

```bash
npm install @mardillu/us-cities-utils
# or
yarn add @mardillu/us-cities-utils
````

---

## Usage

```ts
import {
  getStates,
  getCities,
  getCity,
  getAllZips,
  searchCities,
  groupCitiesByState,
  getCitiesByCounty,
  getNearestCity
} from '@mardillu/us-cities-utils';
```

---

## API Reference

### `getStates(): UsState[]`

Returns a list of all US states in `{ nameAbbr: string, name: string }` format.

---

### `getCities(stateAbbr: string): UsCity[]`

Returns all cities in a given state abbreviation (e.g. `'NY'`, `'CA'`).

---

### `getCitiesBySateName(state): UsCity[]`

Returns all cities in a given state name (e.g. `'New York'`, `'California'`).

---

### `getZipcodes(stateAbbr): UsCity[]`

Returns all cities and zipcodes in a given state abbreviation (e.g. `'NY'`, `'CA'`).

---

### `getZipcodesBySateName(state): UsCity[]`

Returns all cities and zipcodes in a given state name (e.g. `'New York'`, `'California'`).

---

### `getCity(zip: string): UsCity | undefined`

Returns city information for a given ZIP code.

---

### `searchCities(query: string): UsCity[]`

Returns cities whose names match (or partially match) the search string.

---

### `searchCitiesInSate(stateAbbr: string, query: string): UsCity[]`

Returns cities whose names match (or partially match) the search string withing the provided state abbreviation.

---

### `searchCitiesInSateByStateName(state: string, query: string): UsCity[] `

Returns cities whose names match (or partially match) the search string withing the provided state name.

---

### `groupCitiesByState(): Record<string, UsCity[]>`

Groups all cities in the dataset by their state abbreviation.

---

### `getAllZips(): string[]`

Returns a list of all ZIP codes in the dataset.

---

### `getCitiesByCounty(county: string): UsCity[]`

Returns a list of cities belonging to a given county name.

---

### `getNearestCity(lat: number, lon: number): UsCity | undefined`

Finds and returns the city nearest to the given latitude and longitude using the Haversine formula.

---

## Testing

```bash
npm test
```

Includes robust unit tests for all exported functions and geolocation logic.

---

## Data Format

Each city is in the format:

```ts
interface UsCity {
  zip: string;
  name: string;
  state: string;
  stateAbbr: string;
  county: string;
  countCode: string;
  latitude: number;
  longitude: number;
}
```

---

## Roadmap

* [ ] Add support for Canadian provinces
* [ ] Add caching for nearest city lookup
* [ ] Add fuzzy scoring to `searchCities()`

---

## Contribution

PRs are welcome! If you'd like to contribute, open an issue or submit a PR.

---

## License

MIT © \Mardillu

```