ncsbe-lib/dist/lib/collector.d.ts

JavaScript library for working with North Carolina State Board of Elections (NCSBE) historical election data

import { ContestData } from './types';
/**
 * The `Collector` class is responsible for fetching, parsing, and formatting election data
 * from the North Carolina State Board of Elections (NCSBE).
 *
 * This class:
 * - Downloads election data from a provided URL (ZIP file).
 * - Extracts the TSV (tab-separated values) file inside the ZIP.
 * - Parses the TSV file into structured election data.
 * - Formats the parsed data into a hierarchical structure for easy analysis.
 *
 * Example usage:
 * ```ts
 * const collector = new Collector("https://s3.amazonaws.com/dl.ncsbe.gov/ENRS/2024_11_05/results_pct_20241105.zip"); // 2024 election
 * const results = await collector.collect();
 * console.log(results);
 * ```
 */
declare class Collector {
    private url;
    /**
     * Creates a new Collector instance.
     * @param {string} url - The URL of the ZIP file containing election data.
     */
    constructor(url: string);
    private normalizeContestName;
    /**
     * Collects and processes election data from the provided ZIP file URL.
     * @returns {Promise<ContestDatap[]>} A structured representation of the election results.
     * @throws Will throw an error if fetching, extraction, or parsing fails.
     */
    collect(): Promise<ContestData[]>;
    /**
     * Fetches a ZIP file from the provided URL, returning its raw binary data as a Buffer.
     * @param {string} url - The URL to fetch the ZIP file from.
     * @returns {Promise<Buffer>} The raw binary data of the ZIP file.
     * @throws Will throw an error if the request fails.
     */
    private fetchData;
    /**
     * Extracts TSV files from the provided ZIP data.
     * @param {Buffer} zipData - The binary ZIP file data.
     * @returns {string} The extracted TSV content as a string.
     */
    private extractTSVFiles;
    /**
     * Transforms a row of the TSV file into a structured `ParsedRow` object.
     * @param {Record<string, string>} row - A raw TSV row with string values.
     * @returns {ParsedRow} An structured `ParsedRow` object.
     */
    private transformRow;
    /**
     * Parses TSV data into an array of structured election result objects.
     * @param {string} tsvData - The TSV file content as a string.
     * @returns {Promise<ParsedRow[]>} An array of structured election result objects.
     */
    private parseTSVData;
    /**
     * Formats parsed election data into a structured hierarchy.
     *
     * **Expected Output (ContestData[]):**
     * ```json
     * [
     *   {
     *     "contestName": "US_Senate",
     *     "counties": [
     *       {
     *         "county": "Orange",
     *         "precincts": [
     *           {
     *             "precinct": "01-01",
     *             "candidates": [
     *               {
     *                 "candidate": "John Doe",
     *                 "party": "DEM",
     *                 "votes": 1710
     *               },
     *               {
     *                 "candidate": "Jane Smith",
     *                 "party": "REP",
     *                 "votes": 1585
     *               }
     *             ]
     *           }
     *         ]
     *       }
     *     ]
     *   }
     * ]
     * ```
     *
     * @param {ParsedRow[]} parsedData - The parsed election results.
     * @returns {ContestData[]} - The formatted election data structured by contest, county, and precinct.
     */
    private format;
}
export { Collector };