@oscarpalmer/timer 0.19.0 → 0.21.0

package/src/timer.ts

@@ -0,0 +1,186 @@
+import {milliseconds} from './constants';
+import {getOptions, work} from './functions';
+import type {
+	AnyCallback,
+	IndexedCallback,
+	RepeatOptions,
+	TimerOptions,
+	TimerState,
+	WaitOptions,
+} from './models';
+
+export abstract class BasicTimer<State> {
+	protected declare readonly $timer: string;
+	protected declare readonly state: State;
+
+	constructor(type: 'repeat' | 'wait' | 'when', state: State) {
+		this.$timer = type;
+		this.state = state;
+	}
+
+	/**
+	 * Is the timer running?
+	 */
+	abstract readonly active: boolean;
+
+	/**
+	 * Is the timer paused?
+	 */
+	abstract readonly paused: boolean;
+}
+
+/**
+ * A timer that can be started, stopped, and restarted as neeeded
+ */
+export class Timer extends BasicTimer<TimerState> {
+	private declare readonly options: TimerOptions;
+
+	get active() {
+		return this.state.active;
+	}
+
+	get paused() {
+		return this.state.paused;
+	}
+
+	/**
+	 * Gets the traced location of the timer
+	 */
+	get trace() {
+		return globalThis._oscarpalmer_timer_debug ? this.state.trace : undefined;
+	}
+
+	constructor(
+		type: 'repeat' | 'wait',
+		state: TimerState,
+		options: TimerOptions,
+	) {
+		super(type, state);
+
+		this.options = options;
+	}
+
+	/**
+	 * Continues the timer _(if it was paused)_
+	 */
+	continue(): Timer {
+		return work('continue', this, this.state, this.options);
+	}
+
+	/**
+	 * Pauses the timer _(if it was running)_
+	 */
+	pause(): Timer {
+		return work('pause', this, this.state, this.options);
+	}
+
+	/**
+	 * Restarts the timer _(if it was running)_
+	 */
+	restart(): Timer {
+		return work('restart', this, this.state, this.options);
+	}
+
+	/**
+	 * Starts the timer _(if it was stopped)_
+	 */
+	start(): Timer {
+		return work('start', this, this.state, this.options);
+	}
+
+	/**
+	 * Stops the timer _(if it was running)_
+	 */
+	stop(): Timer {
+		return work('stop', this, this.state, this.options);
+	}
+}
+
+class TimerTrace extends Error {
+	constructor() {
+		super();
+
+		this.name = 'TimerTrace';
+	}
+}
+
+/**
+ * Creates a timer which:
+ * - calls a callback after a certain amount of time...
+ * - ... and repeats it a certain amount of times
+ * ---
+ * - `options.count` defaults to `Infinity`
+ * - `options.interval` defaults to `1000/60` _(1 frame)_
+ * - `options.timeout` defaults to `Infinity`
+ */
+export function repeat(
+	callback: IndexedCallback,
+	options?: Partial<RepeatOptions>,
+): Timer {
+	return timer('repeat', callback, options ?? {}, true);
+}
+
+export function timer(
+	type: 'repeat' | 'wait',
+	callback: AnyCallback,
+	partial: Partial<TimerOptions>,
+	start: boolean,
+): Timer {
+	const isRepeated = type === 'repeat';
+	const options = getOptions(partial, isRepeated);
+
+	const instance = new Timer(
+		type,
+		{
+			callback,
+			isRepeated,
+			active: false,
+			minimum: options.interval - (options.interval % milliseconds) / 2,
+			paused: false,
+			trace: new TimerTrace(),
+		},
+		options,
+	);
+
+	if (start) {
+		instance.start();
+	}
+
+	return instance;
+}
+
+/**
+ * Creates a timer which calls a callback after a certain amount of time
+ */
+export function wait(callback: () => void): Timer;
+
+/**
+ * Creates a timer which calls a callback after a certain amount of time
+ */
+export function wait(callback: () => void, time: number): Timer;
+
+/**
+ * Creates a timer which calls a callback after a certain amount of time
+ * - `options.interval` defaults to `1000/60` _(1 frame)_
+ * - `options.timeout` defaults to `30_000` _(30 seconds)_
+ */
+export function wait(
+	callback: () => void,
+	options: Partial<WaitOptions>,
+): Timer;
+
+export function wait(
+	callback: () => void,
+	options?: number | Partial<WaitOptions>,
+): Timer {
+	return timer(
+		'wait',
+		callback,
+		options == null || typeof options === 'number'
+			? {
+					interval: options,
+				}
+			: options,
+		true,
+	);
+}

