@oscarpalmer/timer 0.37.0 → 0.38.0

package/README.md

@@ -36,24 +36,24 @@ const repeated = new Timer(repeatedCallback, 10);
 
 When creating a _Timer_, either with the new `new`-keyword or using the functions, you can configure the timer with a few parameters:
 
-|Parameter|Description|
-|--------:|:----------|
-|`callback`|Callback function to be invoked for each run that are __required__ for all timers.<br>For more information on callbacks, please read [the callbacks section](#callbacks).|
-|`count`|How many times the timer should run.<br>If no value is provided, it will default to `1` when using the `new`-keyword and the `wait`-method, but throws an error for the `repeat`-method.|
-|`time`|How many milliseconds between each invokations of the provided callback.<br>Defaults to `0`, which is not really _0_ milliseconds, but close enough :wink:|
-|`after`|A callback to run after the timer finishes, both when cancelled and completed.<br>If _count_ is greater than `1` and _after_ __is not__ `undefined`, a function is expected.|
+|  Parameter | Description                                                                                                                                                                              |
+| ---------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `callback` | Callback function to be invoked for each run that are **required** for all timers.<br>For more information on callbacks, please read [the callbacks section](#callbacks).                |
+|    `count` | How many times the timer should run.<br>If no value is provided, it will default to `1` when using the `new`-keyword and the `wait`-method, but throws an error for the `repeat`-method. |
+|     `time` | How many milliseconds between each invokations of the provided callback.<br>Defaults to `0`, which is not really _0_ milliseconds, but close enough :wink:                               |
+|    `after` | A callback to run after the timer finishes, both when cancelled and completed.<br>If _count_ is greater than `1` and _after_ **is not** `undefined`, a function is expected.             |
 
 ## Methods and properties
 
 An instance of _Timer_ also has a few helpful methods and properties:
 
-|Name|Type|Description|
-|---:|----|:----------|
-|`active`|_Property_|A `boolean` value to check if the timer is running|
-|`finished`|_Property_|A `boolean` value to check if the timer was able to finish|
-|`start()`|_Method_|Starts the timer.<br>Necessary when creating a timer using the class syntax _(e.g. `new Waited...`)_, but helpful when the timer needs to be started at other times, as well.|
-|`stop()`|_Method_|Stops the timer|
-|`restart()`|_Method_|Restarts the timer|
+|        Name | Type       | Description                                                                                                                                                                   |
+| ----------: | ---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+|    `active` | _Property_ | A `boolean` value to check if the timer is running                                                                                                                            |
+|  `finished` | _Property_ | A `boolean` value to check if the timer was able to finish                                                                                                                    |
+|   `start()` | _Method_   | Starts the timer.<br>Necessary when creating a timer using the class syntax _(e.g. `new Waited...`)_, but helpful when the timer needs to be started at other times, as well. |
+|    `stop()` | _Method_   | Stops the timer                                                                                                                                                               |
+| `restart()` | _Method_   | Restarts the timer                                                                                                                                                            |
 
 ## Callbacks
 

package/dist/constants.js

@@ -5,20 +5,18 @@ function calculate() {
 		function step(now) {
 			if (last != null) values.push(now - last);
 			last = now;
-			if (values.length >= 10) {
-				const median = values.sort().slice(2, -2).reduce((first, second) => first + second, 0) / (values.length - 4);
-				resolve(median);
-			} else requestAnimationFrame(step);
+			if (values.length >= 10) resolve(values.sort().slice(2, -2).reduce((first, second) => first + second, 0) / (values.length - 4));
+			else requestAnimationFrame(step);
 		}
 		requestAnimationFrame(step);
 	});
 }
-const defaultTimeout = 3e4;
-const activeTimers = /* @__PURE__ */ new Set();
-const intervalBuffer = 5;
-const destroyedMessage = "Timer has already been destroyed";
-const hiddenTimers = /* @__PURE__ */ new Set();
-const startedMessage = "Timer has already been started";
+const BUFFER_INTERVAL = 5;
+const DEFAULT_TIMEOUT = 3e4;
+const MESSAGE_DESTROYED = "Timer has already been destroyed";
+const MESSAGE_STARTED = "Timer has already been started";
+const TIMERS_ACTIVE = /* @__PURE__ */ new Set();
+const TIMERS_HIDDEN = /* @__PURE__ */ new Set();
 const TYPE_REPEAT = "repeat";
 const TYPE_WAIT = "wait";
 const TYPE_WHEN = "when";
