@oscarpalmer/timer 0.39.0 → 0.40.0

package/dist/constants.js

@@ -1,9 +1,24 @@
 import FRAME_RATE_MS from "@oscarpalmer/atoms/frame-rate";
+/**
+* Buffer value to use when evaluating if a specific time is within a certain range
+*/
 const BUFFER_INTERVAL = 5;
 const DEFAULT_TIMEOUT = 3e4;
+/**
+* Message to show when a when-timer is destroyed
+*/
 const MESSAGE_DESTROYED = "Timer has already been destroyed";
+/**
+* Message to show when a when-timer is started
+*/
 const MESSAGE_STARTED = "Timer has already been started";
+/**
+* A set of all active timers
+*/
 const TIMERS_ACTIVE = /* @__PURE__ */ new Set();
+/**
+* A set of timers that were paused due to the document being hidden
+*/
 const TIMERS_HIDDEN = /* @__PURE__ */ new Set();
 const TYPE_REPEAT = "repeat";
 const TYPE_WAIT = "wait";

package/dist/delay.js

@@ -1,15 +1,10 @@
-import { BUFFER_INTERVAL, FRAME_RATE_MS } from "./constants.js";
 import { getValidNumber } from "./get.js";
+/**
+* Create a delayed promise that resolves after a certain amount of time
+* @param time How long to wait for _(in milliseconds; defaults to screen refresh rate)_
+* @returns A promise that resolves after the delay
+*/
 function delay(time) {
-	return new Promise((resolve) => {
-		const interval = getValidNumber(time, FRAME_RATE_MS);
-		let start;
-		function step(now) {
-			start ??= now;
-			if (interval === FRAME_RATE_MS || now - start >= interval - 5) resolve();
-			else requestAnimationFrame(step);
-		}
-		requestAnimationFrame(step);
-	});
+	return new Promise((resolve) => setTimeout(resolve, getValidNumber(time)));
 }
 export { delay };

package/dist/is.js

@@ -2,15 +2,35 @@ import { TYPE_REPEAT, TYPE_WAIT, TYPE_WHEN } from "./constants.js";
 function is(names, value) {
 	return names.includes(value?.$timer);
 }
+/**
+* Is the value a repeating timer?
+* @param value Value to check
+* @returns `true` if the value is a repeating timer
+*/
 function isRepeated(value) {
 	return is([TYPE_REPEAT], value);
 }
+/**
+* Is the value a timer?
+* @param value Value to check
+* @returns `true` if the value is a timer
+*/
 function isTimer(value) {
 	return is([TYPE_REPEAT, TYPE_WAIT], value);
 }
+/**
+* Is the value a waiting timer?
+* @param value Value to check
+* @returns `true` if the value is a waiting timer
+*/
 function isWaited(value) {
 	return is([TYPE_WAIT], value);
 }
+/**
+* Is the value a conditional timer?
+* @param value Value to check
+* @returns `true` if the value is a conditional timer
+*/
 function isWhen(value) {
 	return is(["when"], value) && typeof value.then === "function";
 }

package/dist/repeat.js

@@ -3,6 +3,12 @@ import { getCallback, getValidNumber } from "./get.js";
 import "./global.js";
 import { TimerTrace } from "./models.js";
 import { Timer } from "./timer.js";