package/src/when.ts

@@ -0,0 +1,111 @@
+import {noop} from '@oscarpalmer/atoms/function';
+import type {WhenOptions, WhenState} from './models';
+import {BasicTimer, timer} from './timer';
+
+export class When extends BasicTimer<WhenState> {
+	get active() {
+		return this.state.timer.active;
+	}
+
+	get paused() {
+		return this.state.timer.paused;
+	}
+
+	constructor(state: WhenState) {
+		super('when', state);
+	}
+
+	/**
+	 * Continues the timer _(if it was paused)_
+	 */
+	continue(): When {
+		this.state.timer.continue();
+
+		return this;
+	}
+
+	/**
+	 * Pauses the timer _(if it was running)_
+	 */
+	pause(): When {
+		this.state.timer.pause();
+
+		return this;
+	}
+
+	/**
+	 * Stops the timer _(if it was running)_
+	 */
+	stop(): When {
+		if (this.state.timer.active) {
+			this.state.timer.stop();
+
+			this.state.rejecter?.();
+		}
+
+		return this;
+	}
+
+	/**
+	 * Starts the timer and returns a promise that resolves when the condition is met
+	 */
+
+	// biome-ignore lint/suspicious/noThenProperty: returning a promise-like object, so it's ok ;)
+	then(
+		resolve?: (() => void) | null,
+		reject?: (() => void) | null,
+	): Promise<void> {
+		this.state.timer.start();
+
+		return this.state.promise.then(resolve ?? noop, reject ?? noop);
+	}
+}
+
+/**
+ * - Creates a promise that resolves when a condition is met
+ * - If the condition is never met in a timely manner, the promise will reject
+ */
+export function when(
+	condition: () => boolean,
+	options?: Partial<WhenOptions>,
+): When {
+	const repeated = timer(
+		'repeat',
+		() => {
+			if (condition()) {
+				repeated.stop();
+
+				state.resolver?.();
+			}
+		},
+		{
+			afterCallback() {
+				if (!repeated.paused) {
+					if (condition()) {
+						state.resolver?.();
+					} else {
+						state.rejecter?.();
+					}
+				}
+			},
+			errorCallback() {
+				state.rejecter?.();
+			},
+			count: options?.count,
+			interval: options?.interval,
+			timeout: options?.timeout,
+		},
+		false,
+	);
+
+	const state: WhenState = {} as never;
+
+	state.promise = new Promise((resolve, reject) => {
+		state.resolver = resolve;
+		state.rejecter = reject;
+	});
+
+	state.timer = repeated;
+
+	return new When(state);
+}

package/types/constants.d.ts

@@ -0,0 +1,13 @@
+import type { Timer } from './timer';
+/**
+ * A set of all active timers
+ */
+export declare const activeTimers: Set<Timer>;
+/**
+ * A set of timers that were paused due to the document being hidden
+ */
+export declare const hiddenTimers: Set<Timer>;
+/**
+ * Milliseconds in a frame, probably ;-)
+ */
+export declare const milliseconds: number;

package/types/functions.d.ts

@@ -0,0 +1,5 @@
+import type { TimerOptions, TimerState, WorkType } from './models';
+import type { Timer } from './timer';
+export declare function getOptions(options: Partial<TimerOptions>, isRepeated: boolean): TimerOptions;
+export declare function getValueOrDefault(value: unknown, defaultValue: number, minimum?: number): number;
+export declare function work(type: WorkType, timer: Timer, state: TimerState, options: TimerOptions): Timer;

package/types/global.d.ts

