@oscarpalmer/timer 0.19.0 → 0.21.0

package/src/constants.ts

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

package/src/functions.ts

@@ -0,0 +1,151 @@
+import {activeTimers, milliseconds} from './constants';
+import type {TimerOptions, TimerState, WorkType} from './models';
+import type {Timer} from './timer';
+
+export function getOptions(
+	options: Partial<TimerOptions>,
+	isRepeated: boolean,
+): TimerOptions {
+	return {
+		afterCallback: options.afterCallback,
+		count: getValueOrDefault(
+			options.count,
+			isRepeated ? Number.POSITIVE_INFINITY : 1,
+		),
+		errorCallback: options.errorCallback,
+		interval: getValueOrDefault(options.interval, milliseconds, milliseconds),
+		timeout: getValueOrDefault(
+			options.timeout,
+			isRepeated ? Number.POSITIVE_INFINITY : 30_000,
+		),
+	};
+}
+
+export function getValueOrDefault(
+	value: unknown,
+	defaultValue: number,
+	minimum?: number,
+): number {
+	return typeof value === 'number' && value > (minimum ?? 0)
+		? value
+		: defaultValue;
+}
+
+export function work(
+	type: WorkType,
+	timer: Timer,
+	state: TimerState,
+	options: TimerOptions,
+): Timer {
+	if (
+		(['continue', 'start'].includes(type) && state.active) ||
+		(['pause', 'stop'].includes(type) && !state.active)
+	) {
+		return timer;
+	}
+
+	const {count, interval, timeout} = options;
+	const {isRepeated, minimum} = state;
+
+	if (['pause', 'restart', 'stop'].includes(type)) {
+		const isStop = type === 'stop';
+
+		activeTimers.delete(timer);
+
+		cancelAnimationFrame(state.frame as never);
+
+		if (isStop) {
+			options.afterCallback?.(false);
+		}
+
+		state.active = false;
+		state.frame = undefined;
+		state.paused = !isStop;
+
+		if (isStop) {
+			state.elapsed = undefined;
+			state.index = undefined;
+		}
+
+		return type === 'restart' ? work('start', timer, state, options) : timer;
+	}
+
+	state.active = true;
+	state.paused = false;
+
+	const elapsed = type === 'continue' ? +(state.elapsed ?? 0) : 0;
+
+	let index = type === 'continue' ? +(state.index ?? 0) : 0;
+
+	state.elapsed = elapsed;
+	state.index = index;
+
+	const total =
+		(count === Number.POSITIVE_INFINITY
+			? Number.POSITIVE_INFINITY
+			: (count - index) * (interval > 0 ? interval : milliseconds)) - elapsed;
+
+	let current: DOMHighResTimeStamp | null;
+	let start: DOMHighResTimeStamp | null;
+
+	function finish(finished: boolean, error: boolean) {
+		activeTimers.delete(timer);
+
+		state.active = false;
+		state.elapsed = undefined;
+		state.frame = undefined;
+		state.index = undefined;
+
+		if (error) {
+			options.errorCallback?.();
+		}
+
+		options.afterCallback?.(finished);
+	}
+
+	function step(timestamp: DOMHighResTimeStamp): void {
+		if (!state.active) {
+			return;
+		}
+
+		current ??= timestamp;
+		start ??= timestamp;
+
+		const time = timestamp - current;
+
+		state.elapsed = elapsed + (current - start);
+
+		const finished = time - elapsed >= total;
+
+		if (timestamp - start >= timeout - elapsed) {
+			finish(finished, !finished);
+
+			return;
+		}
+
+		if (finished || time >= minimum) {
+			if (state.active) {
+				state.callback((isRepeated ? index : undefined) as never);
+			}
+
+			index += 1;
+
+			state.index = index;
+
+			if (!finished && index < count) {
+				current = null;
+			} else {
+				finish(true, false);
+				return;
+			}
+		}
+
+		state.frame = requestAnimationFrame(step);
+	}
+
+	activeTimers.add(timer);
+
+	state.frame = requestAnimationFrame(step);
+
+	return timer;
+}

package/src/global.ts

@@ -0,0 +1,14 @@
+import {activeTimers} from './constants';
+
+declare global {
+	var _oscarpalmer_timer_debug: boolean | undefined;
+	var _oscarpalmer_timers: Timer[] | undefined;
+}
+
+if (globalThis._oscarpalmer_timers == null) {
+	Object.defineProperty(globalThis, '_oscarpalmer_timers', {
+		get() {
+			return globalThis._oscarpalmer_timer_debug ? [...activeTimers] : [];
+		},
+	});
+}

package/src/index.ts

@@ -1,230 +1,37 @@
-type Callbacks = {
-	after: AfterCallback | undefined;
-	default: (index?: number) => void;
-};
-
-type Configuration = {
-	count: number;
-	time: number;
-};
+import {noop} from '@oscarpalmer/atoms/function';
+import {activeTimers, hiddenTimers} from './constants';
+import './global';
+import {wait} from './timer';
 
 /**
- * @param {boolean} finished Did the timer finish?
+ * Creates a delayed promise that resolves after a certain amount of time _(or rejects when timed out)_
  */