+/**
+* Create a repeating timer
+* @param callback Callback to run on each interval
+* @param options Timer options
+* @returns Timer instance
+*/
 function repeat(callback, options) {
 	return new Timer(TYPE_REPEAT, {
 		callback: getCallback(callback),

package/dist/timer.full.js

@@ -19,11 +19,26 @@ calculate().then((value) => {
 	FRAME_RATE_MS = value;
 });
 var frame_rate_default = FRAME_RATE_MS;
+/**
+* Buffer value to use when evaluating if a specific time is within a certain range
+*/
 const BUFFER_INTERVAL = 5;
 const DEFAULT_TIMEOUT = 3e4;
+/**
+* Message to show when a when-timer is destroyed
+*/
 const MESSAGE_DESTROYED = "Timer has already been destroyed";
+/**
+* Message to show when a when-timer is started
+*/
 const MESSAGE_STARTED = "Timer has already been started";
+/**
+* A set of all active timers
+*/
 const TIMERS_ACTIVE = /* @__PURE__ */ new Set();
+/**
+* A set of timers that were paused due to the document being hidden
+*/
 const TIMERS_HIDDEN = /* @__PURE__ */ new Set();
 const TYPE_REPEAT = "repeat";
 const TYPE_WAIT = "wait";
@@ -71,30 +86,46 @@ function getValidNumber(value, defaultValue) {
 	const actualDefault = defaultValue ?? 0;
 	return typeof value === "number" && value > actualDefault ? value : actualDefault;
 }
+/**
+* Create a delayed promise that resolves after a certain amount of time
+* @param time How long to wait for _(in milliseconds; defaults to screen refresh rate)_
+* @returns A promise that resolves after the delay
+*/
 function delay(time) {
-	return new Promise((resolve) => {
-		const interval = getValidNumber(time, frame_rate_default);
-		let start;
-		function step(now) {
-			start ??= now;
-			if (interval === frame_rate_default || now - start >= interval - BUFFER_INTERVAL) resolve();
-			else requestAnimationFrame(step);
-		}
-		requestAnimationFrame(step);
-	});
+	return new Promise((resolve) => setTimeout(resolve, getValidNumber(time)));
 }
 function is(names, value) {
 	return names.includes(value?.$timer);
 }
+/**
+* Is the value a repeating timer?
+* @param value Value to check
+* @returns `true` if the value is a repeating timer
+*/
 function isRepeated(value) {
 	return is([TYPE_REPEAT], value);
 }
+/**
+* Is the value a timer?
+* @param value Value to check
+* @returns `true` if the value is a timer
+*/
 function isTimer(value) {
 	return is([TYPE_REPEAT, TYPE_WAIT], value);
 }
+/**
+* Is the value a waiting timer?
+* @param value Value to check
+* @returns `true` if the value is a waiting timer
+*/
 function isWaited(value) {
 	return is([TYPE_WAIT], value);
 }
+/**
+* Is the value a conditional timer?
+* @param value Value to check
+* @returns `true` if the value is a conditional timer
+*/
 function isWhen(value) {
 	return is([TYPE_WHEN], value) && typeof value.then === "function";
 }
@@ -185,15 +216,27 @@ function work(type, timer, state, options) {
 }
 var Timer = class {
 	state;
+	/**
+	* Is the timer active?
+	*/
 	get active() {
 		return this.state.active;
 	}
+	/**
+	* Is the timer destroyed?
+	*/
 	get destroyed() {
 		return this.state.destroyed;
 	}
+	/**
+	* Is the timer paused?
+	*/
 	get paused() {
 		return this.state.paused;
 	}
+	/**
+	* Get the timer's origin _(if debugging is enabled)_
+	*/
 	get trace() {
 		return globalThis._oscarpalmer_timer_debug ?? false ? this.state.trace : void 0;
 	}
@@ -212,9 +255,15 @@ var Timer = class {
 		};
 		if (start) this.start();
 	}
+	/**
+	* Continue running the timer _(if it's paused)_
+	*/
 	continue() {
 		return this.#work(WORK_CONTINUE);
 	}
+	/**
+	* Destroy the timer
+	*/
 	destroy() {
 		this.state.destroyed = true;
 		this.options.onAfter = noop;
@@ -226,15 +275,27 @@ var Timer = class {
 			type: this.$timer
 		}, this.state, this.options);
 	}
+	/**
+	* Pause the timer _(if it's running)_
+	*/
 	pause() {
 		return this.#work(WORK_PAUSE);
 	}
+	/**
+	* Restart the timer _(or start it, if it's not running)_
+	*/
 	restart() {
 		return this.#work(WORK_RESTART);
 	}
+	/**
+	* Start the timer _(if it's not running)_
+	*/
 	start() {
 		return this.#work(WORK_START);
 	}
+	/**
+	* Stop the timer _(if it's running)_
+	*/
 	stop() {
 		return this.#work(WORK_STOP);
 	}
@@ -245,6 +306,12 @@ var Timer = class {
 		}, this.state, this.options);
 	}
 };
