timer: add ETimer.IDLE + support passing native arguments in the tail of Timer callback

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

Author: zendive

src/api/time.ts

@@ -90,6 +90,7 @@ export type TTaskPriority =
 export enum ETimer {
   TIMEOUT,
   ANIMATION,
+  IDLE,
   TASK,
 }
 type TTimerMeasurable = {
@@ -103,6 +104,10 @@ type TTimerTimeout = TTimerMeasurable & {
 type TTimerAnimation = TTimerMeasurable & {
   type: ETimer.ANIMATION;
 };
+type TTimerIdle = TTimerMeasurable & {
+  type: ETimer.IDLE;
+  delay: number;
+};
 type TTimerTask = TTimerMeasurable & {
   type: ETimer.TASK;
   delay: number;
@@ -111,6 +116,7 @@ type TTimerTask = TTimerMeasurable & {
 type TTimerOptions =
   | TTimerTimeout
   | TTimerAnimation
+  | TTimerIdle
   | TTimerTask;
 
 /**
@@ -133,6 +139,7 @@ export class Timer {
 
     if (
       this.#options.type === ETimer.TIMEOUT ||
+      this.#options.type === ETimer.IDLE ||
       this.#options.type === ETimer.TASK
     ) {
       this.delay = this.#options.delay;
@@ -158,10 +165,15 @@ export class Timer {
     } else if (
       this.#options.type === ETimer.ANIMATION
     ) {
-      this.#handler = requestAnimationFrame(() => {
+      this.#handler = requestAnimationFrame((...argsAF) => {
         this.#handler = 0;
-        this.trigger(...args);
+        this.trigger(...[...args, ...argsAF]);
       });
+    } else if (this.#options.type === ETimer.IDLE) {
+      this.#handler = requestIdleCallback((...argsIC) => {
+        this.#handler = 0;
+        this.trigger(...[...args, ...argsIC]);
+      }, { timeout: this.delay });
     } else if (this.#options.type === ETimer.TASK) {
       this.#abortController = new AbortController();
       nativePostTask(() => {
@@ -196,6 +208,9 @@ export class Timer {
     } else if (this.#options.type === ETimer.ANIMATION) {
       this.#handler && cancelAnimationFrame(this.#handler);
       this.#handler = 0;
+    } else if (this.#options.type === ETimer.IDLE) {
+      this.#handler && cancelIdleCallback(this.#handler);
+      this.#handler = 0;
     } else if (this.#options.type === ETimer.TASK) {
       this.#abortController && this.#abortController.abort();
       this.#abortController = null;

tests/browserPolyfill.ts

@@ -17,7 +17,7 @@ Object.assign(globalThis, {
   ) {
     return setTimeout(() => {
       callback(performance.now());
-    }, 1e3 / 60);
+    }, 0);
   },
 
   cancelAnimationFrame: function cancelAnimationFrameDumbStub(id: number) {

tests/time_test.ts

@@ -112,25 +112,57 @@ describe('Timer - animation + measurable', () => {
   test('start/stop', async () => {
     let count = 0;
     const TIMESPAN = 100;
+    let timerArg = 0;
+    const timerArgExpected = 100;
+    let hasAnimationArgs = false;
     const animation = new Timer({
       type: ETimer.ANIMATION,
       measurable: true,
-    }, () => {
+    }, (_timerArg: number, time: DOMHighResTimeStamp) => {
       count++;
-      animation.start();
+      timerArg = _timerArg;
+      hasAnimationArgs = !!time && typeof time === 'number';
     });
 
     expect(animation.isPending()).toBe(false);
-    animation.start();
+    animation.start(timerArgExpected);
     expect(animation.isPending()).toBe(true);
 
     await wait(TIMESPAN);
 
-    animation.stop();
+    expect(hasAnimationArgs).toBe(true);
+    expect(timerArg).toBe(timerArgExpected);
     expect(animation.isPending()).toBe(false);
-    expect(animation.callbackSelfTime).toBeLessThan(0.5);
-    expect(count).toBeGreaterThan(1);
-    expect(count).toBeLessThan(TIMESPAN / (1e3 / 60));
+    expect(animation.callbackSelfTime > 0).toBe(true);
+    expect(count).toBe(1);
+  });
+});
+
+describe('Timer - idle', () => {
+  test('start/stop', async () => {
+    let counter = 0;
+    let timerArg = 0;
+    const timerArgExpected = 100;
+    let hasIdleArgs = false;
+    const task = new Timer(
+      { type: ETimer.IDLE, delay: DELAY },
+      (_timerArg: number, deadline: IdleDeadline) => {
+        counter++;
+        timerArg = _timerArg;
+        hasIdleArgs = !!deadline && typeof deadline.didTimeout == 'boolean';
+        task.start();
+      },
+    );
+
+    task.start(timerArgExpected);
+    expect(task.isPending()).toBe(true);
+    await wait(DELAY + DELAY / 2);
+    task.stop();
+
+    expect(timerArg).toBe(timerArgExpected);
+    expect(hasIdleArgs).toBe(true);
+    expect(task.isPending()).toBe(false);
+    expect(counter).toBe(1);
   });
 });