@mrjacket/ahko 1.0.0 → 1.1.5

package/CHANGELOG.md

@@ -5,6 +5,69 @@ 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.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
+- Declarative configuration file support via `config.ahko.json` with multi-profile support (e.g. `default`, `crawler`, `critical-gateway`).
+- Static configuration loaders: `Ahko.loadConfig(config)` for universal programmatic profile loading (Node.js & browser), `Ahko.loadConfigFile(path?)` for asynchronous filesystem loading, and `Ahko.fromProfile(name, overrides?)`.
+- Martin Fowler Circuit Breaker pattern with `ECircuitState` (`CLOSED`, `OPEN`, `HALF_OPEN`), `CircuitBreakerCoordinator`, and `AhkoCircuitBreakerOpenError`:
+  - Protects downstream services by tracking consecutive failures against a `failureThreshold`.
+  - Fast-fails pending and incoming tasks without execution when OPEN.
+  - Automatically transitions to HALF_OPEN after `resetTimeoutMs` cooldown to allow a recovery trial.
+  - Heals to CLOSED on trial success or immediately re-trips to OPEN on trial failure.
+- Priority queue scheduling with stable FIFO ordering:
+  - Supports named priorities (`"high"`, `"normal"`, `"low"`) and arbitrary numerical weights (e.g. `100`, `-5`).
+  - Tasks with higher priority preempt lower priority tasks in the queue; tasks with identical priority preserve strict FIFO ordering.
+- Queue flow control via `ahko.pause()`, `ahko.resume()`, and `ahko.isPaused()`:
+  - Halts dispatching pending tasks without interrupting currently executing tasks.
+  - Immediately dispatches accumulated tasks upon resume up to concurrency limits.
+- Total Timeout Budget (`totalTimeoutMs`):
+  - Sets an overarching execution deadline spanning queue wait time, execution, and retry delays.
+  - Cancels task runners cleanly with `AhkoTimeoutError` when the budget expires.
+- Ergonomic function wrapping via `ahko.wrap(fn, options)`:
+  - Wraps any sync or async function returning a decorated function routed through the scheduler with pre-configured priorities and options.
+- New runnable examples:
+  - `examples/07-circuit-breaker.mjs`: circuit breaker tripping, fast-failing, and cooldown recovery.
+  - `examples/08-priority-queue.mjs`: priority queue ordering and pause/resume flow control.
+  - `config.ahko.example.json`: reference declarative schema configuration file.
+- Extended telemetry in `ahko.stats()`: `isPaused` boolean and `circuitState` indicator.
+
+### Fixed
+- Remediated 2 CodeQL static analysis security alerts:
+  - Alert #4: Removed unused `externalController` declaration in `src/__tests__/e2e.test.ts`.
+  - Alert #3: Removed unused `sleep` helper declaration in `examples/04-retry-backoff-jitter.mjs`.
+
+---
+
 ## [1.0.0] - 2026-09-23 — Stable Scheduler Release
 
 ### Added

package/README.md

@@ -15,6 +15,9 @@
   <a href="https://www.npmjs.com/package/@mrjacket/ahko">
     <img src="https://img.shields.io/node/v/@mrjacket/ahko.svg" alt="node">
   </a>
+  <a href="https://www.npmjs.com/package/@mrjacket/ahko">
+    <img src="https://img.shields.io/npm/dm/@mrjacket/ahko.svg" alt="npm downloads">
+  </a>
   <a href="https://github.com/x-name15/ahko/actions/workflows/ci.yml">
     <img src="https://github.com/x-name15/ahko/actions/workflows/ci.yml/badge.svg" alt="ci">
   </a>
