@mrjacket/ahko 1.1.0 → 1.1.5

package/dist/index.js

@@ -20,6 +20,21 @@ var AhkoError = class extends Error {
   }
 };
 
+// src/errors/cancellation.error.ts
+var AhkoCancellationError = class extends AhkoError {
+  /**
+   * Creates a new AhkoCancellationError.
+   *
+   * @param message - Reason for cancellation.
+   * @param options - Standard Error options including cause.
+   */
+  constructor(message = "Task was cancelled", options) {
+    super(message, options);
+    this.name = "AhkoCancellationError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
 // src/errors/configuration.error.ts
 var AhkoConfigurationError = class extends AhkoError {
   /**
@@ -206,6 +221,137 @@ function calculateBackoff(attempt, options, randomFn = Math.random) {
   return Math.floor(cappedDelay);
 }
 
+// src/scheduler/adaptive-coordinator.ts
+var AdaptiveCoordinator = class {
+  _currentConcurrency;
+  minConcurrency;
+  maxConcurrency;
+  targetLatencyMs;
+  sampleWindowSize;
+  backoffFactor;
+  recentDurations = [];
+  lastAverageLatencyMs = 0;
+  onConcurrencyChange;
+  /**
+   * Initializes a new AdaptiveCoordinator instance.
+   *
+   * @param options - Adaptive concurrency configuration options.
+   * @param initialConcurrency - Starting scheduler concurrency limit.
+   * @param onConcurrencyChange - Callback invoked when concurrency changes.
+   * @throws {AhkoConfigurationError} If options are invalid.
+   */
+  constructor(options, initialConcurrency, onConcurrencyChange) {
+    if (typeof options.targetLatencyMs !== "number" || Number.isNaN(options.targetLatencyMs) || !Number.isFinite(options.targetLatencyMs) || options.targetLatencyMs <= 0) {
+      throw new AhkoConfigurationError(
+        `Invalid targetLatencyMs "${options.targetLatencyMs}". targetLatencyMs must be a positive number greater than 0.`
+      );
+    }
+    const min = options.minConcurrency ?? 1;
+    if (typeof min !== "number" || Number.isNaN(min) || min < 1 || !Number.isInteger(min)) {
+      throw new AhkoConfigurationError(
+        `Invalid minConcurrency "${min}". minConcurrency must be an integer greater than or equal to 1.`
+      );
+    }
+    const defaultMax = Number.isFinite(initialConcurrency) ? Math.max(min, initialConcurrency * 2) : Math.max(min, 10);
+    const max = options.maxConcurrency ?? defaultMax;
+    if (typeof max !== "number" || Number.isNaN(max) || max < min || !Number.isInteger(max)) {
+      throw new AhkoConfigurationError(
+        `Invalid maxConcurrency "${max}". maxConcurrency must be an integer greater than or equal to minConcurrency (${min}).`
+      );
+    }
+    const windowSize = options.sampleWindowSize ?? 5;
+    if (typeof windowSize !== "number" || Number.isNaN(windowSize) || windowSize < 1 || !Number.isInteger(windowSize)) {
+      throw new AhkoConfigurationError(
+        `Invalid sampleWindowSize "${windowSize}". sampleWindowSize must be an integer greater than or equal to 1.`
+      );
+    }
+    const factor = options.backoffFactor ?? 0.7;
+    if (typeof factor !== "number" || Number.isNaN(factor) || factor <= 0.1 || factor >= 0.99) {
+      throw new AhkoConfigurationError(
+        `Invalid backoffFactor "${factor}". backoffFactor must be a number between 0.1 and 0.99.`
+      );
+    }
+    this.minConcurrency = min;
+    this.maxConcurrency = max;
+    this.targetLatencyMs = options.targetLatencyMs;
+    this.sampleWindowSize = windowSize;
+    this.backoffFactor = factor;
+    this.onConcurrencyChange = onConcurrencyChange;
+    const clampedInitial = Number.isFinite(initialConcurrency) ? Math.min(Math.max(initialConcurrency, min), max) : min;
+    this._currentConcurrency = clampedInitial;
+  }
+  /**
+   * Current effective concurrency limit dictated by the adaptive controller.
+   */
+  get currentConcurrency() {
+    return this._currentConcurrency;
+  }
+  /**
+   * Manually overrides the current concurrency within [minConcurrency, maxConcurrency].
+   *
+   * @param concurrency - New concurrency limit to set.
+   */
+  setConcurrency(concurrency) {
+    const clamped = Math.min(Math.max(concurrency, this.minConcurrency), this.maxConcurrency);
+    if (clamped !== this._currentConcurrency) {
+      const prev = this._currentConcurrency;
+      this._currentConcurrency = clamped;
+      this.onConcurrencyChange(prev, clamped, "Manual concurrency override");
+    }
+  }
+  /**
+   * Records a task execution duration sample and triggers AIMD adjustment if window is filled.
+   *
+   * @param durationMs - Execution duration in milliseconds of the completed task.
+   */
+  recordDuration(durationMs) {
+    this.recentDurations.push(durationMs);
+    if (this.recentDurations.length < this.sampleWindowSize) {
+      return;
+    }
+    const total = this.recentDurations.reduce((sum, val) => sum + val, 0);
+    const average = total / this.recentDurations.length;
+    this.lastAverageLatencyMs = average;
+    this.recentDurations = [];
+    if (average > this.targetLatencyMs) {
+      const decreased = Math.max(
+        this.minConcurrency,
+        Math.floor(this._currentConcurrency * this.backoffFactor)
+      );
+      if (decreased !== this._currentConcurrency) {
+        const prev = this._currentConcurrency;
+        this._currentConcurrency = decreased;
+        this.onConcurrencyChange(
+          prev,
+          decreased,
+          `Average latency (${Math.round(average)}ms) exceeded target (${this.targetLatencyMs}ms). Scaled down.`
+        );
+      }
+    } else if (average < this.targetLatencyMs * 0.75) {
+      const increased = Math.min(this.maxConcurrency, this._currentConcurrency + 1);
+      if (increased !== this._currentConcurrency) {
+        const prev = this._currentConcurrency;
+        this._currentConcurrency = increased;
+        this.onConcurrencyChange(
+          prev,
+          increased,
+          `Average latency (${Math.round(average)}ms) below target threshold. Scaled up.`
+        );
+      }
+    }
+  }
+  /**
+   * Returns a snapshot of adaptive telemetry metrics.
+   */
+  getStats() {
+    return {
+      currentConcurrency: this._currentConcurrency,
+      averageLatencyMs: this.lastAverageLatencyMs,
+      samplesRecorded: this.recentDurations.length
+    };
+  }
+};
+
 // src/models/circuit-breaker.model.ts
 var ECircuitState = /* @__PURE__ */ ((ECircuitState2) => {
   ECircuitState2["CLOSED"] = "closed";
@@ -323,21 +469,6 @@ var CircuitBreakerCoordinator = class {
   }
 };
 
-// src/errors/cancellation.error.ts
-var AhkoCancellationError = class extends AhkoError {
-  /**
-   * Creates a new AhkoCancellationError.
-   *
-   * @param message - Reason for cancellation.
-   * @param options - Standard Error options including cause.
-   */
-  constructor(message = "Task was cancelled", options) {
-    super(message, options);
-    this.name = "AhkoCancellationError";
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
-};
-
 // src/scheduler/debounce-coordinator.ts
 var DebounceCoordinator = class {
   entries = /* @__PURE__ */ new Map();
@@ -734,7 +865,7 @@ var AhkoEventEmitter = class {
 // src/scheduler/task-queue.ts
 var TaskQueue = class {
   /** Maximum concurrent active tasks */
-  concurrency;
+  _concurrency;
   /** Minimum interval in milliseconds between consecutive task starts */
   minIntervalMs;
   /** Timestamp of the most recent task start */
@@ -751,6 +882,8 @@ var TaskQueue = class {
   idleEntries = /* @__PURE__ */ new Set();
   /** Set of tasks currently awaiting a retry backoff timer */
   retryEntries = /* @__PURE__ */ new Set();
+  /** Tag index for selective cancellation and task classification */
+  tagIndex = /* @__PURE__ */ new Map();
   /** Coordinator for debounced tasks with key coalescing */
   debounceCoordinator = new DebounceCoordinator();
   /** Coordinator for throttled tasks with leading/trailing coalescing */
@@ -759,6 +892,8 @@ var TaskQueue = class {
   emitter = new AhkoEventEmitter();
   /** Circuit breaker coordinator if configured */
   circuitBreakerCoordinator;
+  /** Adaptive concurrency coordinator if configured */
+  adaptiveCoordinator;
   /** Pause state flag */
   _isPaused = false;
   /** Set of pending resolvers awaiting scheduler idle transition */
@@ -783,9 +918,10 @@ var TaskQueue = class {
    * @param concurrency - Maximum concurrent tasks (defaults to Infinity).
    * @param minIntervalMs - Minimum interval in milliseconds between task dispatches.
    * @param circuitBreakerOptions - Optional circuit breaker policy configuration.
+   * @param adaptiveOptions - Optional adaptive concurrency policy configuration.
    * @throws {AhkoConfigurationError} If concurrency is less than 1 or minIntervalMs is invalid.
    */
-  constructor(concurrency = Infinity, minIntervalMs = 0, circuitBreakerOptions) {
+  constructor(concurrency = Infinity, minIntervalMs = 0, circuitBreakerOptions, adaptiveOptions) {
     if (Number.isNaN(concurrency) || concurrency < 1) {
       throw new AhkoConfigurationError(
         `Invalid concurrency "${concurrency}". Must be a number greater than or equal to 1.`
@@ -796,14 +932,62 @@ var TaskQueue = class {
         `Invalid minIntervalMs "${minIntervalMs}". minIntervalMs must be a non-negative finite number.`
       );
     }
-    this.concurrency = concurrency;
+    this._concurrency = concurrency;
     this.minIntervalMs = minIntervalMs;
     if (circuitBreakerOptions) {
       this.circuitBreakerCoordinator = new CircuitBreakerCoordinator(circuitBreakerOptions);
     }
+    if (adaptiveOptions) {
+      this.adaptiveCoordinator = new AdaptiveCoordinator(
+        adaptiveOptions,
+        this._concurrency,
+        (previous, current, reason) => {
+          this._concurrency = current;
+          this.emitter.emit("concurrency:change", {
+            previousConcurrency: previous,
+            currentConcurrency: current,
+            reason
+          });
+          this.pump();
+        }
+      );
+      this._concurrency = this.adaptiveCoordinator.currentConcurrency;
+    }
     this.debounceCoordinator.onSettled = () => this.checkIdle();
     this.throttleCoordinator.onSettled = () => this.checkIdle();
   }
+  /**
+   * Current concurrency capacity limit.
+   */
+  get concurrency() {
+    return this._concurrency;
+  }
+  /**
+   * Dynamically adjusts the concurrency limit at runtime.
+   *
+   * @param newConcurrency - New maximum concurrency (must be >= 1).
+   * @throws {AhkoConfigurationError} If newConcurrency is less than 1.
+   */
+  setConcurrency(newConcurrency) {
+    if (Number.isNaN(newConcurrency) || newConcurrency < 1) {
+      throw new AhkoConfigurationError(
+        `Invalid concurrency "${newConcurrency}". Must be a number greater than or equal to 1.`
+      );
+    }
+    const previous = this._concurrency;
+    this._concurrency = newConcurrency;
+    if (this.adaptiveCoordinator) {
+      this.adaptiveCoordinator.setConcurrency(newConcurrency);
+    }
+    if (newConcurrency !== previous) {
+      this.emitter.emit("concurrency:change", {
+        previousConcurrency: previous,
+        currentConcurrency: newConcurrency,
+        reason: "Manual concurrency update"
+      });
+    }
+    this.pump();
+  }
   /**
    * Pauses queue execution. Running tasks will complete normally, but no new pending tasks will be dispatched.
    */
@@ -825,6 +1009,76 @@ var TaskQueue = class {
   isPaused() {
     return this._isPaused;
   }
+  /**
+   * Cancels all pending, delayed, and active tasks marked with the specified tag.
+   *
+   * @param tag - Tag identifier to match.
+   * @param reason - Optional cancellation reason.
+   * @returns Total count of tasks cancelled.
+   */
+  cancelByTag(tag, reason) {
+    const runners = this.tagIndex.get(tag);
+    if (!runners || runners.size === 0) {
+      return 0;
+    }
+    const list = Array.from(runners);
+    let count = 0;
+    for (const runner of list) {
+      if (runner.state === "pending" /* PENDING */ || runner.state === "running" /* RUNNING */) {
+        runner.cancel(reason ?? `Task cancelled by tag "${tag}"`);
+        count++;
+      }
+    }
+    return count;
+  }
+  /**
+   * Returns active and pending task counts for a given tag.
+   *
+   * @param tag - Tag identifier.
+   */
+  getStatsByTag(tag) {
+    const runners = this.tagIndex.get(tag);
+    if (!runners) {
+      return { activeTasks: 0, pendingTasks: 0 };
+    }
+    let active = 0;
+    let pending = 0;
+    for (const runner of runners) {
+      if (runner.state === "running" /* RUNNING */) {
+        active++;
+      } else if (runner.state === "pending" /* PENDING */) {
+        pending++;
+      }
+    }
+    return { activeTasks: active, pendingTasks: pending };
+  }
+  /**
+   * Indexes a runner under all its associated tags.
+   */
+  indexTaskTags(runner) {
+    for (const tag of runner.tags) {
+      let set = this.tagIndex.get(tag);
+      if (!set) {
+        set = /* @__PURE__ */ new Set();
+        this.tagIndex.set(tag, set);
+      }
+      set.add(runner);
+    }
+  }
+  /**
+   * Removes a runner from the tag index upon settlement.
+   */
+  cleanupTaskTags(runner) {
+    for (const tag of runner.tags) {
+      const set = this.tagIndex.get(tag);
+      if (set) {
+        set.delete(runner);
+        if (set.size === 0) {
+          this.tagIndex.delete(tag);
+        }
+      }
+    }
+  }
   /**
    * Inserts a task runner into the queue based on priority weight (descending).
    * Preserves FIFO ordering among tasks with identical priority.
@@ -906,6 +1160,11 @@ var TaskQueue = class {
     if (options) {
       this.runnerOptions.set(runner, options);
     }
+    this.indexTaskTags(runner);
+    runner.promise.finally(() => {
+      this.cleanupTaskTags(runner);
+    }).catch(() => {
+    });
     if (runner.state === "cancelled" /* CANCELLED */) {
       this.cancelledTasks++;
       return runner.promise;
@@ -1084,7 +1343,7 @@ var TaskQueue = class {
    * and queue is not paused.
    */
   pump() {
-    if (this._isPaused || this.queue.length === 0 || this.activeRunners.size >= this.concurrency) {
+    if (this._isPaused || this.queue.length === 0 || this.activeRunners.size >= this._concurrency) {
       return;
     }
     if (this.minIntervalMs > 0 && this.lastTaskStartTime > 0) {
@@ -1101,7 +1360,7 @@ var TaskQueue = class {
         return;
       }
     }
-    while (!this._isPaused && this.activeRunners.size < this.concurrency && this.queue.length > 0) {
+    while (!this._isPaused && this.activeRunners.size < this._concurrency && this.queue.length > 0) {
       if (this.minIntervalMs > 0 && this.lastTaskStartTime > 0) {
         const now = Date.now();
         const elapsed = now - this.lastTaskStartTime;
@@ -1143,7 +1402,7 @@ var TaskQueue = class {
       this.lastTaskStartTime = Date.now();
       void this.executeRunner(runner);
       if (this.minIntervalMs > 0) {
-        if (this.queue.length > 0 && this.activeRunners.size < this.concurrency) {
+        if (this.queue.length > 0 && this.activeRunners.size < this._concurrency) {
           if (this.rateLimitTimer === void 0) {
             this.rateLimitTimer = setTimeout(() => {
               this.rateLimitTimer = void 0;
@@ -1168,6 +1427,7 @@ var TaskQueue = class {
     try {
       const result = await runner.run();
       this.circuitBreakerCoordinator?.recordSuccess();
+      this.adaptiveCoordinator?.recordDuration(runner.lastDurationMs);
       this.completedTasks++;
       this.activeRunners.delete(runner);
       this.runnerOptions.delete(runner);
@@ -1206,6 +1466,7 @@ var TaskQueue = class {
       if (this.circuitBreakerCoordinator && !(error instanceof AhkoCircuitBreakerOpenError)) {
         this.circuitBreakerCoordinator.recordFailure(error);
       }
+      this.adaptiveCoordinator?.recordDuration(runner.lastDurationMs);
       if (runner.state === "timed_out" /* TIMED_OUT */ || error instanceof AhkoTimeoutError) {
         this.timedOutTasks++;
         this.emitter.emit("task:timeout", {
@@ -1405,9 +1666,10 @@ var TaskQueue = class {
       timedOutTasks: this.timedOutTasks,
       retriedTasks: this.retriedTasks,
       totalDispatched: this.totalDispatched,
-      capacity: this.concurrency,
+      capacity: this._concurrency,
       isPaused: this._isPaused,
-      circuitState: this.circuitBreakerCoordinator?.state
+      circuitState: this.circuitBreakerCoordinator?.state,
+      adaptive: this.adaptiveCoordinator?.getStats()
     });
   }
 };
@@ -1443,18 +1705,22 @@ var TaskRunner = class {
   attempt = 1;
   /** Duration of the most recent execution attempt in milliseconds */
   lastDurationMs = 0;
+  /** Set of classification tags associated with this task */
+  tags;
   /**
    * Creates a new TaskRunner instance.
    *
    * @param task - The asynchronous work unit to run.
    * @param externalSignal - Optional external AbortSignal to propagate.
    * @param timeoutMs - Optional maximum execution time in milliseconds.
+   * @param tags - Optional array of tags for classifying and selectively cancelling tasks.
    */
-  constructor(task, externalSignal, timeoutMs) {
+  constructor(task, externalSignal, timeoutMs, tags) {
     this.taskId = `task_${Date.now().toString(36)}_${(++taskIdCounter).toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
     this.task = task;
     this.externalSignal = externalSignal;
     this.timeoutMs = timeoutMs;
+    this.tags = new Set(tags ?? []);
     this.abortController = new AbortController();
     this.promise = new Promise((resolve, reject) => {
       this.resolvePromise = resolve;
@@ -1781,7 +2047,8 @@ var Ahko = class _Ahko {
     return new _Ahko({
       ...profile,
       ...overrides,
-      circuitBreaker: overrides?.circuitBreaker ?? profile?.circuitBreaker
+      circuitBreaker: overrides?.circuitBreaker ?? profile?.circuitBreaker,
+      adaptive: overrides?.adaptive ?? profile?.adaptive
     });
   }
   /**
@@ -1800,22 +2067,40 @@ var Ahko = class _Ahko {
     const mergedOptions = {
       ...profile,
       ...options,
-      circuitBreaker: options?.circuitBreaker ?? profile?.circuitBreaker
+      circuitBreaker: options?.circuitBreaker ?? profile?.circuitBreaker,
+      adaptive: options?.adaptive ?? profile?.adaptive
     };
     if (profile) {
       this.defaultScheduleOptions = {
         priority: profile.priority,
         retry: profile.retry,
         timeoutMs: profile.timeoutMs,
-        totalTimeoutMs: profile.totalTimeoutMs
+        totalTimeoutMs: profile.totalTimeoutMs,
+        tags: profile.tags
       };
     }
     this.queue = new TaskQueue(
       mergedOptions.concurrency,
       mergedOptions.minIntervalMs,
-      mergedOptions.circuitBreaker
+      mergedOptions.circuitBreaker,
+      mergedOptions.adaptive
     );
   }
+  /**
+   * Current concurrency limit.
+   */
+  get concurrency() {
+    return this.queue.concurrency;
+  }
+  /**
+   * Dynamically updates the concurrency limit of the scheduler.
+   *
+   * @param concurrency - New maximum concurrency (must be >= 1).
+   * @throws {AhkoConfigurationError} If concurrency is invalid.
+   */
+  setConcurrency(concurrency) {
+    this.queue.setConcurrency(concurrency);
+  }
   /**
    * Pauses scheduler dispatch. In-flight tasks run to completion, but pending tasks remain queued.
    */
@@ -1895,9 +2180,11 @@ var Ahko = class _Ahko {
     if (typeof task !== "function") {
       throw new AhkoConfigurationError("Task must be a valid function.");
     }
+    const mergedTags = options?.tags ?? this.defaultScheduleOptions?.tags;
     const mergedOptions = {
       ...this.defaultScheduleOptions,
-      ...options
+      ...options,
+      tags: mergedTags
     };
     const strategy = mergedOptions.strategy ?? "immediate" /* IMMEDIATE */;
     if (strategy === "debounce" /* DEBOUNCE */) {
@@ -1940,7 +2227,12 @@ var Ahko = class _Ahko {
         (t, opts) => this.schedule(t, { ...opts, strategy: "immediate" /* IMMEDIATE */ })
       );
     }
-    const runner = new TaskRunner(task, mergedOptions.signal, mergedOptions.timeoutMs);
+    const runner = new TaskRunner(
+      task,
+      mergedOptions.signal,
+      mergedOptions.timeoutMs,
+      mergedOptions.tags
+    );
     return this.queue.enqueue(runner, mergedOptions);
   }
   /**
@@ -2001,6 +2293,176 @@ var Ahko = class _Ahko {
       waitMs
     });
   }
+  /**
+   * Transforms an iterable of items concurrently using an asynchronous mapping function.
+   *
+   * Results are guaranteed to be returned in the original index order.
+   * Concurrency can be capped per-batch or fall back to the scheduler's global limit.
+   *
+   * @template TItem - Type of input elements.
+   * @template TResult - Type of mapped elements.
+   * @param items - Iterable sequence of items to process.
+   * @param fn - Mapper callback receiving item, index, and task context.
+   * @param options - Batch execution options (concurrency, stopOnError, retry, signal, tags, etc.).
+   * @returns Array of transformed results in index order.
+   *
+   * @throws {AhkoConfigurationError} If fn is not a function or concurrency is invalid.
+   * @throws {AhkoCancellationError} If batch or item is cancelled.
+   *
+   * @example
+   * ```typescript
+   * const urls = ["/api/1", "/api/2", "/api/3"];
+   * const data = await ahko.map(urls, async (url, i, { signal }) => {
+   *   const res = await fetch(url, { signal });
+   *   return res.json();
+   * }, { concurrency: 2 });
+   * ```
+   */
+  async map(items, fn, options) {
+    if (typeof fn !== "function") {
+      throw new AhkoConfigurationError("Mapper function must be a valid function.");
+    }
+    if (options?.concurrency !== void 0 && (typeof options.concurrency !== "number" || Number.isNaN(options.concurrency) || options.concurrency < 1)) {
+      throw new AhkoConfigurationError(
+        `Invalid concurrency "${options.concurrency}". Must be a number greater than or equal to 1.`
+      );
+    }
+    const list = Array.from(items);
+    if (list.length === 0) {
+      return [];
+    }
+    const { concurrency, stopOnError = false, signal: externalSignal, ...scheduleOpts } = options ?? {};
+    if (externalSignal?.aborted) {
+      throw new AhkoCancellationError(
+        externalSignal.reason ? `Batch cancelled: ${String(externalSignal.reason)}` : "Batch cancelled"
+      );
+    }
+    const abortController = new AbortController();
+    const results = new Array(list.length);
+    let firstError = void 0;
+    let hasAborted = false;
+    const localizedLimit = concurrency !== void 0 ? Math.floor(concurrency) : Number.isFinite(this.concurrency) ? this.concurrency : Infinity;
+    return new Promise((resolve, reject) => {
+      let currentIndex = 0;
+      let activeCount = 0;
+      let settledCount = 0;
+      const onExternalAbort = () => {
+        const reason = externalSignal?.reason ?? "Batch cancelled by external signal";
+        const err = new AhkoCancellationError(
+          typeof reason === "string" ? reason : "Batch cancelled by external signal"
+        );
+        cleanupAndReject(err);
+      };
+      if (externalSignal) {
+        externalSignal.addEventListener("abort", onExternalAbort, { once: true });
+      }
+      const cleanupAndReject = (err) => {
+        if (!hasAborted) {
+          hasAborted = true;
+          abortController.abort(err);
+        }
+        if (externalSignal) {
+          externalSignal.removeEventListener("abort", onExternalAbort);
+        }
+        reject(err);
+      };
+      const checkCompletion = () => {
+        if (settledCount === list.length) {
+          if (externalSignal) {
+            externalSignal.removeEventListener("abort", onExternalAbort);
+          }
+          if (firstError !== void 0) {
+            reject(firstError);
+          } else {
+            resolve(results);
+          }
+        }
+      };
+      const launchNext = () => {
+        if (hasAborted && stopOnError) {
+          return;
+        }
+        while (currentIndex < list.length && activeCount < localizedLimit && !(hasAborted && stopOnError)) {
+          const index = currentIndex++;
+          const item = list[index];
+          activeCount++;
+          const taskPromise = this.schedule(
+            (context) => fn(item, index, context),
+            {
+              ...scheduleOpts,
+              signal: abortController.signal
+            }
+          );
+          taskPromise.then((result) => {
+            results[index] = result;
+          }).catch((err) => {
+            if (firstError === void 0) {
+              firstError = err;
+            }
+            if (stopOnError && !hasAborted) {
+              cleanupAndReject(err);
+              return;
+            }
+          }).finally(() => {
+            activeCount--;
+            settledCount++;
+            if (hasAborted && stopOnError) {
+              return;
+            }
+            if (currentIndex < list.length) {
+              launchNext();
+            } else {
+              checkCompletion();
+            }
+          });
+        }
+      };
+      if (abortController.signal.aborted) {
+        cleanupAndReject(abortController.signal.reason);
+        return;
+      }
+      launchNext();
+    });
+  }
+  /**
+   * Iterates sequentially or concurrently over an iterable sequence of items,
+   * executing the callback function for each element.
+   *
+   * @template TItem - Type of input elements.
+   * @param items - Iterable sequence of items to process.
+   * @param fn - Callback receiving item, index, and task context.
+   * @param options - Batch execution options.
+   * @returns Promise resolving once all items have finished executing.
+   *
+   * @example
+   * ```typescript
+   * await ahko.each(userQueue, async (user, index, { signal }) => {
+   *   await sendWelcomeEmail(user, { signal });
+   * }, { concurrency: 5 });
+   * ```
+   */
+  async each(items, fn, options) {
+    await this.map(items, fn, options);
+  }
+  /**
+   * Cancels all pending, delayed, and active tasks tagged with the given tag.
+   *
+   * @param tag - Tag identifier.
+   * @param reason - Optional cancellation reason.
+   * @returns Total number of tasks cancelled.
+   */
+  cancelByTag(tag, reason) {
+    return this.queue.cancelByTag(tag, reason);
+  }
+  /**
+   * Retrieves active and pending task counts for a given tag.
+   *
+   * @param tag - Tag identifier.
+   * @returns Object with activeTasks and pendingTasks counts.
+   */
+  statsByTag(tag) {
+    return this.queue.getStatsByTag(tag);
+  }
   /**
    * Retrieves real-time telemetry metrics from the scheduler.
    *
@@ -2095,7 +2557,7 @@ var Ahko = class _Ahko {
 };
 
 // src/version.ts
-var VERSION = "1.1.0";
+var VERSION = "1.1.5";
 
 // src/errors/queue.error.ts
 var AhkoQueueError = class extends AhkoError {
@@ -2167,6 +2629,7 @@ function combineSignals(signals) {
   };
 }
 export {
+  AdaptiveCoordinator,
   Ahko,
   AhkoCancellationError,
   AhkoCircuitBreakerOpenError,