@oscarpalmer/timer 0.28.0 → 0.29.0

package/dist/timer.iife.js

@@ -1,431 +0,0 @@
-var Timer = (function (exports) {
-  'use strict';
-
-  function noop() {
-  }
-
-  /**
-   * A set of all active timers
-   */
-  const activeTimers = new Set();
-  /**
-   * A set of types that allow work to begin
-   */
-  const beginTypes = new Set(['continue', 'start']);
-  /**
-   * A set of types that allow work to end
-   */
-  const endTypes = new Set(['pause', 'stop']);
-  /**
-   * A set of types that allow work to end or restart
-   */
-  const endOrRestartTypes = new Set([
-      'pause',
-      'restart',
-      'stop',
-  ]);
-  /**
-   * A set of timers that were paused due to the document being hidden
-   */
-  const hiddenTimers = new Set();
-  /**
-   * Milliseconds in a frame, probably ;-)
-   */
-  const milliseconds = 1_000 / 60;
-
-  if (globalThis._oscarpalmer_timers == null) {
-      Object.defineProperty(globalThis, '_oscarpalmer_timers', {
-          get() {
-              return globalThis._oscarpalmer_timer_debug ? [...activeTimers] : [];
-          },
-      });
-  }
-
-  function getOptions(options, isRepeated) {
-      return {
-          afterCallback: options.afterCallback,
-          count: getNumberOrDefault(options.count, isRepeated ? Number.POSITIVE_INFINITY : 1),
-          errorCallback: options.errorCallback,
-          interval: getNumberOrDefault(options.interval, milliseconds, milliseconds),
-          timeout: getNumberOrDefault(options.timeout, isRepeated ? Number.POSITIVE_INFINITY : 30_000),
-      };
-  }
-  function getNumberOrDefault(value, defaultValue, minimum) {
-      return typeof value === 'number' && value > (minimum ?? 0)
-          ? value
-          : defaultValue;
-  }
-  function work(type, timer, state, options) {
-      if ((state.destroyed && type !== 'stop') ||
-          (beginTypes.has(type) && state.active) ||
-          (endTypes.has(type) && !state.active)) {
-          return timer;
-      }
-      const { count, interval, timeout } = options;
-      const { isRepeated, minimum } = state;
-      if (endOrRestartTypes.has(type)) {
-          const isStop = type === 'stop';
-          activeTimers.delete(timer);
-          cancelAnimationFrame(state.frame);
-          if (isStop) {
-              options.afterCallback?.(false);
-          }
-          state.active = false;
-          state.frame = undefined;
-          state.paused = !isStop;
-          if (isStop) {
-              state.elapsed = undefined;
-              state.index = undefined;
-          }
-          return type === 'restart' ? work('start', timer, state, options) : timer;
-      }
-      state.active = true;
-      state.paused = false;
-      const elapsed = type === 'continue' ? Number(state.elapsed ?? 0) : 0;
-      let index = type === 'continue' ? Number(state.index ?? 0) : 0;
-      state.elapsed = elapsed;
-      state.index = index;
-      const total = (count === Number.POSITIVE_INFINITY
-          ? Number.POSITIVE_INFINITY
-          : (count - index) * (interval > 0 ? interval : milliseconds)) - elapsed;
-      let current;
-      let start;
-      function finish(finished, error) {
-          activeTimers.delete(timer);
-          state.active = false;
-          state.elapsed = undefined;
-          state.frame = undefined;
-          state.index = undefined;
-          if (error) {
-              options.errorCallback?.();
-          }
-          options.afterCallback?.(finished);
-      }
-      function step(timestamp) {
-          if (!state.active) {
-              return;
-          }
-          current ??= timestamp;
-          start ??= timestamp;
-          const time = timestamp - current;
-          state.elapsed = elapsed + (current - start);
-          const finished = time - elapsed >= total;
-          if (timestamp - start >= timeout - elapsed) {
-              finish(finished, !finished);
-              return;
-          }
-          if (finished || time >= minimum) {
-              if (state.active) {
-                  state.callback((isRepeated ? index : undefined));
-              }
-              index += 1;
-              state.index = index;
-              if (!finished && index < count) {
-                  current = null;
-              }
-              else {
-                  finish(true, false);
-                  return;
-              }
-          }
-          state.frame = requestAnimationFrame(step);
-      }
-      activeTimers.add(timer);
-      state.frame = requestAnimationFrame(step);
-      return timer;
-  }
-
-  class TimerTrace extends Error {
-      constructor() {
-          super();
-          this.name = 'TimerTrace';
-      }
-  }
-
-  class BasicTimer {
-      constructor(type, state) {
-          this.$timer = type;
-          this.state = state;
-      }
-  }
-  /**
-   * A timer that can be started, stopped, and restarted as neeeded
-   */
-  class Timer extends BasicTimer {
-      get active() {
-          return this.state.active;
-      }
-      get destroyed() {
-          return this.state.destroyed;
-      }
-      get paused() {
-          return this.state.paused;
-      }
-      get trace() {
-          return globalThis._oscarpalmer_timer_debug ? this.state.trace : undefined;
-      }
-      constructor(type, state, options) {
-          super(type, state);
-          this.options = options;
-      }
-      /**
-       * Continues the timer _(if it was paused)_
-       */
-      continue() {
-          return work('continue', this, this.state, this.options);
-      }
-      /**
-       * Destroys the timer _(after stopping it, if it was running)_
-       */
-      destroy() {
-          if (!this.state.destroyed) {
-              this.state.destroyed = true;
-              this.stop();
-              this.options.afterCallback = undefined;
-              this.options.errorCallback = undefined;
-              this.state.callback = undefined;
-              this.state.trace = undefined;
-          }
-      }
-      /**
-       * Pauses the timer _(if it was running)_
-       */
-      pause() {
-          return work('pause', this, this.state, this.options);
-      }
-      /**
-       * Restarts the timer _(if it was running)_
-       */
-      restart() {
-          return work('restart', this, this.state, this.options);
-      }
-      /**
-       * Starts the timer _(if it was stopped)_
-       */
-      start() {
-          return work('start', this, this.state, this.options);
-      }
-      /**
-       * Stops the timer _(if it was running)_
-       */
-      stop() {
-          return work('stop', this, this.state, this.options);
-      }
-  }
-  /**
-   * 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`
-   */
-  function repeat(callback, options) {
-      return timer('repeat', callback, options ?? {}, true);
-  }
-  function timer(type, callback, partial, start) {
-      const isRepeated = type === 'repeat';
-      const options = getOptions(partial, isRepeated);
-      const instance = new Timer(type, {
-          callback,
-          isRepeated,
-          active: false,
-          destroyed: false,
-          minimum: options.interval - (options.interval % milliseconds) / 2,
-          paused: false,
-          trace: new TimerTrace().stack,
-      }, options);
-      if (start) {
-          instance.start();
-      }
-      return instance;
-  }
-  function wait(callback, options) {
-      return timer('wait', callback, options == null || typeof options === 'number'
-          ? {
-              interval: options,
-          }
-          : options, true);
-  }
-
-  function is(pattern, value) {
-      return pattern.test(value?.$timer);
-  }
-  /**
-   * Is the value a repeating timer?
-   */
-  function isRepeated(value) {
-      return is(/^repeat$/, value);
-  }
-  /**
-   * Is the value a timer?
-   */
-  function isTimer(value) {
-      return is(/^repeat|wait$/, value);
-  }
-  /**
-   * Is the value a waiting timer?
-   */
-  function isWaited(value) {
-      return is(/^wait$/, value);
-  }
-  /**
-   * Is the value a conditional timer?
-   */
-  function isWhen(value) {
-      return is(/^when$/, value) && typeof value.then === 'function';
-  }
-
-  const destroyedMessage = 'Timer has already been destroyed';
-  const startedMessage = 'Timer has already been started';
-  class When extends BasicTimer {
-      get active() {
-          return this.state.timer?.active ?? false;
-      }
-      get destroyed() {
-          return this.state.timer == null;
-      }
-      get paused() {
-          return this.state.timer?.paused ?? false;
-      }
-      get trace() {
-          return this.state.timer?.trace;
-      }
-      constructor(state) {
-          super('when', state);
-      }
-      /**
-       * 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() {
-          this.state.timer?.destroy();
-          this.state.promise = undefined;
-          this.state.resolver = noop;
-          this.state.rejecter = noop;
-          this.state.timer = undefined;
-      }
-      /**
-       * Pauses the timer _(if it was running)_
-       */
-      pause() {
-          this.state.timer?.pause();
-          return this;
-      }
-      /**
-       * Stops the timer _(if it was running)_
-       */
-      stop() {
-          this.state.timer?.stop();
-          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, reject) {
-          if (this.state.timer == null || this.state?.started) {
-              throw new Error(this.state.timer == null ? destroyedMessage : startedMessage);
-          }
-          this.state.started = true;
-          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
-   */
-  function when(condition, options) {
-      let result = false;
-      const state = {
-          started: false,
-          timer: timer('repeat', () => {
-              if (condition()) {
-                  result = true;
-                  state.timer.stop();
-              }
-          }, {
-              afterCallback() {
-                  if (!state.timer.paused) {
-                      if (result) {
-                          state.resolver?.();
-                      }
-                      else {
-                          state.rejecter?.();
-                      }
-                      instance.destroy();
-                  }
-              },
-              errorCallback() {
-                  state.rejecter?.();
-                  instance.destroy();
-              },
-              count: options?.count,
-              interval: options?.interval,
-              timeout: options?.timeout,
-          }, false),
-      };
-      const promise = new Promise((resolve, reject) => {
-          state.resolver = resolve;
-          state.rejecter = reject;
-      });
-      state.promise = promise;
-      const instance = new When(state);
-      return instance;
-  }
-
-  /**
-   * Creates a delayed promise that resolves after a certain amount of time _(or rejects when timed out)_
-   */
-  function delay(time, timeout) {
-      return new Promise((resolve, reject) => {
-          let delayed = wait(() => {
-              delayed?.destroy();
-              delayed = null;
-              (resolve ?? noop)();
-          }, {
-              timeout,
-              errorCallback: () => {
-                  delayed?.destroy();
-                  delayed = null;
-                  (reject ?? noop)();
-              },
-              interval: time,
-          });
-      });
-  }
-  document.addEventListener('visibilitychange', () => {
-      if (document.hidden) {
-          for (const timer of activeTimers) {
-              hiddenTimers.add(timer);
-              timer.pause();
-          }
-      }
-      else {
-          for (const timer of hiddenTimers) {
-              timer.continue();
-          }
-          hiddenTimers.clear();
-      }
-  });
-
-  exports.delay = delay;
-  exports.isRepeated = isRepeated;
-  exports.isTimer = isTimer;
-  exports.isWaited = isWaited;
-  exports.isWhen = isWhen;
-  exports.repeat = repeat;
-  exports.wait = wait;
-  exports.when = when;
-
-  return exports;
-
-})({});

package/src/functions.ts

@@ -1,158 +0,0 @@
-import {
-	activeTimers,
-	beginTypes,
-	endOrRestartTypes,
-	endTypes,
-	milliseconds,
-} from './constants';
-import type {TimerOptions, TimerState, WorkType} from './models';
-import type {Timer} from './timer';
-
-export function getOptions(
-	options: Partial<TimerOptions>,
-	isRepeated: boolean,
-): TimerOptions {
-	return {
-		afterCallback: options.afterCallback,
-		count: getNumberOrDefault(
-			options.count,
-			isRepeated ? Number.POSITIVE_INFINITY : 1,
-		),
-		errorCallback: options.errorCallback,
-		interval: getNumberOrDefault(options.interval, milliseconds, milliseconds),
-		timeout: getNumberOrDefault(
-			options.timeout,
-			isRepeated ? Number.POSITIVE_INFINITY : 30_000,
-		),
-	};
-}
-
-function getNumberOrDefault(
-	value: unknown,
-	defaultValue: number,
-	minimum?: number,
-): number {
-	return typeof value === 'number' && value > (minimum ?? 0)
-		? value
-		: defaultValue;
-}
-
-export function work(
-	type: WorkType,
-	timer: Timer,
-	state: TimerState,
-	options: TimerOptions,
-): Timer {
-	if (
-		(state.destroyed && type !== 'stop') ||
-		(beginTypes.has(type) && state.active) ||
-		(endTypes.has(type) && !state.active)
-	) {
-		return timer;
-	}
-
-	const {count, interval, timeout} = options;
-	const {isRepeated, minimum} = state;
-
-	if (endOrRestartTypes.has(type)) {
-		const isStop = type === 'stop';
-
-		activeTimers.delete(timer);
-
-		cancelAnimationFrame(state.frame as never);
-
-		if (isStop) {
-			options.afterCallback?.(false);
-		}
-
-		state.active = false;
-		state.frame = undefined;
-		state.paused = !isStop;
-
-		if (isStop) {
-			state.elapsed = undefined;
-			state.index = undefined;
-		}
-
-		return type === 'restart' ? work('start', timer, state, options) : timer;
-	}
-
-	state.active = true;
-	state.paused = false;
-
-	const elapsed = type === 'continue' ? Number(state.elapsed ?? 0) : 0;
-
-	let index = type === 'continue' ? Number(state.index ?? 0) : 0;
-
-	state.elapsed = elapsed;
-	state.index = index;
-
-	const total =
-		(count === Number.POSITIVE_INFINITY
-			? Number.POSITIVE_INFINITY
-			: (count - index) * (interval > 0 ? interval : milliseconds)) - elapsed;
-
-	let current: DOMHighResTimeStamp | null;
-	let start: DOMHighResTimeStamp | null;
-
-	function finish(finished: boolean, error: boolean) {
-		activeTimers.delete(timer);
-
-		state.active = false;
-		state.elapsed = undefined;
-		state.frame = undefined;
-		state.index = undefined;
-
-		if (error) {
-			options.errorCallback?.();
-		}
-
-		options.afterCallback?.(finished);
-	}
-
-	function step(timestamp: DOMHighResTimeStamp): void {
-		if (!state.active) {
-			return;
-		}
-
-		current ??= timestamp;
-		start ??= timestamp;
-
-		const time = timestamp - current;
-
-		state.elapsed = elapsed + (current - start);
-
-		const finished = time - elapsed >= total;
-
-		if (timestamp - start >= timeout - elapsed) {
-			finish(finished, !finished);
-
-			return;
-		}
-
-		if (finished || time >= minimum) {
-			if (state.active) {
-				state.callback((isRepeated ? index : undefined) as never);
-			}
-
-			index += 1;
-
-			state.index = index;
-
-			if (!finished && index < count) {
-				current = null;
-			} else {
-				finish(true, false);
-				return;
-			}
-		}
-
-		state.frame = requestAnimationFrame(step);
-	}
-
-	activeTimers.add(timer);
-
-	state.frame = requestAnimationFrame(step);
-
-	return timer;
-}

package/types/functions.d.cts

@@ -1,113 +0,0 @@
-// Generated by dts-bundle-generator v9.5.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 destroyed?
-	 */
-	abstract readonly destroyed: boolean;
-	/**
-	 * Is the timer paused?
-	 */
-	abstract readonly paused: boolean;
-	/**
-	 * Gets the traced location of the timer
-	 */
-	abstract readonly trace: string | undefined;
-}
-declare class Timer extends BasicTimer<TimerState> {
-	private readonly options;
-	get active(): boolean;
-	get destroyed(): boolean;
-	get paused(): boolean;
-	get trace(): string | undefined;
-	constructor(type: "repeat" | "wait", state: TimerState, options: TimerOptions);
-	/**
-	 * Continues the timer _(if it was paused)_
-	 */
-	continue(): Timer;
-	/**
-	 * Destroys the timer _(after stopping it, if it was running)_
-	 */
-	destroy(): void;
-	/**
-	 * Pauses the timer _(if it was running)_
-	 */
-	pause(): Timer;
-	/**
-	 * Restarts the timer _(if it was running)_
-	 */
-	restart(): Timer;
-	/**
-	 * Starts the timer _(if it was stopped)_
-	 */
-	start(): Timer;
-	/**
-	 * Stops the timer _(if it was running)_
-	 */
-	stop(): 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;
-	destroyed: boolean;
-	count?: number;
-	elapsed?: number;
-	frame?: number;
-	index?: number;
-	isRepeated: boolean;
-	minimum: number;
-	paused: boolean;
-	trace?: string;
-};
-export type WorkType = "continue" | "pause" | "restart" | "start" | "stop";
-export declare function getOptions(options: Partial<TimerOptions>, isRepeated: boolean): TimerOptions;
-export declare function work(type: WorkType, timer: Timer, state: TimerState, options: TimerOptions): Timer;
-
-export {};

package/types/functions.d.ts

@@ -1,4 +0,0 @@
-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 work(type: WorkType, timer: Timer, state: TimerState, options: TimerOptions): Timer;