@oscarpalmer/timer 0.43.0 → 0.45.0

package/dist/when.mjs

@@ -1,124 +1,34 @@
-import { MESSAGE_DESTROYED, MESSAGE_STARTED, TYPE_WHEN } from "./constants.mjs";
-import { getValidNumber, getValidTimeout } from "./get.mjs";
+import { MESSAGE_STARTED, TYPE_WHEN, WORK_CONTINUE, WORK_PAUSE, WORK_STOP } from "./constants.mjs";
+import { getValidNumber, getValidTimeout } from "./misc.mjs";
 import "./global.mjs";
 import { TimerTrace } from "./models.mjs";
-import { Timer } from "./timer.mjs";
+import { createTimer } from "./timer.mjs";
 import { noop } from "@oscarpalmer/atoms/function";
 //#region src/when.ts
-var When = class {
-	state = {
-		promise: void 0,
-		rejecter: void 0,
-		resolver: void 0,
-		started: false,
-		timer: void 0
-	};
-	/**
-	* 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 the timer's origin _(if debugging is enabled)_
-	*/
-	get trace() {
-		return globalThis._oscarpalmer_timer_debug ?? false ? this.state.timer?.trace : void 0;
-	}
-	constructor(condition, options) {
-		Object.defineProperty(this, "$timer", { value: TYPE_WHEN });
-		const { state } = this;
-		state.promise = new Promise((resolve, reject) => {
-			state.resolver = resolve;
-			state.rejecter = reject;
-		});
-		let result = false;
-		this.state.timer = new Timer(TYPE_WHEN, {
-			callback() {
-				try {
-					if (condition()) {
-						result = true;
-						state.timer.stop();
-					}
-				} catch {
-					state.timer.stop();
-				}
-			},
-			trace: new TimerTrace().stack
-		}, {
-			onAfter: () => {
-				if (result) state.resolver?.();
-				else state.rejecter?.();
-				this.destroy();
-			},
-			onError: () => {
-				state.rejecter?.();
-				this.destroy();
-			},
-			count: getValidNumber(options?.count),
-			interval: getValidNumber(options?.interval),
-			timeout: getValidTimeout(options?.timeout)
-		}, false);
-	}
-	/**
-	* Continues the timer _(if it was paused)_
-	*/
-	continue() {
-		this.state.timer?.continue();
-		return this;
-	}
-	/**
-	* Destroys the timer _(and stops it,if it was running)_
-	*/
-	destroy() {
-		const { state } = this;
-		state.timer?.destroy();
-		state.promise = void 0;
-		state.resolver = noop;
-		state.rejecter = noop;
-		state.timer = void 0;
-	}
-	/**
-	* Pauses the timer _(if it was running)_
-	*/
-	pause() {
-		this.state.timer?.pause();
-		return this;
-	}
-	/**
-	* Start the timer
-	*
-	* @param resolve Optional resolve callback
-	* @returns Promise that resolves when the condition is met
-	*/
-	start(resolve) {
-		const { state } = this;
-		if (state.timer == null) throw new Error(MESSAGE_DESTROYED);
-		if (state.started) throw new Error(MESSAGE_STARTED);
-		state.started = true;
-		state.timer.start();
-		return state.promise.then(resolve);
-	}
-	/**
-	* Stops the timer _(if it was running)_
-	*/
-	stop() {
-		this.state.timer?.stop();
-		return this;
+function onAfter(state) {
+	if (state.result) state.resolver?.();
+	else state.rejecter?.();
+}
+function onCallback(condition, state) {
+	try {
+		if (condition()) {
+			state.result = true;
+			state.timer.stop();
+		}
+	} catch {
+		state.timer.stop();
 	}
-};
+}
+function onWhen(type, instance, state) {
+	state.timer?.[type]?.();
+	return instance;
+}
+function startWhen(state, resolve) {
+	if (state.started) throw new Error(MESSAGE_STARTED);
+	state.started = true;
+	state.timer.start();
+	return state.promise.then(resolve);
+}
 /**
 * Create a conditional timer
 * @param condition Condition to check
@@ -126,7 +36,57 @@ var When = class {
 * @returns Timer instance
 */
 function when(condition, options) {
-	return new When(condition, options);
+	const state = {
+		promise: void 0,
+		result: false,
+		started: false,
+		timer: void 0
+	};
+	let instance;
+	state.promise = new Promise((resolve, reject) => {
+		state.resolver = resolve;
+		state.rejecter = reject;
+	});
+	state.timer = createTimer(TYPE_WHEN, {
+		callback: () => onCallback(condition, state),
+		trace: new TimerTrace().stack
+	}, {
+		onAfter: () => onAfter(state),
+		onError: () => state.rejecter?.(),
+		count: getValidNumber(options?.count),
+		interval: getValidNumber(options?.interval),
+		timeout: getValidTimeout(options?.timeout)
+	}, false);
+	instance = {
+		continue: () => onWhen(WORK_CONTINUE, instance, state),
+		destroy: noop,
+		pause: () => onWhen(WORK_PAUSE, instance, state),
+		start: (resolve) => startWhen(state, resolve),
+		stop: () => onWhen(WORK_STOP, instance, state)
+	};
+	Object.defineProperties(instance, {
+		$timer: {
+			enumerable: false,
+			value: TYPE_WHEN
+		},
+		active: {
+			enumerable: true,
+			get: () => state.timer.active
+		},
+		destroyed: {
+			enumerable: true,
+			value: false
+		},
+		paused: {
+			enumerable: true,
+			get: () => state.timer.paused
+		},
+		trace: {
+			enumerable: true,
+			get: () => globalThis._oscarpalmer_timer_debug ?? false ? state.timer?.trace : void 0
+		}
+	});
+	return Object.freeze(instance);
 }
 //#endregion
 export { when };

package/dist/work.d.mts

@@ -1,8 +1,6 @@
-import { Timer } from "./timer.mjs";
-import { TimerOptions, TimerState, WorkHandlerTimer, WorkHandlerType } from "./models.mjs";
-
+import { Timer, TimerState, WorkHandlerType } from "./models.mjs";
 //#region src/work.d.ts
-declare function stop(timer: WorkHandlerTimer, state: TimerState, options: TimerOptions): Timer;
-declare function work(type: WorkHandlerType, timer: WorkHandlerTimer, state: TimerState, options: TimerOptions): Timer;
+declare function stop(state: TimerState): Timer;
+declare function work(type: WorkHandlerType, state: TimerState, hide?: boolean): Timer;
 //#endregion
 export { stop, work };

package/dist/work.mjs

@@ -1,25 +1,20 @@
-import { TIMERS_ACTIVE, WORK_PAUSE, WORK_STOP } from "./constants.mjs";
+import { WORK_PAUSE } from "./constants.mjs";
+import { updateStates } from "./misc.mjs";
 //#region src/work.ts
-function finish(timer, state, options, success) {
+function finish(state, success) {
+	updateStates(state);
 	cancelAnimationFrame(state.frame);
-	TIMERS_ACTIVE.delete(timer.instance);
 	state.active = false;
 	state.elapsed = 0;
 	state.frame = void 0;
-	if (timer.type === "wait") state.callback();
-	else options.onAfter?.(success);
+	if (state.name === "wait") state.callback();
+	else state.options.onAfter?.(success);
 }
 function ignore(type, state) {
-	if (state.destroyed) return type !== WORK_STOP;
 	if (state.paused) return type === "pause" || type === "start";
 	return state.active && type === "start";
 }
-function pause(timer, state) {
-	cancelAnimationFrame(state.frame);
-	state.frame = void 0;
-	return timer.instance;
-}
-function run(timer, state, options) {
+function run(state) {
 	let last;
 	let start;
 	return function step(now) {
@@ -30,18 +25,18 @@ function run(timer, state, options) {
 		state.elapsed += difference;
 		state.total += difference;
 		last = now;
-		if (options.timeout > 0 && state.total >= options.timeout) {
-			options.onError?.();
-			finish(timer, state, options, false);
+		if (state.options.timeout > 0 && state.total >= state.options.timeout) {
+			state.options.onError?.();
+			finish(state, false);
 			return;
 		}
-		if (options.interval === 0 || state.elapsed >= options.interval - 5) {
-			if (options.count > -1) state.callback(state.index);
+		if (state.options.interval === 0 || state.elapsed >= state.options.interval - 5) {
+			if (state.options.count > -1) state.callback(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);
+			if (state.options.count === -1 || state.options.count > 0 && state.index >= state.options.count) {
+				finish(state, true);
 				return;
 			}
 		}
@@ -54,30 +49,30 @@ function setState(type, state) {
 	state.index = pausable ? state.index : 0;
 	state.total = pausable ? state.total : 0;
 }
-function stop(timer, state, options) {
+function stop(state) {
+	updateStates(state);
 	cancelAnimationFrame(state.frame);
-	TIMERS_ACTIVE.delete(timer.instance);
-	options.onAfter?.(false);
-	state.active = !stop;
+	state.options.onAfter?.(false);
+	state.active = false;
 	state.frame = void 0;
 	state.paused = false;
-	return timer.instance;
+	return state.timer;
 }
-function work(type, timer, state, options) {
-	if (ignore(type, state)) return timer.instance;
+function work(type, state, hide) {
+	if (ignore(type, state)) return state.timer;
 	setState(type, state);
-	if (type === "stop") return stop(timer, state, options);
+	if (type === "stop") return stop(state);
 	if (type === "pause" || type === "restart") {
 		cancelAnimationFrame(state.frame);
 		state.frame = void 0;
 	}
 	state.active = true;
 	state.paused = type === WORK_PAUSE;
-	if (state.paused) return pause(timer, state);
-	TIMERS_ACTIVE.add(timer.instance);
-	const runner = run(timer, state, options);
+	updateStates(state, state.paused ? hide ?? false ? "hidden" : void 0 : "active");
+	if (state.paused) return state.timer;
+	const runner = run(state);
 	state.frame = requestAnimationFrame(runner);
-	return timer.instance;
+	return state.timer;
 }
 //#endregion
 export { stop, work };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oscarpalmer/timer",
-	"version": "0.43.0",
+	"version": "0.45.0",
 	"description": "A better solution for timeout- and interval-based timers.",
 	"keywords": [
 		"requestAnimationFrame",
@@ -30,9 +30,9 @@
 			"types": "./dist/index.d.mts",
 			"default": "./dist/index.mjs"
 		},
-		"./delay": {
-			"types": "./dist/delay.d.mts",
-			"default": "./dist/delay.mjs"
+		"./models": {
+			"types": "./dist/models.d.mts",
+			"default": "./dist/models.mjs"
 		},
 		"./repeat": {
 			"types": "./dist/repeat.d.mts",
@@ -56,13 +56,13 @@
 		"watch": "npx vite build --watch"
 	},
 	"dependencies": {
-		"@oscarpalmer/atoms": "^0.187"
+		"@oscarpalmer/atoms": "^0.193"
 	},
 	"devDependencies": {
-		"@oxlint/plugins": "^1.66",
-		"@types/node": "^25.9",
+		"@oxlint/plugins": "^1.80",
+		"@types/node": "^26.4",
 		"@vitest/coverage-istanbul": "^4.1",
-		"jsdom": "^29.1",
+		"jsdom": "^30",
 		"tsdown": "^0.22",
 		"typescript": "^6",
 		"vite": "npm:@voidzero-dev/vite-plus-core@latest",

package/src/constants.ts

@@ -1,5 +1,4 @@
-import type {TimerType, WorkHandlerType} from './models';
-import type {Timer} from './timer';
+import type {TimerName, TimerStates, WorkHandlerType} from './models';
 
 /**
  * Buffer value to use when evaluating if a specific time is within a certain range
@@ -8,31 +7,21 @@ export const BUFFER_INTERVAL = 5;
 
 export const DEFAULT_TIMEOUT = 30_000;
 
-/**
- * Message to show when a when-timer is destroyed
- */
-export const MESSAGE_DESTROYED = 'Timer has already been destroyed';
-
 /**
  * Message to show when a when-timer is started
  */
 export const MESSAGE_STARTED = 'Timer has already been started';
 
-/**
- * A set of all active timers
- */
-export const TIMERS_ACTIVE = new Set<Timer>();
-
-/**
- * A set of timers that were paused due to the document being hidden
- */
-export const TIMERS_HIDDEN = new Set<Timer>();
+export const STATES: TimerStates = {
+	active: new Set(),
+	hidden: new Set(),
+};
 
-export const TYPE_REPEAT: TimerType = 'repeat';
+export const TYPE_REPEAT: TimerName = 'repeat';
 
-export const TYPE_WAIT: TimerType = 'wait';
+export const TYPE_WAIT: TimerName = 'wait';
 
-export const TYPE_WHEN: TimerType = 'when';
+export const TYPE_WHEN: TimerName = 'when';
 
 export const WORK_CONTINUE: WorkHandlerType = 'continue';
 

package/src/global.ts

@@ -1,29 +1,19 @@
-import {TIMERS_ACTIVE, TIMERS_HIDDEN, WORK_CONTINUE, WORK_PAUSE} from './constants';
-import type {Timer} from './timer';
+import {STATES} from './constants';
+import {onVisibilityChange} from './misc';
+import type {Timer} from './models';
 
 declare global {
 	var _oscarpalmer_timer_debug: boolean | undefined;
+	/**
+	 * All active timers _(or `undefined` if debugging is not enabled)_
+	 */
 	var _oscarpalmer_timers: Timer[] | undefined;
 }
 
-if (globalThis._oscarpalmer_timers == null) {
-	Object.defineProperty(globalThis, '_oscarpalmer_timers', {
-		get() {
-			return globalThis._oscarpalmer_timer_debug ? [...TIMERS_ACTIVE] : [];
-		},
-	});
-}
-
-/* istanbul ignore next */
-document.addEventListener('visibilitychange', () => {
-	const from = document.hidden ? TIMERS_ACTIVE : TIMERS_HIDDEN;
-	const method = document.hidden ? WORK_PAUSE : WORK_CONTINUE;
-	const to = document.hidden ? TIMERS_HIDDEN : TIMERS_ACTIVE;
-
-	for (const timer of from) {
-		timer[method]();
-		to.add(timer);
-	}
-
-	from.clear();
+Object.defineProperty(globalThis, '_oscarpalmer_timers', {
+	get() {
+		return globalThis._oscarpalmer_timer_debug ? [...STATES.active].map(state => state.timer) : [];
+	},
 });
+
+document.addEventListener('visibilitychange', onVisibilityChange);

package/src/index.ts

@@ -1,8 +1,7 @@
 import './global';
 
-export * from './delay';
 export {isRepeated, isTimer, isWaited, isWhen} from './is';
-export * from './repeat';
-export type {Timer} from './timer';
-export * from './wait';
-export * from './when';
+export type {RepeatOptions, Timer, TimerOptions, When, WhenOptions} from './models';
+export {repeat} from './repeat';
+export {wait} from './wait';
+export {when} from './when';

package/src/is.ts

@@ -1,7 +1,6 @@
 import type {PlainObject} from '@oscarpalmer/atoms/models';
 import {TYPE_REPEAT, TYPE_WAIT, TYPE_WHEN} from './constants';
-import type {Timer} from './timer';
-import type {When} from './when';
+import type {Timer, When} from './models';
 
 function is(names: string[], value: unknown) {
 	return names.includes((value as PlainObject)?.$timer as string);

package/src/misc.ts

@@ -0,0 +1,49 @@
+import {noop} from '@oscarpalmer/atoms/function';
+import type {GenericCallback} from '@oscarpalmer/atoms/models';
+import {DEFAULT_TIMEOUT, STATES, WORK_CONTINUE, WORK_PAUSE} from './constants';
+import type {TimerStates, TimerState} from './models';
+import {work} from './work';
+
+export function getCallback(value: unknown): GenericCallback {
+	return typeof value === 'function' ? (value as GenericCallback) : noop;
+}
+
+export function getValidNumber(value: unknown, defaultValue?: number): number {
+	const actualDefault = defaultValue ?? 0;
+
+	return typeof value === 'number' && value > actualDefault ? value : actualDefault;
+}
+
+export function getValidTimeout(value: unknown): number {
+	return typeof value === 'number' && value > 0 ? value : DEFAULT_TIMEOUT;
+}
+
+/* istanbul ignore next */
+export function onVisibilityChange(): void {
+	const from = document.hidden ? STATES.active : STATES.hidden;
+	const type = document.hidden ? WORK_PAUSE : WORK_CONTINUE;
+
+	for (const stored of from) {
+		const state = stored instanceof WeakRef ? stored.deref() : stored;
+
+		if (state != null) {
+			work(type, state, true);
+		}
+	}
+}
+
+export function updateStates(state: TimerState, key?: keyof TimerStates): void {
+	STATES.active.delete(state);
+
+	const hidden = [...STATES.hidden].find(stored => stored.deref() === state);
+
+	/* istanbul ignore next */
+	if (hidden != null) {
+		STATES.hidden.delete(hidden);
+	}
+
+	if (key != null) {
+		/* istanbul ignore next */
+		STATES[key].add((key === 'hidden' ? new WeakRef(state) : state) as never);
+	}
+}

package/src/models.ts

@@ -1,5 +1,3 @@
-import type {Timer} from './timer';
-
 /**
  * Options for a repeating timer
  */
@@ -26,6 +24,64 @@ export type RepeatOptions = {
 	timeout: number;
 };
 
+export type Timer = {
+	/**
+	 * Is the timer active?
+	 */
+	get active(): boolean;
+
+	/**
+	 * Is the timer destroyed?
+	 * 
+	 * @deprecated Timers take care of their own cleanup; this always returns `false`
+	 */
+	get destroyed(): boolean;
+
+	/**
+	 * Is the timer paused?
+	 */
+	get paused(): boolean;
+
+	/**
+	 * Get the timer's origin _(if debugging is enabled)_
+	 */
+	get trace(): string | undefined;
+
+	/**
+	 * Continue running the timer _(if it's paused)_
+	 */
+	continue(): Timer;
+
+	/**
+	 * Destroy the timer
+	 * 
+	 * @deprecated Timers take care of their own cleanup
+	 */
+	destroy(): void;
+
+	/**
+	 * Pause the timer _(if it's running)_
+	 */
+	pause(): Timer;
+
+	/**
+	 * Restart the timer _(or start it, if it's not running)_
+	 */
+	restart(): Timer;
+
+	/**
+	 * Start the timer _(if it's not running)_
+	 */
+	start(): Timer;
+
+	/**
+	 * Stop the timer _(if it's running)_
+	 */
+	stop(): Timer;
+};
+
+export type TimerName = 'repeat' | 'wait' | 'when';
+
 export type TimerOptions = {
 	onAfter: ((finished: boolean) => void) | undefined;
 	onError: (() => void) | undefined;
@@ -39,11 +95,25 @@ export type TimerState = {
 	callback: () => void;
 	destroyed: boolean;
 	elapsed: number;
-	frame: number | undefined;
+	frame?: number;
 	index: number;
+	name: TimerName;
+	options: TimerOptions;
 	paused: boolean;
+	timer: Timer;
 	total: number;
-	trace: string | undefined;
+	trace?: string;
+};
+
+export type TimerStates = {
+	/**
+	 * A set of all active timers
+	 */
+	active: Set<TimerState>;
+	/**
+	 * A set of timers that were paused due to the document being hidden
+	 */
+	hidden: Set<WeakRef<TimerState>>;
 };
 
 export class TimerTrace extends Error {
@@ -54,7 +124,59 @@ export class TimerTrace extends Error {
 	}
 }
 
-export type TimerType = 'repeat' | 'wait' | 'when';
+export type When = {
+	/**
+	 * Is the timer active?
+	 */
+	get active(): boolean;
+
+	/**
+	 * Is the timer destroyed?
+	 * 
+	 * @deprecated Timers take care of their own cleanup; this always returns `false`
+	 */
+	get destroyed(): boolean;
+
+	/**
+	 * Is the timer paused?
+	 */
+	get paused(): boolean;
+
+	/**
+	 * Get the timer's origin _(if debugging is enabled)_
+	 */
+	get trace(): string | undefined;
+
+	/**
+	 * Continues the timer _(if it was paused)_
+	 */
+	continue(): When;
+
+	/**
+	 * Destroys the timer _(and stops it,if it was running)_
+	 * 
+	 * @deprecated Timers take care of their own cleanup
+	 */
+	destroy(): void;
+
+	/**
+	 * Pauses the timer _(if it was running)_
+	 */
+	pause(): When;
+
+	/**
+	 * Start the timer
+	 *
+	 * @param resolve Optional resolve callback
+	 * @returns Promise that resolves when the condition is met
+	 */
+	start(resolve?: (() => void) | null): Promise<void>;
+
+	/**
+	 * Stops the timer _(if it was running)_
+	 */
+	stop(): When;
+};
 
 /**
  * Options for a conditional timer
@@ -78,6 +200,7 @@ export type WhenState = {
 	promise: Promise<void>;
 	rejecter?: () => void;
 	resolver?: () => void;
+	result: boolean;
 	started: boolean;
 	timer: Timer;
 };
@@ -91,7 +214,7 @@ export type WorkHandler = (
 
 export type WorkHandlerTimer = {
 	instance: Timer;
-	type: TimerType;
+	name: TimerName;
 };
 
 export type WorkHandlerType = 'continue' | 'pause' | 'restart' | 'start' | 'stop';