@oscarpalmer/timer 0.25.0 → 0.27.0

package/dist/timer.iife.js

@@ -0,0 +1,429 @@
+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: getValueOrDefault(options.count, isRepeated ? Number.POSITIVE_INFINITY : 1),
+          errorCallback: options.errorCallback,
+          interval: getValueOrDefault(options.interval, milliseconds, milliseconds),
+          timeout: getValueOrDefault(options.timeout, isRepeated ? Number.POSITIVE_INFINITY : 30_000),
+      };
+  }
+  function getValueOrDefault(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' ? +(state.elapsed ?? 0) : 0;
+      let index = type === 'continue' ? +(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) => {
+          const delayed = wait(() => {
+              delayed.destroy();
+              (resolve ?? noop)();
+          }, {
+              timeout,
+              errorCallback: () => {
+                  delayed.destroy();
+                  (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/dist/timer.js

@@ -1,145 +1,12 @@
-// src/constants.ts
-var activeTimers = new Set;
-var beginTypes = new Set(["continue", "start"]);
-var endTypes = new Set(["pause", "stop"]);
-var endOrRestartTypes = new Set([
-  "pause",
-  "restart",
-  "stop"
-]);
-var hiddenTimers = new Set;
-var milliseconds = 1000 / 60;
-
-// src/functions.ts
-function getOptions(options, isRepeated) {
-  return {
-    afterCallback: options.afterCallback,
-    count: getValueOrDefault(options.count, isRepeated ? Number.POSITIVE_INFINITY : 1),
-    errorCallback: options.errorCallback,
-    interval: getValueOrDefault(options.interval, milliseconds, milliseconds),
-    timeout: getValueOrDefault(options.timeout, isRepeated ? Number.POSITIVE_INFINITY : 30000)
-  };
-}
-function getValueOrDefault(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" ? +(state.elapsed ?? 0) : 0;
-  let index = type === "continue" ? +(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;
-}
-
-// src/models.ts
-class TimerTrace extends Error {
-  constructor() {
-    super();
-    this.name = "TimerTrace";
-  }
-}
-
-// src/timer.ts
-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
-  }, options);
-  if (start) {
-    instance.start();
-  }
-  return instance;
-}
-function wait(callback, options) {
-  return timer("wait", callback, options == null || typeof options === "number" ? {
-    interval: options
-  } : options, true);
-}
-
+import { milliseconds } from "./constants.js";
+import { work, getOptions } from "./functions.js";
+import { TimerTrace } from "./models.js";
 class BasicTimer {
   constructor(type, state) {
     this.$timer = type;
     this.state = state;
   }
 }
-
 class Timer extends BasicTimer {
   get active() {
     return this.state.active;
@@ -151,42 +18,94 @@ class Timer extends BasicTimer {
     return this.state.paused;
   }
   get trace() {
-    return globalThis._oscarpalmer_timer_debug ? this.state.trace : undefined;
+    return globalThis._oscarpalmer_timer_debug ? this.state.trace : void 0;
   }
   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;
+      this.options.afterCallback = void 0;
+      this.options.errorCallback = void 0;
+      this.state.callback = void 0;
+      this.state.trace = void 0;
     }
   }
+  /**
+   * 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);
   }
 }
+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
+  );
+}
 export {
-  wait,
-  timer,
-  repeat,
+  BasicTimer,
   Timer,
-  BasicTimer
+  repeat,
+  timer,
+  wait
 };