index.ts

Filename	Percent	Threshold	Total	Covered	Uncovered
src/index.ts	100.00%	80%	245	245	0

import { Events } from './events/index.js';
import { InitError } from './exceptions/errors.js';
import type { Logger } from 'winston';
import { Postgres } from 'db/postgres.js';
import type { QueryFilter } from 'types.js';
import { Results } from './results/index.js';
import { TestSchedule } from './testSchedule/index.js';
import { defaultLogger } from 'utils/logger.js';

/**
 * The ElectionTonight client
 *
 * @example
 * ```javascript
 * import { ElectionTonightClient } from 'election-tonight-client';`
 * ```
 * @module
 */
export class ElectionTonightClient {
  /** @hidden */
  private postgres: Postgres;
  /** @hidden */
  private events: Events;
  /** @hidden */
  private results: Results;
  /** @hidden */
  db: ReturnType<Postgres['connect']>;
  test: TestSchedule;

  /**
   * Creates an instance of ElectionTonightClient class.
   *
   * @example
   * ```javascript
   * import { ElectionTonightClient } from 'election-tonight-client';
   *
   * const client = new ElectionTonightClient('APIKEY', 'EVENTID');
   * ```
   *
   * #### Backup API
   *
   * You can use environment variables to change the API root the client uses
   * for requests.
   * - `ELECTION_TONIGHT_CLIENT_BACKUP_API=True` Use Edison's backup API
   * - `ELECTION_TONIGHT_CLIENT_API_ROOT=https://...` Set a custom API root
   *
   * @param apiKey ElectionTonight API key
   * @param eventId ElectionTonight election event ID
   * @param logger Winston Logger instance
   */
  constructor(
    private apiKey: string,
    private eventId: string,
    private logger: Logger = defaultLogger
  ) {}

  connect(pgUri: string, pgOptions = {}) {
    this.postgres = new Postgres(pgUri, pgOptions);
    this.db = this.postgres.connect();

    const { apiKey, eventId, logger, db } = this;

    this.events = new Events({ apiKey, eventId, logger, db });
    this.results = new Results({ apiKey, eventId, logger, db });
    /** @interface */
    this.test = new TestSchedule(db, logger);
  }

  async disconnect() {
    if (!this.db) return;
    await this.postgres.disconnect();
    this.db = undefined;
  }

  async dropTables() {
    await this.postgres.dropTables();
  }

  /**
   * Checks if the clent has been connected.
   */
  private checkClientConnected() {
    if (!this.db) {
      throw new InitError(
        'Must connect the client before calling this method.'
      );
    }
  }

  /**
   * Checks if the election event has been setup, which can be used to verify if results methods can be called.
   *
   * This is likely necessary to call before running any direct database queries during a simulated test
   * with {@link TestSchedule.getTestTime}.
   *
   * @example
   * ```typescript
   * const eventIsSetup = await client.checkEventSetup();
   *
   * if (!eventIsSetup) return;
   *
   * client.db // Query models only if the event is setup...
   * ```
   *
   * @param warnWhenNotSetup Log a warning when event is not setup
   */
  async checkEventSetup(warnWhenNotSetup = true) {
    const eventInstance = await this.db.query.event.findFirst({
      where: (event, { eq }) => eq(event.id, this.eventId),
    });
    if (!eventInstance && warnWhenNotSetup)
      this.logger.warning('Election event has not been setup yet.');
    return !!eventInstance;
  }

  /**
   * Filters events and results.
   *
   * @example
   * ```javascript
   * client.filter({ states: ['TX'] });
   * ```
   *
   * @param filter Filter options
   */
  filter(filter: Partial<QueryFilter>) {
    this.events.filter(filter);
    this.results.filter(filter);
    return this;
  }

  /**
   *
   * Resets filters passed to events and results.
   *
   * @example
   * ```javascript
   * client.resetFilter();
   * ```
   */
  resetFilter() {
    this.events.resetFilter();
    this.results.resetFilter();
    return this;
  }