@@ -0,0 +1,5 @@
+declare global {
+    var _oscarpalmer_timer_debug: boolean | undefined;
+    var _oscarpalmer_timers: Timer[] | undefined;
+}
+export {};

package/types/index.d.cts

@@ -0,0 +1,184 @@
+// Generated by dts-bundle-generator v9.5.1
+
+/**
+ * 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
+	 */
+	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;
+	count?: number;
+	elapsed?: number;
+	frame?: number;
+	index?: number;
+	isRepeated: boolean;
+	minimum: number;
+	paused: boolean;
+	trace: unknown;
+};
+export type WaitOptions = {} & BaseOptions & OptionsWithError;
+export type WhenOptions = {} & OptionsWithCount;
+export type WhenState = {
+	promise: Promise<void>;
+	rejecter?: () => void;
+	resolver?: () => void;
+	timer: Timer$1;
+};
+declare abstract class BasicTimer<State> {
+	protected readonly $timer: string;
+	protected readonly state: State;
+	constructor(type: "repeat" | "wait" | "when", state: State);
+	/**
+	 * Is the timer running?
+	 */
+	abstract readonly active: boolean;
+	/**
+	 * Is the timer paused?
+	 */
+	abstract readonly paused: boolean;
+}
+/**
+ * A timer that can be started, stopped, and restarted as neeeded
+ */
+declare class Timer$1 extends BasicTimer<TimerState> {
+	private readonly options;
+	get active(): boolean;
+	get paused(): boolean;
+	/**
+	 * Gets the traced location of the timer
+	 */
+	get trace(): unknown;
+	constructor(type: "repeat" | "wait", state: TimerState, options: TimerOptions);
+	/**
+	 * Continues the timer _(if it was paused)_
+	 */
+	continue(): Timer$1;
+	/**
+	 * Pauses the timer _(if it was running)_
+	 */
+	pause(): Timer$1;
+	/**
+	 * Restarts the timer _(if it was running)_
+	 */
+	restart(): Timer$1;
+	/**
+	 * Starts the timer _(if it was stopped)_
+	 */
+	start(): Timer$1;
+	/**
+	 * Stops the timer _(if it was running)_
+	 */
+	stop(): Timer$1;
+}
+/**
+ * Creates a timer which:
+ * - calls a callback after a certain amount of time...
+ * - ... and repeats it a certain amount of times
+ * ---
+ * - `options.count` defaults to `Infinity`
+ * - `options.interval` defaults to `1000/60` _(1 frame)_
+ * - `options.timeout` defaults to `Infinity`
+ */
+export declare function repeat(callback: IndexedCallback, options?: Partial<RepeatOptions>): Timer$1;
+/**
+ * Creates a timer which calls a callback after a certain amount of time
+ */
+export declare function wait(callback: () => void): Timer$1;
+/**
+ * Creates a timer which calls a callback after a certain amount of time
+ */
+export declare function wait(callback: () => void, time: number): Timer$1;
+/**
+ * Creates a timer which calls a callback after a certain amount of time
+ * - `options.interval` defaults to `1000/60` _(1 frame)_
+ * - `options.timeout` defaults to `30_000` _(30 seconds)_
+ */
+export declare function wait(callback: () => void, options: Partial<WaitOptions>): Timer$1;
+export declare class When extends BasicTimer<WhenState> {
+	get active(): boolean;
+	get paused(): boolean;
+	constructor(state: WhenState);
+	/**
+	 * Continues the timer _(if it was paused)_
+	 */
+	continue(): When;
+	/**
+	 * Pauses the timer _(if it was running)_
+	 */
+	pause(): When;
+	/**
+	 * Stops the timer _(if it was running)_
+	 */
+	stop(): When;
+	/**
+	 * Starts the timer and returns a promise that resolves when the condition is met
+	 */
+	then(resolve?: (() => void) | null, reject?: (() => void) | null): Promise<void>;
+}
+/**
+ * - Creates a promise that resolves when a condition is met
+ * - If the condition is never met in a timely manner, the promise will reject
+ */
+export declare function when(condition: () => boolean, options?: Partial<WhenOptions>): When;
+/**
+ * Is the value a repeating timer?
+ */
+export declare function isRepeated(value: unknown): value is Timer$1;
+/**
+ * Is the value a timer?
+ */
+export declare function isTimer(value: unknown): value is Timer$1;
+/**
+ * Is the value a waiting timer?
+ */
+export declare function isWaited(value: unknown): value is Timer$1;
+/**
+ * Is the value a conditional timer?
+ */
+export declare function isWhen(value: unknown): value is When;
+/**
+ * Creates a delayed promise that resolves after a certain amount of time _(or rejects when timed out)_
+ */
+export declare function delay(time: number, timeout?: number): Promise<void>;
+
+export {
+	Timer$1 as Timer,
+};
+
+export {};

