@mrjacket/ahko 0.5.0 → 1.0.0

package/dist/index.cjs

@@ -150,6 +150,8 @@ var AhkoCancellationError = class extends AhkoError {
 // src/scheduler/debounce-coordinator.ts
 var DebounceCoordinator = class {
   entries = /* @__PURE__ */ new Map();
+  /** Optional callback invoked whenever entries are settled or removed from coordinator */
+  onSettled;
   /**
    * Schedules a task under the debounce strategy.
    *
@@ -236,6 +238,7 @@ var DebounceCoordinator = class {
       return;
     }
     this.entries.delete(key);
+    this.onSettled?.();
     if (entry.options?.signal && entry.abortListener) {
       entry.options.signal.removeEventListener("abort", entry.abortListener);
     }
@@ -259,6 +262,7 @@ var DebounceCoordinator = class {
     }
     clearTimeout(entry.timerId);
     this.entries.delete(key);
+    this.onSettled?.();
     if (entry.options?.signal && entry.abortListener) {
       entry.options.signal.removeEventListener("abort", entry.abortListener);
     }
@@ -278,7 +282,7 @@ var DebounceCoordinator = class {
    * Cancels all pending debounced entries and clears the map.
    */
   clear() {
-    for (const [key, entry] of this.entries) {
+    for (const entry of this.entries.values()) {
       clearTimeout(entry.timerId);
       if (entry.options?.signal && entry.abortListener) {
         entry.options.signal.removeEventListener("abort", entry.abortListener);
@@ -286,6 +290,7 @@ var DebounceCoordinator = class {
       entry.reject(new AhkoCancellationError("Debounced tasks cleared"));
     }
     this.entries.clear();
+    this.onSettled?.();
   }
 };
 
@@ -331,6 +336,8 @@ var IdleScheduler = class {
 // src/scheduler/throttle-coordinator.ts
 var ThrottleCoordinator = class {
   entries = /* @__PURE__ */ new Map();
+  /** Optional callback invoked whenever entries are settled or removed from coordinator */
+  onSettled;
   /**
    * Schedules a task under the throttle strategy.
    *
@@ -416,6 +423,7 @@ var ThrottleCoordinator = class {
       return;
     }
     this.entries.delete(key);
+    this.onSettled?.();
   }
   /**
    * Cancels any pending trailing throttled task for a given key.
@@ -432,6 +440,7 @@ var ThrottleCoordinator = class {
       clearTimeout(entry.windowTimerId);
     }
     this.entries.delete(key);
+    this.onSettled?.();
     if (entry.trailingReject) {
       const cancelError = new AhkoCancellationError(
         typeof reason === "string" ? reason : "Throttled task was cancelled",
@@ -450,7 +459,7 @@ var ThrottleCoordinator = class {
    * Clears all throttled entries and timers.
    */
   clear() {
-    for (const [key, entry] of this.entries) {
+    for (const entry of this.entries.values()) {
       if (entry.windowTimerId !== void 0) {
         clearTimeout(entry.windowTimerId);
       }
@@ -459,6 +468,75 @@ var ThrottleCoordinator = class {
       }
     }
     this.entries.clear();
+    this.onSettled?.();
+  }
+};
+
+// src/events/event-emitter.ts
+var AhkoEventEmitter = class {
+  listeners = /* @__PURE__ */ new Map();
+  /**
+   * Subscribes a listener to a specific Ahko lifecycle event.
+   *
+   * @param event - The event name to subscribe to.
+   * @param handler - The callback function to invoke when the event is emitted.
+   * @returns An unsubscribe function to remove the listener.
+   */
+  on(event, handler) {
+    let set = this.listeners.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.listeners.set(event, set);
+    }
+    set.add(handler);
+    return () => {
+      this.off(event, handler);
+    };
+  }
+  /**
+   * Unsubscribes a listener from a specific Ahko lifecycle event.
+   *
+   * @param event - The event name.
+   * @param handler - The callback function to remove.
+   */
+  off(event, handler) {
+    const set = this.listeners.get(event);
+    if (set) {
+      set.delete(handler);
+      if (set.size === 0) {
+        this.listeners.delete(event);
+      }
+    }
+  }
+  /**
+   * Emits an event with the corresponding typed payload to all subscribed listeners.
+   * Listener invocations are safely isolated in try/catch to protect scheduler integrity.
+   *
+   * @param event - The event name to emit.
+   * @param payload - The event-specific payload data.
+   */
+  emit(event, payload) {
+    const set = this.listeners.get(event);
+    if (!set || set.size === 0) {
+      return;
+    }
+    const handlers = Array.from(set);
+    for (const handler of handlers) {
+      try {
+        const result = handler(payload);
+        if (result && typeof result.catch === "function") {
+          result.catch(() => {
+          });
+        }
+      } catch {
+      }
+    }
+  }
+  /**
+   * Removes all registered event listeners.
+   */
+  clear() {
+    this.listeners.clear();
   }
 };
 
@@ -486,6 +564,10 @@ var TaskQueue = class {
   debounceCoordinator = new DebounceCoordinator();
   /** Coordinator for throttled tasks with leading/trailing coalescing */
   throttleCoordinator = new ThrottleCoordinator();
+  /** Lifecycle event emitter for task and scheduler events */
+  emitter = new AhkoEventEmitter();
+  /** Set of pending resolvers awaiting scheduler idle transition */
+  idleResolvers = /* @__PURE__ */ new Set();
   /** WeakMap associating task runners with their scheduling options */
   runnerOptions = /* @__PURE__ */ new WeakMap();
   /** Cumulative completed tasks counter */
@@ -496,6 +578,10 @@ var TaskQueue = class {
   cancelledTasks = 0;
   /** Cumulative timed out tasks counter */
   timedOutTasks = 0;
+  /** Cumulative count of retry attempts triggered */
+  retriedTasks = 0;
+  /** Cumulative count of tasks dispatched to concurrency slots */
+  totalDispatched = 0;
   /**
    * Creates a new TaskQueue.
    *
@@ -516,6 +602,8 @@ var TaskQueue = class {
     }
     this.concurrency = concurrency;
     this.minIntervalMs = minIntervalMs;
+    this.debounceCoordinator.onSettled = () => this.checkIdle();
+    this.throttleCoordinator.onSettled = () => this.checkIdle();
   }
   /**
    * Enqueues a task runner according to the specified schedule options.
@@ -601,6 +689,11 @@ var TaskQueue = class {
       if (index !== -1) {
         this.queue.splice(index, 1);
         this.cancelledTasks++;
+        this.emitter.emit("task:cancel", {
+          taskId: runner.taskId,
+          reason: "Task cancelled while queued"
+        });
+        this.checkIdle();
       }
     };
     this.queue.push(runner);
@@ -624,6 +717,11 @@ var TaskQueue = class {
           if (index !== -1) {
             this.queue.splice(index, 1);
             this.cancelledTasks++;
+            this.emitter.emit("task:cancel", {
+              taskId: runner.taskId,
+              reason: "Task cancelled while queued"
+            });
+            this.checkIdle();
           }
         };
         this.queue.push(runner);
@@ -636,6 +734,11 @@ var TaskQueue = class {
         clearTimeout(delayedEntry.timerId);
         this.delayedEntries.delete(delayedEntry);
         this.cancelledTasks++;
+        this.emitter.emit("task:cancel", {
+          taskId: runner.taskId,
+          reason: "Task cancelled while waiting in delay"
+        });
+        this.checkIdle();
       }
     };
   }
@@ -655,6 +758,11 @@ var TaskQueue = class {
         if (index !== -1) {
           this.queue.splice(index, 1);
           this.cancelledTasks++;
+          this.emitter.emit("task:cancel", {
+            taskId: runner.taskId,
+            reason: "Task cancelled while queued"
+          });
+          this.checkIdle();
         }
       };
       this.queue.push(runner);
@@ -667,6 +775,11 @@ var TaskQueue = class {
         handle.cancel();
         this.idleEntries.delete(idleEntry);
         this.cancelledTasks++;
+        this.emitter.emit("task:cancel", {
+          taskId: runner.taskId,
+          reason: "Task cancelled while waiting for idle"
+        });
+        this.checkIdle();
       }
     };
   }
@@ -735,36 +848,69 @@ var TaskQueue = class {
    */
   async executeRunner(runner) {
     const options = this.runnerOptions.get(runner);
+    this.totalDispatched++;
+    this.emitter.emit("task:start", {
+      taskId: runner.taskId,
+      attempt: runner.attempt
+    });
     try {
       const result = await runner.run();
       this.completedTasks++;
       this.activeRunners.delete(runner);
       this.runnerOptions.delete(runner);
+      this.emitter.emit("task:complete", {
+        taskId: runner.taskId,
+        attempt: runner.attempt,
+        durationMs: runner.lastDurationMs,
+        result
+      });
       runner.resolve(result);
     } catch (error) {
       if (runner.state === "cancelled" /* CANCELLED */) {
         this.cancelledTasks++;
         this.activeRunners.delete(runner);
         this.runnerOptions.delete(runner);
+        this.emitter.emit("task:cancel", {
+          taskId: runner.taskId,
+          reason: error
+        });
         runner.reject(error);
         return;
       }
       const shouldRetry = await runner.canRetry(error, options?.retry);
       if (shouldRetry) {
+        this.retriedTasks++;
         this.activeRunners.delete(runner);
+        this.emitter.emit("task:fail", {
+          taskId: runner.taskId,
+          attempt: runner.attempt - 1,
+          error,
+          willRetry: true
+        });
         this.scheduleRetry(runner, options);
         return;
       }
       if (runner.state === "timed_out" /* TIMED_OUT */ || error instanceof AhkoTimeoutError) {
         this.timedOutTasks++;
+        this.emitter.emit("task:timeout", {
+          taskId: runner.taskId,
+          timeoutMs: runner.timeoutMs
+        });
       } else {
         this.failedTasks++;
       }
       this.activeRunners.delete(runner);
       this.runnerOptions.delete(runner);
+      this.emitter.emit("task:fail", {
+        taskId: runner.taskId,
+        attempt: runner.attempt,
+        error,
+        willRetry: false
+      });
       runner.reject(error);
     } finally {
       this.pump();
+      this.checkIdle();
     }
   }
   /**
@@ -779,6 +925,11 @@ var TaskQueue = class {
         if (index !== -1) {
           this.queue.splice(index, 1);
           this.cancelledTasks++;
+          this.emitter.emit("task:cancel", {
+            taskId: runner.taskId,
+            reason: "Task cancelled while queued"
+          });
+          this.checkIdle();
         }
       };
       this.queue.push(runner);
@@ -797,6 +948,11 @@ var TaskQueue = class {
           if (index !== -1) {
             this.queue.splice(index, 1);
             this.cancelledTasks++;
+            this.emitter.emit("task:cancel", {
+              taskId: runner.taskId,
+              reason: "Task cancelled while queued"
+            });
+            this.checkIdle();
           }
         };
         this.queue.push(runner);
@@ -809,9 +965,91 @@ var TaskQueue = class {
         clearTimeout(retryEntry.timerId);
         this.retryEntries.delete(retryEntry);
         this.cancelledTasks++;
+        this.emitter.emit("task:cancel", {
+          taskId: runner.taskId,
+          reason: "Task cancelled during retry backoff"
+        });
+        this.checkIdle();
       }
     };
   }
+  /**
+   * Checks whether the scheduler has transitioned to idle and notifies listeners/resolvers.
+   */
+  checkIdle() {
+    if (this.isIdle()) {
+      if (this.idleResolvers.size > 0) {
+        for (const resolve of this.idleResolvers) {
+          resolve();
+        }
+        this.idleResolvers.clear();
+      }
+      this.emitter.emit("idle", { timestamp: Date.now() });
+    }
+  }
+  /**
+   * Checks whether the scheduler is currently idle (no active runners and no pending tasks).
+   *
+   * @returns True if completely idle, false otherwise.
+   */
+  isIdle() {
+    return this.activeRunners.size === 0 && this.queue.length === 0 && this.delayedEntries.size === 0 && this.idleEntries.size === 0 && this.retryEntries.size === 0 && this.debounceCoordinator.size === 0 && this.throttleCoordinator.size === 0;
+  }
+  /**
+   * Returns a promise that resolves once the scheduler has processed all tasks and is idle.
+   *
+   * @returns Promise resolving when idle.
+   */
+  onIdle() {
+    if (this.isIdle()) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      this.idleResolvers.add(resolve);
+    });
+  }
+  /**
+   * Clears all pending and waiting tasks from the scheduler, cancelling their runners.
+   * Active tasks currently in flight will continue to run to completion or abort via signal.
+   */
+  clear() {
+    while (this.queue.length > 0) {
+      const runner = this.queue.shift();
+      if (runner && runner.state !== "cancelled" /* CANCELLED */) {
+        runner.cancel("Scheduler cleared");
+        this.cancelledTasks++;
+        this.emitter.emit("task:cancel", { taskId: runner.taskId, reason: "Scheduler cleared" });
+      }
+    }
+    for (const entry of this.delayedEntries.values()) {
+      clearTimeout(entry.timerId);
+      entry.runner.cancel("Scheduler cleared");
+      this.cancelledTasks++;
+      this.emitter.emit("task:cancel", { taskId: entry.runner.taskId, reason: "Scheduler cleared" });
+    }
+    this.delayedEntries.clear();
+    for (const entry of this.idleEntries.values()) {
+      entry.handle.cancel();
+      entry.runner.cancel("Scheduler cleared");
+      this.cancelledTasks++;
+      this.emitter.emit("task:cancel", { taskId: entry.runner.taskId, reason: "Scheduler cleared" });
+    }
+    this.idleEntries.clear();
+    for (const entry of this.retryEntries.values()) {
+      clearTimeout(entry.timerId);
+      entry.runner.cancel("Scheduler cleared");
+      this.cancelledTasks++;
+      this.emitter.emit("task:cancel", { taskId: entry.runner.taskId, reason: "Scheduler cleared" });
+    }
+    this.retryEntries.clear();
+    this.debounceCoordinator.clear();
+    this.throttleCoordinator.clear();
+    if (this.rateLimitTimer !== void 0) {
+      clearTimeout(this.rateLimitTimer);
+      this.rateLimitTimer = void 0;
+    }
+    this.checkIdle();
+  }
   /**
    * Returns telemetry snapshot for the scheduler.
    *
@@ -825,6 +1063,8 @@ var TaskQueue = class {
       failedTasks: this.failedTasks,
       cancelledTasks: this.cancelledTasks,
       timedOutTasks: this.timedOutTasks,
+      retriedTasks: this.retriedTasks,
+      totalDispatched: this.totalDispatched,
       capacity: this.concurrency
     });
   }
@@ -859,6 +1099,8 @@ var TaskRunner = class {
   onCancel;
   /** Current execution attempt count (1-indexed) */
   attempt = 1;
+  /** Duration of the most recent execution attempt in milliseconds */
+  lastDurationMs = 0;
   /**
    * Creates a new TaskRunner instance.
    *
@@ -1017,9 +1259,11 @@ var TaskRunner = class {
     if (timeoutPromise) {
       racePromises.push(timeoutPromise);
     }
+    const startTime = Date.now();
     try {
       const result = await Promise.race(racePromises);
       this.clearTimeoutTimer();
+      this.lastDurationMs = Math.max(0, Date.now() - startTime);
       if (abortListener) {
         this.abortController.signal.removeEventListener("abort", abortListener);
       }
@@ -1036,6 +1280,7 @@ var TaskRunner = class {
       return result;
     } catch (error) {
       this.clearTimeoutTimer();
+      this.lastDurationMs = Math.max(0, Date.now() - startTime);
       if (abortListener) {
         this.abortController.signal.removeEventListener("abort", abortListener);
       }
@@ -1277,10 +1522,87 @@ var Ahko = class {
   stats() {
     return this.queue.getStats();
   }
+  /**
+   * Subscribes to a scheduler lifecycle event.
+   *
+   * @param event - Event name to listen for.
+   * @param handler - Callback function invoked when the event is emitted.
+   * @returns Unsubscribe function to remove the listener.
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = ahko.on("task:start", ({ taskId, attempt }) => {
+   *   console.log(`Task ${taskId} started attempt ${attempt}`);
+   * });
+   * ```
+   */
+  on(event, handler) {
+    return this.queue.emitter.on(event, handler);
+  }
+  /**
+   * Unsubscribes an event listener from a scheduler lifecycle event.
+   *
+   * @param event - Event name.
+   * @param handler - The exact listener callback to remove.
+   */
+  off(event, handler) {
+    this.queue.emitter.off(event, handler);
+  }
+  /**
+   * Checks whether the scheduler is currently idle (no active runners and no pending tasks).
+   *
+   * @returns True if completely idle, false otherwise.
+   */
+  isIdle() {
+    return this.queue.isIdle();
+  }
+  /**
+   * Returns a promise that resolves once the scheduler has completed all tasks and is idle.
+   *
+   * @returns Promise resolving when the scheduler is idle.
+   *
+   * @example
+   * ```typescript
+   * ahko.schedule(doWork);
+   * await ahko.onIdle();
+   * console.log("All work finished!");
+   * ```
+   */
+  onIdle() {
+    return this.queue.onIdle();
+  }
+  /**
+   * Clears all pending, delayed, and throttled/debounced tasks from the scheduler.
+   * In-flight active tasks will continue executing to completion or abort via signal.
+   */
+  clear() {
+    this.queue.clear();
+  }
+  /**
+   * Returns the delightful Ahko mascot battery telemetry status.
+   *
+   * Low energy, completely chill.
+   */
+  battery() {
+    return {
+      level: 3,
+      chill: true,
+      status: "low-energy",
+      quote: "Mwee... my battery is low, but all your tasks are handled completely chill."
+    };
+  }
+  /**
+   * Delightful alias for `onIdle()`: wait for all tasks to settle chill and relaxed.
+   *
+   * @returns Promise resolving when all tasks have finished.
+   */
+  chill() {
+    return this.onIdle();
+  }
 };
 
 // src/version.ts
-var VERSION = "0.5.0";
+var VERSION = "1.0.0";
 
 // src/errors/queue.error.ts
 var AhkoQueueError = class extends AhkoError {