  /**
   * Fetches metadata for an election event such as race and candidate definitions and sets up the database.
   *
   * You should run it then whenever you're setting up a fresh database **before** you start getting results. You can then continue running it periodically to make sure metadata is up-to-date.
   *
   * @example
   * ```javascript
   * await client.setupEvent();
   * ```
   */
  async setupEvent() {
    this.checkClientConnected();
    await this.events.setupEvent();
  }

  /**
   * Gets the latest county vote documents from the results endpoint (`results/county-vote`).
   *
   * A vote document sends vote results for a single, unique contest.
   *
   * Calling it will also update the streams position for the county votes doc type, so you can use it concurrently with the streams county vote endpoint.
   *
   * @example
   * ```javascript
   * await client.getCountyVotes();
   * ```
   */
  async getCountyVotes() {
    this.checkClientConnected();
    if (!(await this.checkEventSetup())) return;

    await this.results.updateCountyVotes();
  }

  /**
   * Gets county vote documents from the streams endpoint (`streams/county-vote`), which is the fastest way to get just the latest updated vote documents.
   *
   * Updates the stream position for the county vote doc type if all votes are successfully commited to the database.
   *
   * @example
   * ```javascript
   * const updated = await client.getStreamedCountyVotes();
   *
   * // Pass a maximum number of requests to make to the API.
   * const updated = await client.getStreamedCountyVotes(10);
   * ```
   *
   * @param maxRequests Maximum number of requests to make for documents.
   */
  async getStreamedCountyVotes(maxRequests: number = Infinity) {
    this.checkClientConnected();
    if (!(await this.checkEventSetup())) return;

    return this.results.updateStreamedCountyVotes(maxRequests);
  }

  /**
   * Gets the latest electoral vote documents from the results endpoint (`results/electoral-vote`).
   *
   * A vote document sends vote results for a single, unique contest.
   *
   * Calling it will also update the streams position for the electoral votes doc type, so you can use it concurrently with the streams electoral vote endpoint.
   *
   * @example
   * ```javascript
   * await client.getElectoralVotes();
   * ```
   */
  async getElectoralVotes() {
    this.checkClientConnected();
    if (!(await this.checkEventSetup())) return;

    await this.results.updateElectoralVotes();
  }

  /**
   * Gets electoral vote documents from the streams endpoint (`streams/electoral-vote`), which is the fastest way to get just the latest updated vote documents.
   *
   * Updates the stream position for the electoral vote doc type if all votes are successfully commited to the database.
   *
   * @example
   * ```javascript
   * const updated = await client.getStreamedElectoralVotes();
   *
   * // Pass a maximum number of requests to make to the API.
   * const updated = await client.getStreamedElectoralVotes(10);
   * ```
   *
   * @param maxRequests Maximum number of requests to make for documents.
   */
  async getStreamedElectoralVotes(maxRequests = Infinity) {
    this.checkClientConnected();
    if (!(await this.checkEventSetup())) return;

    return this.results.updateStreamedElectoralVotes(maxRequests);
  }

  /**
   * Gets the latest estimate documents from the results endpoint (`results/est`).
   *
   * An estimate document contains ENS race calls for a single, unique contest.
   *
   * Calling it will also update the streams position for the estimate doc type, so you can use it concurrently with the streams estimate endpoint.
   *
   * @example
   * ```javascript
   * await client.getCalls();
   * ```
   */
  async getCalls() {
    this.checkClientConnected();
    if (!(await this.checkEventSetup())) return;

    await this.results.updateCalls();
  }

  /**
   * Gets estimate documents from the streams endpoint (`streams/est`), which is the fastest way to get just the latest updated estimate documents.
   *
   * Updates the stream position for the estimate doc type if all calls are successfully commited to the database.
   *
   * @example
   * ```javascript
   * const updated = await client.getStreamedCalls();
   *
   * // Pass a maximum number of requests to make to the API.
   * const updated = await client.getStreamedCalls(10);
   * ```
   *
   * @param maxRequests Maximum number of requests to make for documents.
   */
  async getStreamedCalls(maxRequests = Infinity) {
    this.checkClientConnected();
    if (!(await this.checkEventSetup())) return;

    return this.results.updateStreamedCalls(maxRequests);
  }

