@oscarpalmer/timer 0.28.0 → 0.30.0

package/src/get.ts

@@ -0,0 +1,12 @@
+import {noop} from '@oscarpalmer/atoms/function';
+import type {GenericCallback} from '@oscarpalmer/atoms/models';
+
+export function getCallback(value: unknown): GenericCallback {
+	return typeof value === 'function' ? (value as GenericCallback) : noop;
+}
+
+export function getValidNumber(value: unknown, defaultValue?: number): number {
+	return typeof value === 'number' && value > (defaultValue ?? 0)
+		? value
+		: defaultValue ?? 0;
+}

package/src/global.ts

@@ -1,5 +1,5 @@
+import {activeTimers, hiddenTimers} from './constants';
 import type {Timer} from './timer';
-import {activeTimers} from './constants';
 
 declare global {
 	var _oscarpalmer_timer_debug: boolean | undefined;
@@ -13,3 +13,18 @@ if (globalThis._oscarpalmer_timers == null) {
 		},
 	});
 }
+
+document.addEventListener('visibilitychange', () => {
+	if (document.hidden) {
+		for (const timer of activeTimers) {
+			hiddenTimers.add(timer);
+			timer.pause();
+		}
+	} else {
+		for (const timer of hiddenTimers) {
+			timer.continue();
+		}
+
+		hiddenTimers.clear();
+	}
+});

package/src/index.ts

@@ -1,51 +1,8 @@
-import {noop} from '@oscarpalmer/atoms/function';
-import {activeTimers, hiddenTimers} from './constants';
 import './global';
-import {type Timer, wait} from './timer';
-
-/**
- * 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) => {
-		let delayed: Timer | null = wait(
-			() => {
-				delayed?.destroy();
-
-				delayed = null;
-
-				(resolve ?? noop)();
-			},
-			{
-				timeout,
-				errorCallback: () => {
-					delayed?.destroy();
-
-					delayed = null;
-
-					(reject ?? noop)();
-				},
-				interval: time,
-			},
-		);
-	});
-}
-
-document.addEventListener('visibilitychange', () => {
-	if (document.hidden) {
-		for (const timer of activeTimers) {
-			hiddenTimers.add(timer);
-			timer.pause();
-		}
-	} else {
-		for (const timer of hiddenTimers) {
-			timer.continue();
-		}
-
-		hiddenTimers.clear();
-	}
-});
 
+export * from './delay';
 export {isRepeated, isTimer, isWaited, isWhen} from './is';
-export {repeat, wait, type Timer} from './timer';
-export {when, type When} from './when';
+export * from './repeat';
+export type {Timer} from './timer';
+export * from './wait';
+export * from './when';

package/src/is.ts

@@ -2,34 +2,34 @@ 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);
+function is(names: string[], value: unknown) {
+	return names.includes((value as PlainObject)?.$timer as string);
 }
 
 /**
  * Is the value a repeating timer?
  */
 export function isRepeated(value: unknown): value is Timer {
-	return is(/^repeat$/, value);
+	return is(['repeat'], value);
 }
 
 /**
  * Is the value a timer?
  */
 export function isTimer(value: unknown): value is Timer {
-	return is(/^repeat|wait$/, value);
+	return is(['repeat', 'wait'], value);
 }
 
 /**
  * Is the value a waiting timer?
  */
 export function isWaited(value: unknown): value is Timer {
-	return is(/^wait$/, value);
+	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';
+	return is(['when'], value) && typeof (value as When).then === 'function';
 }

package/src/models.ts

@@ -1,66 +1,41 @@
 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
+ * Options for a repeating timer
  */
