Election Helpers

Overview

election-helpers is a lightweight JavaScript utility library that makes it easier to work with U.S. election data—FIPS codes, vote tallies, boundary checks, and more. Each helper is fully unit-tested and documented. If you need to turn messy election spreadsheets into clean insights, this package has your back.

Installation

npm install election-helpers --save

Usage

import {
  getStateAbbrFromStateFips,
  candidateVotePercentage,
} from 'election-helpers';

getStateAbbrFromStateFips('36'); // => 'NY'

candidateVotePercentage(3490, 9876); // => 35.34 (rounded)

For full examples, check the documentation site.

Testing

The project uses Vitest for fast, browser-like unit tests.

# Run tests once
npm test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

Coverage is automatically published to Codecov on every push.

API Reference

Below is a quick look at the available helpers. Each link jumps to the generated JSDoc on the docs site.

getStateFipsFromStateAbbr(stateAbbr) → string
stateAbbrToName(stateAbbr) → string
getStateAbbrFromStateFips(stateFips) → string
getStateCodeFromCountyFips(countyFips) → string
candidateVotePercentage(candidateVote, totalVotes) → number
sortCandidatesByVotes(candidates, sortFn?) → array
stateFipsToName(stateFips) → string
stateAbbrToFips(stateAbbreviation) → string
stateNameToFips(stateName) → string
boundariesAvailableForRaceType(raceType) → array
isBoundaryAvailableForRaceType(raceType, boundaryType)

Development

Quality Checks

This project uses modern tooling to ensure code quality:

# Run all quality checks (format, lint, test)
npm run check

# Individual checks
npm run format:check  # Check code formatting
npm run lint          # Run ESLint
npm run lint:fix      # Auto-fix linting issues
npm run format        # Format all code
npm test              # Run tests

TypeScript Support

TypeScript type definitions are included for better IDE support and autocomplete, even though the library is written in JavaScript.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for detailed guidelines.

Quick start:

Fork & clone the repo
npm install to grab dev deps
Create a branch, write code and matching tests
npm run check to ensure quality standards
Commit using Conventional Commits (npm run cz)
Open a PR—CI will handle the rest

Note: In true Room 302 fashion, we jokingly skip "security features." Feel free to prove us wrong with a well-crafted PR.