-export type AfterCallback = (finished: boolean) => void;
-
-/**
- * @param {number} index The index of the current iteration
- */
-export type RepeatedCallback = (index: number) => void;
-
-type State = {
-	active: boolean;
-	finished: boolean;
-	frame?: number;
-};
-
-const callbacks = new WeakMap<Timed<never, never>, Callbacks>();
-const configuration = new WeakMap<Timed<never, never>, Configuration>();
-const state = new WeakMap<Timed<never, never>, State>();
-
-const milliseconds = Math.round(1000 / 60);
-
-function run(timed: Timed<never, never>): void {
-	const timedConfiguration = configuration.get(timed)!;
-	const timedCallbacks = callbacks.get(timed)!;
-	const timedState = state.get(timed)!;
-
-	timedState.active = true;
-	timedState.finished = false;
-
-	const isRepeated = timed instanceof Repeated;
-
-	let index = 0;
-
-	let start;
-
-	function step(timestamp: DOMHighResTimeStamp): void {
-		if (!timedState.active) {
-			return;
-		}
-
-		start ??= timestamp;
-
-		const elapsed = timestamp - start;
-
-		const elapsedMinimum = elapsed - milliseconds;
-		const elapsedMaximum = elapsed + milliseconds;
-
-		if (
-			elapsedMinimum < timedConfiguration.time &&
-			timedConfiguration.time < elapsedMaximum
-		) {
-			if (timedState.active) {
-				timedCallbacks.default(isRepeated ? index : undefined);
-			}
-
-			index += 1;
-
-			if (isRepeated && index < timedConfiguration.count) {
-				start = undefined;
-			} else {
-				timedState.finished = true;
-
-				timed.stop();
-
-				return;
-			}
-		}
-
-		timedState.frame = globalThis.requestAnimationFrame(step);
-	}
-
-	timedState.frame = globalThis.requestAnimationFrame(step);
-}
-
-class Timed<Type, Callback> {
-	get active(): boolean {
-		return state.get(this as never)?.active ?? false;
-	}
-
-	get finished(): boolean {
-		return !this.active && (state.get(this as never)?.finished ?? false);
-	}
-
-	/**
-	 * @param {Callback} callback
-	 * @param {number} time
-	 * @param {number} count
-	 * @param {AfterCallback=} afterCallback
-	 */
-	constructor(
-		callback: Callback,
-		time: number,
-		count: number,
-		afterCallback?: AfterCallback,
-	) {
-		const isRepeated = this instanceof Repeated;
-
-		const type = isRepeated ? 'repeated' : 'waited';
-
-		if (typeof callback !== 'function') {
-			throw new TypeError(`A ${type} timer must have a callback function`);
-		}
-
-		if (typeof time !== 'number' || time < 0) {
-			throw new TypeError(
-				`A ${type} timer must have a non-negative number as its time`,
-			);
-		}
-
-		if (isRepeated && (typeof count !== 'number' || count < 2)) {
-			throw new TypeError(
-				'A repeated timer must have a number above 1 as its repeat count',
-			);
-		}
-
-		if (
-			isRepeated &&
-			afterCallback !== undefined &&
-			typeof afterCallback !== 'function'
-		) {
-			throw new TypeError(
-				"A repeated timer's after-callback must be a function",
-			);
-		}
-
-		callbacks.set(this as never, {
-			after: afterCallback,
-			default: callback as never,
+export function delay(time: number, timeout?: number): Promise<void> {
+	return new Promise((resolve, reject) => {
+		wait(resolve ?? noop, {
+			timeout,
+			errorCallback: reject ?? noop,
+			interval: time,
 		});
+	});
+}
 
-		configuration.set(this as never, {count, time});
-
-		state.set(this as never, {
-			active: false,
-			finished: false,
-		});
-	}
-
-	restart(): Type {
-		this.stop();
-
-		run(this as never);
-
-		return this as never;
-	}
-
-	start(): Type {
-		if (!this.active) {
-			run(this as never);
+document.addEventListener('visibilitychange', () => {
+	if (document.hidden) {
+		for (const timer of activeTimers) {
+			hiddenTimers.add(timer);
+			timer.pause();
 		}
-
-		return this as never;
-	}
-
-	stop(): Type {
-		const timedCallbacks = callbacks.get(this as never)!;
-		const timedState = state.get(this as never)!;
-
-		timedState.active = false;
-
-		if (timedState.frame === undefined) {
-			return this as never;
+	} else {
+		for (const timer of hiddenTimers) {
+			timer.continue();
 		}
 
-		globalThis.cancelAnimationFrame(timedState.frame);
-
-		timedCallbacks.after?.(this.finished);
-
-		timedState.frame = undefined;
-
-		return this as never;
-	}
-}
-
-/**
- * A timer that waits and runs repeatedly
- */
-export class Repeated extends Timed<Repeated, RepeatedCallback> {}
-
-/**
- * A timer that waits and runs once
- */
-export class Waited extends Timed<Waited, () => void> {
-	/**
-	 * Creates a new waited timer
-	 * @param {() => void} callback
-	 * @param {number} time
-	 */
-	constructor(callback: () => void, time: number) {
-		super(callback, time, 1);
+		hiddenTimers.clear();
 	}
-}
+});
 
-/**
- * Creates and starts a new repeated timer
- * @param {RepeatedCallback} callback
- * @param {number} time
- * @param {number} count
- * @param {AfterCallback=} afterCallback
- * @return {Repeated}
- */
-export function repeat(
-	callback: RepeatedCallback,
-	time: number,
-	count: number,
-	afterCallback?: AfterCallback,
-): Repeated {
-	return new Repeated(callback as never, time, count, afterCallback).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
- * @param {() => void} callback
- * @param {number} time
- * @return {Waited}
- */
-export function wait(callback: () => void, time: number): Waited {
-	return new Waited(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';