@mrjacket/ahko 1.1.0 → 1.1.6

package/dist/models/adaptive.model.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Configuration options for Additive Increase / Multiplicative Decrease (AIMD) Adaptive Concurrency.
+ */
+export interface IAdaptiveConcurrencyOptions {
+    /**
+     * Target average task execution latency in milliseconds.
+     * When measured latency exceeds this threshold, concurrency decreases multiplicatively.
+     * When latency remains comfortably below, concurrency increases additively.
+     * Must be a positive finite number greater than 0.
+     */
+    targetLatencyMs: number;
+    /**
+     * Minimum concurrency floor allowed during backoff / chill mode.
+     * Must be an integer greater than or equal to 1.
+     * @default 1
+     */
+    minConcurrency?: number;
+    /**
+     * Maximum concurrency ceiling allowed during scaling.
+     * Must be greater than or equal to `minConcurrency`.
+     * Defaults to twice the initial scheduler concurrency, or 10 if initial is Infinity.
+     */
+    maxConcurrency?: number;
+    /**
+     * Number of task execution samples to accumulate before calculating moving average and adjusting capacity.
+     * Must be an integer greater than or equal to 1.
+     * @default 5
+     */
+    sampleWindowSize?: number;
+    /**
+     * Multiplicative factor applied to reduce concurrency when latency threshold is violated.
+     * Must be a number between 0.1 and 0.95.
+     * @default 0.7
+     */
+    backoffFactor?: number;
+}
+/**
+ * Real-time telemetry snapshot of the adaptive concurrency controller.
+ */
+export interface IAdaptiveStats {
+    /** Current effective concurrency limit */
+    currentConcurrency: number;
+    /** Moving average execution latency in milliseconds across the latest sample window */
+    averageLatencyMs: number;
+    /** Total duration samples recorded in the current evaluation window */
+    samplesRecorded: number;
+}

package/dist/models/batch.model.d.ts

@@ -0,0 +1,22 @@
+import type { IScheduleOptions } from "./options.model.js";
+/**
+ * Common configuration options for batch processing operations (e.g. `ahko.map`, `ahko.each`).
+ */
+export interface IBatchOptions extends Omit<IScheduleOptions, "strategy"> {
+    /**
+     * Optional localized concurrency cap specifically for this batch operation.
+     * If omitted, uses the scheduler's global concurrency limit.
+     */
+    concurrency?: number;
+    /**
+     * Whether to abort remaining items in the batch as soon as an item fails.
+     * If `true`, unstarted items are cancelled and the batch promise rejects immediately with the error.
+     * If `false`, all items run and errors are thrown/propagated once all items settle.
+     * @default false
+     */
+    stopOnError?: boolean;
+}
+/**
+ * Options specifically for `ahko.map()` collection operations.
+ */
+export type IBatchMapOptions<_TItem = unknown, _TResult = unknown> = IBatchOptions;

package/dist/models/events.model.d.ts

@@ -35,6 +35,12 @@ export interface IAhkoEventMap {
     idle: {
         timestamp: number;
     };
+    /** Emitted when scheduler concurrency is dynamically or adaptively updated */
+    "concurrency:change": {
+        previousConcurrency: number;
+        currentConcurrency: number;
+        reason: string;
+    };
 }
 /**
  * Union of all valid event names emitted by the Ahko scheduler.

package/dist/models/index.d.ts

@@ -9,3 +9,5 @@ export * from "./events.model.js";
 export * from "./circuit-breaker.model.js";
 export * from "./priority.model.js";
 export * from "./config.model.js";
+export * from "./batch.model.js";
+export * from "./adaptive.model.js";

package/dist/models/options.model.d.ts

@@ -1,3 +1,4 @@
+import type { IAdaptiveConcurrencyOptions } from "./adaptive.model.js";
 import type { ICircuitBreakerOptions } from "./circuit-breaker.model.js";
 import type { TTaskPriority } from "./priority.model.js";
 import type { IRetryOptions } from "./retry.model.js";
@@ -62,6 +63,10 @@ export interface IScheduleOptions {
      * If aborted while running, the abort event is propagated to the task context signal.
      */
     signal?: AbortSignal;
+    /**
+     * Optional tags for classifying tasks and enabling selective cancellation (e.g. `ahko.cancelByTag()`).
+     */
+    tags?: string[];
 }
 /**
  * Global configuration options for the Ahko scheduler instance.
@@ -84,6 +89,10 @@ export interface IAhkoOptions {
      * Optional circuit breaker policy to guard against cascading failures.
      */
     circuitBreaker?: ICircuitBreakerOptions;
+    /**
+     * Optional adaptive concurrency policy (AIMD Auto-Chill mode) based on real-time task latency.
+     */
+    adaptive?: IAdaptiveConcurrencyOptions;
     /**
      * Optional named profile from `config.ahko.json` to inherit configuration defaults from.
      */

package/dist/models/stats.model.d.ts

@@ -1,3 +1,4 @@
+import type { IAdaptiveStats } from "./adaptive.model.js";
 import type { ECircuitState } from "./circuit-breaker.model.js";
 /**
  * Telemetry snapshot of the Ahko scheduler.
@@ -25,4 +26,6 @@ export interface IAhkoStats {
     isPaused: boolean;
     /** Current state of the scheduler circuit breaker, if configured */
     circuitState?: ECircuitState;
+    /** Telemetry from the adaptive concurrency controller, if configured */
+    adaptive?: IAdaptiveStats;
 }

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

