@mrjacket/ahko 1.0.0 → 1.1.5

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/circuit-breaker.model.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Discrete lifecycle states of the circuit breaker.
+ */
+export declare enum ECircuitState {
+    /** Normal operation: calls pass through to execution */
+    CLOSED = "closed",
+    /** Failure threshold exceeded: calls fast-fail immediately */
+    OPEN = "open",
+    /** Cool-down timer elapsed: trial call allowed to test recovery */
+    HALF_OPEN = "half_open"
+}
+/** Union type representing circuit breaker states */
+export type TCircuitState = `${ECircuitState}`;
+/**
+ * Configuration options for the circuit breaker policy.
+ */
+export interface ICircuitBreakerOptions {
+    /**
+     * Number of consecutive task failures required to trip the circuit to OPEN state.
+     * Must be an integer greater than or equal to 1.
+     */
+    failureThreshold: number;
+    /**
+     * Time in milliseconds the circuit remains OPEN before transitioning to HALF_OPEN
+     * to attempt a recovery trial call. Must be a positive finite number.
+     */
+    resetTimeoutMs: number;
+}
+/**
+ * Telemetry snapshot of circuit breaker status.
+ */
+export interface ICircuitBreakerStats {
+    /** Current state of the breaker */
+    state: ECircuitState;
+    /** Number of consecutive errors recorded */
+    consecutiveFailures: number;
+    /** Timestamp in ms when the breaker tripped to OPEN, if open */
+    lastFailureTime?: number;
+}

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

@@ -0,0 +1,23 @@
+import type { ICircuitBreakerOptions } from "./circuit-breaker.model.js";
+import type { IAhkoOptions, IScheduleOptions } from "./options.model.js";
+import type { TTaskPriority } from "./priority.model.js";
+/**
+ * Pre-configured profile containing scheduler defaults and task scheduling policies.
+ */
+export interface IAhkoProfileConfig extends IAhkoOptions, Partial<IScheduleOptions> {
+    /** Optional default task priority for tasks scheduled under this profile */
+    priority?: TTaskPriority;
+    /** Optional circuit breaker policy for the scheduler */
+    circuitBreaker?: ICircuitBreakerOptions;
+}
+/**
+ * Structure of `config.ahko.json` declarative configuration file.
+ */
+export interface IAhkoFileConfig {
+    /** Optional JSON schema URL */
+    $schema?: string;
+    /** Default profile applied when no named profile is requested */
+    default?: IAhkoProfileConfig;
+    /** Named profiles for distinct workloads (e.g. "api", "background", "critical") */
+    profiles?: Record<string, IAhkoProfileConfig>;
+}

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

@@ -6,3 +6,8 @@ export * from "./stats.model.js";
 export * from "./strategy.model.js";
 export * from "./task.model.js";
 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,6 @@
+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";
 import type { TScheduleStrategy } from "./strategy.model.js";
 /**
@@ -31,6 +34,19 @@ export interface IScheduleOptions {
      * Must be a positive finite number greater than 0 if provided.
      */
     timeoutMs?: number;
+    /**
+     * Overall budget in milliseconds allowed for the entire task lifecycle,
+     * including queue wait times, execution durations, and retry backoffs.
+     * If exceeded, the task rejects with an AhkoTimeoutError.
+     */
+    totalTimeoutMs?: number;
+    /**
+     * Priority assigned to the task ("high", "normal", "low", or explicit numeric value).
+     * High priority tasks jump ahead of lower priority tasks in the pending queue.
+     * FIFO ordering is strictly preserved among tasks of equal priority.
+     * @default "normal" (0)
+     */
+    priority?: TTaskPriority;
     /**
      * Explicit identity key for "debounce" and "throttle" strategies.
      * Tasks sharing the same key coalesce into shared executions.
@@ -47,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.
@@ -65,4 +85,16 @@ export interface IAhkoOptions {
      * @default 0
      */
     minIntervalMs?: number;
+    /**
+     * 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.
+     */
+    profile?: string;
 }

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

@@ -0,0 +1,18 @@
+/**
+ * Named priority level or explicit numeric priority for scheduled tasks.
+ * Higher numeric values indicate higher execution priority.
+ */
+export type TTaskPriority = "high" | "normal" | "low" | number;
+/** Default priority weight mappings */
+export declare const TASK_PRIORITY_WEIGHTS: {
+    readonly high: 10;
+    readonly normal: 0;
+    readonly low: -10;
+};
+/**
+ * Resolves a task priority into a normalized numeric weight.
+ *
+ * @param priority - Named or numeric priority.
+ * @returns Numeric weight (default 0 for normal).
+ */
+export declare function resolvePriorityWeight(priority?: TTaskPriority): number;

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

