Election Helpers

View on NPM

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)

---

Contributing

1. Fork & clone the repo.
2. npm install to grab dev deps.
3. Create a branch, write code and matching tests.
4. npm test should pass and coverage should stay 💯.
5. Commit using Conventional Commits (npm run cz).
6. 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.

---

License

MIT © EJ Fox