@mrjacket/ahko 1.1.0 → 1.1.6

package/CHANGELOG.md

@@ -5,6 +5,42 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.6] - 2026-09-24
+
+### Documentation
+- Add Coffee <3
+
+---
+
+## [1.1.5] - 2026-09-24 — Batch Collections, Dynamic & Adaptive Concurrency, Task Tags
+
+### Added
+- **Batch Collections API (`ahko.map` & `ahko.each`)**:
+  - `ahko.map<TItem, TResult>(items, fn, options?)`: Concurrently transforms any iterable sequence while strictly preserving original element order.
+  - `ahko.each<TItem>(items, fn, options?)`: Concurrently iterates over any sequence returning `Promise<void>`.
+  - Supports localized concurrency caps per-batch (`options.concurrency`), falling back to scheduler concurrency when omitted.
+  - Fail-fast flow control via `stopOnError: true` (aborts remaining tasks immediately and rejects) or settled error propagation via `stopOnError: false` (default).
+  - Native integration with `signal`, `retry`, `tags`, and priority options.
+- **Dynamic & Adaptive Concurrency (AIMD Auto-Chill Mode)**:
+  - Runtime dynamic concurrency reconfiguration via `ahko.setConcurrency(n)` and getter `ahko.concurrency`.
+  - Additive Increase / Multiplicative Decrease (AIMD) algorithm (`AdaptiveCoordinator`) adjusting scheduler capacity based on real-time task latency (`options.adaptive`).
+  - Seamlessly handles network latency spikes by scaling down concurrency on congestion and recovering when latency drops.
+  - Lifecycle event `"concurrency:change"` emitting `previousConcurrency`, `currentConcurrency`, and human-readable `reason`.
+  - Telemetry metrics in `ahko.stats().adaptive`: `currentConcurrency`, `averageLatencyMs`, `samplesRecorded`.
+- **Task Tags & Selective Cancellation**:
+  - Categorize tasks via `tags: string[]` in `schedule()`, `map()`, or declarative profiles.
+  - Selectively cancel related tasks via `ahko.cancelByTag(tag, reason?)` without interrupting other pending or active workloads.
+  - Inspect workload density per category via `ahko.statsByTag(tag)` (`activeTasks` and `pendingTasks`).
+  - Memory-safe automatic tag indexing and instant cleanup upon task runner settlement.
+- **Declarative Configuration Schema Expansion**:
+  - Added `adaptive` policy and `tags` classification to `schema.json` and `config.ahko.example.json`.
+- **New Runnable Examples**:
+  - `examples/09-batch-collections.mjs`: Concurrent mapping over iterables with strict index ordering.
+  - `examples/10-adaptive-concurrency.mjs`: AIMD Auto-Chill mode reacting to upstream latency.
+  - `examples/11-tag-cancellation.mjs`: Tagged workload telemetry and selective cancellation.
+
+---
+
 ## [1.1.0] - 2026-09-23 — Declarative Config, Circuit Breaker & Priority Queue
 
 ### Added

package/README.md

@@ -33,6 +33,9 @@
   <a href="https://github.com/x-name15/ahko/issues">
     <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome">
   </a>
+  <a href="https://buymeacoffee.com/mrjacket">
+    <img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?logo=buy-me-a-coffee&logoColor=black" alt="Buy Me A Coffee">
+  </a>
 </p>
 
 `ahko` is a low-energy task scheduler for JavaScript and TypeScript.
