@cadenza.io/core 3.9.2 → 3.10.0

package/dist/index.d.mts

@@ -1,6 +1,10 @@
 type AnyObject = {
     [key: string | number]: any;
 };
+interface ThrottleHandle {
+    /** Stop the repeating emission */
+    clear(): void;
+}
 
 declare class GraphContext {
     readonly id: string;
@@ -708,6 +712,18 @@ declare class SignalBroker {
      * @edge Removes all instances if duplicate; deletes if empty.
      */
     unsubscribe(signal: string, routineOrTask: Task | GraphRoutine): void;
+    schedule(signal: string, context: AnyObject, timeoutMs?: number, exactDateTime?: Date): AbortController;
+    /**
+     * Emits `signal` repeatedly with a fixed interval.
+     *
+     * @param signal
+     * @param context
+     * @param intervalMs
+     * @param leading  If true, emits immediately (unless a startDateTime is given and we are before it).
+     * @param startDateTime  Optional absolute Date when the *first* emission after `leading` should occur.
+     * @returns a handle with `clear()` to stop the loop.
+     */
+    throttle(signal: string, context: AnyObject, intervalMs?: number, leading?: boolean, startDateTime?: Date): ThrottleHandle;
     /**
      * Emits a signal and bubbles to matching wildcards/parents (e.g., 'a.b.action' triggers 'a.b.action', 'a.b.*', 'a.*').
      * @param signal The signal name.

package/dist/index.d.ts

@@ -1,6 +1,10 @@
 type AnyObject = {
     [key: string | number]: any;
 };
+interface ThrottleHandle {
+    /** Stop the repeating emission */
+    clear(): void;
+}
 
 declare class GraphContext {
     readonly id: string;
@@ -708,6 +712,18 @@ declare class SignalBroker {
      * @edge Removes all instances if duplicate; deletes if empty.
      */
     unsubscribe(signal: string, routineOrTask: Task | GraphRoutine): void;
+    schedule(signal: string, context: AnyObject, timeoutMs?: number, exactDateTime?: Date): AbortController;
+    /**
+     * Emits `signal` repeatedly with a fixed interval.
+     *
+     * @param signal
+     * @param context
+     * @param intervalMs
+     * @param leading  If true, emits immediately (unless a startDateTime is given and we are before it).
+     * @param startDateTime  Optional absolute Date when the *first* emission after `leading` should occur.
+     * @returns a handle with `clear()` to stop the loop.
+     */
+    throttle(signal: string, context: AnyObject, intervalMs?: number, leading?: boolean, startDateTime?: Date): ThrottleHandle;
     /**
      * Emits a signal and bubbles to matching wildcards/parents (e.g., 'a.b.action' triggers 'a.b.action', 'a.b.*', 'a.*').
      * @param signal The signal name.

package/dist/index.js

@@ -196,6 +196,67 @@ var SignalBroker = class _SignalBroker {
       }
     }
   }
+  schedule(signal, context, timeoutMs = 6e4, exactDateTime) {
+    let delay = timeoutMs;
+    if (exactDateTime != null) {
+      delay = exactDateTime.getTime() - Date.now();
+    }
+    delay = Math.max(0, timeoutMs);
+    const controller = new AbortController();
+    const { signal: signalController } = controller;
+    const tick = () => this.emit(signal, context);
+    const timerId = setTimeout(() => {
+      if (!signalController.aborted) tick();
+    }, delay);
+    signalController.addEventListener("abort", () => clearTimeout(timerId));
+    return controller;
+  }
+  /**
+   * Emits `signal` repeatedly with a fixed interval.
+   *
+   * @param signal
+   * @param context
+   * @param intervalMs
+   * @param leading  If true, emits immediately (unless a startDateTime is given and we are before it).
+   * @param startDateTime  Optional absolute Date when the *first* emission after `leading` should occur.
+   * @returns a handle with `clear()` to stop the loop.
+   */
+  throttle(signal, context, intervalMs = 6e4, leading = false, startDateTime) {
+    if (intervalMs <= 0) {
+      throw new Error("intervalMs must be a positive number");
+    }
+    const emit = () => this.emit(signal, context);
+    if (leading) {
+      const now = Date.now();
+      const start = startDateTime?.getTime();
+      if (!start || start <= now) {
+        emit();
+      }
+    }
+    let firstDelay = intervalMs;
+    if (startDateTime) {
+      let slot = startDateTime.getTime();
+      const now = Date.now();
+      while (slot < now) {
+        slot += intervalMs;
+      }
+      firstDelay = slot - now;
+    }
+    let timer = null;
+    let stopped = false;
+    const scheduleNext = () => {
+      if (stopped) return;
+      emit();
+      timer = setTimeout(scheduleNext, intervalMs);
+    };
+    timer = setTimeout(scheduleNext, firstDelay);
+    return {
+      clear() {
+        stopped = true;
+        if (timer !== null) clearTimeout(timer);
+      }
+    };
+  }
   /**
    * Emits a signal and bubbles to matching wildcards/parents (e.g., 'a.b.action' triggers 'a.b.action', 'a.b.*', 'a.*').
    * @param signal The signal name.