@@ -1,3 +1,5 @@
+import type { IAdaptiveStats } from "./adaptive.model.js";
+import type { ECircuitState } from "./circuit-breaker.model.js";
 /**
  * Telemetry snapshot of the Ahko scheduler.
  */
@@ -20,4 +22,10 @@ export interface IAhkoStats {
     totalDispatched: number;
     /** Maximum concurrent execution capacity */
     capacity: number;
+    /** Whether task dispatching is currently paused */
+    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/circuit-breaker.d.ts

@@ -0,0 +1,56 @@
+import { ECircuitState, type ICircuitBreakerOptions, type ICircuitBreakerStats } from "../models/circuit-breaker.model.js";
+/**
+ * Manages circuit breaker failure tracking, state transitions, and fast-fail enforcement.
+ *
+ * Implements standard Martin Fowler Circuit Breaker state machine:
+ * - CLOSED: All operations execute normally.
+ * - OPEN: All operations fast-fail immediately with AhkoCircuitBreakerOpenError.
+ * - HALF_OPEN: Probe execution allowed to verify recovery.
+ */
+export declare class CircuitBreakerCoordinator {
+    private _state;
+    private _consecutiveFailures;
+    private _lastFailureTime;
+    readonly failureThreshold: number;
+    readonly resetTimeoutMs: number;
+    /**
+     * Initializes a new CircuitBreakerCoordinator.
+     *
+     * @param options - Configuration options for threshold and cool-down window.
+     * @throws {AhkoConfigurationError} If options are invalid.
+     */
+    constructor(options: ICircuitBreakerOptions);
+    /** Current state of the circuit breaker */
+    get state(): ECircuitState;
+    /**
+     * Checks whether an execution is currently allowed.
+     * If the circuit is OPEN and cool-down has not elapsed, fast-fails immediately.
+     *
+     * @throws {AhkoCircuitBreakerOpenError} If the circuit is currently OPEN.
+     */
+    checkAllowed(): void;
+    /**
+     * Records a successful task execution.
+     * Heals HALF_OPEN state back to CLOSED and resets consecutive failure counters.
+     */
+    recordSuccess(): void;
+    /**
+     * Records a failed task execution.
+     * Trips CLOSED to OPEN when threshold is met, or re-trips HALF_OPEN immediately.
+     *
+     * @param _error - Optional error that caused the failure.
+     */
+    recordFailure(_error?: unknown): void;
+    /**
+     * Evaluates if enough time has passed to transition from OPEN to HALF_OPEN.
+     */
+    private refreshState;
+    /**
+     * Resets the circuit breaker back to initial CLOSED state.
+     */
+    reset(): void;
+    /**
+     * Returns a snapshot of circuit breaker telemetry.
+     */
+    getStats(): ICircuitBreakerStats;
+}

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

@@ -1,16 +1,21 @@
+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";
 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.
+ * Memory-safe priority-aware task queue managing concurrency allocation,
+ * 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 */
@@ -27,12 +32,20 @@ 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 */
     readonly throttleCoordinator: ThrottleCoordinator;
     /** Lifecycle event emitter for task and scheduler events */
     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 */
     private readonly idleResolvers;
     /** WeakMap associating task runners with their scheduling options */
@@ -54,9 +67,64 @@ 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);
+    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.
+     */
+    pause(): void;
+    /**
+     * Resumes queue execution, immediately dispatching waiting tasks up to available concurrency.
+     */
+    resume(): void;
+    /**
+     * 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.
+     */
+    private insertIntoQueue;
     /**
      * Enqueues a task runner according to the specified schedule options.
      *
@@ -79,7 +147,8 @@ export declare class TaskQueue {
     private scheduleIdle;
     /**
      * Pumps the queue by picking pending tasks and executing them
-     * as long as concurrency capacity is available and minIntervalMs is respected.
+     * as long as concurrency capacity is available, minIntervalMs is respected,
+     * and queue is not paused.
      */
     private pump;
     /**

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

@@ -36,14 +36,19 @@ 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;
     /**
      * Gets the current lifecycle state of the task.
      */
@@ -84,6 +89,13 @@ export declare class TaskRunner<T> {
      * @param reason - Optional cancellation reason.
      */
     cancel(reason?: unknown): void;
+    /**
+     * Times out the task, aborting pending or running execution with AhkoTimeoutError.
+     *
+     * @param timeoutMs - Timeout duration in milliseconds.
+     * @param message - Optional custom timeout message.
+     */
+    timeout(timeoutMs: number, message?: string): void;
     /**
      * Handles external AbortSignal trigger.
      */

package/dist/version.d.ts

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

package/package.json

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