@mrjacket/ahko 0.1.0

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

@@ -0,0 +1,63 @@
+import type { IScheduleOptions } from "../models/options.model.js";
+import type { IAhkoStats } from "../models/stats.model.js";
+import { TaskRunner } from "./task-runner.js";
+/**
+ * Memory-safe FIFO task queue managing concurrency allocation,
+ * delayed scheduling, and task lifecycle counters.
+ */
+export declare class TaskQueue {
+    /** Maximum concurrent active tasks */
+    readonly concurrency: number;
+    /** Queue of pending task runners waiting for a concurrency slot */
+    private readonly queue;
+    /** Set of task runners currently executing */
+    private readonly activeRunners;
+    /** Set of tasks currently in delay phase */
+    private readonly delayedEntries;
+    /** Cumulative completed tasks counter */
+    private completedTasks;
+    /** Cumulative failed tasks counter */
+    private failedTasks;
+    /** Cumulative cancelled tasks counter */
+    private cancelledTasks;
+    /** Cumulative timed out tasks counter */
+    private timedOutTasks;
+    /**
+     * Creates a new TaskQueue.
+     *
+     * @param concurrency - Maximum concurrent tasks (defaults to Infinity).
+     * @throws {AhkoConfigurationError} If concurrency is less than 1 or not a valid number.
+     */
+    constructor(concurrency?: number);
+    /**
+     * Enqueues a task runner according to the specified schedule options.
+     *
+     * @template T - The return type produced by the task.
+     * @param runner - The task runner instance.
+     * @param options - Scheduling options.
+     * @returns The deferred promise associated with the task runner.
+     * @throws {AhkoConfigurationError} If scheduling options are invalid.
+     */
+    enqueue<T>(runner: TaskRunner<T>, options?: IScheduleOptions): Promise<T>;
+    /**
+     * Schedules a task to be placed into the queue after a delay,
+     * handling early cancellation safely.
+     */
+    private scheduleDelayed;
+    /**
+     * Pumps the queue by picking pending tasks and executing them
+     * as long as concurrency capacity is available.
+     */
+    private pump;
+    /**
+     * Internal execution of an active task runner.
+     * Settle caller promise strictly after stats and active status are updated.
+     */
+    private executeRunner;
+    /**
+     * Returns telemetry snapshot for the scheduler.
+     *
+     * @returns Frozen snapshot of current task metrics.
+     */
+    getStats(): IAhkoStats;
+}

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

@@ -0,0 +1,73 @@
+import { ETaskState } from "../models/state.model.js";
+import type { ITask } from "../models/task.model.js";
+/**
+ * Internal task lifecycle manager responsible for execution, state transitions,
+ * AbortSignal coordination, and deterministic resource cleanup.
+ *
+ * @template T - The return type produced by the underlying task.
+ */
+export declare class TaskRunner<T> {
+    /** Unique task identifier */
+    readonly taskId: string;
+    /** Current lifecycle state */
+    private _state;
+    /** Internal AbortController whose signal is passed to the task context */
+    private readonly abortController;
+    /** The user task function to execute */
+    private readonly task;
+    /** User-supplied AbortSignal for external cancellation */
+    private readonly externalSignal?;
+    /** Abort event listener reference for clean detachment */
+    private readonly abortListener?;
+    /** Promise resolve handler */
+    private resolvePromise;
+    /** Promise reject handler */
+    private rejectPromise;
+    /** Deferred promise exposed to the caller */
+    readonly promise: Promise<T>;
+    /** Callback invoked when runner is cancelled while pending */
+    onCancel?: (runner: TaskRunner<T>) => void;
+    /**
+     * Creates a new TaskRunner instance.
+     *
+     * @param task - The asynchronous work unit to run.
+     * @param externalSignal - Optional external AbortSignal to propagate.
+     */
+    constructor(task: ITask<T>, externalSignal?: AbortSignal);
+    /**
+     * Gets the current lifecycle state of the task.
+     */
+    get state(): ETaskState;
+    /**
+     * Resolves the deferred promise.
+     *
+     * @param value - Value to resolve with.
+     */
+    resolve(value: T): void;
+    /**
+     * Rejects the deferred promise.
+     *
+     * @param reason - Reason to reject with.
+     */
+    reject(reason: unknown): void;
+    /**
+     * Executes the task within an allocated concurrency slot.
+     *
+     * @returns A promise resolving to the task result or rejecting on failure/cancellation.
+     */
+    run(): Promise<T>;
+    /**
+     * Cancels the task, aborting pending or running execution.
+     *
+     * @param reason - Optional cancellation reason.
+     */
+    cancel(reason?: unknown): void;
+    /**
+     * Handles external AbortSignal trigger.
+     */
+    private handleExternalAbort;
+    /**
+     * Detaches event listeners from external signal to guarantee memory safety.
+     */
+    cleanup(): void;
+}

package/dist/version.d.ts

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

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@mrjacket/ahko",
+  "version": "0.1.0",
+  "description": "A low-energy task scheduler for JavaScript and TypeScript. Let your code chill.",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "npm run build:js && npm run build:types",
+    "build:js": "tsup",
+    "build:types": "tsc --declaration --emitDeclarationOnly --outDir dist",
+    "prepublishOnly": "npm run build && npm test",
+    "test": "vitest run",
+    "test:package": "node scripts/package-smoke-test.mjs",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "license": "GPL-3.0-only",
+  "author": {
+    "name": "x-name15",
+    "url": "https://github.com/x-name15"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/x-name15/ahko.git"
+  },
+  "homepage": "https://github.com/x-name15/ahko#readme",
+  "bugs": {
+    "url": "https://github.com/x-name15/ahko/issues"
+  },
+  "keywords": [
+    "scheduler",
+    "queue",
+    "concurrency",
+    "delay",
+    "abortsignal",
+    "async"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.13.0",
+    "tsup": "^8.3.6",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5"
+  }
+}