index.ts

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

import { eq, sql } from 'drizzle-orm';

import { ConfigurationError } from '../exceptions/errors.js';
import type { DB } from 'db/index.js';
import type { Logger } from 'winston';
import { eventSchema } from 'constants/schema.js';
import { scaleLinear } from 'd3-scale';
import { testSchedule } from 'db/schema/testSchedule.js';

/**
 * Test schedule class and utilities for running a test in compressed time.
 */
export class TestSchedule {
  constructor(
    /** @hidden */
    private db: DB,
    private logger: Logger
  ) {}

  /** @private */
  async createTestSchedule(key: string) {
    const testScheduleInstance = (
      await this.db
        .insert(testSchedule)
        .values({ key, startTime: new Date() })
        .returning()
    )[0];
    return testScheduleInstance;
  }

  /**
   * A convenience method for reseting all event models except the test schedule.
   */
  async resetEventModels() {
    const tableSchema = this.db._.schema;

    const queries = Object.values(tableSchema)
      .filter(({ dbName }) => dbName !== 'TestSchedule')
      .map((table) => {
        return sql.raw(
          `TRUNCATE TABLE "${eventSchema}"."${table.dbName}" CASCADE;`
        );
      });

    await this.db.transaction(async (tx) => {
      await Promise.all(
        queries.map(async (query) => {
          if (query) await tx.execute(query);
        })
      );
    });
  }

  /**
   * Gets a point-in-time within a simulated test period as part of a repeating test.
   *
   * You can use it to help simulate election events by requesting results at [points in time](https://subscriberdocs.electiontonight.com/guides/overview.html#point-in-time-simulations) during the event.
   *
   * When you first request a test time, the client will save an initial datetime in the database and calculate consecutive test periods from that point in time compressed to the specified duration for the test.
   *
   * An example:
   *
   * Say you want to simulate a test period from noon to midnight on a particular day and compress that to run within an hour. When you first request a test time using a new test key, It then will return a test time representing noon. If you request a test time 15 minutes later, it will return a test time around 3 p.m., about a quarter through the test period. 15 minutes later again and It then will return a test time of 6 p.m., and so on. After the first hour, the test period will start again and return a test time of noon.
   *
   * @example
   * ```javascript
   * const key = 'my-test';
   * const testPeriodStart = new Date('2020-11-03T12:00-05:00');
   * const testPeriodEnd = new Date('2020-11-04T04:00-05:00');
   * const testDuration = 60; // 60 minutes
   *
   * const testTime = await client.test.getTestTime(key, testPeriodStart, testPeriodEnd, testDuration);
   * ```
   *
   * ---
   *
   * You can use the returned values to set the `maxDateTime` filter when updating election results.
   *
   * @example
   * ```javascript
   * await client.setupEvent();
   *
   * // A hypothetical infinite test loop...
   * while(true) {
   *   const testTime = await client.test.getTestTime(key, testPeriodStart, testPeriodEnd, testDuration);
   *
   *   client.filter({
   *     maxDateTime: testTime.maxDateTime,
   *   });
   *
   *   await client.getCountyVotes();
   *
   *   // A simple 5-minute delay between steps...
   *   await Promise((resolve) => setTimeout(resolve, 5 * 60 * 1000));
   * };
   * ```
   *
   * ---
   *
   * **Note:** When a simulated test rolls over to the beginning of the test period, this method will
   * clear all event models. You should use the returned `resetEvent` property to signal when you
   * should call {@link ElectionTonightClient.setupEvent} to re-initialise the event models before
   * calling other client methods or directly querying the database.
   *
   * @example
   * ```typescript
   * const { resetEvent } = await client.test.getTestTime(key, testPeriodStart, testPeriodEnd, testDuration);
   *
   * if (resetEvent) await client.setupEvent();
   *
   * // Now call other client methods...
   * ```
   *
   * @param key A key to identify the test schedule
   * @param testPeriodStart Start datetime of the test period
   * @param testPeriodEnd End datetime of the test period
   * @param testDuration Duration to compress the test period into in minutes
   */
  async getTestTime(
    key: string,
    testPeriodStart: Date,
    testPeriodEnd: Date,
    testDuration: number = 60
  ): Promise<{
    /** Simulated test point-in-time date */
    date: Date;
    /**
     * Simulated test point-in-time date in ISO format, which can be passed to directly to
     * the client filter.
     *
     * @example
     * ```typescript
     * const { maxDateTime } = await client.test.getTestTime(key, testPeriodStart, testPeriodEnd, testDuration);
     *
     * client.filter({ maxDateTime });
     * ```
     */
    maxDateTime: string;
    /**
     * When `true`, the test period has rolled over to the beginning of the test,
     * which resets all event models and prevents client API methods from being called
     * until the event is re-setup.
     *
     * Use this property to reset the database to the beginning of the test period during
     * test loops.
     *
     * @example
     * ```typescript
     * const { resetEvent } = await client.test.getTestTime(key, testPeriodStart, testPeriodEnd, testDuration);
     *
     * if (resetEvent) client.setupEvent();
     * ```
     */
    resetEvent: boolean;
  }> {
    const testDurtionInMs = testDuration * 60 * 1000;

    // If test start and end are the same, just return that time immediately.
    // Can be used to help generate specific datetime data examples.
    if (testPeriodStart.getTime() === testPeriodEnd.getTime()) {
      return {
        date: testPeriodStart,
        maxDateTime: testPeriodStart.toISOString(),
        resetEvent: false,
      };
    }

    if (testPeriodStart >= testPeriodEnd) {
      throw new ConfigurationError(
        'getTestTime test period start must be before test period end'
      );
    }

    if (testDurtionInMs > testPeriodEnd.getTime() - testPeriodStart.getTime()) {
      throw new ConfigurationError(
        'getTestTime test duration should be shorter than the test period'
      );
    }

    let currentTestSchedule = (
      await this.db.select().from(testSchedule).where(eq(testSchedule.key, key))
    )[0];

    if (!currentTestSchedule)
      currentTestSchedule = await this.createTestSchedule(key);

    const currentTick =
      (Date.now() - currentTestSchedule.startTime.getTime()) % testDurtionInMs;

    const msScale = scaleLinear()
      .domain([0, testDurtionInMs])
      .range([testPeriodStart.getTime(), testPeriodEnd.getTime()]);

    const currentMS = msScale(currentTick);

    const currentTestTime = new Date(currentMS);
    const { lastTestTime } = currentTestSchedule;

    let resetEvent = false;

    /**
     * If the last test time is later than the current one, we've rolled
     * back to the beginning of the test period. We'll reset the event models
     * at this point. Now all client API models will fail `client.checkEventSetup`
     * and return immediately until `client.setupEvent` is called again.
     *
     * Note: This doesn't stop any direct DB queries users may call, so they should
     * check `client.checkEventSetup` before assuming the database is up-to-date.
     */
    if (lastTestTime && lastTestTime > currentTestTime) {
      await this.resetEventModels();
      resetEvent = true;
    }

    await this.db
      .update(testSchedule)
      .set({ lastTestTime: new Date(currentMS) })
      .where(eq(testSchedule.key, key));

    return {
      date: currentTestTime,
      maxDateTime: currentTestTime.toISOString(),
      resetEvent,
    };
  }
}

[]

TypeScript coverage report