@mrjacket/ahko 0.1.0 → 0.3.0

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

@@ -0,0 +1,52 @@
+/**
+ * Supported backoff algorithms for retry attempts.
+ */
+export type TRetryBackoff = "exponential" | "linear" | "none";
+/**
+ * Predicate function determining whether a specific error warrants a retry attempt.
+ *
+ * @param error - The error thrown by the failed attempt.
+ * @param attempt - The 1-based index of the attempt that just failed.
+ * @returns Boolean or Promise<boolean> indicating whether to retry.
+ */
+export type TRetryPredicate = (error: unknown, attempt: number) => boolean | Promise<boolean>;
+/**
+ * Options configuring automatic retry behavior for a scheduled task.
+ */
+export interface IRetryOptions {
+    /**
+     * Total number of execution attempts allowed (initial attempt + retries).
+     * For example, `attempts: 3` means 1 initial execution plus up to 2 retries.
+     * Must be an integer greater than or equal to 1.
+     * @default 1
+     */
+    attempts: number;
+    /**
+     * Backoff algorithm to apply between failed attempts.
+     * @default "exponential"
+     */
+    backoff?: TRetryBackoff;
+    /**
+     * Base delay in milliseconds used as the starting multiplier for backoff.
+     * Must be a non-negative number.
+     * @default 250
+     */
+    baseDelay?: number;
+    /**
+     * Maximum backoff delay cap in milliseconds to prevent unbounded growth.
+     * Must be a non-negative number greater than or equal to baseDelay.
+     * @default 10000
+     */
+    maxDelay?: number;
+    /**
+     * Whether to apply full jitter randomization to the calculated delay
+     * to distribute retry waves across concurrent tasks.
+     * @default false
+     */
+    jitter?: boolean;
+    /**
+     * Optional predicate filter to evaluate whether an error is retryable.
+     * If not provided, all errors (except cancellations) trigger a retry.
+     */
+    shouldRetry?: TRetryPredicate;
+}

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

@@ -5,9 +5,11 @@ export declare enum EScheduleStrategy {
     /** Execute as soon as a concurrency slot is available */
     IMMEDIATE = "immediate",
     /** Delay execution for a designated duration before queuing */
-    DELAY = "delay"
+    DELAY = "delay",
+    /** Execute during platform idle opportunities (requestIdleCallback in browser, setImmediate in Node.js) */
+    IDLE = "idle"
 }
 /**
  * Union type representing valid scheduling strategy identifiers.
  */
-export type TScheduleStrategy = EScheduleStrategy | "immediate" | "delay";
+export type TScheduleStrategy = EScheduleStrategy | "immediate" | "delay" | "idle";

package/dist/retry/backoff.d.ts

@@ -0,0 +1,18 @@
+import type { IRetryOptions } from "../models/retry.model.js";
+/**
+ * Default base delay for backoff calculations in milliseconds.
+ */
+export declare const DEFAULT_BASE_DELAY = 250;
+/**
+ * Default maximum delay ceiling for backoff calculations in milliseconds.
+ */
+export declare const DEFAULT_MAX_DELAY = 10000;
+/**
+ * Computes backoff delay in milliseconds for a retry attempt based on configured policy.
+ *
+ * @param attempt - 1-based index of the attempt that failed (1 for first failure, 2 for second, etc.).
+ * @param options - Retry configuration options.
+ * @param randomFn - Injectable random generator function (defaults to Math.random) for deterministic testing.
+ * @returns Delay duration in milliseconds before next attempt.
+ */
+export declare function calculateBackoff(attempt: number, options?: IRetryOptions, randomFn?: () => number): number;

package/dist/retry/index.d.ts

@@ -0,0 +1 @@
+export * from "./backoff.js";

