refactor Timer

+ simpler constructor parameter options
+ support scheduler.postTask

Signed-off-by: 🕷️ <[email protected]>

Author: zendive

src/api-monitor-cs-main.ts

@@ -1,6 +1,6 @@
 import { EMsg, windowListen, windowPost } from './api/communication.ts';
 import { TELEMETRY_FREQUENCY_1PS } from './api/const.ts';
-import { adjustTelemetryDelay, Timer } from './api/time.ts';
+import { adjustTelemetryDelay, ETimer, Timer } from './api/time.ts';
 import {
   applyConfig,
   applySession,
@@ -14,36 +14,42 @@ import diff from './api/diff.ts';
 
 let originalMetrics: TTelemetry | null;
 let currentMetrics: TTelemetry | null;
-const eachSecond = new Timer({ delay: 1e3, repetitive: true }, onEachSecond);
-const tick = new Timer(
-  { delay: TELEMETRY_FREQUENCY_1PS, repetitive: false },
-  function apiMonitorTelemetryTick() {
-    const now = Date.now();
-    currentMetrics = structuredClone(collectMetrics());
+const eachSecond = new Timer(
+  { type: ETimer.TIMEOUT, delay: 1e3 },
+  () => {
+    onEachSecond();
+    eachSecond.start();
+  },
+);
+const tick = new Timer({
+  type: ETimer.TIMEOUT,
+  delay: TELEMETRY_FREQUENCY_1PS,
+}, function apiMonitorTelemetryTick() {
+  const now = Date.now();
+  currentMetrics = structuredClone(collectMetrics());
+
+  if (!originalMetrics) {
+    originalMetrics = currentMetrics;
 
-    if (!originalMetrics) {
-      originalMetrics = currentMetrics;
+    windowPost({
+      msg: EMsg.TELEMETRY,
+      timeOfCollection: now,
+      telemetry: originalMetrics,
+    });
+  } else {
+    const delta = diff.diff(originalMetrics, currentMetrics);
 
+    if (delta) {
       windowPost({
-        msg: EMsg.TELEMETRY,
+        msg: EMsg.TELEMETRY_DELTA,
         timeOfCollection: now,
-        telemetry: originalMetrics,
+        telemetryDelta: delta,
       });
     } else {
-      const delta = diff.diff(originalMetrics, currentMetrics);
-
-      if (delta) {
-        windowPost({
-          msg: EMsg.TELEMETRY_DELTA,
-          timeOfCollection: now,
-          telemetryDelta: delta,
-        });
-      } else {
-        tick.start();
-      }
+      tick.start();
     }
-  },
-);
+  }
+});
 
 windowListen((o) => {
   if (EMsg.TELEMETRY_ACKNOWLEDGED === o.msg) {

src/api/const.ts

@@ -1,5 +1,6 @@
 import type { TWritableBooleanKeys } from './generics.ts';
 
+export function NOOP() {}
 export const ERRORS_IGNORED = [
   'Could not establish connection. Receiving end does not exist.',
   'The message port closed before a response was received.',
@@ -24,6 +25,12 @@ export const requestAnimationFrame = /*@__PURE__*/ globalThis
   .requestAnimationFrame.bind(globalThis);
 export const cancelAnimationFrame = /*@__PURE__*/ globalThis
   .cancelAnimationFrame.bind(globalThis);
+export const nativeYield = /*@__PURE__*/ globalThis.scheduler.yield.bind(
+  globalThis.scheduler,
+);
+export const nativePostTask = /*@__PURE__*/ globalThis.scheduler.postTask.bind(
+  globalThis.scheduler,
+);
 
 export const TAG_DELAY_NOT_FOUND = '';
 export const TAG_BAD_DELAY = (x: unknown) => `${x}`;

src/api/time.ts

@@ -1,6 +1,8 @@
 import {
   cancelAnimationFrame,
   clearTimeout,
+  nativePostTask,
+  NOOP,
   requestAnimationFrame,
   setTimeout,
   TELEMETRY_FREQUENCY_30PS,
@@ -80,81 +82,106 @@ export class Stopper {
   }
 }
 
-interface ITimerOptions {
-  /** a delay of setTimeout or setInterval (default: 0); irrelevant if `animation` is true */
-  delay?: number;
-  /** act as setInterval by repeating setTimeout (default: false) */
-  repetitive?: boolean;
-  /** act as requestAnimationFrame called from another requestAnimationFrame (default: false);
-  if true - `delay` is redundant */
-  animation?: boolean;
+/** @link: https://developer.mozilla.org/en-US/docs/Web/API/Prioritized_Task_Scheduling_API#task_priorities */
+export type TTaskPriority =
+  | 'user-blocking'
+  | 'user-visible' // default
+  | 'background';
+export enum ETimer {
+  TIMEOUT,
+  ANIMATION,
+  TASK,
+}
+type TTimerMeasurable = {
   /** populate `callbackSelfTime` with measured execution time of `callback` (default: false) */
   measurable?: boolean;
-}
+};
+type TTimerTimeout = TTimerMeasurable & {
+  type: ETimer.TIMEOUT;
+  delay: number;
+};
+type TTimerAnimation = TTimerMeasurable & {
+  type: ETimer.ANIMATION;
+};
+type TTimerTask = TTimerMeasurable & {
+  type: ETimer.TASK;
+  delay: number;
+  priority?: TTaskPriority;
+};
+type TTimerOptions =
+  | TTimerTimeout
+  | TTimerAnimation
+  | TTimerTask;
 
 /**
- * A unification of ways to delay a callback to another time in javascript event-loop
- * - `repetitive: false` - will call `setTimeout` with constant `delay`.
- * - `repetitive: true` - will call `setTimeout` but act as `setInterval` with changeable `delay`.
- * - `animation: true` - will call `requestAnimationFrame` in recursive way (means to follow the browser's frame-rate).
- * - `measurable: true` - measure the callback's execution time.
+ * A unification of ways to delay a callback execution
+ * in javascript event-loop
  */
 export class Timer {
   delay: number = 0;
   /** callback's self-time in milliseconds */
   callbackSelfTime: number = -1;
   #handler: number = 0;
+  #abortController: AbortController | null = null;
   readonly #fn: (...args: unknown[]) => void;
   readonly #stopper?: Stopper;
-  readonly #options: ITimerOptions;
-  static readonly DEFAULT_OPTIONS: ITimerOptions = {
-    delay: 0,
-    repetitive: false,
-    animation: false,
-    measurable: false,
-  };
+  readonly #options: TTimerOptions;
 
-  constructor(o: ITimerOptions, fn: (...args: unknown[]) => void) {
-    this.#options = Object.assign({}, Timer.DEFAULT_OPTIONS, o);
+  constructor(o: TTimerOptions, fn: (...args: unknown[]) => void) {
+    this.#options = Object.assign({}, o);
     this.#fn = fn;
-    this.delay = this.#options.delay || 0;
+
+    if (
+      this.#options.type === ETimer.TIMEOUT ||
+      this.#options.type === ETimer.TASK
+    ) {
+      this.delay = this.#options.delay;
+    }
 
     if (this.#options.measurable) {
       this.#stopper = new Stopper();
     }
   }
 
   start(...args: unknown[]) {
-    if (this.#handler) {
+    if (this.isPending()) {
       this.stop();
     }
 
-    if (this.#options.animation) {
-      this.#handler = requestAnimationFrame(() => {
+    if (
+      this.#options.type === ETimer.TIMEOUT
+    ) {
+      this.#handler = setTimeout(() => {
+        this.#handler = 0;
         this.trigger(...args);
+      }, this.delay);
+    } else if (
+      this.#options.type === ETimer.ANIMATION
+    ) {
+      this.#handler = requestAnimationFrame(() => {
         this.#handler = 0;
-
-        if (this.#options.repetitive) {
-          this.start(...args);
-        }
+        this.trigger(...args);
       });
-    } else {
-      this.#handler = setTimeout(() => {
+    } else if (this.#options.type === ETimer.TASK) {
+      this.#abortController = new AbortController();
+      nativePostTask(() => {
+        this.#abortController = null;
         this.trigger(...args);
-        this.#handler = 0;
-
-        if (this.#options.repetitive) {
-          this.start(...args);
-        }
-      }, this.delay);
+      }, {
+        delay: this.delay,
+        signal: this.#abortController.signal,
+        priority: this.#options.priority,
+      }).catch(NOOP);
     }
 
     return this;
   }
 
   trigger(...args: unknown[]) {
     this.#stopper?.start();
+
     this.#fn(...args);
+
     if (this.#stopper) {
       this.callbackSelfTime = this.#stopper.stop().value();
     }
@@ -163,21 +190,30 @@ export class Timer {
   }
 
   stop() {
-    if (this.#handler) {
-      if (this.#options.animation) {
-        cancelAnimationFrame(this.#handler);
-      } else {
-        clearTimeout(this.#handler);
-      }
-
+    if (this.#options.type === ETimer.TIMEOUT) {
+      this.#handler && clearTimeout(this.#handler);
+      this.#handler = 0;
+    } else if (this.#options.type === ETimer.ANIMATION) {
+      this.#handler && cancelAnimationFrame(this.#handler);
       this.#handler = 0;
+    } else if (this.#options.type === ETimer.TASK) {
+      this.#abortController && this.#abortController.abort();
+      this.#abortController = null;
     }
 
     return this;
   }
 
-  /** Timer status: true | false => Pending | unstarted/finished/stopped */
-  isPending() {
+  /**
+   * Timer status:
+   *    true := scheduled, pending execution
+   *    false := unstarted or finished
+   */
+  isPending(): boolean {
+    if (this.#options.type === ETimer.TASK) {
+      return !!this.#abortController;
+    }
+
     return this.#handler !== 0;
   }
 }
@@ -190,20 +226,21 @@ export class Fps {
   /** registered number of calls */
   value = 0;
   #ticks = 0;
-  #interval: Timer;
+  #eachSecond: Timer;
 
   constructor(callback?: (value: number) => void) {
-    this.#interval = new Timer({ delay: 1e3, repetitive: true }, () => {
+    this.#eachSecond = new Timer({ type: ETimer.TIMEOUT, delay: 1e3 }, () => {
       this.value = this.#ticks;
       this.#ticks = 0;
       callback?.(this.value);
+      this.#eachSecond.start();
     });
   }
 
   start() {
     this.#ticks = 0;
     this.value = 0;
-    this.#interval.start();
+    this.#eachSecond.start();
     return this;
   }
 
@@ -213,7 +250,7 @@ export class Fps {
   }
 
   stop() {
-    this.#interval.stop();
+    this.#eachSecond.stop();
     return this;
   }
 }

src/view/ConnectionAlert.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
   import { EMsg, portPost, runtimeListen } from '../api/communication.ts';
-  import { Timer } from '../api/time.ts';
+  import { ETimer, Timer } from '../api/time.ts';
   import Alert from './shared/Alert.svelte';
   import {
     INJECTION_ALERT_TIMEOUT,
@@ -12,16 +12,17 @@
   let tabReloadAlertEl: Alert | null = null;
   let devtoolsReloadAlertEl: Alert | null = null;
   const delayedAlert = new Timer(
-    { delay: INJECTION_ALERT_TIMEOUT },
+    { type: ETimer.TIMEOUT, delay: INJECTION_ALERT_TIMEOUT },
     () => void tabReloadAlertEl?.show(),
   );
   const extensionUpdateSensor = new Timer(
-    { delay: UPDATE_SENSOR_INTERVAL, repetitive: true },
+    { type: ETimer.TIMEOUT, delay: UPDATE_SENSOR_INTERVAL },
     () => {
       whenUpdateDetected(() => {
         devtoolsReloadAlertEl?.show();
         extensionUpdateSensor.stop();
       });
+      extensionUpdateSensor.start();
     },
   );
 

src/view/menu/SummaryBarItem.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
   import type { TPanel } from '../../api/storage/storage.local.ts';
   import Variable from '../shared/Variable.svelte';
-  import { Timer } from '../../api/time.ts';
+  import { ETimer, Timer } from '../../api/time.ts';
   import {
     AFTER_SCROLL_ANIMATION_CLASSNAME,
     SCROLLABLE_CLASSNAME,
@@ -22,7 +22,7 @@
   } = $props();
   let enabled: boolean = $derived.by(() => panel.visible && count > 0);
   const stopAnimate = new Timer(
-    { delay: 512 },
+    { type: ETimer.TIMEOUT, delay: 512 },
     (el: HTMLElement | unknown) => {
       if (el instanceof HTMLElement) {
         el.classList.remove(AFTER_SCROLL_ANIMATION_CLASSNAME);

src/view/panels/shared/CellSelfTimeStats.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
   import { onMount, type Snippet } from 'svelte';
-  import { Timer } from '../../../api/time.ts';
+  import { ETimer, Timer } from '../../../api/time.ts';
   import { Mean } from '../../../api/Mean.ts';
 
   let {
@@ -16,7 +16,7 @@
     mean: time,
     max: time,
   });
-  const eachSecond = new Timer({ delay: 1e3, repetitive: true }, () => {
+  const eachSecond = new Timer({ type: ETimer.TIMEOUT, delay: 1e3 }, () => {
     if (!mean.samples) {
       return;
     }
@@ -26,6 +26,7 @@
     vs.max = mean.max;
 
     mean.reset();
+    eachSecond.start();
   });
 
   $effect(() => void mean.add(time));