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)

---

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:

1. Fork & clone the repo
2. npm install to grab dev deps
3. Create a branch, write code and matching tests
4. npm run check to ensure quality standards
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