ncsbe-lib
Version:
JavaScript library for working with North Carolina State Board of Elections (NCSBE) historical election data
188 lines (187 loc) • 8.28 kB
TypeScript
import { CandidateData, PrecinctData, CountyData, ContestData } from './types';
/**
* The `NCSBE` class provides an interface for fetching and querying election data
* from the North Carolina State Board of Elections (NCSBE). It uses the `Collector`
* class to retrieve, parse, and format election data.
*
* This class allows users to:
* - Retrieve election data for a specific date.
* - List available contests (races).
* - List counties where voting occurred for a given contest.
* - List precincts within a county for a specific contest.
*
* Example usage:
* ```typescript
* const electionData = new NCSBE("2024-11-05");
* await electionData.initialize();
* const contests = electionData.listContests();
* ```
*/
declare class NCSBE {
/** Election date in YYYY-MM-DD format. */
private electionDate;
/** URL to fetch the election data ZIP file. */
private url;
/** Cached dataset after calling `initialize()`. */
private dataSet;
/**
* Creates a new instance of `NCSBE` for a given election date.
* @param {string} electionDate - The date of the election in YYYY-MM-DD format.
*/
constructor(electionDate: string);
private static makeBaseUrl;
collect(): Promise<ContestData[]>;
/**
* Initializes the election dataset by fetching and storing the results in memory.
* This method **must** be called before using `listContests()`, `listCounties()`, etc.
* @returns {Promise<void>} - Resolves when the dataset is loaded.
*/
initialize(): Promise<void>;
/**
* Refreshes the election dataset by re-fetching and **completely replacing** `dataSet`
* with a new snapshot of the TSV file.
* @returns {Promise<void>} - Resolves when the dataset is loaded.
*/
refresh(): Promise<void>;
/**
* Retrieves contest data for a specific contest name.
* @param {string} contest - The contest name.
* @returns {ContestData | null} The contest data or null if not found.
*/
private getContestData;
/**
* Retrieves the entire election dataset.
* @returns {ContestData[] | null} The dataset, or null if it hasn't been initialized.
* @throws Will return null if `initialize()` has not been called.
*/
getDataset(): ContestData[] | null;
/**
* Retrieves a list of all contests (races) available in the dataset.
* @returns {string[]} An array of contest names.
* @throws Will return an empty array if `initialize()` has not been called.
*/
listContests(): string[];
/**
* Lists all counties where voting took place for a specific contest.
* @param {string} contest - The contest name (e.g., "US Senate").
* @returns {string[]} - An array of county names.
* @throws Will return an empty array if `initialize()` has not been called.
*/
listCounties(contest: string): string[];
/**
* Lists all precincts in a given county for a specific contest.
* @param {string} contest - The contest name (e.g., "US Senate").
* @param {string} county - The county name (e.g., "Wake").
* @returns {string[]} - An array of precinct names.
* @throws Will return an empty array if `initialize()` has not been called.
*/
listPrecincts(contest: string, county: string): string[];
/**
* Retrieves a list of candidates in a given contest.
* @param {string} contest - The contest name.
* @returns {string[]} An array of candidate names.
* @throws Will return an empty array if `initialize()` has not been called.
*/
listCandidates(contest: string): string[];
/**
* Retrieves a contest object by its name.
* @param {string} contest - The contest name.
* @returns {ContestData | null} The contest data or null if not found.
*/
getContest(contest: string): ContestData | null;
/**
* Retrieves detailed information about a specific candidate in a contest.
* @param {string} contest - The contest name.
* @param {string} candidateName - The candidate's name.
* @returns {CandidateData | null} The candidate's data or null if not found.
*/
getCandidateInfo(contest: string, candidateName: string): CandidateData | null;
/**
* Retrieves results for all precincts in a county for a given contest.
* @param {string} contest - The contest name.
* @param {string} county - The county name.
* @returns {CountyData | null} The county's election results or null if not found.
*/
getCountyResults(contest: string, county: string): CountyData | null;
/**
* Retrieves all election results for a specific candidate across all contests.
* @param {string} candidateName - The candidate's name.
* @returns {CandidateData[]} An array of the candidate's results in different contests.
*/
getAllCandidateResults(candidateName: string): CandidateData[];
/**
* Retrieves the total vote count for a specific candidate in a contest.
* @param {string} contest - The contest name.
* @param {string} candidateName - The candidate's name.
* @returns {number} The total vote count for the candidate.
*/
getCandidateVoteTotal(contest: string, candidateName: string): number;
/**
* Retrieves a dictionary mapping candidates to their total votes in a contest.
* @param {string} contest - The contest name.
* @returns {Record<string, number>} A record mapping candidate names to total vote counts.
*/
getContestVoteTotals(contest: string): Record<string, number>;
/**
* Retrieves the total number of votes for a given contest.
* @param {string} contest - The contest name.
* @returns {number} The total number of votes for a given contest.
*/
getTotalVotesForContest(contest: string): number;
/**
* Retrieve a candidate's percentage of total votes in a contest.
* @param {string} contest - The contest name
* @param {string} candidateName - The candidate's name
* @returns {number} a percentage (e.g. 25.4, 1.0, 90)
*/
getCandidateVotePercentage(contest: string, candidateName: string): number;
/**
* Retrieves the data of the candidate who currently has the
* most votes in a given contest. Does not handle the case of a tie.
* @param {string} contest - The name of the contest
* @returns {CandidateData | null} The name of the winning candidate
*/
getContestWinner(contest: string): CandidateData | null;
/**
* Finds the contest with the smallest margin between the top two candidates.
* @returns {ContestData | null} The closest race contest data, or null if no data is available.
*/
getClosestRace(): ContestData | null;
/**
* Retrieves all candidates in a given contest.
* @param {string} contest - The contest name.
* @returns {CandidateData[]} An array of candidate data objects.
*/
getCandidates(contest: string): CandidateData[];
/**
* Retrieves all counties in a given contest.
* @param {string} contest - The contest name.
* @returns {CountyData[]} An array of count data objects.
*/
getCounties(contest: string): CountyData[];
/**
* Retrieves all precincts in a given contest.
* @param {string} contest - The contest name.
* @returns {PrecinctData[]} An array of precinct data objects.
*/
getPrecincts(contest: string): PrecinctData[];
/**
* Retrieves all contests that a given candidate is a part of.
* @param {string} candidateName - The candidate's name
* @returns {ContestData[]} An array of contest data objects that a candidate is a part of
*/
getContestsByCandidate(candidateName: string): ContestData[];
/**
* Checks whether a given contest exists in the dataset.
* @param {string} contest - The contest's name.
* @returns {boolean} True if the contest exists, false otherwise.
*/
hasContest(contest: string): boolean;
/**
* Checks whether a given candidate exists in the dataset.
* @param {string} candidate - The candidate's name.
* @returns {boolean} True if the candidate exists, false otherwise.
*/
hasCandidate(candidate: string): boolean;
}
export { NCSBE };