@@ -27,8 +25,8 @@ const WORK_PAUSE = "pause";
 const WORK_RESTART = "restart";
 const WORK_START = "start";
 const WORK_STOP = "stop";
-let milliseconds = 1e3 / 60;
+let MILLISECONDS = 1e3 / 60;
 calculate().then((value) => {
-	milliseconds = value;
+	MILLISECONDS = value;
 });
-export { TYPE_REPEAT, TYPE_WAIT, TYPE_WHEN, WORK_CONTINUE, WORK_PAUSE, WORK_RESTART, WORK_START, WORK_STOP, activeTimers, defaultTimeout, destroyedMessage, hiddenTimers, intervalBuffer, milliseconds, startedMessage };
+export { BUFFER_INTERVAL, DEFAULT_TIMEOUT, MESSAGE_DESTROYED, MESSAGE_STARTED, MILLISECONDS, TIMERS_ACTIVE, TIMERS_HIDDEN, TYPE_REPEAT, TYPE_WAIT, TYPE_WHEN, WORK_CONTINUE, WORK_PAUSE, WORK_RESTART, WORK_START, WORK_STOP };

package/dist/delay.js

@@ -1,12 +1,12 @@
-import { intervalBuffer, milliseconds } from "./constants.js";
+import { BUFFER_INTERVAL, MILLISECONDS } from "./constants.js";
 import { getValidNumber } from "./get.js";
 function delay(time) {
 	return new Promise((resolve) => {
-		const interval = getValidNumber(time, milliseconds);
+		const interval = getValidNumber(time, MILLISECONDS);
 		let start;
 		function step(now) {
 			start ??= now;
-			if (interval === milliseconds || now - start >= interval - 5) resolve();
+			if (interval === MILLISECONDS || now - start >= interval - 5) resolve();
 			else requestAnimationFrame(step);
 		}
 		requestAnimationFrame(step);

package/dist/get.js

@@ -1,10 +1,10 @@
-import { defaultTimeout } from "./constants.js";
+import { DEFAULT_TIMEOUT } from "./constants.js";
 import { noop } from "@oscarpalmer/atoms/function";
 function getCallback(value) {
 	return typeof value === "function" ? value : noop;
 }
 function getValidTimeout(value) {
-	return typeof value === "number" && value > 0 ? value : defaultTimeout;
+	return typeof value === "number" && value > 0 ? value : DEFAULT_TIMEOUT;
 }
 function getValidNumber(value, defaultValue) {
 	const actualDefault = defaultValue ?? 0;

package/dist/global.js

@@ -1,12 +1,12 @@
-import { WORK_CONTINUE, WORK_PAUSE, activeTimers, hiddenTimers } from "./constants.js";
+import { TIMERS_ACTIVE, TIMERS_HIDDEN, WORK_CONTINUE, WORK_PAUSE } from "./constants.js";
 if (globalThis._oscarpalmer_timers == null) Object.defineProperty(globalThis, "_oscarpalmer_timers", { get() {
-	return globalThis._oscarpalmer_timer_debug ? [...activeTimers] : [];
+	return globalThis._oscarpalmer_timer_debug ? [...TIMERS_ACTIVE] : [];
 } });
 /* istanbul ignore next */
 document.addEventListener("visibilitychange", () => {
-	const from = document.hidden ? activeTimers : hiddenTimers;
+	const from = document.hidden ? TIMERS_ACTIVE : TIMERS_HIDDEN;
 	const method = document.hidden ? WORK_PAUSE : WORK_CONTINUE;
-	const to = document.hidden ? hiddenTimers : activeTimers;
+	const to = document.hidden ? TIMERS_HIDDEN : TIMERS_ACTIVE;
 	for (const timer of from) {
 		timer[method]();
 		to.add(timer);

package/dist/index.js

@@ -1,7 +1,7 @@
+import { delay } from "./delay.js";
 import "./global.js";
-import { when } from "./when.js";
-import { wait } from "./wait.js";
-import { repeat } from "./repeat.js";
 import { isRepeated, isTimer, isWaited, isWhen } from "./is.js";
-import { delay } from "./delay.js";
+import { repeat } from "./repeat.js";
+import { wait } from "./wait.js";
+import { when } from "./when.js";
 export { delay, isRepeated, isTimer, isWaited, isWhen, repeat, wait, when };

package/dist/repeat.js

@@ -1,4 +1,4 @@
-import { TYPE_REPEAT, milliseconds } from "./constants.js";
+import { MILLISECONDS, TYPE_REPEAT } from "./constants.js";
 import { getCallback, getValidNumber } from "./get.js";
 import "./global.js";
 import { TimerTrace } from "./models.js";
@@ -11,7 +11,7 @@ function repeat(callback, options) {
 		onAfter: getCallback(options?.onAfter),
 		onError: getCallback(options?.onTimeout),
 		count: getValidNumber(options?.count),
-		interval: getValidNumber(options?.interval, milliseconds),
+		interval: getValidNumber(options?.interval, MILLISECONDS),
 		timeout: getValidNumber(options?.timeout)
 	}, true);
 }

package/dist/toretto.full.js

@@ -0,0 +1,515 @@
+function calculate$1() {
+	return new Promise((resolve) => {
+		const values = [];
+		let last;
+		function step(now) {
+			if (last != null) values.push(now - last);
+			last = now;
+			if (values.length >= 10) resolve(values.sort().slice(2, -2).reduce((first, second) => first + second, 0) / (values.length - 4));
+			else requestAnimationFrame(step);
+		}
+		requestAnimationFrame(step);
+	});
+}
+/**
+* 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";
+const TYPE_WHEN = "when";
+const WORK_CONTINUE = "continue";
+const WORK_PAUSE = "pause";
+const WORK_RESTART = "restart";
+const WORK_START = "start";
+const WORK_STOP = "stop";
+/**
+* A calculated average of the refresh rate of the display _(in milliseconds)_
+*/
+let MILLISECONDS = 1e3 / 60;
+calculate$1().then((value) => {
+	MILLISECONDS = value;
+});
+
+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();
+});
+
+var typeArrays = new Set([
+	Int8Array,
+	Uint8Array,
+	Uint8ClampedArray,
+	Int16Array,
+	Uint16Array,
+	Int32Array,
+	Uint32Array,
+	Float32Array,
+	Float64Array,
+	BigInt64Array,
+	BigUint64Array
+]);
+
+function calculate() {
+	return new Promise((resolve) => {
+		const values = [];
+		let last;
+		function step(now) {
+			if (last != null) values.push(now - last);
+			last = now;
+			if (values.length >= 10) resolve(values.sort().slice(2, -2).reduce((first, second) => first + second, 0) / (values.length - 4));
+			else requestAnimationFrame(step);
+		}
+		requestAnimationFrame(step);
+	});
+}
+function noop() {}
+let milliseconds = 1e3 / 60;
+calculate().then((value) => {
+	milliseconds = value;
+});
+
+function getCallback(value) {
+	return typeof value === "function" ? value : noop;
+}
+function getValidTimeout(value) {
+	return typeof value === "number" && value > 0 ? value : DEFAULT_TIMEOUT;
+}
+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, MILLISECONDS);
+		let start;
+		function step(now) {
+			start ??= now;
+			if (interval === MILLISECONDS || now - start >= interval - BUFFER_INTERVAL) resolve();
+			else requestAnimationFrame(step);
+		}
+		requestAnimationFrame(step);
+	});
+}
+
+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";
+}
+
+var TimerTrace = class extends Error {
+	constructor() {
+		super();
+		this.name = "TimerTrace";
+	}
+};
+
+function finish(timer, state, options, success) {
+	cancelAnimationFrame(state.frame);
+	TIMERS_ACTIVE.delete(timer.instance);
+	state.active = false;
+	state.elapsed = 0;
+	state.frame = void 0;
+	if (timer.type === TYPE_WAIT) state.callback();
+	else options.onAfter?.(success);
+}
+function ignore(type, state) {
+	if (state.destroyed) return type !== WORK_STOP;
+	if (state.paused) return type === WORK_PAUSE || type === WORK_START;
+	return state.active && type === WORK_START;
+}
+function pause(timer, state) {
+	cancelAnimationFrame(state.frame);
+	state.frame = void 0;
+	return timer.instance;
+}
+function run(timer, state, options) {
+	let last;
+	let start;
+	return function step(now) {
+		if (!state.active) return;
+		last ??= now;
+		start ??= now;
+		const difference = now - last;
+		state.elapsed += difference;
+		state.total += difference;
+		last = now;
+		if (options.timeout > 0 && state.total >= options.timeout) {
+			options.onError?.();
+			finish(timer, state, options, false);
+			return;
+		}
+		if (options.interval === MILLISECONDS || state.elapsed >= options.interval - BUFFER_INTERVAL) {
+			if (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);
+				return;
+			}
+		}
+		state.frame = requestAnimationFrame(step);
+	};
+}
+function setState(type, state) {
+	const pausable = type === WORK_CONTINUE || type === WORK_PAUSE;
+	state.elapsed = pausable ? state.elapsed : 0;
+	state.index = pausable ? state.index : 0;
+	state.total = pausable ? state.total : 0;
+}
+function stop(timer, state, options) {
+	cancelAnimationFrame(state.frame);
+	TIMERS_ACTIVE.delete(timer.instance);
+	options.onAfter?.(false);
+	state.active = !stop;
+	state.frame = void 0;
+	state.paused = false;
+	return timer.instance;
+}
+function work(type, timer, state, options) {
+	if (ignore(type, state)) return timer.instance;
+	setState(type, state);
+	if (type === WORK_STOP) return stop(timer, state, options);
+	if (type === WORK_PAUSE || type === WORK_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);
+	state.frame = requestAnimationFrame(runner);
+	return timer.instance;
+}
+
+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;
+	}
+	constructor(type, state, options, start) {
+		this.options = options;
+		this.$timer = type;
+		this.state = {
+			...state,
+			active: false,
+			destroyed: false,
+			elapsed: 0,
+			frame: void 0,
+			index: 0,
+			paused: false,
+			total: 0
+		};
+		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;
+		this.options.onError = noop;
+		this.state.callback = noop;
+		if (!globalThis._oscarpalmer_timer_debug) this.state.trace = void 0;
+		stop({
+			instance: this,
+			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);
+	}
+	#work(type) {
+		return work(type, {
+			instance: this,
+			type: this.$timer
+		}, 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),
+		trace: new TimerTrace().stack
+	}, {
+		onAfter: getCallback(options?.onAfter),
+		onError: getCallback(options?.onTimeout),
+		count: getValidNumber(options?.count),
+		interval: getValidNumber(options?.interval, MILLISECONDS),
+		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),
+		trace: new TimerTrace().stack
+	}, {
+		onAfter: void 0,
+		onError: void 0,
+		count: -1,
+		interval: getValidNumber(time, MILLISECONDS),
+		timeout: 0
+	}, true);
+}
+
+var When = class {
+	$timer = TYPE_WHEN;
+	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) {
+		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, MILLISECONDS),
+			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
+	* @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);
+		if (state.started) throw new Error(MESSAGE_STARTED);
+		state.started = true;
+		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);
+}
+
+export { delay, isRepeated, isTimer, isWaited, isWhen, repeat, wait, when };

package/dist/wait.js

@@ -1,4 +1,4 @@
-import { TYPE_WAIT, milliseconds } from "./constants.js";
+import { MILLISECONDS, TYPE_WAIT } from "./constants.js";
 import { getCallback, getValidNumber } from "./get.js";
 import "./global.js";
 import { TimerTrace } from "./models.js";
@@ -11,7 +11,7 @@ function wait(callback, time) {
 		onAfter: void 0,
 		onError: void 0,
 		count: -1,
-		interval: getValidNumber(time, milliseconds),
+		interval: getValidNumber(time, MILLISECONDS),
 		timeout: 0
 	}, true);
 }