@@ -0,0 +1,45 @@
+import type { IAdaptiveConcurrencyOptions, IAdaptiveStats } from "../models/adaptive.model.js";
+/**
+ * Controller implementing Additive Increase / Multiplicative Decrease (AIMD)
+ * dynamic concurrency adjustment based on real-time task latency metrics.
+ */
+export declare class AdaptiveCoordinator {
+    private _currentConcurrency;
+    readonly minConcurrency: number;
+    readonly maxConcurrency: number;
+    readonly targetLatencyMs: number;
+    readonly sampleWindowSize: number;
+    readonly backoffFactor: number;
+    private recentDurations;
+    private lastAverageLatencyMs;
+    private readonly 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: IAdaptiveConcurrencyOptions, initialConcurrency: number, onConcurrencyChange: (previous: number, current: number, reason: string) => void);
+    /**
+     * Current effective concurrency limit dictated by the adaptive controller.
+     */
+    get currentConcurrency(): number;
+    /**
+     * Manually overrides the current concurrency within [minConcurrency, maxConcurrency].
+     *
+     * @param concurrency - New concurrency limit to set.
+     */
+    setConcurrency(concurrency: number): void;
+    /**
+     * 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: number): void;
+    /**
+     * Returns a snapshot of adaptive telemetry metrics.
+     */
+    getStats(): IAdaptiveStats;
+}

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

@@ -1,6 +1,8 @@
+import type { IAdaptiveConcurrencyOptions } from "../models/adaptive.model.js";
 import type { ICircuitBreakerOptions } from "../models/circuit-breaker.model.js";
 import type { IScheduleOptions } from "../models/options.model.js";
 import type { IAhkoStats } from "../models/stats.model.js";
+import { AdaptiveCoordinator } from "./adaptive-coordinator.js";
 import { CircuitBreakerCoordinator } from "./circuit-breaker.js";
 import { DebounceCoordinator } from "./debounce-coordinator.js";
 import { TaskRunner } from "./task-runner.js";
@@ -8,11 +10,12 @@ import { ThrottleCoordinator } from "./throttle-coordinator.js";
 import { AhkoEventEmitter } from "../events/event-emitter.js";
 /**
  * Memory-safe priority-aware task queue managing concurrency allocation,
- * rate limiting, circuit breaker protection, flow control (pause/resume), and task lifecycle counters.
+ * rate limiting, circuit breaker protection, dynamic & adaptive concurrency,
+ * tags, flow control (pause/resume), and task lifecycle counters.
  */
 export declare class TaskQueue {
     /** Maximum concurrent active tasks */
-    readonly concurrency: number;
+    private _concurrency;
     /** Minimum interval in milliseconds between consecutive task starts */
     readonly minIntervalMs: number;
     /** Timestamp of the most recent task start */
@@ -29,6 +32,8 @@ export declare class TaskQueue {
     private readonly idleEntries;
     /** Set of tasks currently awaiting a retry backoff timer */
     private readonly retryEntries;
+    /** Tag index for selective cancellation and task classification */
+    private readonly tagIndex;
     /** Coordinator for debounced tasks with key coalescing */
     readonly debounceCoordinator: DebounceCoordinator;
     /** Coordinator for throttled tasks with leading/trailing coalescing */
@@ -37,6 +42,8 @@ export declare class TaskQueue {
     readonly emitter: AhkoEventEmitter;
     /** Circuit breaker coordinator if configured */
     readonly circuitBreakerCoordinator?: CircuitBreakerCoordinator;
+    /** Adaptive concurrency coordinator if configured */
+    readonly adaptiveCoordinator?: AdaptiveCoordinator;
     /** Pause state flag */
     private _isPaused;
     /** Set of pending resolvers awaiting scheduler idle transition */
@@ -61,9 +68,21 @@ export declare class TaskQueue {
      * @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?: number, minIntervalMs?: number, circuitBreakerOptions?: ICircuitBreakerOptions);
+    constructor(concurrency?: number, minIntervalMs?: number, circuitBreakerOptions?: ICircuitBreakerOptions, adaptiveOptions?: IAdaptiveConcurrencyOptions);
+    /**
+     * Current concurrency capacity limit.
+     */
+    get concurrency(): number;
+    /**
+     * 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: number): void;
     /**
      * Pauses queue execution. Running tasks will complete normally, but no new pending tasks will be dispatched.
      */
@@ -76,6 +95,31 @@ export declare class TaskQueue {
      * Checks whether the task queue is currently paused.
      */
     isPaused(): boolean;
+    /**
+     * 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: string, reason?: unknown): number;
+    /**
+     * Returns active and pending task counts for a given tag.
+     *
+     * @param tag - Tag identifier.
+     */
+    getStatsByTag(tag: string): {
+        activeTasks: number;
+        pendingTasks: number;
+    };
+    /**
+     * Indexes a runner under all its associated tags.
+     */
+    private indexTaskTags;
+    /**
+     * Removes a runner from the tag index upon settlement.
+     */
+    private cleanupTaskTags;
     /**
      * Inserts a task runner into the queue based on priority weight (descending).
      * Preserves FIFO ordering among tasks with identical priority.

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

@@ -36,14 +36,17 @@ export declare class TaskRunner<T> {
     attempt: number;
     /** Duration of the most recent execution attempt in milliseconds */
     lastDurationMs: number;
+    /** Set of classification tags associated with this task */
+    readonly tags: ReadonlySet<string>;
     /**
      * 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: ITask<T>, externalSignal?: AbortSignal, timeoutMs?: number);
+    constructor(task: ITask<T>, externalSignal?: AbortSignal, timeoutMs?: number, tags?: string[]);
     /** Flag indicating if runner was aborted by an overall total timeout deadline */
     totalTimedOut: boolean;
     /**

package/dist/version.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrjacket/ahko",
-  "version": "1.1.0",
+  "version": "1.1.6",
   "description": "A low-energy task scheduler for JavaScript and TypeScript. Let your code chill.",
   "type": "module",
   "main": "dist/index.cjs",