@oscarpalmer/timer 0.28.0 → 0.30.0

package/src/when.ts

@@ -1,29 +1,46 @@
 import {noop} from '@oscarpalmer/atoms/function';
-import type {WhenOptions, WhenState} from './models';
-import {BasicTimer, timer} from './timer';
+import {destroyedMessage, milliseconds, startedMessage} from './constants';
+import {getValidNumber} from './get';
+import {TimerTrace, type WhenOptions, type WhenState} from './models';
+import {Timer} from './timer';
+import {work} from './work';
 
-const destroyedMessage = 'Timer has already been destroyed';
-const startedMessage = 'Timer has already been started';
+class When {
+	private readonly $timer = 'when';
+	private readonly state: WhenState;
 
-export class When extends BasicTimer<WhenState> {
+	/**
+	 * Is the timer active?
+	 */
 	get active() {
 		return this.state.timer?.active ?? false;
 	}
 
+	/**
+	 * Is the timer destroyed?
+	 */
 	get destroyed() {
 		return this.state.timer == null;
 	}
 
+	/**
+	 * Is the timer paused?
+	 */
 	get paused() {
 		return this.state.timer?.paused ?? false;
 	}
 
-	get trace() {
-		return this.state.timer?.trace;
+	/**
+	 * Get the timer's origin _(if debugging is enabled)_
+	 */
+	get trace(): string | undefined {
+		return globalThis._oscarpalmer_timer_debug ?? false
+			? this.state.timer?.trace
+			: undefined;
 	}
 
 	constructor(state: WhenState) {
-		super('when', state);
+		this.state = state;
 	}
 
 	/**
@@ -88,29 +105,35 @@ export class When extends BasicTimer<WhenState> {
 }
 
 /**
- * - Creates a promise that resolves when a condition is met
- * - If the condition is never met in a timely manner, the promise will reject
+ * Create a conditional timer
  */
 export function when(
 	condition: () => boolean,
 	options?: Partial<WhenOptions>,
 ): When {
+	let called = false;
 	let result = false;
 
 	const state: WhenState = {
 		started: false,
-		timer: timer(
-			'repeat',
-			() => {
-				if (condition()) {
-					result = true;
-
-					state.timer.stop();
-				}
+		timer: new Timer(
+			'when',
+			work,
+			{
+				callback() {
+					if (condition()) {
+						result = true;
+
+						state.timer.stop();
+					}
+				},
+				trace: new TimerTrace().stack,
 			},
 			{
-				afterCallback() {
-					if (!state.timer.paused) {
+				onAfter() {
+					if (!(state.timer?.paused ?? false) && !called) {
+						called = true;
+
 						if (result) {
 							state.resolver?.();
 						} else {
@@ -120,14 +143,14 @@ export function when(
 						instance.destroy();
 					}
 				},
-				errorCallback() {
+				onError() {
 					state.rejecter?.();
 
 					instance.destroy();
 				},
-				count: options?.count,
-				interval: options?.interval,
-				timeout: options?.timeout,
+				count: getValidNumber(options?.count),
+				interval: getValidNumber(options?.interval, milliseconds),
+				timeout: getValidNumber(options?.timeout),
 			},
 			false,
 		),
@@ -144,3 +167,5 @@ export function when(
 
 	return instance;
 }
+
+export type {When};

package/src/work.ts

@@ -0,0 +1,129 @@
+import {
+	activeTimers,
+	beginTypes,
+	endOrRestartTypes,
+	endTypes,
+	milliseconds,
+	pauseTypes,
+} from './constants';
+import type {
+	TimerOptions,
+	TimerState,
+	WorkHandlerTimer,
+	WorkHandlerType,
+} from './models';
+import type {Timer} from './timer';
+
+function finish(
+	timer: WorkHandlerTimer,
+	state: TimerState,
+	options: TimerOptions,
+	success: boolean,
+): void {
+	activeTimers.delete(timer.instance);
+
+	state.active = false;
+	state.elapsed = 0;
+	state.frame = undefined;
+
+	if (timer.type === 'wait') {
+		state.callback();
+	} else {
+		options.onAfter?.(success);
+	}
+}
+
+export function work(
+	type: WorkHandlerType,
+	timer: WorkHandlerTimer,
+	state: TimerState,
+	options: TimerOptions,
+): Timer {
+	if (
+		(state.destroyed && type !== 'stop') ||
+		(state.active ? beginTypes.has(type) : endTypes.has(type))
+	) {
+		return timer.instance;
+	}
+
+	const pausable = pauseTypes.has(type);
+
+	state.elapsed = pausable ? state.elapsed : 0;
+	state.index = pausable ? state.index : 0;
+	state.total = pausable ? state.total : 0;
+
+	if (endOrRestartTypes.has(type)) {
+		activeTimers.delete(timer.instance);
+
+		cancelAnimationFrame(state.frame as never);
+
+		if (type === 'stop') {
+			options.onAfter?.(false);
+		}
+
+		state.active = false;
+		state.frame = undefined;
+		state.paused = type === 'pause';
+
+		return type === 'restart'
+			? work('start', timer, state, options)
+			: timer.instance;
+	}
+
+	state.active = true;
+	state.paused = false;
+
+	let start: DOMHighResTimeStamp | undefined;
+
+	function step(now: DOMHighResTimeStamp): void {
+		if (!state.active) {
+			return;
+		}
+
+		start ??= now;
+
+		const difference = now - start;
+
+		state.elapsed += difference;
+		state.total += difference;
+
+		if (options.timeout > 0 && state.total >= options.timeout) {
+			options.onError?.();
+
+			finish(timer, state, options, false);
+
+			return;
+		}
+
+		if (
+			options.interval === milliseconds ||
+			state.elapsed >= options.interval - 5
+		) {
+			if (options.count > -1) {
+				(state.callback as (index: number) => void)(state.index);
+			}
+
+			start = now;
+
+			state.elapsed = 0;
+			state.index += 1;
+
+			if (
+				options.count === -1 ||
+				(options.count > 0 && state.index >= options.count)
+			) {
+				finish(timer, state, options, true);
+
+				return;
+			}
+		}
+
+		state.frame = requestAnimationFrame(step);
+	}
+
+	activeTimers.add(timer.instance);
+
+	state.frame = requestAnimationFrame(step);
+
+	return timer.instance;
+}

package/types/constants.d.cts

@@ -1,112 +1,78 @@
 // Generated by dts-bundle-generator v9.5.1
 
-declare abstract class BasicTimer<State> {
-	protected readonly $timer: string;
-	protected readonly state: State;
-	constructor(type: "repeat" | "wait" | "when", state: State);
+declare class Timer {
+	#private;
+	protected readonly worker: WorkHandler;
+	protected readonly options: TimerOptions;
+	private readonly $timer;
+	protected readonly state: TimerState;
 	/**
-	 * Is the timer running?
+	 * Is the timer active?
 	 */
-	abstract readonly active: boolean;
+	get active(): boolean;
 	/**
 	 * Is the timer destroyed?
 	 */
-	abstract readonly destroyed: boolean;
+	get destroyed(): boolean;
 	/**
 	 * Is the timer paused?
 	 */
-	abstract readonly paused: boolean;
+	get paused(): boolean;
 	/**
-	 * Gets the traced location of the timer
+	 * Get the timer's origin _(if debugging is enabled)_
 	 */
-	abstract readonly trace: string | undefined;
-}
-declare class Timer extends BasicTimer<TimerState> {
-	private readonly options;
-	get active(): boolean;
-	get destroyed(): boolean;
-	get paused(): boolean;
 	get trace(): string | undefined;
-	constructor(type: "repeat" | "wait", state: TimerState, options: TimerOptions);
+	constructor(type: TimerType, worker: WorkHandler, state: Pick<TimerState, "callback" | "trace">, options: TimerOptions, start: boolean);
 	/**
-	 * Continues the timer _(if it was paused)_
+	 * Continue running the timer _(if it's paused)_
 	 */
 	continue(): Timer;
 	/**
-	 * Destroys the timer _(after stopping it, if it was running)_
+	 * Destroy the timer
 	 */
 	destroy(): void;
 	/**
-	 * Pauses the timer _(if it was running)_
+	 * Pause the timer _(if it's running)_
 	 */
 	pause(): Timer;
 	/**
-	 * Restarts the timer _(if it was running)_
+	 * Restart the timer _(or start it, if it's not running)_
 	 */
 	restart(): Timer;
 	/**
-	 * Starts the timer _(if it was stopped)_
+	 * Start the timer _(if it's not running)_
 	 */
 	start(): Timer;
 	/**
-	 * Stops the timer _(if it was running)_
+	 * Stop the timer _(if it's running)_
 	 */
 	stop(): 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
-	 */
+export type TimerOptions = {
+	onAfter: ((finished: boolean) => void) | undefined;
+	onError: (() => void) | undefined;
+	count: number;
 	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;
+	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 type WorkType = "continue" | "pause" | "restart" | "start" | "stop";
+export type TimerType = "repeat" | "wait" | "when";
+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";
 /**
  * A set of all active timers
  */
@@ -114,22 +80,31 @@ export declare const activeTimers: Set<Timer>;
 /**
  * A set of types that allow work to begin
  */
-export declare const beginTypes: Set<WorkType>;
+export declare const beginTypes: Set<WorkHandlerType>;
+/**
+ * Message to show when a when-timer is destroyed
+ */
+export declare const destroyedMessage = "Timer has already been destroyed";
 /**
  * A set of types that allow work to end
  */
-export declare const endTypes: Set<WorkType>;
+export declare const endTypes: Set<WorkHandlerType>;
 /**
  * A set of types that allow work to end or restart
  */
-export declare const endOrRestartTypes: Set<WorkType>;
+export declare const endOrRestartTypes: Set<WorkHandlerType>;
 /**
  * A set of timers that were paused due to the document being hidden
  */
 export declare const hiddenTimers: Set<Timer>;
+export declare const pauseTypes: Set<WorkHandlerType>;
+/**
+ * Message to show when a when-timer is started
+ */
+export declare const startedMessage = "Timer has already been started";
 /**
- * Milliseconds in a frame, probably ;-)
+ * A calculated average of the refresh rate of the display _(in milliseconds)_
  */
-export declare const milliseconds: number;
+export declare let milliseconds: number;
 
 export {};

package/types/constants.d.ts

@@ -1,4 +1,4 @@
-import type { WorkType } from './models';
+import type { WorkHandlerType } from './models';
 import type { Timer } from './timer';
 /**
  * A set of all active timers
@@ -7,20 +7,29 @@ export declare const activeTimers: Set<Timer>;
 /**
  * A set of types that allow work to begin
  */
-export declare const beginTypes: Set<WorkType>;
+export declare const beginTypes: Set<WorkHandlerType>;
+/**
+ * Message to show when a when-timer is destroyed
+ */
+export declare const destroyedMessage = "Timer has already been destroyed";
 /**
  * A set of types that allow work to end
  */
-export declare const endTypes: Set<WorkType>;
+export declare const endTypes: Set<WorkHandlerType>;
 /**
  * A set of types that allow work to end or restart
  */
-export declare const endOrRestartTypes: Set<WorkType>;
+export declare const endOrRestartTypes: Set<WorkHandlerType>;
 /**
  * A set of timers that were paused due to the document being hidden
  */
 export declare const hiddenTimers: Set<Timer>;
+export declare const pauseTypes: Set<WorkHandlerType>;
+/**
+ * Message to show when a when-timer is started
+ */
+export declare const startedMessage = "Timer has already been started";
 /**
- * Milliseconds in a frame, probably ;-)
+ * A calculated average of the refresh rate of the display _(in milliseconds)_
  */
-export declare const milliseconds: number;
+export declare let milliseconds: number;

package/types/delay.d.cts

@@ -0,0 +1,8 @@
+// Generated by dts-bundle-generator v9.5.1
+
+/**
+ * Create a delayed promise that resolves after a certain amount of time _(in milliseconds; defaults to screen refresh rate)_
+ */
+export declare function delay(time?: number): Promise<void>;
+
+export {};

package/types/delay.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Create a delayed promise that resolves after a certain amount of time _(in milliseconds; defaults to screen refresh rate)_
+ */
+export declare function delay(time?: number): Promise<void>;

package/types/get.d.cts

@@ -0,0 +1,7 @@
+// Generated by dts-bundle-generator v9.5.1
+
+export type GenericCallback = (...args: any[]) => any;
+export declare function getCallback(value: unknown): GenericCallback;
+export declare function getValidNumber(value: unknown, defaultValue?: number): number;
+
+export {};

package/types/get.d.ts

@@ -0,0 +1,3 @@
+import type { GenericCallback } from '@oscarpalmer/atoms/models';
+export declare function getCallback(value: unknown): GenericCallback;
+export declare function getValidNumber(value: unknown, defaultValue?: number): number;