@oscarpalmer/timer 0.41.4 → 0.43.0

package/README.md

@@ -64,7 +64,7 @@ function callback(index) {
 	// 'index' is the current step
 	// starts at 0, goes up to a maximum of count - 1
 	// for this example: 0 → 9
-};
+}
 ```
 
 When you create a repeated timer, you can also provide a callback to run when the timer stops, as below:

package/dist/constants.d.mts

@@ -0,0 +1,35 @@
+import { Timer } from "./timer.mjs";
+import { TimerType, WorkHandlerType } from "./models.mjs";
+
+//#region src/constants.d.ts
+/**
+ * Buffer value to use when evaluating if a specific time is within a certain range
+ */
+declare const BUFFER_INTERVAL = 5;
+declare const DEFAULT_TIMEOUT = 30000;
+/**
+ * Message to show when a when-timer is destroyed
+ */
+declare const MESSAGE_DESTROYED = "Timer has already been destroyed";
+/**
+ * Message to show when a when-timer is started
+ */
+declare const MESSAGE_STARTED = "Timer has already been started";
+/**
+ * A set of all active timers
+ */
+declare const TIMERS_ACTIVE: Set<Timer>;
+/**
+ * A set of timers that were paused due to the document being hidden
+ */
+declare const TIMERS_HIDDEN: Set<Timer>;
+declare const TYPE_REPEAT: TimerType;
+declare const TYPE_WAIT: TimerType;
+declare const TYPE_WHEN: TimerType;
+declare const WORK_CONTINUE: WorkHandlerType;
+declare const WORK_PAUSE: WorkHandlerType;
+declare const WORK_RESTART: WorkHandlerType;
+declare const WORK_START: WorkHandlerType;
+declare const WORK_STOP: WorkHandlerType;
+//#endregion
+export { BUFFER_INTERVAL, DEFAULT_TIMEOUT, MESSAGE_DESTROYED, MESSAGE_STARTED, TIMERS_ACTIVE, TIMERS_HIDDEN, TYPE_REPEAT, TYPE_WAIT, TYPE_WHEN, WORK_CONTINUE, WORK_PAUSE, WORK_RESTART, WORK_START, WORK_STOP };

package/dist/{constants.js → constants.mjs}

@@ -1,3 +1,4 @@
+//#region src/constants.ts
 /**
 * Buffer value to use when evaluating if a specific time is within a certain range
 */
@@ -27,4 +28,5 @@ const WORK_PAUSE = "pause";
 const WORK_RESTART = "restart";
 const WORK_START = "start";
 const WORK_STOP = "stop";
+//#endregion
 export { BUFFER_INTERVAL, DEFAULT_TIMEOUT, MESSAGE_DESTROYED, MESSAGE_STARTED, TIMERS_ACTIVE, TIMERS_HIDDEN, TYPE_REPEAT, TYPE_WAIT, TYPE_WHEN, WORK_CONTINUE, WORK_PAUSE, WORK_RESTART, WORK_START, WORK_STOP };

package/dist/delay.d.mts

@@ -0,0 +1,3 @@
+import { delay } from "@oscarpalmer/atoms/promise/delay";
+import { PromiseOptions } from "@oscarpalmer/atoms/promise/models";
+export { type PromiseOptions, delay };

package/dist/delay.mjs

@@ -0,0 +1,2 @@
+import { delay } from "@oscarpalmer/atoms/promise/delay";
+export { delay };

package/dist/get.d.mts

@@ -0,0 +1,8 @@
+import { GenericCallback } from "@oscarpalmer/atoms/models";
+
+//#region src/get.d.ts
+declare function getCallback(value: unknown): GenericCallback;
+declare function getValidTimeout(value: unknown): number;
+declare function getValidNumber(value: unknown, defaultValue?: number): number;
+//#endregion
+export { getCallback, getValidNumber, getValidTimeout };

package/dist/{get.js → get.mjs}

@@ -1,5 +1,6 @@
-import { DEFAULT_TIMEOUT } from "./constants.js";
+import { DEFAULT_TIMEOUT } from "./constants.mjs";
 import { noop } from "@oscarpalmer/atoms/function";
+//#region src/get.ts
 function getCallback(value) {
 	return typeof value === "function" ? value : noop;
 }
@@ -10,4 +11,5 @@ function getValidNumber(value, defaultValue) {
 	const actualDefault = defaultValue ?? 0;
 	return typeof value === "number" && value > actualDefault ? value : actualDefault;
 }
+//#endregion
 export { getCallback, getValidNumber, getValidTimeout };

package/dist/global.d.mts

@@ -0,0 +1,7 @@
+import { Timer } from "./timer.mjs";
+
+//#region src/global.d.ts
+declare global {
+  var _oscarpalmer_timer_debug: boolean | undefined;
+  var _oscarpalmer_timers: Timer[] | undefined;
+}

package/dist/{global.js → global.mjs}

@@ -1,4 +1,5 @@
-import { TIMERS_ACTIVE, TIMERS_HIDDEN, WORK_CONTINUE, WORK_PAUSE } from "./constants.js";
+import { TIMERS_ACTIVE, TIMERS_HIDDEN, WORK_CONTINUE, WORK_PAUSE } from "./constants.mjs";
+//#region src/global.ts
 if (globalThis._oscarpalmer_timers == null) Object.defineProperty(globalThis, "_oscarpalmer_timers", { get() {
 	return globalThis._oscarpalmer_timer_debug ? [...TIMERS_ACTIVE] : [];
 } });
@@ -13,3 +14,5 @@ document.addEventListener("visibilitychange", () => {
 	}
 	from.clear();
 });
+//#endregion
+export {};

package/dist/index.d.mts

@@ -0,0 +1,249 @@
+//#region src/models.d.ts
+/**
+ * Options for a repeating timer
+ */
+type RepeatOptions = {
+  /**
+   * Callback to be called when the timer has stopped, either manually or by completing its work
+   */
+  onAfter: (finished: boolean) => void;
+  /**
+   * Callback to be called after the timer has timed out
+   */
+  onTimeout: () => void;
+  /**
+   * How many times the timer should repeat
+   */
+  count: number;
+  /**
+   * The interval between each repeat
+   */
+  interval: number;
+  /**
+   * The timeout for the timer _(any value above `0` will enable the timeout)_
+   */
+  timeout: number;
+};
+type TimerOptions = {
+  onAfter: ((finished: boolean) => void) | undefined;
+  onError: (() => void) | undefined;
+  count: number;
+  interval: number;
+  timeout: number;
+};
+type TimerState = {
+  active: boolean;
+  callback: () => void;
+  destroyed: boolean;
+  elapsed: number;
+  frame: number | undefined;
+  index: number;
+  paused: boolean;
+  total: number;
+  trace: string | undefined;
+};
+type TimerType = 'repeat' | 'wait' | 'when';
+/**
+ * Options for a conditional timer
+ */
+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 _(any value above `0` will enable the timeout)_
+   */
+  timeout: number;
+};
+//#endregion
+//#region src/timer.d.ts
+declare class Timer {
+  #private;
+  protected readonly options: TimerOptions;
+  private readonly $timer;
+  protected readonly state: TimerState;
+  /**
+   * Is the timer active?
+   */
+  get active(): boolean;
+  /**
+   * Is the timer destroyed?
+   */
+  get destroyed(): boolean;
+  /**
+   * Is the timer paused?
+   */
+  get paused(): boolean;
+  /**
+   * Get the timer's origin _(if debugging is enabled)_
+   */
+  get trace(): string | undefined;
+  constructor(type: TimerType, state: Pick<TimerState, 'callback' | 'trace'>, options: TimerOptions, start: boolean);
+  /**
+   * Continue running the timer _(if it's paused)_
+   */
+  continue(): Timer;
+  /**
+   * Destroy the timer
+   */
+  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;
+}
+//#endregion
+//#region src/global.d.ts
+declare global {
+  var _oscarpalmer_timer_debug: boolean | undefined;
+  var _oscarpalmer_timers: Timer[] | undefined;
+}
+//#endregion
+//#region node_modules/@oscarpalmer/atoms/dist/promise/models.d.mts
+/**
+ * Options for a _Promise_-handling function
+ */
+type PromiseOptions = {
+  /**
+   * AbortSignal for aborting the _Promise_; when aborted, the _Promise_ will reject with the reason of the signal
+   */
+  signal?: AbortSignal;
+  /**
+   * How long to wait for _(in milliseconds; defaults to `0`)_
+   */
+  time?: number;
+};
+//#endregion
+//#region node_modules/@oscarpalmer/atoms/dist/promise/delay.d.mts
+//#region src/promise/delay.d.ts
+/**
+ * Create a delayed promise that resolves after a certain amount of time, or rejects if aborted
+ *
+ * @param options Options for the delay
+ * @returns Delayed promise
+ */
+declare function delay(options?: PromiseOptions): Promise<void>;
+/**
+ * Create a delayed promise that resolves after a certain amount of time
+ *
+ * @param time How long to wait for _(in milliseconds; defaults to `0`)_
+ * @returns Delayed promise
+ */
+declare function delay(time?: number): Promise<void>; //#endregion
+//#endregion
+//#region src/when.d.ts
+declare class When {
+  private readonly $timer;
+  private readonly state;
+  /**
+   * Is the timer active?
+   */
+  get active(): boolean;
+  /**
+   * Is the timer destroyed?
+   */
+  get destroyed(): boolean;
+  /**
+   * Is the timer paused?
+   */
+  get paused(): boolean;
+  /**
+   * Get the timer's origin _(if debugging is enabled)_
+   */
+  get trace(): string | undefined;
+  constructor(condition: () => boolean, options?: Partial<WhenOptions>);
+  /**
+   * Continues the timer _(if it was paused)_
+   */
+  continue(): When;
+  /**
+   * Destroys the timer _(and stops it,if it was running)_
+   */
+  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;
+}
+/**
+ * Create a conditional timer
+ * @param condition Condition to check
+ * @param options Timer options
+ * @returns Timer instance
+ */
+declare function when(condition: () => boolean, options?: Partial<WhenOptions>): When;
+//#endregion
+//#region src/is.d.ts
+/**
+ * Is the value a repeating timer?
+ * @param value Value to check
+ * @returns `true` if the value is a repeating timer
+ */
+declare function isRepeated(value: unknown): value is Timer;
+/**
+ * Is the value a timer?
+ * @param value Value to check
+ * @returns `true` if the value is a timer
+ */
+declare function isTimer(value: unknown): value is Timer;
+/**
+ * Is the value a waiting timer?
+ * @param value Value to check
+ * @returns `true` if the value is a waiting timer
+ */
+declare function isWaited(value: unknown): value is Timer;
+/**
+ * Is the value a conditional timer?
+ * @param value Value to check
+ * @returns `true` if the value is a conditional timer
+ */
+declare function isWhen(value: unknown): value is When;
+//#endregion
+//#region src/repeat.d.ts
+/**
+ * Create a repeating timer
+ *
+ * @param callback Callback to run on each interval
+ * @param options Timer options
+ * @returns Timer instance
+ */
+declare function repeat(callback: (index: number) => void, options?: Partial<RepeatOptions>): Timer;
+//#endregion
+//#region src/wait.d.ts
+/**
+ * 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)_
+ */
+declare function wait(callback: () => void, time?: number): Timer;
+//#endregion
+export { type PromiseOptions, type RepeatOptions, type Timer, type When, delay, isRepeated, isTimer, isWaited, isWhen, repeat, wait, when };

package/dist/{timer.full.js → index.mjs}

@@ -1,7 +1,4 @@
-/**
-* Buffer value to use when evaluating if a specific time is within a certain range
-*/
-const BUFFER_INTERVAL = 5;
+//#region src/constants.ts
 const DEFAULT_TIMEOUT = 3e4;
 /**
 * Message to show when a when-timer is destroyed
@@ -27,6 +24,8 @@ const WORK_PAUSE = "pause";
 const WORK_RESTART = "restart";
 const WORK_START = "start";
 const WORK_STOP = "stop";
+//#endregion
+//#region src/global.ts
 if (globalThis._oscarpalmer_timers == null) Object.defineProperty(globalThis, "_oscarpalmer_timers", { get() {
 	return globalThis._oscarpalmer_timer_debug ? [...TIMERS_ACTIVE] : [];
 } });
@@ -41,56 +40,74 @@ document.addEventListener("visibilitychange", () => {
 	}
 	from.clear();
 });
-const PROMISE_ABORT_OPTIONS = { once: true };
-const PROMISE_EVENT_NAME = "abort";
-function getNumberOrDefault(value) {
-	return typeof value === "number" && value > 0 ? value : 0;
-}
-function getPromiseOptions(input) {
-	if (typeof input === "number") return { time: getNumberOrDefault(input) };
-	if (input instanceof AbortSignal) return {
-		signal: input,
-		time: 0
-	};
-	const options = typeof input === "object" && input !== null ? input : {};
-	return {
-		signal: options.signal instanceof AbortSignal ? options.signal : void 0,
-		time: getNumberOrDefault(options.time)
-	};
-}
-function settlePromise(aborter, settler, value, signal) {
-	signal?.removeEventListener(PROMISE_EVENT_NAME, aborter);
-	settler(value);
-}
+//#endregion
+//#region node_modules/@oscarpalmer/atoms/dist/internal/function/timer.mjs
 function getInterval(value) {
 	return typeof value === "number" && value > 0 ? value : 0;
 }
 function getTimer(type, callback, time) {
-	const interval = getInterval(time);
-	function run(now) {
+	function run() {
+		const now = performance.now();
 		start ??= now;
 		if (interval === 0 || now - start >= interval - OFFSET) {
-			if (throttle) start = now;
+			start = throttle ? now : void 0;
 			callback(...args);
-		} else frame = requestAnimationFrame(run);
+		} else id = startTimer(run);
 	}
+	const interval = getInterval(time);
 	const throttle = type === TIMER_THROTTLE;
 	let args;
-	let frame;
+	let id;
 	let start;
 	const timer = (...parameters) => {
 		timer.cancel();
 		args = parameters;
-		frame = requestAnimationFrame(run);
+		if (throttle) run();
+		else id = startTimer(run);
 	};
 	timer.cancel = () => {
-		cancelAnimationFrame(frame);
+		clearTimer(id);
 	};
 	return timer;
 }
-var OFFSET = 5;
+const OFFSET = 5;
 const TIMER_THROTTLE = "throttle";
 const TIMER_WAIT = "wait";
+// istanbul ignore next
+const clearTimer = typeof cancelAnimationFrame === "function" ? cancelAnimationFrame : clearTimeout;
+// istanbul ignore next
+const startTimer = typeof requestAnimationFrame === "function" ? requestAnimationFrame : setTimeout;
+//#endregion
+//#region node_modules/@oscarpalmer/atoms/dist/promise/models.mjs
+const PROMISE_ABORT_EVENT = "abort";
+const PROMISE_ABORT_OPTIONS = { once: true };
+//#endregion
+//#region node_modules/@oscarpalmer/atoms/dist/internal/number.mjs
+function getNumberOrDefault(value, defaultValue, minimum) {
+	return typeof value === "number" && !Number.isNaN(value) && value >= (minimum ?? 0) ? Math.floor(value) : defaultValue;
+}
+//#endregion
+//#region node_modules/@oscarpalmer/atoms/dist/promise/helpers.mjs
+function getPromiseOptions(input) {
+	if (typeof input === "number") return { time: getNumberOrDefault(input, 0) };
+	if (input instanceof AbortSignal) return {
+		signal: input,
+		time: 0
+	};
+	const options = typeof input === "object" && input !== null ? input : {};
+	return {
+		signal: options.signal instanceof AbortSignal ? options.signal : void 0,
+		time: getNumberOrDefault(options.time, 0)
+	};
+}
+//#endregion
+//#region node_modules/@oscarpalmer/atoms/dist/promise/misc.mjs
+function settlePromise(aborter, settler, value, signal) {
+	signal?.removeEventListener(PROMISE_ABORT_EVENT, aborter);
+	settler(value);
+}
+//#endregion
+//#region node_modules/@oscarpalmer/atoms/dist/promise/delay.mjs
 function delay(options) {
 	const { signal, time } = getPromiseOptions(options);
 	if (signal?.aborted ?? false) return Promise.reject(signal.reason);
@@ -101,7 +118,7 @@ function delay(options) {
 	const timer = getTimer(TIMER_WAIT, () => {
 		settlePromise(abort, resolver, void 0, signal);
 	}, time);
-	signal?.addEventListener("abort", abort, PROMISE_ABORT_OPTIONS);
+	signal?.addEventListener(PROMISE_ABORT_EVENT, abort, PROMISE_ABORT_OPTIONS);
 	let rejector;
 	let resolver;
 	return new Promise((resolve, reject) => {
@@ -111,6 +128,8 @@ function delay(options) {
 		else timer();
 	});
 }
+//#endregion
+//#region src/is.ts
 function is(names, value) {
 	return names.includes(value?.$timer);
 }
@@ -144,12 +163,16 @@ function isWaited(value) {
 * @returns `true` if the value is a conditional timer
 */
 function isWhen(value) {
-	return is([TYPE_WHEN], value) && typeof value.then === "function";
+	return is(["when"], value) && typeof value.start === "function";
 }
+//#endregion
+//#region node_modules/@oscarpalmer/atoms/dist/internal/function/misc.mjs
 /**
 * A function that does nothing, which can be useful, I guess…
 */
 function noop() {}
+//#endregion
+//#region src/get.ts
 function getCallback(value) {
 	return typeof value === "function" ? value : noop;
 }
@@ -160,25 +183,29 @@ function getValidNumber(value, defaultValue) {
 	const actualDefault = defaultValue ?? 0;
 	return typeof value === "number" && value > actualDefault ? value : actualDefault;
 }
+//#endregion
+//#region src/models.ts
 var TimerTrace = class extends Error {
 	constructor() {
 		super();
 		this.name = "TimerTrace";
 	}
 };
+//#endregion
+//#region src/work.ts
 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();
+	if (timer.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;
+	if (state.paused) return type === "pause" || type === "start";
+	return state.active && type === "start";
 }
 function pause(timer, state) {
 	cancelAnimationFrame(state.frame);
@@ -201,7 +228,7 @@ function run(timer, state, options) {
 			finish(timer, state, options, false);
 			return;
 		}
-		if (options.interval === 0 || state.elapsed >= options.interval - BUFFER_INTERVAL) {
+		if (options.interval === 0 || state.elapsed >= options.interval - 5) {
 			if (options.count > -1) state.callback(state.index);
 			start = now;
 			state.elapsed = 0;
@@ -215,7 +242,7 @@ function run(timer, state, options) {
 	};
 }
 function setState(type, state) {
-	const pausable = type === WORK_CONTINUE || type === WORK_PAUSE;
+	const pausable = type === "continue" || type === "pause";
 	state.elapsed = pausable ? state.elapsed : 0;
 	state.index = pausable ? state.index : 0;
 	state.total = pausable ? state.total : 0;
@@ -232,8 +259,8 @@ function stop(timer, state, options) {
 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) {
+	if (type === "stop") return stop(timer, state, options);
+	if (type === "pause" || type === "restart") {
 		cancelAnimationFrame(state.frame);
 		state.frame = void 0;
 	}
@@ -245,7 +272,10 @@ function work(type, timer, state, options) {
 	state.frame = requestAnimationFrame(runner);
 	return timer.instance;
 }
+//#endregion
+//#region src/timer.ts
 var Timer = class {
+	options;
 	state;
 	/**
 	* Is the timer active?
@@ -337,8 +367,11 @@ var Timer = class {
 		}, this.state, this.options);
 	}
 };
+//#endregion
+//#region src/repeat.ts
 /**
 * Create a repeating timer
+*
 * @param callback Callback to run on each interval
 * @param options Timer options
 * @returns Timer instance
@@ -355,8 +388,11 @@ function repeat(callback, options) {
 		timeout: getValidNumber(options?.timeout)
 	}, true);
 }
+//#endregion
+//#region src/wait.ts
 /**
 * 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)_
 */
@@ -372,6 +408,8 @@ function wait(callback, time) {
 		timeout: 0
 	}, true);
 }
+//#endregion
+//#region src/when.ts
 var When = class {
 	state = {
 		promise: void 0,
@@ -466,17 +504,17 @@ var When = class {
 	}
 	/**
 	* 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) {
+	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 ?? noop, reject ?? noop);
+		return state.promise.then(resolve);
 	}
 	/**
 	* Stops the timer _(if it was running)_
@@ -485,16 +523,6 @@ var When = class {
 		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
@@ -505,4 +533,5 @@ var When = class {
 function when(condition, options) {
 	return new When(condition, options);
 }
+//#endregion
 export { delay, isRepeated, isTimer, isWaited, isWhen, repeat, wait, when };