@@ -281,6 +284,182 @@ console.log(ahko.battery());
 // { level: 3, chill: true, status: "low-energy", quote: "Mwee... my battery is low, but all your tasks are handled completely chill." }
 ```
 
+### 12. Priority-Aware Scheduling
+
+Ensure critical tasks jump ahead of normal or background work while preserving strict FIFO ordering among peers:
+
+```typescript
+// Named priorities: "high" (10), "normal" (0), "low" (-10), or custom numeric weights
+await ahko.schedule(criticalTask, { priority: "high" });
+await ahko.schedule(backgroundSync, { priority: "low" });
+await ahko.schedule(superUrgent, { priority: 100 });
+```
+
+### 13. Circuit Breaker Protection
+
+Protect fragile downstream services and databases from cascading failures. When consecutive failures meet `failureThreshold`, the circuit trips to `OPEN` and fast-fails tasks immediately without execution:
+
+```typescript
+const ahko = new Ahko({
+  concurrency: 2,
+  circuitBreaker: {
+    failureThreshold: 3, // trip after 3 consecutive failures
+    resetTimeoutMs: 15000, // wait 15s before attempting recovery probe
+  },
+});
+
+try {
+  await ahko.schedule(callFlakyService);
+} catch (err) {
+  if (err instanceof AhkoCircuitBreakerOpenError) {
+    console.warn("Fast-failed: Circuit breaker is OPEN!");
+  }
+}
+```
+
+### 14. Pause & Resume Flow Control
+
+Temporarily halt queue dispatching without aborting in-flight tasks. Resuming immediately pumps accumulated tasks up to capacity:
+
+```typescript
+// Stop dispatching new tasks
+ahko.pause();
+console.log(ahko.isPaused()); // true
+
+// In-flight tasks finish peacefully...
+
+// Resume dispatching
+ahko.resume();
+```
+
+### 15. Total Timeout Budget
+
+Enforce an overarching deadline spanning queue wait time, execution, and retries:
+
+```typescript
+// Task will abort with AhkoTimeoutError if total elapsed time exceeds 5000ms
+await ahko.schedule(fetchWithRetries, {
+  totalTimeoutMs: 5000,
+  retry: { attempts: 3, baseDelay: 1000 },
+});
+```
+
+### 16. Function Wrapping (`ahko.wrap`)
+
+Decorate any async function to automatically route every invocation through Ahko:
+
+```typescript
+const fetchUser = ahko.wrap(
+  async (userId: string) => {
+    const res = await fetch(`https://api.example.com/users/${userId}`);
+    return res.json();
+  },
+  { priority: "high", retry: { attempts: 2 } }
+);
+
+// Seamlessly executed via scheduler
+const user = await fetchUser("usr_42");
+```
+
+### 17. Declarative Configuration (`config.ahko.json`)
+
+Define scheduler defaults and workload profiles cleanly in JSON:
+
+```json
+{
+  "default": {
+    "concurrency": 2,
+    "minIntervalMs": 50,
+    "priority": "normal"
+  },
+  "profiles": {
+    "crawler": {
+      "concurrency": 4,
+      "minIntervalMs": 200,
+      "priority": "low"
+    },
+    "critical-gateway": {
+      "concurrency": 1,
+      "circuitBreaker": {
+        "failureThreshold": 3,
+        "resetTimeoutMs": 10000
+      }
+    }
+  }
+}
+```
+
+```typescript
+// Programmatically or from config file:
+Ahko.loadConfig(config);
+
+// Instantiate configured scheduler from profile
+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
@@ -291,10 +470,11 @@ Comprehensive guides and technical documentation are available in the [`docs/`](
 |---|---|
 | [**Documentation Portal**](./docs/README.md) | Master overview and index of all guides and specifications. |
 | [**Getting Started**](./docs/guides/getting-started.md) | Quickstart guide, installation, and fundamental usage patterns. |
+| [**Declarative Configuration**](./docs/guides/configuration.md) | Centralizing limits in `config.ahko.json`, `$schema` validation, named profiles, and fallback rules. |
 | [**Library API**](./docs/guides/library.md) | Complete programmatic API reference, TypeScript interfaces, and options. |
 | [**Production Recipes**](./docs/guides/recipes.md) | Battle-tested recipes (paced API client, debounced search, throttled scroll, graceful shutdown). |
 | [**Architecture**](./docs/architecture/ARCHITECTURE.md) | Architectural specifications, lifecycle state machine, and design decisions. |
-| [**Roadmap**](./docs/architecture/ROADMAP.md) | Milestone progression from 0.1.0 through 1.0.0. |
+| [**Roadmap**](./docs/architecture/ROADMAP.md) | Milestone progression from 0.1.0 through 1.1.0. |
 | [**Engineering Log**](./docs/architecture/LOG.md) | Chronological log of engineering decisions and ADRs. |
 
 > **Runnable Examples:** A comprehensive suite of standalone, runnable Node.js scripts is available in the [`examples/`](./examples/) folder. See [`examples/README.md`](./examples/README.md) for details.
@@ -311,6 +491,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>`
 
@@ -319,29 +526,44 @@ Schedules an asynchronous task with full return type inference.
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `strategy` | `"immediate" \| "delay" \| "idle" \| "throttle" \| "debounce"` | `"immediate"` | Scheduling execution strategy. |
+| `priority` | `"high" \| "normal" \| "low" \| number` | `"normal"` | Task priority weight for queue ordering. |
 | `delay` | `number` | `0` | Delay in milliseconds when strategy is `"delay"`. |
 | `key` | `string \| symbol` | `undefined` | Explicit identity key for `"debounce"` and `"throttle"`. |
 | `waitMs` | `number` | `undefined` | Window duration in ms for debounce quiet period or throttle interval. |
 | `idleTimeout` | `number` | `undefined` | Maximum time to wait for idle window before forcing queue entry. |
 | `retry` | `IRetryOptions` | `undefined` | Automatic retry policy (attempts, backoff, jitter, predicate). |
 | `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?)`
+
+Returns a wrapped version of `fn` routed through the scheduler.
+
+### `ahko.pause() / ahko.resume() / ahko.isPaused()`
+
+Pauses and resumes task dispatching.
+
+### `ahko.circuitState`
+
+Returns current circuit breaker state (`"closed" | "open" | "half_open"` or `undefined`).
 
-### `ahko.debounce<T>(key: string | symbol, task: ITask<T>, waitMs: number, options?: IScheduleOptions): Promise<T>`
+### `ahko.debounce<T>(key, task, waitMs, options?): Promise<T>`
 
 Convenience method scheduling a debounced task with key-based Promise coalescing.
 
-### `ahko.throttle<T>(key: string | symbol, task: ITask<T>, waitMs: number, options?: IScheduleOptions): Promise<T>`
+### `ahko.throttle<T>(key, task, waitMs, options?): Promise<T>`
 
 Convenience method scheduling a throttled task with leading execution and coalesced trailing run.
 
-### `ahko.idle<T>(task: ITask<T>, options?: Omit<IScheduleOptions, "strategy">): Promise<T>`
+### `ahko.idle<T>(task, options?): Promise<T>`
 
 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)`
 
