clock.js

// Copyright Titanium I.T. LLC.
import FakeTimers from "@sinonjs/fake-timers";
import * as ensure from "util/ensure.js";

const NOT_A_NULLED_CLOCK_MESSAGE = "Can't advance the clock because it isn't a nulled clock";

/** System clock, including time zone and locale. */
export class Clock {

	/**
	 * Factory method. Wraps the system clock.
	 * @returns {Clock} the wrapped clock
	 */
	static create() {
		ensure.signature(arguments, []);

		return new Clock({
			Date,
			DateTimeFormat: Intl.DateTimeFormat,
			setTimeout,
			clearTimeout,
			advanceNulledClockAsync() { throw new Error(NOT_A_NULLED_CLOCK_MESSAGE); },
			advanceNulledClockUntilTimersExpireAsync() { throw new Error(NOT_A_NULLED_CLOCK_MESSAGE); }
		});
	}

	/**
	 * Factory method. Creates a simulated system clock.
	 * @param [options] overridable options for the simulated clock
	 * @param [options.now] simulated current time
	 * @param [options.locale] computer's default locale
	 * @param [options.timeZone] computer's default time zone
	 * @returns {Clock} the simulated clock
	 */
	static createNull(options) {
		return new Clock(stubbedGlobals(options));
	}

	/** Only for use by tests. (Use a factory method instead.) */
	constructor(globals) {
		ensure.signature(arguments, [ Object ]);

		this._globals = globals;
	}

	/**
	 * @returns {number} the current time in milliseconds (equivalent to Date.now())
	 */
	now() {
		ensure.signature(arguments, []);

		return this._globals.Date.now();
	}

	/**
	 * Render the current date and/or time as a string.
	 * @param intlDateTimeFormatOptions Formatting options (see Intl.DateTimeFormatOptions); timeZone
	 * must be specified (use 'local' for computer's time zone)
	 * @param locale Locale to use for localization (use 'local' for computer's default locale)
	 * @returns {string} the formatted date/time
	 */
	toFormattedString(intlDateTimeFormatOptions, locale) {
		if (intlDateTimeFormatOptions?.timeZone === undefined) {
			throw new Error("Must specify options.timeZone (use 'local' for computer's time zone)");
		}
		if (locale === undefined) {
			throw new Error("Must specify locale (use 'local' for computer's default locale)");
		}
		ensure.signature(arguments, [ Object, String ]);

		const options = { ...intlDateTimeFormatOptions };
		if (options.timeZone === "local") delete options.timeZone;
		if (locale === "local") locale = undefined;

		const now = new this._globals.Date();
		const formatter = this._globals.DateTimeFormat(locale, options);
		return formatter.format(now);
	}

	/**
	 * Advance a nulled clock forward in time. Throws an exception if the clock isn't nulled. (For
	 * non-nulled clocks, use waitAsync() instead.)
	 * @param milliseconds the number of milliseconds to advance the clock
	 */
	async advanceNulledClockAsync(milliseconds) {
		ensure.signature(arguments, [ Number ]);

		await this._globals.advanceNulledClockAsync(milliseconds);
	}

	/**
	 * Advance a nulled clock forward in time until all timers expire. Throws an exception if the
	 * clock isn't nulled.
	 * @returns {Promise<void>}
	 */
	async advanceNulledClockUntilTimersExpireAsync() {
		ensure.signature(arguments, []);

		await this._globals.advanceNulledClockUntilTimersExpireAsync();
	}

	/**
	 * Wait for a certain amount of time has passed. Equivalent to setTimeout(), which is not guaranteed
	 * to be exact. Special note for nulled clocks: time doesn't pass automatically for nulled clocks, so
	 * this method won't return unless one of the advanceNulledClock methods is called.
	 * @param milliseconds the approximate number of milliseconds to wait
	 */
	async waitAsync(milliseconds) {
		ensure.signature(arguments, [ Number ]);

		await new Promise((resolve) => {
			this._globals.setTimeout(resolve, milliseconds);
		});
	}

	/**
	 * Wait for a promise to resolve and return its value. If it hasn't completed in a certain amount
	 * of time, run a timeout function and return its value instead. Note that this DOES NOT CANCEL
	 * the original promise, which will still run to completion, although its return value will be
	 * discarded. (Promises cannot be cancelled.) Any cancellation mechanism you want to use must be
	 * programmed into the promise and timeout function.
	 * @param milliseconds the approximate number of milliseconds to wait
	 * @param promiseToWaitFor the promise to wait for
	 * @param timeoutFnAsync the function to run when the time is up
	 * @returns {Promise<unknown>} the promise's return value (if the promise resolves in time) or the
	 * timeout function's return value (if it doesn't)
	 */
	async timeoutAsync(milliseconds, promiseToWaitFor, timeoutFnAsync) {
		ensure.signature(arguments, [ Number, Promise, Function ]);

		return await new Promise(async (resolve, reject) => {
			const cancelToken = this._globals.setTimeout(async () => {
				try {
					const result = await timeoutFnAsync();
					resolve(result);
				}
				catch (err) {
					reject(err);
				}
			}, milliseconds);

			try {
				const result = await promiseToWaitFor;
				resolve(result);
			}
			catch (err) {
				reject(err);
			}
			finally {
				this._globals.clearTimeout(cancelToken);
			}
		});
	}

}


function stubbedGlobals({
	now = 0,
	locale = "gv-GB",
	timeZone = "Australia/Lord_Howe"
} = {}) {
	ensure.signature(arguments, [[ undefined, {
		now: [ undefined, Number ],
		locale: [ undefined, String ],
		timeZone: [ undefined, String ],
	}]]);

	const fake = FakeTimers.createClock(now);

	return {
		Date: fake.Date,

		DateTimeFormat(locales, options) {
			if (locales === undefined) locales = locale;
			options = { timeZone, ...options };
			return Intl.DateTimeFormat(locales, options);
		},

		async advanceNulledClockAsync(milliseconds) {
			await fake.tickAsync(milliseconds);
		},

		async advanceNulledClockUntilTimersExpireAsync() {
			await fake.runAllAsync();
		},

		setTimeout(fn, milliseconds) {
			return fake.setTimeout(fn, milliseconds);
		},

		clearTimeout(fn, milliseconds) {
			return fake.clearTimeout(fn, milliseconds);
		},
	};

}