@mrjacket/ahko 1.0.0 → 1.1.0

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/index.d.ts

@@ -6,3 +6,6 @@ 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";

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

@@ -1,3 +1,5 @@
+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 +33,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.
@@ -65,4 +80,12 @@ export interface IAhkoOptions {
      * @default 0
      */
     minIntervalMs?: number;
+    /**
+     * Optional circuit breaker policy to guard against cascading failures.
+     */
+    circuitBreaker?: ICircuitBreakerOptions;
+    /**
+     * 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,4 @@
+import type { ECircuitState } from "./circuit-breaker.model.js";
 /**
  * Telemetry snapshot of the Ahko scheduler.
  */
@@ -20,4 +21,8 @@ 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;
 }

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,12 +1,14 @@
+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 { 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, flow control (pause/resume), and task lifecycle counters.
  */
 export declare class TaskQueue {
     /** Maximum concurrent active tasks */
@@ -33,6 +35,10 @@ export declare class TaskQueue {
     readonly throttleCoordinator: ThrottleCoordinator;
     /** Lifecycle event emitter for task and scheduler events */
     readonly emitter: AhkoEventEmitter;
+    /** Circuit breaker coordinator if configured */
+    readonly circuitBreakerCoordinator?: CircuitBreakerCoordinator;
+    /** 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 +60,27 @@ 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.
      * @throws {AhkoConfigurationError} If concurrency is less than 1 or minIntervalMs is invalid.
      */
-    constructor(concurrency?: number, minIntervalMs?: number);
+    constructor(concurrency?: number, minIntervalMs?: number, circuitBreakerOptions?: ICircuitBreakerOptions);
+    /**
+     * 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;
+    /**
+     * 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 +103,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

@@ -44,6 +44,8 @@ export declare class TaskRunner<T> {
      * @param timeoutMs - Optional maximum execution time in milliseconds.
      */
     constructor(task: ITask<T>, externalSignal?: AbortSignal, timeoutMs?: number);
+    /** Flag indicating if runner was aborted by an overall total timeout deadline */
+    totalTimedOut: boolean;
     /**
      * Gets the current lifecycle state of the task.
      */
@@ -84,6 +86,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.0";

package/package.json

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