@@ -369,7 +591,7 @@ Returns mascot battery status and quote.
 
 ### `ahko.stats(): IAhkoStats`
 
-Returns a snapshot of current task counters, retry counts, total dispatches, and queue capacity.
+Returns a snapshot of current task counters, retry counts, total dispatches, pause status, circuit state, and queue capacity.
 
 ---
 
@@ -381,7 +603,8 @@ All scheduler errors inherit from `AhkoError`:
 - `AhkoCancellationError`: Thrown when a task is aborted.
 - `AhkoConfigurationError`: Thrown when invalid options are provided.
 - `AhkoQueueError`: Thrown when queue constraints are violated.
-- `AhkoTimeoutError`: Thrown when a task exceeds its configured duration.
+- `AhkoTimeoutError`: Thrown when a task exceeds its configured duration or totalTimeoutMs.
+- `AhkoCircuitBreakerOpenError`: Thrown when task execution is fast-failed because the circuit breaker is OPEN.
 
 ---
 

package/dist/ahko.d.ts

@@ -1,12 +1,18 @@
+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";
 import type { ITask } from "./models/task.model.js";
+import type { CircuitBreakerCoordinator } from "./scheduler/circuit-breaker.js";
 /**
  * Ahko — Low-energy asynchronous task scheduler.
  *
- * Coordinates execution timing, enforces concurrency limits, and cooperates
- * natively with AbortSignal cancellation.
+ * Coordinates execution timing, enforces concurrency limits, manages priorities,
+ * provides circuit-breaker stability, supports pause/resume flow control,
+ * and cooperates natively with AbortSignal cancellation.
  *
  * @example
  * ```typescript
@@ -23,6 +29,37 @@ import type { ITask } from "./models/task.model.js";
 export declare class Ahko {
     /** Internal queue and concurrency manager */
     private readonly queue;