package/dist/scheduler/idle-scheduler.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Handle returned by the IdleScheduler allowing cancellation of an idle request.
+ */
+export interface IIdleHandle {
+    /**
+     * Cancels the scheduled idle callback and cleans up platform resources.
+     */
+    cancel(): void;
+}
+/**
+ * Platform-agnostic scheduler for opportunistic idle task execution.
+ *
+ * Automatically detects and selects platform capabilities:
+ * 1. Browser: `requestIdleCallback` / `cancelIdleCallback` (with optional timeout)
+ * 2. Node.js: `setImmediate` / `clearImmediate` as low-priority primitive
+ * 3. Fallback: `setTimeout(..., 0)` / `clearTimeout`
+ */
+export declare class IdleScheduler {
+    /**
+     * Schedules a callback to execute during the next idle opportunity.
+     *
+     * @param callback - Function to invoke when idle opportunity arises.
+     * @param timeout - Optional max deadline in milliseconds to wait before invoking (browser only).
+     * @param runtime - Target runtime scope providing scheduling primitives (defaults to globalThis).
+     * @returns An {@link IIdleHandle} with a `cancel()` method for cleanup.
+     */
+    static schedule(callback: () => void, timeout?: number, runtime?: typeof globalThis): IIdleHandle;
+}

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

@@ -14,6 +14,12 @@ export declare class TaskQueue {
     private readonly activeRunners;
     /** Set of tasks currently in delay phase */
     private readonly delayedEntries;
+    /** Set of tasks currently awaiting an idle opportunity */
+    private readonly idleEntries;
+    /** Set of tasks currently awaiting a retry backoff timer */
+    private readonly retryEntries;
+    /** WeakMap associating task runners with their scheduling options */
+    private readonly runnerOptions;
     /** Cumulative completed tasks counter */
     private completedTasks;
     /** Cumulative failed tasks counter */
@@ -44,6 +50,11 @@ export declare class TaskQueue {
      * handling early cancellation safely.
      */
     private scheduleDelayed;
+    /**
+     * Schedules a task to be placed into the queue during an idle opportunity,
+     * handling early cancellation safely.
+     */
+    private scheduleIdle;
     /**
      * Pumps the queue by picking pending tasks and executing them
      * as long as concurrency capacity is available.
@@ -51,9 +62,13 @@ export declare class TaskQueue {
     private pump;
     /**
      * Internal execution of an active task runner.
-     * Settle caller promise strictly after stats and active status are updated.
      */
     private executeRunner;
+    /**
+     * Schedules a retry attempt following backoff delay,
+     * without holding a concurrency slot.
+     */
+    private scheduleRetry;
     /**
      * Returns telemetry snapshot for the scheduler.
      *

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

@@ -1,3 +1,4 @@
+import type { IRetryOptions } from "../models/retry.model.js";
 import { ETaskState } from "../models/state.model.js";
 import type { ITask } from "../models/task.model.js";
 /**
@@ -38,6 +39,8 @@ export declare class TaskRunner<T> {
      * Gets the current lifecycle state of the task.
      */
     get state(): ETaskState;
+    /** Current execution attempt count (1-indexed) */
+    attempt: number;
     /**
      * Resolves the deferred promise.
      *
@@ -50,6 +53,14 @@ export declare class TaskRunner<T> {
      * @param reason - Reason to reject with.
      */
     reject(reason: unknown): void;
+    /**
+     * Evaluates if the task should be retried following an execution failure.
+     *
+     * @param error - The error encountered during the attempt.
+     * @param retryOptions - Configured retry policy.
+     * @returns A promise resolving to true if retry should proceed, false otherwise.
+     */
+    canRetry(error: unknown, retryOptions?: IRetryOptions): Promise<boolean>;
     /**
      * Executes the task within an allocated concurrency slot.
      *

package/dist/version.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrjacket/ahko",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "A low-energy task scheduler for JavaScript and TypeScript. Let your code chill.",
   "type": "module",
   "main": "dist/index.cjs",
@@ -47,16 +47,35 @@
   },
   "keywords": [
     "scheduler",
+    "task-scheduler",
     "queue",
     "concurrency",
+    "concurrency-control",
     "delay",
+    "idle",
+    "requestidlecallback",
+    "retry",
+    "backoff",
+    "exponential-backoff",
+    "jitter",
+    "throttle",
+    "debounce",
+    "rate-limit",
     "abortsignal",
-    "async"
+    "abortcontroller",
+    "async",
+    "flow-control",
+    "task-runner",
+    "zero-dependencies",
+    "cooperative-scheduling",
+    "low-energy",
+    "typescript",
+    "100 kanojo"
   ],
   "devDependencies": {
-    "@types/node": "^22.13.0",
+    "@types/node": "^26.6.2",
     "tsup": "^8.3.6",
-    "typescript": "^5.7.3",
-    "vitest": "^3.0.5"
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.1"
   }
 }