-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 = {
+export type RepeatOptions = {
 	/**
-	 * Interval between each callback
+	 * Callback to be called when the timer has stopped, either manually or by completing its work
 	 */
-	interval: number;
-	/**
-	 * Maximum amount of time the timer may run for
-	 */
-	timeout: number;
-};
-
-export type OptionsWithCount = {
+	onAfter: ((finished: boolean) => void) | undefined;
 	/**
 	 * How many times the timer should repeat
 	 */
 	count: number;
-} & BaseOptions;
-
-export type OptionsWithError = {
 	/**
-	 * Callback to run when an error occurs _(usually a timeout)_
+	 * The interval between each repeat
 	 */
-	errorCallback?: () => void;
+	interval: number;
 };
 
-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 TimerOptions = {
+	onAfter: ((finished: boolean) => void) | undefined;
+	onError: (() => void) | undefined;
+	count: number;
+	interval: number;
+	timeout: number;
+};
 
 export type TimerState = {
 	active: boolean;
-	callback: AnyCallback;
+	callback: () => void;
 	destroyed: boolean;
-	count?: number;
-	elapsed?: number;
-	frame?: number;
-	index?: number;
-	isRepeated: boolean;
-	minimum: number;
+	elapsed: number;
+	frame: number | undefined;
+	index: number;
 	paused: boolean;
-	trace?: string;
+	total: number;
+	trace: string | undefined;
 };
 
 export class TimerTrace extends Error {
@@ -71,9 +46,25 @@ export class TimerTrace extends Error {
 	}
 }
 
-export type WaitOptions = {} & BaseOptions & OptionsWithError;
+export type TimerType = 'repeat' | 'wait' | 'when';
 
-export type WhenOptions = {} & OptionsWithCount;
+/**
+ * Options for a conditional timer
+ */
+export type WhenOptions = {
+	/**
+	 * How many times the timer should check the condition
+	 */
+	count: number;
+	/**
+	 * Then interval between each condtional check
+	 */
+	interval: number;
+	/**
+	 * The timeout for the timer
+	 */
+	timeout: number;
+};
 
 export type WhenState = {
 	promise: Promise<void>;
@@ -83,4 +74,21 @@ export type WhenState = {
 	timer: Timer;
 };
 
-export type WorkType = 'continue' | 'pause' | 'restart' | 'start' | 'stop';
+export type WorkHandler = (
+	type: WorkHandlerType,
+	timer: WorkHandlerTimer,
+	state: TimerState,
+	options: TimerOptions,
+) => Timer;
+
+export type WorkHandlerTimer = {
+	instance: Timer;
+	type: TimerType;
+};
+
+export type WorkHandlerType =
+	| 'continue'
+	| 'pause'
+	| 'restart'
+	| 'start'
+	| 'stop';

package/src/repeat.ts

@@ -0,0 +1,32 @@
+import {milliseconds} from './constants';
+import {getCallback, getValidNumber} from './get';
+import {type RepeatOptions, TimerTrace} from './models';
+import {Timer} from './timer';
+import {work} from './work';
+
+/**
+ * Create a repeating timer
+ */
+export function repeat(
+	callback: (index: number) => void,
+	options?: Partial<RepeatOptions>,
+): Timer {
+	return new Timer(
+		'repeat',
+		work,
+		{
+			callback: getCallback(callback),
+			trace: new TimerTrace().stack,
+		},
+		{
+			onAfter: getCallback(options?.onAfter),
+			onError: undefined,
+			count: getValidNumber(options?.count),
+			interval: getValidNumber(options?.interval, milliseconds),
+			timeout: 0,
+		},
+		true,
+	);
+}
+
+export type {RepeatOptions, Timer};

package/src/timer.ts

@@ -1,208 +1,124 @@
-import {milliseconds} from './constants';
-import {getOptions, work} from './functions';
-import {
-	type AnyCallback,
-	type IndexedCallback,
-	type RepeatOptions,
-	type TimerOptions,
-	type TimerState,
-	TimerTrace,
-	type WaitOptions,
+import type {
+	TimerOptions,
+	TimerState,
+	TimerType,
+	WorkHandler,
+	WorkHandlerType,
 } from './models';
 
-export abstract class BasicTimer<State> {
-	protected declare readonly $timer: string;
-	protected declare readonly state: State;
+export class Timer {
+	private declare readonly $timer: TimerType;
 
-	constructor(type: 'repeat' | 'wait' | 'when', state: State) {
-		this.$timer = type;
-		this.state = state;
-	}
+	protected readonly state: TimerState;
 
 	/**
-	 * Is the timer running?
+	 * Is the timer active?
 	 */
-	abstract readonly active: boolean;
+	get active(): boolean {
+		return this.state.active;
+	}
 
 	/**
 	 * Is the timer destroyed?
 	 */
-	abstract readonly destroyed: boolean;
+	get destroyed(): boolean {
+		return this.state.destroyed;
+	}
 
 	/**
 	 * Is the timer paused?
 	 */
-	abstract readonly paused: boolean;
-
-	/**
-	 * Gets the traced location of the timer
-	 */
-	abstract readonly trace: string | undefined;
-}
-
-/**
- * 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 destroyed() {
-		return this.state.destroyed;
-	}
-
-	get paused() {
+	get paused(): boolean {
 		return this.state.paused;
 	}
 
-	get trace() {
-		return globalThis._oscarpalmer_timer_debug ? this.state.trace : undefined;
+	/**
+	 * Get the timer's origin _(if debugging is enabled)_
+	 */
+	get trace(): string | undefined {
+		return globalThis._oscarpalmer_timer_debug ?? false
+			? this.state.trace
+			: undefined;
 	}
 
 	constructor(
-		type: 'repeat' | 'wait',
-		state: TimerState,
-		options: TimerOptions,
+		type: TimerType,
+		protected readonly worker: WorkHandler,
+		state: Pick<TimerState, 'callback' | 'trace'>,
+		protected readonly options: TimerOptions,
+		start: boolean,
 	) {
-		super(type, state);
+		this.$timer = type;
+
+		this.state = {
+			...state,
+			active: false,
+			destroyed: false,
+			elapsed: 0,
+			frame: undefined,
+			index: 0,
+			paused: false,
+			total: 0,
+		};
 
-		this.options = options;
+		if (start) {
+			this.start();
+		}
 	}
 
 	/**
-	 * Continues the timer _(if it was paused)_
+	 * Continue running the timer _(if it's paused)_
 	 */
 	continue(): Timer {
-		return work('continue', this, this.state, this.options);
+		return this.#work('continue');
 	}
 
 	/**
-	 * Destroys the timer _(after stopping it, if it was running)_
+	 * Destroy the timer
 	 */
 	destroy(): void {
-		if (!this.state.destroyed) {
-			this.state.destroyed = true;
-
-			this.stop();
-
-			this.options.afterCallback = undefined;
-			this.options.errorCallback = undefined;
+		this.state.destroyed = true;
 
-			this.state.callback = undefined as never;
-			this.state.trace = undefined as never;
-		}
+		this.#work('stop');
 	}
 
 	/**
-	 * Pauses the timer _(if it was running)_
+	 * Pause the timer _(if it's running)_
 	 */
 	pause(): Timer {
-		return work('pause', this, this.state, this.options);
+		return this.#work('pause');
 	}
 
 	/**
-	 * Restarts the timer _(if it was running)_
+	 * Restart the timer _(or start it, if it's not running)_
 	 */
 	restart(): Timer {
-		return work('restart', this, this.state, this.options);
+		return this.#work('restart');
 	}
 
 	/**
-	 * Starts the timer _(if it was stopped)_
+	 * Start the timer _(if it's not running)_
 	 */
 	start(): Timer {
-		return work('start', this, this.state, this.options);
+		return this.#work('start');
 	}
 
 	/**
-	 * Stops the timer _(if it was running)_
+	 * Stop the timer _(if it's running)_
 	 */
 	stop(): Timer {
-		return work('stop', this, this.state, this.options);
+		return this.#work('stop');
 	}
-}
 
-/**
- * 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,
-			destroyed: false,
-			minimum: options.interval - (options.interval % milliseconds) / 2,
-			paused: false,
-			trace: new TimerTrace().stack,
-		},
-		options,
-	);
-
-	if (start) {
-		instance.start();
+	#work(type: WorkHandlerType): Timer {
+		return this.worker(
+			type,
+			{
+				instance: this,
+				type: this.$timer,
+			},
+			this.state,
+			this.options,
+		);
 	}
-
-	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/wait.ts

@@ -0,0 +1,31 @@
+import {milliseconds} from './constants';
+import {getCallback, getValidNumber} from './get';
+import {TimerTrace} from './models';
+import {Timer} from './timer';
+import {work} from './work';
+
+/**
+ * Create a waiting timer
+ * @param callback Callback to run when the timer has finished
+ * @param time How long to wait for _(in milliseconds; defaults to screen refresh rate)_
+ */
+export function wait(callback: () => void, time?: number): Timer {
+	return new Timer(
+		'wait',
+		work,
+		{
+			callback: getCallback(callback),
+			trace: new TimerTrace().stack,
+		},
+		{
+			onAfter: undefined,
+			onError: undefined,
+			count: -1,
+			interval: getValidNumber(time, milliseconds),
+			timeout: 0,
+		},
+		true,
+	);
+}
+
+export type {Timer};