  /**
   * Gets the latest message documents from the results endpoint (`results/msg`).
   *
   * A message document contains an election message from the EAS. It is used to commumicate important information such as an increase in total expected vote or a weather problem that is delaying vote count collection.
   *
   * Calling it will also update the streams position for the message doc type, so you can use it concurrently with the streams message endpoint.
   *
   * @example
   * ```javascript
   * await client.getMessages();
   * ```
   */
  async getMessages() {
    this.checkClientConnected();
    if (!(await this.checkEventSetup())) return;

    await this.results.updateMessages();
  }

  /**
   * Ges  message documents from the streams endpoint (`streams/msg`), which is the fastest way to get just the latest updated message documents.
   *
   * Updates the stream position for the message doc type if all calls are successfully commited to the database.
   *
   * @example
   * ```javascript
   * const updated = await client.getStreamedMessages();
   *
   * // Pass a maximum number of requests to make to the API.
   * const updated = await client.getStreamedMessages(10);
   * ```
   *
   * @param maxRequests Maximum number of requests to make for documents.
   */
  async getStreamedMessages(maxRequests = Infinity) {
    this.checkClientConnected();
    if (!(await this.checkEventSetup())) return;

    return this.results.updateStreamedMessages(maxRequests);
  }

  /**
   * Gets the latest editorial turnout documents from the results endpoint (`results/editorial-turnout`).
   *
   * A editorial turnout document contains the voting eligible population and optionally turnout as a percentage of the voting age population.
   *
   * Calling it will also update the streams position for the editorial turnout doc type, so you can use it concurrently with the streams editorial turnout endpoint.
   *
   * @example
   * ```javascript
   * await client.updateEditorialTurnouts();
   * ```
   */
  async getEditorialTurnout() {
    this.checkClientConnected();
    if (!(await this.checkEventSetup())) return;

    await this.results.updateEditorialTurnouts();
  }

  /**
   * Gets editorial turnout documents from the streams endpoint (`streams/editorial-turnout`), which is the fastest way to get just the latest updated editorial turnout documents.
   *
   * Updates the stream position for the editorial turnout doc type if all calls are successfully commited to the database.
   *
   * @example
   * ```javascript
   * const updated = await client.getStreamedEditorialTurnout();
   *
   * // Pass a maximum number of requests to make to the API.
   * const updated = await client.getStreamedEditorialTurnout(10);
   * ```
   *
   * @param maxRequests Maximum number of requests to make for documents.
   */
  async getStreamedEditorialTurnout(maxRequests = Infinity) {
    this.checkClientConnected();
    if (!(await this.checkEventSetup())) return;

    return this.results.updateStreamedEditorialTurnouts(maxRequests);
  }

  /**
   * Gets the latest total expected vote documents from the results endpoint (`results/total-expected-vote`).
   *
   * A total expected vote document contains total expected vote estimate for a county and election. Also contains other information regarding the status of that counties total vote count.
   *
   * Calling it will also update the streams position for the total expected vote doc type, so you can use it concurrently with the streams total expected vote endpoint.
   *
   * @example
   * ```javascript
   * await client.getTotalExpectedVote();
   * ```
   */
  async getTotalExpectedVote() {
    this.checkClientConnected();
    if (!(await this.checkEventSetup())) return;

    await this.results.updateTotalExpectedVotes();
  }

  /**
   * Gets total expected vote documents from the streams endpoint (`streams/total-expected-vote`), which is the fastest way to get just the latest update total expected vote documents.
   *
   * Updates the stream position for the total expected vote doc type if all calls are successfully commited to the database.
   *
   * @example
   * ```javascript
   * const updated = await client.getStreamedTotalExpectedVote();
   *
   * // Pass a maximum number of requests to make to the API.
   * const updated = await client.getStreamedTotalExpectedVote(10);
   * ```
   *
   * @param maxRequests Maximum number of requests to make for documents.
   */
  async getStreamedTotalExpectedVote(maxRequests = Infinity) {
    this.checkClientConnected();
    if (!(await this.checkEventSetup())) return;

    return this.results.updateStreamedTotalExpectedVotes(maxRequests);
  }
}

export { TestSchedule, type QueryFilter };
export type * as models from './models.js';

[]

TypeScript coverage report