+/**
+* Create a repeating timer
+* @param callback Callback to run on each interval
+* @param options Timer options
+* @returns Timer instance
+*/
 function repeat(callback, options) {
 	return new Timer(TYPE_REPEAT, {
 		callback: getCallback(callback),
@@ -257,6 +324,11 @@ function repeat(callback, options) {
 		timeout: getValidNumber(options?.timeout)
 	}, true);
 }
+/**
+* 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)_
+*/
 function wait(callback, time) {
 	return new Timer(TYPE_WAIT, {
 		callback: getCallback(callback),
@@ -277,15 +349,27 @@ var When = class {
 		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;
 	}
@@ -324,10 +408,16 @@ var When = class {
 			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();
@@ -336,10 +426,19 @@ var When = class {
 		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
+	* @param reject Optional reject callback
+	* @returns Promise that resolves when the condition is met
+	*/
 	start(resolve, reject) {
 		const { state } = this;
 		if (state.timer == null) throw new Error(MESSAGE_DESTROYED);
@@ -348,14 +447,30 @@ var When = class {
 		state.timer.start();
 		return state.promise.then(resolve ?? noop, reject ?? noop);
 	}
+	/**
+	* Stops the timer _(if it was running)_
+	*/
 	stop() {
 		this.state.timer?.stop();
 		return this;
 	}
+	/**
+	* Start the timer
+	* @deprecated Use `start()` instead
+	* @param resolve Optional resolve callback
+	* @param reject Optional reject callback
+	* @returns Promise that resolves when the condition is met
+	*/
 	then(resolve, reject) {
 		return this.start(resolve, reject);
 	}
 };
+/**
+* Create a conditional timer
+* @param condition Condition to check
+* @param options Timer options
+* @returns Timer instance
+*/
 function when(condition, options) {
 	return new When(condition, options);
 }

package/dist/timer.js

@@ -3,15 +3,27 @@ import { stop, work } from "./work.js";
 import { noop } from "@oscarpalmer/atoms/function";
 var Timer = class {
 	state;
+	/**
+	* Is the timer active?
+	*/
 	get active() {
 		return this.state.active;
 	}
+	/**
+	* Is the timer destroyed?
+	*/
 	get destroyed() {
 		return this.state.destroyed;
 	}
+	/**
+	* Is the timer paused?
+	*/
 	get paused() {
 		return this.state.paused;
 	}
+	/**
+	* Get the timer's origin _(if debugging is enabled)_
+	*/
 	get trace() {
 		return globalThis._oscarpalmer_timer_debug ?? false ? this.state.trace : void 0;
 	}
@@ -30,9 +42,15 @@ var Timer = class {
 		};
 		if (start) this.start();
 	}
+	/**
+	* Continue running the timer _(if it's paused)_
+	*/
 	continue() {
 		return this.#work(WORK_CONTINUE);
 	}
+	/**
+	* Destroy the timer
+	*/
 	destroy() {
 		this.state.destroyed = true;
 		this.options.onAfter = noop;
@@ -44,15 +62,27 @@ var Timer = class {
 			type: this.$timer
 		}, this.state, this.options);
 	}
+	/**
+	* Pause the timer _(if it's running)_
+	*/
 	pause() {
 		return this.#work(WORK_PAUSE);
 	}
+	/**
+	* Restart the timer _(or start it, if it's not running)_
+	*/
 	restart() {
 		return this.#work(WORK_RESTART);
 	}
+	/**
+	* Start the timer _(if it's not running)_
+	*/
 	start() {
 		return this.#work(WORK_START);
 	}
+	/**
+	* Stop the timer _(if it's running)_
+	*/
 	stop() {
 		return this.#work(WORK_STOP);
 	}

package/dist/wait.js

@@ -3,6 +3,11 @@ import { getCallback, getValidNumber } from "./get.js";
 import "./global.js";
 import { TimerTrace } from "./models.js";
 import { Timer } from "./timer.js";
+/**
+* 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)_
+*/
 function wait(callback, time) {
 	return new Timer(TYPE_WAIT, {
 		callback: getCallback(callback),

package/dist/when.js

@@ -12,15 +12,27 @@ var When = class {
 		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;
 	}
@@ -59,10 +71,16 @@ var When = class {
 			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();
@@ -71,10 +89,19 @@ var When = class {
 		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
+	* @param reject Optional reject callback
+	* @returns Promise that resolves when the condition is met
+	*/
 	start(resolve, reject) {
 		const { state } = this;
 		if (state.timer == null) throw new Error(MESSAGE_DESTROYED);
@@ -83,14 +110,30 @@ var When = class {
 		state.timer.start();
 		return state.promise.then(resolve ?? noop, reject ?? noop);
 	}
+	/**
+	* Stops the timer _(if it was running)_
+	*/
 	stop() {
 		this.state.timer?.stop();
 		return this;
 	}
+	/**
+	* Start the timer
+	* @deprecated Use `start()` instead
+	* @param resolve Optional resolve callback
+	* @param reject Optional reject callback
+	* @returns Promise that resolves when the condition is met
+	*/
 	then(resolve, reject) {
 		return this.start(resolve, reject);
 	}
 };
+/**
+* Create a conditional timer
+* @param condition Condition to check
+* @param options Timer options
+* @returns Timer instance
+*/
 function when(condition, options) {
 	return new When(condition, options);
 }

package/package.json

@@ -8,15 +8,15 @@
 	},
 	"description": "A better solution for timeout- and interval-based timers.",
 	"devDependencies": {
-		"@types/node": "^25",
+		"@types/node": "^25.2",
 		"@vitest/coverage-istanbul": "^4",
-		"jsdom": "^27.3",
-		"oxfmt": "^0.19",
-		"oxlint": "^1.34",
-		"rolldown": "1.0.0-beta.55",
+		"jsdom": "^28.1",
+		"oxfmt": "^0.33",
+		"oxlint": "^1.48",
+		"rolldown": "1.0.0-rc.4",
 		"tslib": "^2.8",
 		"typescript": "^5.9",
-		"vite": "8.0.0-beta.2",
+		"vite": "8.0.0-beta.14",
 		"vitest": "^4"
 	},
 	"exports": {
@@ -70,5 +70,5 @@
 	},
 	"type": "module",
 	"types": "types/index.d.ts",
-	"version": "0.39.0"
+	"version": "0.40.0"
 }

package/src/delay.ts

@@ -1,4 +1,3 @@
-import {BUFFER_INTERVAL, FRAME_RATE_MS} from './constants';
 import {getValidNumber} from './get';
 
 /**
@@ -7,21 +6,5 @@ import {getValidNumber} from './get';
  * @returns A promise that resolves after the delay
  */
 export function delay(time?: number): Promise<void> {
-	return new Promise(resolve => {
-		const interval = getValidNumber(time, FRAME_RATE_MS);
-
-		let start: DOMHighResTimeStamp;
-
-		function step(now: DOMHighResTimeStamp) {
-			start ??= now;
-
-			if (interval === FRAME_RATE_MS || now - start >= interval - BUFFER_INTERVAL) {
-				resolve();
-			} else {
-				requestAnimationFrame(step);
-			}
-		}
-
-		requestAnimationFrame(step);
-	});
+	return new Promise(resolve => setTimeout(resolve, getValidNumber(time)));
 }

package/src/when.ts

@@ -6,7 +6,7 @@ import {TimerTrace, type WhenOptions, type WhenState} from './models';
 import {Timer} from './timer';
 
 class When {
-	private declare readonly $timer: string;
+	declare private readonly $timer: string;
 
 	private readonly state: WhenState = {
 		promise: undefined as never,