@@ -397,6 +400,69 @@ Ahko.loadConfig(config);
 const gateway = Ahko.fromProfile("critical-gateway");
 ```
 
+### 18. Batch Collections API (`ahko.map` & `ahko.each`)
+
+Transform collections concurrently with strict index order preservation and localized concurrency limits:
+
+```typescript
+const urls = ["/api/users", "/api/posts", "/api/comments"];
+
+// Processes concurrently (max 2 at a time), guaranteed return in original order
+const responses = await ahko.map(
+  urls,
+  async (url, index, { signal }) => {
+    const res = await fetch(url, { signal });
+    return res.json();
+  },
+  { concurrency: 2, stopOnError: true }
+);
+
+// Or iterate over items returning void:
+await ahko.each(userIds, async (id) => syncUser(id), { concurrency: 5 });
+```
+
+### 19. Dynamic & Adaptive Concurrency (AIMD Auto-Chill)
+
+Adjust concurrency dynamically on the fly or let Ahko adapt automatically to network latency:
+
+```typescript
+// Manually update concurrency at runtime:
+ahko.setConcurrency(5);
+console.log(ahko.concurrency); // 5
+
+// Or enable AIMD (Additive Increase / Multiplicative Decrease) Auto-Chill mode:
+const adaptiveAhko = new Ahko({
+  concurrency: 4,
+  adaptive: {
+    targetLatencyMs: 150, // if tasks take >150ms, cut concurrency in half
+    sampleWindowSize: 5,   // adjust after every 5 completed tasks
+    minConcurrency: 1,
+    maxConcurrency: 10,
+    backoffFactor: 0.5,
+  },
+});
+
+adaptiveAhko.on("concurrency:change", ({ previousConcurrency, currentConcurrency, reason }) => {
+  console.log(`Capacity adapted: ${previousConcurrency} -> ${currentConcurrency} (${reason})`);
+});
+```
+
+### 20. Task Tags & Selective Cancellation
+
+Classify tasks by tags, query categorical telemetry, and selectively cancel specific operations:
+
+```typescript
+// Tag tasks during scheduling:
+ahko.schedule(generateReport, { tags: ["reports", "finance"] });
+ahko.schedule(syncDatabase, { tags: ["sync"] });
+
+// Check active and pending tasks by tag:
+console.log(ahko.statsByTag("reports")); // { activeTasks: 1, pendingTasks: 0 }
+
+// Cancel all tasks associated with a tag without affecting other tasks:
+ahko.cancelByTag("reports", "User navigated away");
+```
+
 ---
 
 ## Documentation
@@ -429,8 +495,33 @@ Creates an ahko scheduler instance.
 | `concurrency` | `number` | `Infinity` | Maximum concurrent tasks allowed to run simultaneously. Must be $\ge 1$. |
 | `minIntervalMs` | `number` | `0` | Minimum interval in milliseconds between consecutive task starts. Must be $\ge 0$. |
 | `circuitBreaker` | `ICircuitBreakerOptions` | `undefined` | Optional failure threshold and cooldown reset configuration. |
+| `adaptive` | `IAdaptiveConcurrencyOptions` | `undefined` | Optional AIMD adaptive concurrency options based on task execution latency. |
 | `profile` | `string` | `undefined` | Name of declarative profile to inherit settings from. |
 
+### `ahko.concurrency`
+
+Getter returning the current concurrency capacity limit.
+
+### `ahko.setConcurrency(newConcurrency: number): void`
+
+Dynamically updates the concurrency limit of the scheduler at runtime.
+
+### `ahko.map<TItem, TResult>(items, fn, options?): Promise<TResult[]>`
+
+Concurrently transforms an iterable sequence into an array with strict index ordering. Supports localized `concurrency` limits and `stopOnError`.
+
+### `ahko.each<TItem>(items, fn, options?): Promise<void>`
+
+Iterates over an iterable sequence concurrently, executing the callback for each element.
+
+### `ahko.cancelByTag(tag: string, reason?: unknown): number`
+
+Cancels all pending, delayed, and active tasks marked with the specified tag. Returns the number of cancelled tasks.
+
+### `ahko.statsByTag(tag: string): { activeTasks: number; pendingTasks: number }`
+
+Returns active and pending task counts for a specific classification tag.
+
 ### `ahko.schedule<T>(task: ITask<T>, options?: IScheduleOptions): Promise<T>`
 
 Schedules an asynchronous task with full return type inference.
@@ -447,6 +538,7 @@ Schedules an asynchronous task with full return type inference.
 | `timeoutMs` | `number` | `undefined` | Maximum execution duration in milliseconds per attempt before aborting with `AhkoTimeoutError`. |
 | `totalTimeoutMs` | `number` | `undefined` | Total execution budget across wait time, retries, and execution. |
 | `signal` | `AbortSignal` | `undefined` | Optional external `AbortSignal` for cooperative cancellation. |
+| `tags` | `string[]` | `undefined` | Classification tags for selective cancellation and metric grouping. |
 
 ### `ahko.wrap(fn, options?)`
 
@@ -474,7 +566,7 @@ Convenience method scheduling a task under `strategy: "idle"`.
 
 ### `ahko.on(event, handler)`
 
-Subscribes to scheduler lifecycle events (`task:start`, `task:complete`, `task:fail`, `task:cancel`, `task:timeout`, `idle`). Returns an unsubscribe function.
+Subscribes to scheduler lifecycle events (`task:start`, `task:complete`, `task:fail`, `task:cancel`, `task:timeout`, `idle`, `concurrency:change`). Returns an unsubscribe function.
 
 ### `ahko.off(event, handler)`
 
@@ -519,6 +611,16 @@ All scheduler errors inherit from `AhkoError`:
 
 ---
 
+## Support & Sponsoring
+
+If you liked this library or want to support my work, I'd be eternally grateful for a warm coffee! ☕ <3
+
+<a href="https://buymeacoffee.com/mrjacket" target="_blank">
+  <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" width="180">
+</a>
+
+---
+
 ## License
 [GNU General Public License v3.0 (GPL-3.0-only)](LICENSE) 
 

package/dist/ahko.d.ts

@@ -1,5 +1,7 @@
+import type { IBatchOptions, IBatchMapOptions } from "./models/batch.model.js";
 import type { ECircuitState } from "./models/circuit-breaker.model.js";
 import type { IAhkoFileConfig } from "./models/config.model.js";
+import type { ITaskContext } from "./models/context.model.js";
 import type { TAhkoEventName, TAhkoEventHandler, TAhkoUnsubscribe } from "./models/events.model.js";
 import type { IAhkoOptions, IScheduleOptions } from "./models/options.model.js";
 import type { IAhkoStats } from "./models/stats.model.js";
@@ -70,6 +72,17 @@ export declare class Ahko {
      * ```
      */
     constructor(options?: IAhkoOptions);
