@mrjacket/ahko 0.4.0 → 0.6.0

package/dist/scheduler/task-queue.d.ts

@@ -1,6 +1,9 @@
 import type { IScheduleOptions } from "../models/options.model.js";
 import type { IAhkoStats } from "../models/stats.model.js";
+import { DebounceCoordinator } from "./debounce-coordinator.js";
 import { TaskRunner } from "./task-runner.js";
+import { ThrottleCoordinator } from "./throttle-coordinator.js";
+import { AhkoEventEmitter } from "../events/event-emitter.js";
 /**
  * Memory-safe FIFO task queue managing concurrency allocation,
  * delayed scheduling, and task lifecycle counters.
@@ -8,6 +11,12 @@ import { TaskRunner } from "./task-runner.js";
 export declare class TaskQueue {
     /** Maximum concurrent active tasks */
     readonly concurrency: number;
+    /** Minimum interval in milliseconds between consecutive task starts */
+    readonly minIntervalMs: number;
+    /** Timestamp of the most recent task start */
+    private lastTaskStartTime;
+    /** Active rate limit timer for pacing consecutive tasks */
+    private rateLimitTimer?;
     /** Queue of pending task runners waiting for a concurrency slot */
     private readonly queue;
     /** Set of task runners currently executing */
@@ -18,6 +27,14 @@ export declare class TaskQueue {
     private readonly idleEntries;
     /** Set of tasks currently awaiting a retry backoff timer */
     private readonly retryEntries;
+    /** Coordinator for debounced tasks with key coalescing */
+    readonly debounceCoordinator: DebounceCoordinator;
+    /** Coordinator for throttled tasks with leading/trailing coalescing */
+    readonly throttleCoordinator: ThrottleCoordinator;
+    /** Lifecycle event emitter for task and scheduler events */
+    readonly emitter: AhkoEventEmitter;
+    /** Set of pending resolvers awaiting scheduler idle transition */
+    private readonly idleResolvers;
     /** WeakMap associating task runners with their scheduling options */
     private readonly runnerOptions;
     /** Cumulative completed tasks counter */
@@ -28,13 +45,18 @@ export declare class TaskQueue {
     private cancelledTasks;
     /** Cumulative timed out tasks counter */
     private timedOutTasks;
+    /** Cumulative count of retry attempts triggered */
+    private retriedTasks;
+    /** Cumulative count of tasks dispatched to concurrency slots */
+    private totalDispatched;
     /**
      * Creates a new TaskQueue.
      *
      * @param concurrency - Maximum concurrent tasks (defaults to Infinity).
-     * @throws {AhkoConfigurationError} If concurrency is less than 1 or not a valid number.
+     * @param minIntervalMs - Minimum interval in milliseconds between task dispatches.
+     * @throws {AhkoConfigurationError} If concurrency is less than 1 or minIntervalMs is invalid.
      */
-    constructor(concurrency?: number);
+    constructor(concurrency?: number, minIntervalMs?: number);
     /**
      * Enqueues a task runner according to the specified schedule options.
      *
@@ -57,7 +79,7 @@ export declare class TaskQueue {
     private scheduleIdle;
     /**
      * Pumps the queue by picking pending tasks and executing them
-     * as long as concurrency capacity is available.
+     * as long as concurrency capacity is available and minIntervalMs is respected.
      */
     private pump;
     /**
@@ -69,6 +91,27 @@ export declare class TaskQueue {
      * without holding a concurrency slot.
      */
     private scheduleRetry;
+    /**
+     * Checks whether the scheduler has transitioned to idle and notifies listeners/resolvers.
+     */
+    checkIdle(): void;
+    /**
+     * Checks whether the scheduler is currently idle (no active runners and no pending tasks).
+     *
+     * @returns True if completely idle, false otherwise.
+     */
+    isIdle(): boolean;
+    /**
+     * Returns a promise that resolves once the scheduler has processed all tasks and is idle.
+     *
+     * @returns Promise resolving when idle.
+     */
+    onIdle(): Promise<void>;
+    /**
+     * 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(): void;
     /**
      * Returns telemetry snapshot for the scheduler.
      *

package/dist/scheduler/task-runner.d.ts

@@ -34,6 +34,8 @@ export declare class TaskRunner<T> {
     onCancel?: (runner: TaskRunner<T>) => void;
     /** Current execution attempt count (1-indexed) */
     attempt: number;
+    /** Duration of the most recent execution attempt in milliseconds */
+    lastDurationMs: number;
     /**
      * Creates a new TaskRunner instance.
      *

package/dist/scheduler/throttle-coordinator.d.ts

@@ -0,0 +1,43 @@
+import type { IScheduleOptions } from "../models/options.model.js";
+import type { ITask } from "../models/task.model.js";
+/**
+ * Coordinates throttle execution with leading execution, trailing execution,
+ * and Promise coalescing by explicit key.
+ *
+ * Incoming calls with the same key within the throttle period coalesce into a
+ * single shared trailing execution, preventing overload while ensuring callers
+ * receive the final result.
+ */
+export declare class ThrottleCoordinator {
+    private readonly entries;
+    /**
+     * Schedules a task under the throttle strategy.
+     *
+     * @param key - Explicit identity key.
+     * @param task - Work to execute.
+     * @param waitMs - Throttle interval duration in milliseconds.
+     * @param options - Scheduling options.
+     * @param dispatchFn - Callback invoked to dispatch task execution into the queue.
+     * @returns Promise resolving with the leading execution or coalesced trailing result.
+     */
+    schedule<T>(key: string | symbol, task: ITask<T>, waitMs: number, options: IScheduleOptions | undefined, dispatchFn: (task: ITask<T>, options?: IScheduleOptions) => Promise<T>): Promise<T>;
+    /**
+     * Invoked when the throttle interval window timer expires.
+     */
+    private onWindowExpire;
+    /**
+     * Cancels any pending trailing throttled task for a given key.
+     *
+     * @param key - Identity key to cancel.
+     * @param reason - Optional cancellation reason.
+     */
+    cancel(key: string | symbol, reason?: unknown): void;
+    /**
+     * Number of keys currently actively throttled.
+     */
+    get size(): number;
+    /**
+     * Clears all throttled entries and timers.
+     */
+    clear(): void;
+}

package/dist/version.d.ts

@@ -1,4 +1,4 @@
 /**
  * Current version of @mrjacket/ahko package.
  */
-export declare const VERSION = "0.4.0";
+export declare const VERSION = "0.6.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrjacket/ahko",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "A low-energy task scheduler for JavaScript and TypeScript. Let your code chill.",
   "type": "module",
   "main": "dist/index.cjs",
@@ -70,6 +70,11 @@
     "cooperative-scheduling",
     "low-energy",
     "typescript",
+    "events",
+    "telemetry",
+    "observability",
+    "metrics",
+    "dx",
     "100 kanojo"
   ],
   "devDependencies": {