+    /** Default schedule options inherited from profile if configured */
+    private readonly defaultScheduleOptions?;
+    /**
+     * Programmatically loads a declarative configuration into memory.
+     * Works universally across Node.js, browsers, and edge runtimes.
+     *
+     * @param config - File configuration object containing default and named profiles.
+     */
+    static loadConfig(config: IAhkoFileConfig): void;
+    /**
+     * Asynchronously loads a configuration file from disk (Node.js).
+     *
+     * @param filePath - Path to configuration file (default: "config.ahko.json").
+     */
+    static loadConfigFile(filePath?: string): Promise<IAhkoFileConfig | undefined>;
+    /**
+     * Resets the active declarative configuration.
+     */
+    static resetConfig(): void;
+    /**
+     * Retrieves the currently active declarative configuration.
+     */
+    static getActiveConfig(): IAhkoFileConfig | undefined;
+    /**
+     * Instantiates an Ahko scheduler initialized with settings from a declarative profile.
+     *
+     * @param profileName - Optional name of the profile (e.g. "api", "background").
+     * @param overrides - Optional scheduler options overriding profile values.
+     * @returns A new configured Ahko instance.
+     */
+    static fromProfile(profileName?: string, overrides?: IAhkoOptions): Ahko;
     /**
      * Initializes a new Ahko scheduler instance.
      *
@@ -35,28 +72,73 @@ 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.
+     */
+    pause(): void;
+    /**
+     * Resumes scheduler dispatch, immediately executing waiting tasks up to available concurrency.
+     */
+    resume(): void;
+    /**
+     * Checks whether the scheduler is currently paused.
+     */
+    isPaused(): boolean;
+    /**
+     * Current circuit breaker state if circuit breaker protection is configured.
+     */
+    get circuitState(): ECircuitState | undefined;
+    /**
+     * Access to the underlying circuit breaker coordinator instance if configured.
+     */
+    get circuitBreaker(): CircuitBreakerCoordinator | undefined;
+    /**
+     * Wraps an async function so every execution is automatically routed through this Ahko scheduler.
+     *
+     * @template TArgs - Parameter types of the wrapped function.
+     * @template TReturn - Return type of the wrapped function.
+     * @param fn - The function to wrap.
+     * @param options - Optional scheduling options applied to every wrapped call.
+     * @returns A wrapped function returning a Promise.
+     *
+     * @example
+     * ```typescript
+     * const fetchUser = ahko.wrap(async (id: string) => api.getUser(id), { priority: "high" });
+     * const user = await fetchUser("usr_123");
+     * ```
+     */
+    wrap<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => Promise<TReturn> | TReturn, options?: IScheduleOptions): (...args: TArgs) => Promise<TReturn>;
     /**
      * Schedules a task for execution with full return type inference.
      *
      * @template T - Inferred return type of the task.
      * @param task - Asynchronous or synchronous task function accepting an {@link ITaskContext}.
-     * @param options - Task-specific scheduling options such as strategy, delay, and cancellation signal.
+     * @param options - Task-specific scheduling options such as strategy, priority, delay, and cancellation signal.
      * @returns A promise that resolves with the task's return value.
      *
      * @throws {AhkoConfigurationError} If the task is not a function or options are invalid.
      * @throws {AhkoCancellationError} If the task is cancelled prior to or during execution.
-     * @throws {AhkoTimeoutError} If task execution exceeds timeoutMs.
+     * @throws {AhkoTimeoutError} If task execution exceeds timeoutMs or totalTimeoutMs.
+     * @throws {AhkoCircuitBreakerOpenError} If the circuit breaker is OPEN and rejects the execution.
      *
      * @example
      * ```typescript
      * // Immediate execution (subject to concurrency)
      * const count = await ahko.schedule(async () => 42);
      *
-     * // Delayed execution
-     * await ahko.schedule(
-     *   async ({ signal }) => doWork({ signal }),
-     *   { strategy: "delay", delay: 1000 }
-     * );
+     * // High priority task
+     * await ahko.schedule(doUrgentWork, { priority: "high" });
      * ```
      */
     schedule<T>(task: ITask<T>, options?: IScheduleOptions): Promise<T>;