+    /**
+     * Current concurrency limit.
+     */
+    get concurrency(): number;
+    /**
+     * Dynamically updates the concurrency limit of the scheduler.
+     *
+     * @param concurrency - New maximum concurrency (must be >= 1).
+     * @throws {AhkoConfigurationError} If concurrency is invalid.
+     */
+    setConcurrency(concurrency: number): void;
     /**
      * Pauses scheduler dispatch. In-flight tasks run to completion, but pending tasks remain queued.
      */
@@ -168,6 +181,68 @@ export declare class Ahko {
      * @returns Promise resolving with the leading or coalesced trailing result.
      */
     throttle<T>(key: string | symbol, task: ITask<T>, waitMs: number, options?: Omit<IScheduleOptions, "strategy" | "key" | "waitMs">): Promise<T>;
+    /**
+     * 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 });
+     * ```
+     */
+    map<TItem, TResult>(items: Iterable<TItem>, fn: (item: TItem, index: number, context: ITaskContext) => Promise<TResult> | TResult, options?: IBatchMapOptions<TItem, TResult>): Promise<TResult[]>;
+    /**
+     * 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 });
+     * ```
+     */
+    each<TItem>(items: Iterable<TItem>, fn: (item: TItem, index: number, context: ITaskContext) => Promise<void> | void, options?: IBatchOptions): Promise<void>;
+    /**
+     * 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: string, reason?: unknown): number;
+    /**
+     * Retrieves active and pending task counts for a given tag.
+     *
+     * @param tag - Tag identifier.
+     * @returns Object with activeTasks and pendingTasks counts.
+     */
+    statsByTag(tag: string): {
+        activeTasks: number;
+        pendingTasks: number;
+    };
     /**
      * Retrieves real-time telemetry metrics from the scheduler.
      *