@mrjacket/ahko 0.1.0

package/README.md

@@ -0,0 +1,157 @@
+<h1><img src=".github/images/ahko.png" width="80" height="80"> ahko</h1>
+
+[![npm version](https://img.shields.io/npm/v/@mrjacket/ahko.svg?color=success)](https://www.npmjs.com/package/@mrjacket/ahko)
+[![npm downloads](https://img.shields.io/npm/dm/@mrjacket/ahko.svg)](https://www.npmjs.com/package/@mrjacket/ahko)
+[![node](https://img.shields.io/node/v/@mrjacket/ahko.svg)](https://www.npmjs.com/package/@mrjacket/ahko)
+[![ci](https://github.com/x-name15/ahko/actions/workflows/ci.yml/badge.svg)](https://github.com/x-name15/ahko/actions/workflows/ci.yml)
+[![types](https://img.shields.io/npm/types/@mrjacket/ahko.svg)](https://www.npmjs.com/package/@mrjacket/ahko)
+[![license](https://img.shields.io/npm/l/@mrjacket/ahko.svg)](https://github.com/x-name15/ahko/blob/main/LICENSE)
+
+> Let your code chill.
+
+`@mrjacket/ahko` is a low-energy, production-grade task scheduler for JavaScript and TypeScript.
+
+Inspired by Aashii Kedarui / Ahko from *"The 100 Girlfriends Who Really, Really, Really, Really, Really Love You"*, AHKO brings calm, controlled execution to asynchronous workflows without rush, bursts, or unnecessary complexity.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @mrjacket/ahko
+```
+
+Requires **Node.js >= 22.12.0** or a modern browser environment. Zero external dependencies.
+
+---
+
+## ⚡ Quick Start
+
+```typescript
+import { Ahko } from "@mrjacket/ahko";
+
+const ahko = new Ahko({ concurrency: 2 });
+
+// Return types are inferred automatically
+const data = await ahko.schedule(async ({ signal, taskId }) => {
+  const response = await fetch("https://api.example.com/data", { signal });
+  return response.json();
+});
+```
+
+---
+
+## 🧘 Core Capabilities
+
+### 1. Concurrency Control
+
+Prevent bursts by capping the number of concurrently running asynchronous tasks:
+
+```typescript
+const ahko = new Ahko({ concurrency: 3 });
+
+// 20 operations scheduled at once -> 3 running, 17 queued in FIFO order
+const promises = Array.from({ length: 20 }, (_, i) =>
+  ahko.schedule(async () => {
+    await performWork(i);
+    return i;
+  })
+);
+
+const results = await Promise.all(promises);
+```
+
+### 2. Delayed Execution
+
+Wait calmly for a specified time before task execution begins:
+
+```typescript
+await ahko.schedule(
+  async () => {
+    console.log("Executed after chill window");
+  },
+  {
+    strategy: "delay",
+    delay: 1500, // milliseconds
+  }
+);
+```
+
+### 3. First-Class Cancellation (`AbortSignal`)
+
+AHKO provides native, cooperative cancellation:
+
+```typescript
+const controller = new AbortController();
+
+const taskPromise = ahko.schedule(
+  async ({ signal }) => {
+    return doHeavyOperation({ signal });
+  },
+  { signal: controller.signal }
+);
+
+// Cancel while pending: immediately dequeued and rejected with AhkoCancellationError
+// Cancel while running: signal triggers abort on the task context
+controller.abort();
+```
+
+### 4. Telemetry (`stats`)
+
+Inspect real-time scheduler state without synthetic metrics:
+
+```typescript
+const stats = ahko.stats();
+
+console.log(stats);
+// {
+//   activeTasks: 2,
+//   pendingTasks: 5,
+//   completedTasks: 42,
+//   failedTasks: 1,
+//   cancelledTasks: 2,
+//   timedOutTasks: 0,
+//   capacity: 3
+// }
+```
+
+---
+
+## 📖 API Reference
+
+### `new Ahko(options?: IAhkoOptions)`
+
+Creates an AHKO scheduler instance.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `concurrency` | `number` | `Infinity` | Maximum concurrent tasks allowed to run simultaneously. Must be $\ge 1$. |
+
+### `ahko.schedule<T>(task: ITask<T>, options?: IScheduleOptions): Promise<T>`
+
+Schedules an asynchronous task with full return type inference.
+
+- `task`: `(context: ITaskContext) => Promise<T> | T`
+- `options.strategy`: `"immediate"` (default) or `"delay"`.
+- `options.delay`: Delay in milliseconds when strategy is `"delay"`.
+- `options.signal`: Optional `AbortSignal` for cancellation.
+
+### `ahko.stats(): IAhkoStats`
+
+Returns a snapshot of current task counters and capacity.
+
+---
+
+## 🛡️ Errors
+
+- `AhkoError`: Base class for all scheduler errors.
+- `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.
+
+---
+
+## 📜 License
+
+[GNU General Public License v3.0 (GPL-3.0-only)](LICENSE) © [x-name15](https://github.com/x-name15)

package/dist/ahko.d.ts

@@ -0,0 +1,73 @@
+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";
+/**
+ * Ahko — Low-energy, production-grade asynchronous task scheduler.
+ *
+ * Coordinates execution timing, enforces concurrency limits, and cooperates
+ * natively with AbortSignal cancellation.
+ *
+ * @example
+ * ```typescript
+ * import { Ahko } from "@mrjacket/ahko";
+ *
+ * const ahko = new Ahko({ concurrency: 2 });
+ *
+ * const result = await ahko.schedule(async ({ signal, taskId }) => {
+ *   const res = await fetch("https://api.example.com", { signal });
+ *   return res.json();
+ * });
+ * ```
+ */
+export declare class Ahko {
+    /** Internal queue and concurrency manager */
+    private readonly queue;
+    /**
+     * Initializes a new Ahko scheduler instance.
+     *
+     * @param options - Optional scheduler configuration.
+     * @throws {AhkoConfigurationError} If concurrency is invalid (less than 1 or NaN).
+     *
+     * @example
+     * ```typescript
+     * const ahko = new Ahko({ concurrency: 4 });
+     * ```
+     */
+    constructor(options?: IAhkoOptions);
+    /**
+     * 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.
+     * @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.
+     *
+     * @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 }
+     * );
+     * ```
+     */
+    schedule<T>(task: ITask<T>, options?: IScheduleOptions): Promise<T>;
+    /**
+     * Retrieves real-time telemetry metrics from the scheduler.
+     *
+     * @returns An {@link IAhkoStats} snapshot of active, pending, completed, failed, cancelled, and timed out tasks.
+     *
+     * @example
+     * ```typescript
+     * const stats = ahko.stats();
+     * console.log(`Active: ${stats.activeTasks}, Pending: ${stats.pendingTasks}`);
+     * ```
+     */
+    stats(): IAhkoStats;
+}

package/dist/errors/ahko.error.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Base error class for all errors originating from the Ahko scheduler.
+ */
+export declare class AhkoError extends Error {
+    /**
+     * Creates a new AhkoError instance.
+     *
+     * @param message - Descriptive error message.
+     * @param options - Standard Error options including cause.
+     */
+    constructor(message: string, options?: ErrorOptions);
+}

package/dist/errors/cancellation.error.d.ts

@@ -0,0 +1,13 @@
+import { AhkoError } from "./ahko.error.js";
+/**
+ * Thrown when a task is cancelled before or during execution.
+ */
+export declare class AhkoCancellationError extends AhkoError {
+    /**
+     * Creates a new AhkoCancellationError.
+     *
+     * @param message - Reason for cancellation.
+     * @param options - Standard Error options including cause.
+     */
+    constructor(message?: string, options?: ErrorOptions);
+}

package/dist/errors/configuration.error.d.ts

@@ -0,0 +1,13 @@
+import { AhkoError } from "./ahko.error.js";
+/**
+ * Thrown when invalid configuration or scheduling options are provided.
+ */
+export declare class AhkoConfigurationError extends AhkoError {
+    /**
+     * Creates a new AhkoConfigurationError.
+     *
+     * @param message - Explanation of the invalid configuration parameter.
+     * @param options - Standard Error options including cause.
+     */
+    constructor(message: string, options?: ErrorOptions);
+}

package/dist/errors/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./ahko.error.js";
+export * from "./cancellation.error.js";
+export * from "./configuration.error.js";
+export * from "./queue.error.js";
+export * from "./timeout.error.js";

package/dist/errors/queue.error.d.ts

@@ -0,0 +1,13 @@
+import { AhkoError } from "./ahko.error.js";
+/**
+ * Thrown when an internal queue invariant is violated or queue limits are breached.
+ */
+export declare class AhkoQueueError extends AhkoError {
+    /**
+     * Creates a new AhkoQueueError.
+     *
+     * @param message - Explanation of the queue failure.
+     * @param options - Standard Error options including cause.
+     */
+    constructor(message: string, options?: ErrorOptions);
+}

package/dist/errors/timeout.error.d.ts

@@ -0,0 +1,13 @@
+import { AhkoError } from "./ahko.error.js";
+/**
+ * Thrown when a task exceeds its allotted timeout duration.
+ */
+export declare class AhkoTimeoutError extends AhkoError {
+    /**
+     * Creates a new AhkoTimeoutError.
+     *
+     * @param message - Explanation of timeout expiry.
+     * @param options - Standard Error options including cause.
+     */
+    constructor(message?: string, options?: ErrorOptions);
+}