@oscarpalmer/timer 0.20.0 → 0.21.0

package/src/index.ts

@@ -1,229 +1,37 @@
-export type AfterCallback = (finished: boolean) => void;
+import {noop} from '@oscarpalmer/atoms/function';
+import {activeTimers, hiddenTimers} from './constants';
+import './global';
+import {wait} from './timer';
 
-type Callbacks = {
-	after: AfterCallback | undefined;
-	default: IndexedCallback;
-};
-
-type Configuration = {
-	callbacks: Callbacks;
-	count: number;
-	time: number;
-};
-
-type IndexedCallback = (index: number) => void;
-
-type State = {
-	active: boolean;
-	finished: boolean;
-	frame?: number;
-};
-
-const milliseconds = Math.round(1000 / 60);
-
-function run(timer: Timer): void {
-	// @ts-expect-error Keep private status, but allow access
-	const {_configuration, _state} = timer;
-
-	_state.active = true;
-	_state.finished = false;
-
-	const isRepeated = _configuration.count > 1;
-
-	let index = 0;
-
-	let start;
-
-	function step(timestamp: DOMHighResTimeStamp): void {
-		if (!_state.active) {
-			return;
-		}
-
-		start ??= timestamp;
-
-		const elapsed = timestamp - start;
-
-		const elapsedMinimum = elapsed - milliseconds;
-		const elapsedMaximum = elapsed + milliseconds;
-
-		if (
-			elapsedMinimum < _configuration.time &&
-			_configuration.time < elapsedMaximum
-		) {
-			if (_state.active) {
-				_configuration.callbacks.default(index);
-			}
-
-			index += 1;
-
-			if (isRepeated && index < _configuration.count) {
-				start = undefined;
-			} else {
-				_state.finished = true;
-
-				timer.stop();
-
-				return;
-			}
-		}
-
-		_state.frame = requestAnimationFrame(step);
-	}
-
-	_state.frame = requestAnimationFrame(step);
-}
-
-export class Timer {
-	private declare readonly _configuration: Configuration;
-	private declare readonly _state: State;
-
-	get active(): boolean {
-		return this._state.active;
-	}
-
-	get finished(): boolean {
-		return this._state.finished;
-	}
-
-	/**
-	 * @param {Callback} callback
-	 * @param {number} time
-	 * @param {number} count
-	 * @param {AfterCallback=} afterCallback
-	 */
-	constructor(
-		callback: IndexedCallback,
-		time?: number,
-		count?: number,
-		afterCallback?: AfterCallback,
-	) {
-		if (typeof callback !== 'function') {
-			throw new TypeError('A timer must have a callback function');
-		}
-
-		const actualTime = typeof time === 'number' ? time : 0;
-
-		if (actualTime < 0) {
-			throw new TypeError(
-				'A timer must have a non-negative number as its time',
-			);
-		}
-
-		const actualCount = typeof count === 'number' ? count : 1;
-
-		if (actualCount < 1) {
-			throw new TypeError(
-				'A timer must have a number greater than or equal to 1 as its run count',
-			);
-		}
-
-		if (
-			actualCount > 1 &&
-			afterCallback !== undefined &&
-			typeof afterCallback !== 'function'
-		) {
-			throw new TypeError(
-				"A repeated timer's after-callback must be a function",
-			);
-		}
-
-		Object.defineProperty(this, '_configuration', {
-			value: {
-				callbacks: {
-					after: afterCallback,
-					default: callback,
-				},
-				count: actualCount,
-				time: actualTime,
-			},
-		});
-
-		Object.defineProperty(this, '_state', {
-			value: {
-				active: false,
-				finished: false,
-			},
+/**
+ * Creates a delayed promise that resolves after a certain amount of time _(or rejects when timed out)_
+ */
+export function delay(time: number, timeout?: number): Promise<void> {
+	return new Promise((resolve, reject) => {
+		wait(resolve ?? noop, {
+			timeout,
+			errorCallback: reject ?? noop,
+			interval: time,
 		});
-	}
-
-	restart(): Timer {
-		this.stop();
-
-		run(this);
-
-		return this;
-	}
+	});
+}
 
-	start(): Timer {
-		if (!this._state.active) {
-			run(this);
+document.addEventListener('visibilitychange', () => {
+	if (document.hidden) {
+		for (const timer of activeTimers) {
+			hiddenTimers.add(timer);
+			timer.pause();
 		}
-
-		return this;
-	}
-
-	stop(): Timer {
-		this._state.active = false;
-
-		if (this._state.frame === undefined) {
-			return this;
+	} else {
+		for (const timer of hiddenTimers) {
+			timer.continue();
 		}
 
-		cancelAnimationFrame(this._state.frame);
-
-		this._configuration.callbacks.after?.(this._state.finished);
-
-		this._state.frame = undefined;
-
-		return this;
-	}
-}
-
-/**
- * Creates and starts a new repeated timer
- */
-export function repeat(callback: IndexedCallback, count: number): Timer;
-export function repeat(
-	callback: IndexedCallback,
-	count: number,
-	afterCallback: AfterCallback,
-): Timer;
-export function repeat(
-	callback: IndexedCallback,
-	count: number,
-	time: number,
-): Timer;
-export function repeat(
-	callback: IndexedCallback,
-	count: number,
-	time: number,
-	afterCallback: AfterCallback,
-): Timer;
-export function repeat(
-	callback: IndexedCallback,
-	count: number,
-	afterOrTime?: number | AfterCallback,
-	after?: AfterCallback,
-): Timer {
-	if (typeof count !== 'number' || count < 2) {
-		throw new TypeError(
-			'A repeated timer must have a number greater than or equal to 2 as its run count',
-		);
+		hiddenTimers.clear();
 	}
+});
 
-	const afterOrTimeIsFunction = typeof afterOrTime === 'function';
-
-	return new Timer(
-		callback,
-		afterOrTimeIsFunction ? 0 : afterOrTime,
-		count,
-		afterOrTimeIsFunction ? afterOrTime : after,
-	).start();
-}
+export {isRepeated, isTimer, isWaited, isWhen} from './is';
+export {repeat, wait, type Timer} from './timer';
+export {when, type When} from './when';
 
-/**
- * Creates and starts a new waited timer
- */
-export function wait(callback: IndexedCallback, time?: number): Timer {
-	return new Timer(callback, time).start();
-}

package/src/is.ts

@@ -0,0 +1,35 @@
+import type {PlainObject} from '@oscarpalmer/atoms/models';
+import type {Timer} from './timer';
+import type {When} from './when';
+
+function is(pattern: RegExp, value: unknown) {
+	return pattern.test((value as PlainObject)?.$timer as string);
+}
+
+/**
+ * Is the value a repeating timer?
+ */
+export function isRepeated(value: unknown): value is Timer {
+	return is(/^repeat$/, value);
+}
+
+/**
+ * Is the value a timer?
+ */
+export function isTimer(value: unknown): value is Timer {
+	return is(/^repeat|wait$/, value);
+}
+
+/**
+ * Is the value a waiting timer?
+ */
+export function isWaited(value: unknown): value is Timer {
+	return is(/^wait$/, value);
+}
+
+/**
+ * Is the value a conditional timer?
+ */
+export function isWhen(value: unknown): value is When {
+	return is(/^when$/, value) && typeof (value as When).then === 'function';
+}

package/src/models.ts

@@ -0,0 +1,76 @@
+import type {Timer} from './timer';
+
+/**
+ * Callback that runs after the timer has finished (or is stopped)
+ * - `finished` is `true` if the timer was allowed to finish, and `false` if it was stopped
+ */
+export type AfterCallback = (finished: boolean) => void;
+
+export type AnyCallback = (() => void) | IndexedCallback;
+
+/**
+ * Callback that runs for each iteration of the timer
+ */
+export type IndexedCallback = (index: number) => void;
+
+export type BaseOptions = {
+	/**
+	 * Interval between each callback
+	 */
+	interval: number;
+	/**
+	 * Maximum amount of time the timer may run for
+	 */
+	timeout: number;
+};
+
+export type OptionsWithCount = {
+	/**
+	 * How many times the timer should repeat
+	 */
+	count: number;
+} & BaseOptions;
+
+export type OptionsWithError = {
+	/**
+	 * Callback to run when an error occurs _(usually a timeout)_
+	 */
+	errorCallback?: () => void;
+};
+
+export type RepeatOptions = {
+	/**
+	 * Callback to run after the timer has finished (or is stopped)
+	 * - `finished` is `true` if the timer was allowed to finish, and `false` if it was stopped
+	 */
+	afterCallback?: AfterCallback;
+} & OptionsWithCount &
+	OptionsWithError;
+
+export type TimerOptions = {} & RepeatOptions;
+
+export type TimerState = {
+	active: boolean;
+	callback: AnyCallback;
+	count?: number;
+	elapsed?: number;
+	frame?: number;
+	index?: number;
+	isRepeated: boolean;
+	minimum: number;
+	paused: boolean;
+	trace: unknown;
+};
+
+export type WaitOptions = {} & BaseOptions & OptionsWithError;
+
+export type WhenOptions = {} & OptionsWithCount;
+
+export type WhenState = {
+	promise: Promise<void>;
+	rejecter?: () => void;
+	resolver?: () => void;
+	timer: Timer;
+};
+
+export type WorkType = 'continue' | 'pause' | 'restart' | 'start' | 'stop';

package/src/timer.ts

@@ -0,0 +1,186 @@
+import {milliseconds} from './constants';
+import {getOptions, work} from './functions';
+import type {
+	AnyCallback,
+	IndexedCallback,
+	RepeatOptions,
+	TimerOptions,
+	TimerState,
+	WaitOptions,
+} from './models';
+
+export abstract class BasicTimer<State> {
+	protected declare readonly $timer: string;
+	protected declare readonly state: State;
+
+	constructor(type: 'repeat' | 'wait' | 'when', state: State) {
+		this.$timer = type;
+		this.state = state;
+	}
+
+	/**
+	 * Is the timer running?
+	 */
+	abstract readonly active: boolean;
+
+	/**
+	 * Is the timer paused?
+	 */
+	abstract readonly paused: boolean;
+}
+
+/**
+ * A timer that can be started, stopped, and restarted as neeeded
+ */
+export class Timer extends BasicTimer<TimerState> {
+	private declare readonly options: TimerOptions;
+
+	get active() {
+		return this.state.active;
+	}
+
+	get paused() {
+		return this.state.paused;
+	}
+
+	/**
+	 * Gets the traced location of the timer
+	 */
+	get trace() {
+		return globalThis._oscarpalmer_timer_debug ? this.state.trace : undefined;
+	}
+
+	constructor(
+		type: 'repeat' | 'wait',
+		state: TimerState,
+		options: TimerOptions,
+	) {
+		super(type, state);
+
+		this.options = options;
+	}
+
+	/**
+	 * Continues the timer _(if it was paused)_
+	 */
+	continue(): Timer {
+		return work('continue', this, this.state, this.options);
+	}
+
+	/**
+	 * Pauses the timer _(if it was running)_
+	 */
+	pause(): Timer {
+		return work('pause', this, this.state, this.options);
+	}
+
+	/**
+	 * Restarts the timer _(if it was running)_
+	 */
+	restart(): Timer {
+		return work('restart', this, this.state, this.options);
+	}
+
+	/**
+	 * Starts the timer _(if it was stopped)_
+	 */
+	start(): Timer {
+		return work('start', this, this.state, this.options);
+	}
+
+	/**
+	 * Stops the timer _(if it was running)_
+	 */
+	stop(): Timer {
+		return work('stop', this, this.state, this.options);
+	}
+}
+
+class TimerTrace extends Error {
+	constructor() {
+		super();
+
+		this.name = 'TimerTrace';
+	}
+}
+
+/**
+ * Creates a timer which:
+ * - calls a callback after a certain amount of time...
+ * - ... and repeats it a certain amount of times
+ * ---
+ * - `options.count` defaults to `Infinity`
+ * - `options.interval` defaults to `1000/60` _(1 frame)_
+ * - `options.timeout` defaults to `Infinity`
+ */
+export function repeat(
+	callback: IndexedCallback,
+	options?: Partial<RepeatOptions>,
+): Timer {
+	return timer('repeat', callback, options ?? {}, true);
+}
+
+export function timer(
+	type: 'repeat' | 'wait',
+	callback: AnyCallback,
+	partial: Partial<TimerOptions>,
+	start: boolean,
+): Timer {
+	const isRepeated = type === 'repeat';
+	const options = getOptions(partial, isRepeated);
+
+	const instance = new Timer(
+		type,
+		{
+			callback,
+			isRepeated,
+			active: false,
+			minimum: options.interval - (options.interval % milliseconds) / 2,
+			paused: false,
+			trace: new TimerTrace(),
+		},
+		options,
+	);
+
+	if (start) {
+		instance.start();
+	}
+
+	return instance;
+}
+
+/**
+ * Creates a timer which calls a callback after a certain amount of time
+ */
+export function wait(callback: () => void): Timer;
+
+/**
+ * Creates a timer which calls a callback after a certain amount of time
+ */
+export function wait(callback: () => void, time: number): Timer;
+
+/**
+ * Creates a timer which calls a callback after a certain amount of time
+ * - `options.interval` defaults to `1000/60` _(1 frame)_
+ * - `options.timeout` defaults to `30_000` _(30 seconds)_
+ */
+export function wait(
+	callback: () => void,
+	options: Partial<WaitOptions>,
+): Timer;
+
+export function wait(
+	callback: () => void,
+	options?: number | Partial<WaitOptions>,
+): Timer {
+	return timer(
+		'wait',
+		callback,
+		options == null || typeof options === 'number'
+			? {
+					interval: options,
+				}
+			: options,
+		true,
+	);
+}

package/src/when.ts

@@ -0,0 +1,111 @@
+import {noop} from '@oscarpalmer/atoms/function';
+import type {WhenOptions, WhenState} from './models';
+import {BasicTimer, timer} from './timer';
+
+export class When extends BasicTimer<WhenState> {
+	get active() {
+		return this.state.timer.active;
+	}
+
+	get paused() {
+		return this.state.timer.paused;
+	}
+
+	constructor(state: WhenState) {
+		super('when', state);
+	}
+
+	/**
+	 * Continues the timer _(if it was paused)_
+	 */
+	continue(): When {
+		this.state.timer.continue();
+
+		return this;
+	}
+
+	/**
+	 * Pauses the timer _(if it was running)_
+	 */
+	pause(): When {
+		this.state.timer.pause();
+
+		return this;
+	}
+
+	/**
+	 * Stops the timer _(if it was running)_
+	 */
+	stop(): When {
+		if (this.state.timer.active) {
+			this.state.timer.stop();
+
+			this.state.rejecter?.();
+		}
+
+		return this;
+	}
+
+	/**
+	 * Starts the timer and returns a promise that resolves when the condition is met
+	 */
+
+	// biome-ignore lint/suspicious/noThenProperty: returning a promise-like object, so it's ok ;)
+	then(
+		resolve?: (() => void) | null,
+		reject?: (() => void) | null,
+	): Promise<void> {
+		this.state.timer.start();
+
+		return this.state.promise.then(resolve ?? noop, reject ?? noop);
+	}
+}
+
+/**
+ * - Creates a promise that resolves when a condition is met
+ * - If the condition is never met in a timely manner, the promise will reject
+ */
+export function when(
+	condition: () => boolean,
+	options?: Partial<WhenOptions>,
+): When {
+	const repeated = timer(
+		'repeat',
+		() => {
+			if (condition()) {
+				repeated.stop();
+
+				state.resolver?.();
+			}
+		},
+		{
+			afterCallback() {
+				if (!repeated.paused) {
+					if (condition()) {
+						state.resolver?.();
+					} else {
+						state.rejecter?.();
+					}
+				}
+			},
+			errorCallback() {
+				state.rejecter?.();
+			},
+			count: options?.count,
+			interval: options?.interval,
+			timeout: options?.timeout,
+		},
+		false,
+	);
+
+	const state: WhenState = {} as never;
+
+	state.promise = new Promise((resolve, reject) => {
+		state.resolver = resolve;
+		state.rejecter = reject;
+	});
+
+	state.timer = repeated;
+
+	return new When(state);
+}

package/types/constants.d.ts

@@ -0,0 +1,13 @@
+import type { Timer } from './timer';
+/**
+ * A set of all active timers
+ */
+export declare const activeTimers: Set<Timer>;
+/**
+ * A set of timers that were paused due to the document being hidden
+ */
+export declare const hiddenTimers: Set<Timer>;
+/**
+ * Milliseconds in a frame, probably ;-)
+ */
+export declare const milliseconds: number;

package/types/functions.d.ts

@@ -0,0 +1,5 @@
+import type { TimerOptions, TimerState, WorkType } from './models';
+import type { Timer } from './timer';
+export declare function getOptions(options: Partial<TimerOptions>, isRepeated: boolean): TimerOptions;
+export declare function getValueOrDefault(value: unknown, defaultValue: number, minimum?: number): number;
+export declare function work(type: WorkType, timer: Timer, state: TimerState, options: TimerOptions): Timer;

package/types/global.d.ts

@@ -0,0 +1,5 @@
+declare global {
+    var _oscarpalmer_timer_debug: boolean | undefined;
+    var _oscarpalmer_timers: Timer[] | undefined;
+}
+export {};