package/types/index.d.ts

@@ -1,72 +1,8 @@
+import './global';
 /**
- * @param {boolean} finished Did the timer finish?
+ * Creates a delayed promise that resolves after a certain amount of time _(or rejects when timed out)_
  */
-export type AfterCallback = (finished: boolean) => void;
-
-/**
- * @param {number} index The index of the current iteration
- */
-export type RepeatedCallback = (index: number) => void;
-
-declare class Timed<Type, Callback> {
-	get active(): boolean;
-	get finished(): boolean;
-
-	/**
-	 * @param {Callback} callback
-	 * @param {number} time
-	 * @param {number} count
-	 * @param {AfterCallback=} afterCallback
-	 */
-
-	constructor(
-		callback: () => void | ((index: number) => void),
-		time: number,
-		count: number,
-		afterCallback?: AfterCallback,
-	);
-
-	restart(): Type;
-	start(): Type;
-	stop(): Type;
-}
-
-/**
- * A timer that waits and runs repeatedly
- */
-export declare class Repeated extends Timed<Repeated, RepeatedCallback> {}
-
-/**
- * A timer that waits and runs once
- */
-export declare class Waited extends Timed<Waited, () => void> {
-	/**
-	 * Creates a new waited timer
-	 * @param {() => void} callback
-	 * @param {number} time
-	 */
-	constructor(callback: () => void, time: number);
-}
-
-/**
- * Creates and starts a new repeated timer
- * @param {RepeatedCallback} callback
- * @param {number} time
- * @param {number} count
- * @param {AfterCallback=} afterCallback
- * @return {Repeated}
- */
-export declare function repeat(
-	callback: RepeatedCallback,
-	time: number,
-	count: number,
-	afterCallback?: AfterCallback,
-): Repeated;
-
-/**
- * Creates and starts a new waited timer
- * @param {() => void} callback
- * @param {number} time
- * @return {Waited}
- */
-export declare function wait(callback: () => void, time: number): Waited;
+export declare function delay(time: number, timeout?: number): Promise<void>;
+export { isRepeated, isTimer, isWaited, isWhen } from './is';
+export { repeat, wait, type Timer } from './timer';
+export { when, type When } from './when';

package/types/is.d.ts

@@ -0,0 +1,18 @@
+import type { Timer } from './timer';
+import type { When } from './when';
+/**
+ * Is the value a repeating timer?
+ */
+export declare function isRepeated(value: unknown): value is Timer;
+/**
+ * Is the value a timer?
+ */
+export declare function isTimer(value: unknown): value is Timer;
+/**
+ * Is the value a waiting timer?
+ */
+export declare function isWaited(value: unknown): value is Timer;
+/**
+ * Is the value a conditional timer?
+ */
+export declare function isWhen(value: unknown): value is When;

package/types/models.d.ts

@@ -0,0 +1,62 @@
+import type { Timer } from './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
+     */
+    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;
+    count?: number;
+    elapsed?: number;
+    frame?: number;
+    index?: number;
+    isRepeated: boolean;
+    minimum: number;
+    paused: boolean;
+    trace: unknown;
+};
+export type WaitOptions = {} & BaseOptions & OptionsWithError;
+export type WhenOptions = {} & OptionsWithCount;
+export type WhenState = {
+    promise: Promise<void>;
+    rejecter?: () => void;
+    resolver?: () => void;
+    timer: Timer;
+};
+export type WorkType = 'continue' | 'pause' | 'restart' | 'start' | 'stop';