index.ts

Filename	Percent	Threshold	Total	Covered	Uncovered
src/results/parsers/est/index.ts	100.00%	80%	248	248	0

import {
  prettifyCallStatusCodes,
  prettifyTransmissionSourceTypeCodes,
} from 'utils/prettifyCodes.js';

import type { Document } from './types.js';
import { EST } from 'constants/docTypes.js';
import type { NewCall } from 'db/schema/call.js';
import type { NewCandidateRace } from 'db/schema/candidateRace.js';
import type { NewDocumentSequence } from 'db/schema/documentSequence.js';
import { getOfficeBodyUid } from 'utils/officeBodyUid.js';
import { parseKey } from 'utils/documentKey.js';
import { validateTimestamp } from 'utils/validateTimestamp.js';
import { isSpecialElection } from 'utils/specialElection.js';

/**
 * Determines if a winner has been called in a race, which includes calls made before polls are closed. Such calls may need to be embargoed until after polls close.
 *
 * @param status Edison call status
 * @returns True if a winner has been called, false otherwise.
 */
const isWinnerCalled = (status: string) => ['W', 'B'].includes(status);

/**
 * Gets the latest timestamp in the document set.
 *
 * @param documents An array of documents returned from querying the ElectionTonight API endpoint.
 * @returns The latest timestamp in the document set, or null if the document set is empty.
 */
const getLatestDocTimestamp = (documents: Document[]) => {
  if (documents.length === 0) return null;
  const timeStamps = documents.map((doc) => new Date(doc.ts).getTime());
  return Math.max(...timeStamps);
};

/**
 * Checks if a call should be embargoed by comparing the latest timestamp in the EST documents against the jurisdiction's poll closing time.
 *
 * This allows us to publish 'B' status calls -- winner before poll closing -- ONLY IF we are sure that the current time (which is simulated in tests) is after the jurisdiction's poll closing time.
 *
 * @param jurisdictionPollCloseTime The poll close time for the race's jurisdiction
 * @param callStatus Edison call status
 * @param latestDocumentTime The latest EST document timestamp
 * @returns True if the call should be embargoed, false otherwise.
 */
const isCallEmbargoed = (
  jurisdictionPollCloseTime: Date,
  callStatus: string,
  latestDocumentTime: number
) => {
  const winnerIsCalled = isWinnerCalled(callStatus);

  if (!winnerIsCalled) return null;

  // If call status is 'W', winner after poll closing, so it is not embargoed and we can publish this result
  if (callStatus === 'W') return false;

  // ... Otherwise call status is 'B', winner before poll closing.

  // If there is no pollCloseTime, embargo the call. This should never happen
  // -- except for national jurisdiction for president -- because a jurisdiction
  // should always have a poll close time.
  /**
   * @TODO Review if this should return false. I.e., if president is called before
   * poll closing and there is no jurisdiction poll close time, do we want to embargo
   * that call?? Or will this not generally happen b/c Edison won't ship that call
   * with a "B" code?
   */
  if (!jurisdictionPollCloseTime) return true;

  // If the latest document timestamp is after poll close time,
  // the call is no longer embargoed and we CAN publish it.
  if (
    latestDocumentTime &&
    latestDocumentTime > jurisdictionPollCloseTime.getTime()
  )
    return false;

  // Otherwise, call status is 'B' and we don't know if it's after poll close
  // time, so call should be embargoed.
  return true;
};

interface JurisdictionRacePollCloseTime {
  /** Jurisdiction code */
  jurisdiction: string;
  /** Election type code */
  electionType: string;
  /** Major poll close time */
  majorPollCloseTime: Date;
}

/**
 * Parses EST calls.
 *
 * @param documents EST documents
 * @param pollCloseTimes Poll close times for all jurisdiction races
 */