@@ -99,15 +181,77 @@ 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.
      *
-     * @returns An {@link IAhkoStats} snapshot of active, pending, completed, failed, cancelled, and timed out tasks.
+     * @returns An {@link IAhkoStats} snapshot of active, pending, completed, failed, cancelled, timed out tasks, pause status, and circuit state.
      *
      * @example
      * ```typescript
      * const stats = ahko.stats();
-     * console.log(`Active: ${stats.activeTasks}, Pending: ${stats.pendingTasks}`);
+     * console.log(`Active: ${stats.activeTasks}, Pending: ${stats.pendingTasks}, Paused: ${stats.isPaused}`);
      * ```
      */
     stats(): IAhkoStats;

package/dist/config/config-loader.d.ts

@@ -0,0 +1,31 @@
+import type { IAhkoFileConfig, IAhkoProfileConfig } from "../models/config.model.js";
+/**
+ * Programmatically loads and activates a declarative configuration.
+ * Universal across Node.js, browsers, and edge environments.
+ *
+ * @param config - Complete configuration object conforming to `IAhkoFileConfig`.
+ */
+export declare function loadConfig(config: IAhkoFileConfig): void;
+/**
+ * Resets the currently active configuration in memory to undefined.
+ */
+export declare function resetConfig(): void;
+/**
+ * Asynchronously loads a `config.ahko.json` or custom config file from the filesystem in Node.js.
+ * Sets the active configuration in memory upon successful read and parse.
+ *
+ * @param filePath - Optional relative or absolute path to the configuration file (default: "config.ahko.json").
+ * @returns The parsed configuration object, or `undefined` if not running in Node.js or if file cannot be read.
+ */
+export declare function loadConfigFile(filePath?: string): Promise<IAhkoFileConfig | undefined>;
+/**
+ * Returns the currently active declarative configuration, attempting auto-discovery if in Node.js.
+ */
+export declare function getActiveConfig(): IAhkoFileConfig | undefined;
+/**
+ * Retrieves a specific profile configuration by name, or the default profile if no name is provided.
+ *
+ * @param profileName - Optional name of the profile (e.g. "api", "background").
+ * @returns The profile configuration if defined, or undefined.
+ */
+export declare function getProfileConfig(profileName?: string): IAhkoProfileConfig | undefined;

package/dist/config/index.d.ts

@@ -0,0 +1 @@
+export { loadConfig, resetConfig, loadConfigFile, getActiveConfig, getProfileConfig, } from "./config-loader.js";

package/dist/errors/circuit-breaker.error.d.ts

@@ -0,0 +1,24 @@
+import { AhkoError } from "./ahko.error.js";
+/**
+ * Options describing the circuit breaker open state.
+ */
+export interface IAhkoCircuitBreakerErrorOptions {
+    /** Time remaining in milliseconds before the circuit attempts half-open trial */
+    resetTimeoutMs?: number;
+    /** Timestamp when the circuit tripped open */
+    trippedAt?: number;
+    /** Consecutive failures that caused the trip */
+    consecutiveFailures?: number;
+}
+/**
+ * Thrown when attempting to execute a task while the scheduler's circuit breaker is in OPEN state.
+ */
+export declare class AhkoCircuitBreakerOpenError extends AhkoError {
+    /** Time remaining in milliseconds before trial execution is allowed */
+    readonly resetTimeoutMs?: number;
+    /** Timestamp when the circuit tripped open */
+    readonly trippedAt?: number;
+    /** Total consecutive failures that caused the trip */
+    readonly consecutiveFailures?: number;
+    constructor(message?: string, options?: IAhkoCircuitBreakerErrorOptions);
+}

package/dist/errors/index.d.ts

@@ -3,3 +3,4 @@ export * from "./cancellation.error.js";
 export * from "./configuration.error.js";
 export * from "./queue.error.js";
 export * from "./timeout.error.js";
+export * from "./circuit-breaker.error.js";