const parseCalls = (
  documents: Document[],
  pollCloseTimes: JurisdictionRacePollCloseTime[]
) => {
  const instances: NewCall[] = [];

  const latestDocTimestamp = getLatestDocTimestamp(documents);

  for (const doc of documents) {
    const {
      cStat: status,
      leadCId: leadingCandidate,
      pStat: percentStatus,
      transSrc,
      ts,
    } = doc;
    const { officeRace, office, electionType, state, jurisdiction } = parseKey(
      doc.key
    );
    const { ofc } = doc.key;

    // Check if it's a special election
    const specialElection = isSpecialElection(electionType, ofc);

    const pollCloseTime = pollCloseTimes.find(
      (j) => j.jurisdiction === jurisdiction && j.electionType === electionType
    )?.majorPollCloseTime;

    const instance: NewCall = {
      uid: officeRace,
      officeBody: getOfficeBodyUid(ofc),
      office,
      officeRace,
      electionType,
      state,
      jurisdiction,
      specialElection,
      /**
       * Call reversals come in with a "0" for leadingCandidate,
       * which we set to null b/c 0 is an invalid candidate ID.
       */
      leadingCandidate: leadingCandidate === 0 ? null : leadingCandidate,
      status,
      description: prettifyCallStatusCodes(status),

      // Includes embargoed calls...
      winnerIsCalled: isWinnerCalled(status),
      isEmbargoed: isCallEmbargoed(pollCloseTime, status, latestDocTimestamp),
      percentStatus,
      transmissionSource: prettifyTransmissionSourceTypeCodes(transSrc),
      timestamp: validateTimestamp(ts),
    };
    instances.push(instance);
  }

  return instances;
};

/**
 * Parses EST calls for candidates.
 *
 * @param documents EST documents
 * @param pollCloseTimes Poll close times for all jurisdiction races
 */
const parseCandidateCalls = (
  documents: Document[],
  pollCloseTimes: JurisdictionRacePollCloseTime[]
) => {
  const instances: Partial<NewCandidateRace>[] = [];

  const latestDocTimestamp = getLatestDocTimestamp(documents);

  for (const doc of documents) {
    const { candidates, cStat: callStatus, leadCId: leadingCandidate } = doc;
    const { officeRace, electionType, jurisdiction } = parseKey(doc.key);

    const pollCloseTime = pollCloseTimes.find(
      (j) => j.jurisdiction === jurisdiction && j.electionType === electionType
    )?.majorPollCloseTime;

    const isEmbargoed = isCallEmbargoed(
      pollCloseTime,
      callStatus,
      latestDocTimestamp
    );

    for (const candidate of candidates) {
      const {
        cId,
        cPct: candidatePercentage,
        orderOfFinish,
        runoffCandidate,
      } = candidate;

      // Filter out call reversals (R), calls with no status yet (N) and embargoed calls
      if (callStatus !== 'R' && callStatus !== 'N' && !isEmbargoed) {
        const instance: Partial<NewCandidateRace> = {
          uid: `${officeRace}_${cId}`, // matches CandidateRace uid
          candidatePercentage,
          winner: cId === leadingCandidate,

          /**
           * @TODO CHECK if it is ok that orderOfFinish = 0 when the order hasn't been called
           */
          finishingOrder: orderOfFinish,
          advancesToRunoff:
            runoffCandidate === 'Y' ? true : callStatus === 'V' ? false : null,
          tiedForFirstPlace: callStatus === 'C',
          callStatus,
          callDescription: prettifyCallStatusCodes(callStatus),
        };
        instances.push(instance);
      }
    }
  }
  return instances;
};

const parseSequenceId = (doc: Document) => {
  const { officeRace } = parseKey(doc.key);
  return officeRace;
};

const parseDocumentSequences = (documents: Document[]) => {
  const sequences: NewDocumentSequence[] = [];
  for (const call of documents) {
    const { seq: sequence } = call;
    const uid = parseSequenceId(call);

    const documentSequence = {
      uid,
      docType: EST,
      sequence,
    };

    sequences.push(documentSequence);
  }
  return sequences;
};

export default {
  parseCalls,
  parseCandidateCalls,
  parseSequenceId,
  parseDocumentSequences,
};

[]

TypeScript coverage report