time-queues 1.2.4 → 1.3.1

package/llms.txt

@@ -0,0 +1,95 @@
+# time-queues
+
+> Lightweight async task scheduling and concurrency control for JavaScript: schedulers, idle/frame/limited queues, throttle, debounce, batch, page lifecycle, random delays.
+
+- NPM: https://npmjs.org/package/time-queues
+- GitHub: https://github.com/uhop/time-queues
+- Wiki: https://github.com/uhop/time-queues/wiki
+- License: BSD-3-Clause
+
+## Install
+
+```bash
+npm install time-queues
+```
+
+## Quick start
+
+```js
+import sleep from 'time-queues/sleep.js';
+import {Scheduler, repeat} from 'time-queues/Scheduler.js';
+import {batch} from 'time-queues/batch.js';
+
+// Simple delay
+await sleep(1000);
+
+// Run a task every 5 seconds
+const scheduler = new Scheduler();
+scheduler.enqueue(repeat(({task, scheduler}) => {
+  console.log('tick');
+}, 5000), 5000);
+
+// Fetch URLs, max 3 at a time
+const results = await batch(
+  urls.map(url => () => fetch(url).then(r => r.json())),
+  3
+);
+```
+
+## Modules
+
+### Queues
+
+- **Scheduler** (`time-queues/Scheduler.js`) — time-based task scheduling with delays, dates, and repeats. Extends MicroTaskQueue. Uses a min-heap. Exports: `Scheduler`, `Task`, `repeat(fn, delay)`, `scheduler` (global instance).
+- **IdleQueue** (`time-queues/IdleQueue.js`) — run tasks during browser idle periods via `requestIdleCallback()`. Extends ListQueue. Exports: `IdleQueue`, `idleQueue` (global instance), `defer(fn)`.
+- **FrameQueue** (`time-queues/FrameQueue.js`) — run tasks in animation frames via `requestAnimationFrame()`. Extends ListQueue. Exports: `FrameQueue`, `frameQueue` (global instance).
+- **LimitedQueue** (`time-queues/LimitedQueue.js`) — concurrency-controlled async queue. Extends ListQueue. Exports: `LimitedQueue`, `Task`.
+- **PageWatcher** (`time-queues/PageWatcher.js`) — react to page lifecycle changes (active, passive, hidden, frozen, terminated). Extends ListQueue. Exports: `PageWatcher`, `watchStates(states, fn)`, `pageWatcher` (global instance).
+
+### Utility functions
+
+- **sleep** (`time-queues/sleep.js`) — `sleep(ms | Date): Promise<void>`. Promise-based delay.
+- **defer** (`time-queues/defer.js`) — `defer(fn): void`. Execute on next tick via `requestIdleCallback`/`setImmediate`/`setTimeout`. Also exports `scheduleDefer(fn): Promise`.
+- **throttle** (`time-queues/throttle.js`) — `throttle(fn, ms): fn`. Rate-limit: execute immediately, ignore calls until timeout expires.
+- **debounce** (`time-queues/debounce.js`) — `debounce(fn, ms): fn`. Delay until input stabilizes.
+- **sample** (`time-queues/sample.js`) — `sample(fn, ms): fn`. Execute at regular intervals with last seen args.
+- **audit** (`time-queues/audit.js`) — `audit(fn, ms): fn`. Collect then execute after delay with last seen args.
+- **batch** (`time-queues/batch.js`) — `batch(fns, limit?): Promise<results[]>`. Run async operations with concurrency limit (default: 5).
+
+### Supporting classes
+
+- **Throttler** (`time-queues/Throttler.js`) — key-based rate limiting with vacuum cleanup. Methods: `getDelay(key)`, `wait(key)`, `startVacuum()`, `stopVacuum()`.
+- **Retainer** (`time-queues/Retainer.js`) — resource lifecycle management with reference counting. Methods: `get(): Promise<value>`, `release(): Promise<void>`.
+- **Counter** (`time-queues/Counter.js`) — numeric counter with async waiting. Methods: `increment()`, `decrement()`, `advance(delta)`, `waitForZero()`, `waitFor(target)`.
+- **CancelTaskError** (`time-queues/CancelTaskError.js`) — `Error` subclass for task cancellation signals.
+
+### Base classes
+
+- **MicroTask** (`time-queues/MicroTask.js`) — base task unit with lazy promise creation. Methods: `makePromise()`, `resolve(value)`, `cancel(error)`.
+- **MicroTaskQueue** (`time-queues/MicroTaskQueue.js`) — abstract queue base class. Methods: `enqueue(fn)`, `dequeue(task)`, `schedule(fn)`, `clear()`, `pause()`, `resume()`.
+- **ListQueue** (`time-queues/ListQueue.js`) — linked-list queue implementation extending MicroTaskQueue. Adds `startQueue()` lifecycle.
+
+### Random utilities
+
+- **random-dist** (`time-queues/random-dist.js`) — `uniform(min, max)`, `normal(mean, stdDev, skewness?)`, `expo(lambda)`, `pareto(min, alpha)`.
+- **random-sleep** (`time-queues/random-sleep.js`) — `randomUniformSleep(min, max)`, `randomNormalSleep(mean, stdDev)`, `randomExpoSleep(lambda, scale)`, `randomParetoSleep(min, ratio)`, `randomSleep(max)`. Each returns `() => Promise<void>`.
+
+### Page load helpers
+
+- **whenDomLoaded** (`time-queues/when-dom-loaded.js`) — `whenDomLoaded(fn)`. Also exports `scheduleWhenDomLoaded(fn): Promise`, `remove(fn): boolean`.
+- **whenLoaded** (`time-queues/when-loaded.js`) — `whenLoaded(fn)`. Also exports `scheduleWhenLoaded(fn): Promise`, `remove(fn): boolean`.
+
+## Key concepts
+
+- All modules are **ESM** with `import ... from 'time-queues/<module>.js'`.
+- **Inheritance**: `MicroTaskQueue` → `ListQueue` → `IdleQueue`/`FrameQueue`/`LimitedQueue`/`PageWatcher`. `Scheduler` extends `MicroTaskQueue` directly.
+- **Lazy promises** — only created when `.makePromise()` is called or via `schedule()`.
+- **Clean cancellation** — all tasks support cancellation via `CancelTaskError`.
+- **Graceful degradation** — feature detection for browser APIs, works in Node.js/Bun/Deno.
+- **TypeScript** — built-in `.d.ts` declarations for all modules.
+
+## Links
+
+- Docs: https://github.com/uhop/time-queues/wiki
+- npm: https://www.npmjs.com/package/time-queues
+- Full LLM reference: https://github.com/uhop/time-queues/blob/master/llms-full.txt

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "time-queues",
-  "version": "1.2.4",
-  "description": "Time queues to organize multitasking and scheduled tasks.",
+  "version": "1.3.1",
+  "description": "Lightweight async task scheduling and concurrency control: schedulers, idle/frame/limited queues, throttle, debounce, batch, page lifecycle, random delays. Browsers, Node.js, Deno, Bun.",
   "type": "module",
   "types": "./src/index.d.ts",
   "exports": {
@@ -12,14 +12,23 @@
     "test:bun": "tape6-bun --flags FO",
     "test:deno": "tape6-deno --flags FO",
     "test:proc": "tape6-proc --flags FO",
-    "test:proc:bun": "bun run `npx tape6-proc --self` --flags FO",
-    "test:proc:deno": "deno run -A `npx tape6-proc --self` --flags FO --runFileArgs -A",
+    "test:proc:bun": "bun run `tape6-proc --self` --flags FO",
+    "test:proc:deno": "deno run -A `tape6-proc --self` --flags FO -r -A",
+    "test:seq": "tape6-seq --flags FO",
+    "test:seq:bun": "bun run `tape6-seq --self` --flags FO",
+    "test:seq:deno": "deno run -A `tape6-seq --self` --flags FO",
     "ts-check": "tsc --noEmit",
     "ts-test": "tape6 --flags FO '/ts-tests/test-*.*ts'",
     "ts-test:bun": "tape6-bun --flags FO '/ts-tests/test-*.*ts'",
     "ts-test:deno": "tape6-deno --flags FO '/ts-tests/test-*.*ts'",
-    "lint": "prettier --check src/ tests/ wiki/",
-    "lint:fix": "prettier --write src/ tests/ wiki/",
+    "ts-test:proc": "tape6-proc --flags FO '/ts-tests/test-*.*ts'",
+    "ts-test:proc:bun": "bun run `tape6-proc --self` --flags FO '/ts-tests/test-*.*ts'",
+    "ts-test:proc:deno": "deno run -A `tape6-proc --self` --flags FO -r -A '/ts-tests/test-*.*ts'",
+    "ts-test:seq": "tape6-seq --flags FO '/ts-tests/test-*.*ts'",
+    "ts-test:seq:bun": "bun run `tape6-seq --self` --flags FO '/ts-tests/test-*.*ts'",
+    "ts-test:seq:deno": "deno run -A `tape6-seq --self` --flags FO '/ts-tests/test-*.*ts'",
+    "lint": "prettier --check .",
+    "lint:fix": "prettier --write .",
     "start": "tape6-server --trace"
   },
   "repository": {
@@ -27,9 +36,25 @@
     "url": "git+ssh://git@github.com/uhop/time-queues.git"
   },
   "keywords": [
+    "scheduler",
+    "task-queue",
+    "async-queue",
+    "concurrency",
+    "throttle",
+    "debounce",
+    "rate-limit",
+    "batch",
+    "sleep",
+    "defer",
+    "idle-queue",
+    "requestIdleCallback",
+    "requestAnimationFrame",
+    "page-lifecycle",
     "timer",
     "time",
-    "queue"
+    "queue",
+    "esm",
+    "typescript"
   ],
   "author": "Eugene Lazutkin <eugene.lazutkin@gmail.com> (https://www.lazutkin.com/)",
   "funding": "https://github.com/sponsors/uhop",
@@ -37,11 +62,16 @@
   "bugs": {
     "url": "https://github.com/uhop/time-queues/issues"
   },
+  "github": "https://github.com/uhop/time-queues",
   "homepage": "https://github.com/uhop/time-queues#readme",
+  "llms": "https://raw.githubusercontent.com/uhop/time-queues/master/llms.txt",
+  "llmsFull": "https://raw.githubusercontent.com/uhop/time-queues/master/llms-full.txt",
   "files": [
     "/src",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "llms.txt",
+    "llms-full.txt"
   ],
   "tape6": {
     "tests": [
@@ -56,12 +86,13 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^25.0.10",
-    "tape-six": "^1.4.5",
-    "tape-six-proc": "^1.1.6",
+    "@types/node": "^25.3.0",
+    "prettier": "^3.8.1",
+    "tape-six": "^1.7.2",
+    "tape-six-proc": "^1.2.3",
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "list-toolkit": "^2.2.5"
+    "list-toolkit": "^2.3.0"
   }
 }

package/src/CancelTaskError.d.ts

@@ -2,7 +2,8 @@
  * A cancellation error that is thrown when a microtask is canceled.
  */
 export declare class CancelTaskError extends Error {
-  constructor();
+  name: 'CancelTaskError';
+  constructor(message?: string, options?: ErrorOptions);
 }
 
 export default CancelTaskError;

package/src/CancelTaskError.js

@@ -1,10 +1,8 @@
 // @ts-self-types="./CancelTaskError.d.ts"
 
-'use strict';
-
 export class CancelTaskError extends Error {
-  constructor() {
-    super('Task was canceled');
+  constructor(message = 'Task was canceled', options) {
+    super(message, options);
     this.name = 'CancelTaskError';
     if (Error.captureStackTrace) {
       Error.captureStackTrace(this, CancelTaskError);

package/src/Counter.d.ts

@@ -15,7 +15,6 @@ export declare class Counter {
 
   /**
    * Gets the current value of the counter.
-   * @returns The current value of the counter.
    */
   get value(): number;
 

package/src/Counter.js

@@ -1,7 +1,5 @@
 // @ts-self-types="./Counter.d.ts"
 
-'use strict';
-
 export class Counter {
   constructor(initial = 0) {
     this.count = initial;

package/src/FrameQueue.d.ts

@@ -44,7 +44,7 @@ export declare class FrameQueue extends ListQueue {
 
   /**
    * Schedules a task to run in the next frame.
-   * @param fn The function to execute. If `undefined` or `null`, the task's promise will be resolved with function's arguments. Otherwise, it is resolved with the function's return value.
+   * @param fn The function to execute. If `undefined` or `null`, the task's promise will be resolved with the function's arguments. Otherwise, it is resolved with the function's return value.
    * @returns The task object.
    */
   schedule(
@@ -82,4 +82,4 @@ export declare class FrameQueue extends ListQueue {
  */
 export const frameQueue: FrameQueue;
 
-export default FrameQueue;
+export default frameQueue;

package/src/FrameQueue.js

@@ -1,7 +1,5 @@
 // @ts-self-types="./FrameQueue.d.ts"
 
-'use strict';
-
 import List from 'list-toolkit/list.js';
 import ListQueue from './ListQueue.js';
 

package/src/IdleQueue.d.ts

@@ -51,7 +51,7 @@ export declare class IdleQueue extends ListQueue {
 
   /**
    * Schedules a task to run in the next idle period.
-   * @param fn The function to execute. If `undefined` or `null`, the task's promise will be resolved with function's arguments. Otherwise, it is resolved with the function's return value.
+   * @param fn The function to execute. If `undefined` or `null`, the task's promise will be resolved with the function's arguments. Otherwise, it is resolved with the function's return value.
    * @returns The task object.
    */
   schedule(
@@ -96,4 +96,4 @@ export const defer: (
   fn: ({deadline: IdleDeadline, task: Task, queue: IdleQueue}) => unknown
 ) => Task;
 
-export default IdleQueue;
+export default idleQueue;

package/src/IdleQueue.js

@@ -1,7 +1,5 @@
 // @ts-self-types="./IdleQueue.d.ts"
 
-'use strict';
-
 import List from 'list-toolkit/list.js';
 import ListQueue from './ListQueue.js';
 

package/src/LimitedQueue.d.ts

@@ -0,0 +1,104 @@
+import {ListQueue, Task} from './ListQueue';
+
+export {Task};
+
+export declare class LimitedQueue extends ListQueue {
+  /**
+   * Whether the queue is paused.
+   */
+  paused: boolean;
+
+  /**
+   * The function that stops the queue.
+   * It is used internally by `pause()` and `resume()`.
+   */
+  stopQueue: (() => void) | null;
+
+  /**
+   * Creates a new limited queue.
+   * @param limit The maximum number of tasks that can be run in parallel.
+   * @param paused Whether the queue should start paused.
+   */
+  constructor(limit: number, paused?: boolean);
+
+  /**
+   * Whether the queue is empty.
+   */
+  get isEmpty(): boolean;
+
+  /**
+   * Get the maximum number of tasks that can be run in parallel.
+   */
+  get taskLimit(): number;
+
+  /**
+   * Set the maximum number of tasks that can be run in parallel.
+   * @param limit The new maximum number of tasks that can be run in parallel. Setting a higher limit may immediately start additional tasks.
+   */
+  set taskLimit(limit: number);
+
+  /**
+   * Get the number of currently active tasks.
+   */
+  get activeTasks(): number;
+
+  /**
+   * Whether the queue is idle.
+   */
+  get isIdle(): boolean;
+
+  /**
+   * Waits for the queue to become idle.
+   * @returns A promise that resolves when the queue becomes idle. If the queue is already idle, the promise is resolved immediately.
+   */
+  waitForIdle(): Promise<void>;
+
+  /**
+   * Enqueues a microtask.
+   * @param fn The function to execute when the microtask is scheduled.
+   * @returns The enqueued microtask.
+   */
+  enqueue(fn: () => unknown): Task;
+
+  /**
+   * Dequeues a microtask.
+   * @param task The microtask to dequeue.
+   * @returns The queue.
+   */
+  dequeue(task: Task): this;
+
+  /**
+   * Schedules a microtask.
+   * @param fn The function to execute. If `undefined` or `null`, the task's promise will be resolved with the function's arguments. Otherwise, it is resolved with the function's return value.
+   * @returns The task object.
+   */
+  schedule(fn: (() => unknown) | null | undefined): Task;
+
+  /**
+   * Clears the queue.
+   * @returns The queue.
+   */
+  clear(): this;
+
+  /**
+   * Pauses the queue.
+   * @returns The queue.
+   */
+  pause(): this;
+
+  /**
+   * Resumes the queue.
+   * @returns The queue.
+   */
+  resume(): this;
+
+  /**
+   * Starts the queue.
+   * It is used internally by `resume()`.
+   * It is meant to be overridden in subclasses.
+   * @returns The function that stops the queue.
+   */
+  startQueue(): (() => void) | null;
+}
+
+export default LimitedQueue;

package/src/LimitedQueue.js

@@ -0,0 +1,78 @@
+// @ts-self-types="./LimitedQueue.d.ts"
+
+import ListQueue from './ListQueue.js';
+
+export class LimitedQueue extends ListQueue {
+  #taskLimit;
+  #activeTasks;
+  #idleWaiters;
+
+  constructor(limit, paused) {
+    super(paused);
+    this.#taskLimit = limit;
+    this.#activeTasks = 0;
+    this.#idleWaiters = [];
+  }
+
+  get taskLimit() {
+    return this.#taskLimit;
+  }
+
+  set taskLimit(limit) {
+    this.#taskLimit = Math.max(1, limit);
+    this.#processTasks();
+  }
+
+  get activeTasks() {
+    return this.#activeTasks;
+  }
+
+  get isIdle() {
+    return !this.#activeTasks && this.list.isEmpty;
+  }
+
+  waitForIdle() {
+    return new Promise(resolve => {
+      if (this.isIdle) {
+        resolve();
+      } else {
+        this.#idleWaiters.push(resolve);
+      }
+    });
+  }
+
+  startQueue() {
+    this.#processTasks();
+    return null;
+  }
+
+  #processTasks() {
+    if (this.paused) return;
+    if (this.isIdle) {
+      const waiters = this.#idleWaiters;
+      this.#idleWaiters = [];
+      waiters.forEach(resolve => resolve());
+      return;
+    }
+    while (this.#activeTasks < this.#taskLimit && !this.list.isEmpty) {
+      const task = this.list.popFront();
+      ++this.#activeTasks;
+      LimitedQueue.wrap(() => task.fn({task, queue: this})).finally(() => {
+        --this.#activeTasks;
+        this.#processTasks();
+      });
+    }
+  }
+
+  static wrap(fn) {
+    return new Promise((resolve, reject) => {
+      try {
+        resolve(fn());
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+}
+
+export default LimitedQueue;

package/src/ListQueue.d.ts

@@ -45,7 +45,7 @@ export declare class ListQueue extends MicroTaskQueue {
 
   /**
    * Schedules a microtask.
-   * @param fn The function to execute. If `undefined` or `null`, the task's promise will be resolved with function's arguments. Otherwise, it is resolved with the function's return value.
+   * @param fn The function to execute. If `undefined` or `null`, the task's promise will be resolved with the function's arguments. Otherwise, it is resolved with the function's return value.
    * @returns The task object.
    */
   schedule(fn: (() => unknown) | null | undefined): MicroTask;
@@ -82,9 +82,4 @@ export declare class ListQueue extends MicroTaskQueue {
  */
 export declare type Task = MicroTask;
 
-/**
- * A task for list queues with a promise.
- */
-export declare type TaskWithPromise = MicroTaskWithPromise;
-
 export default ListQueue;

package/src/ListQueue.js

@@ -1,14 +1,20 @@
 // @ts-self-types="./ListQueue.d.ts"
 
-'use strict';
-
 import List from 'list-toolkit/list.js';
 import MicroTaskQueue from './MicroTaskQueue.js';
 
+/**
+ * ListQueue extends MicroTaskQueue with linked-list task storage.
+ * AI-NOTE: This is the concrete base class most specialized queues extend.
+ * Key pattern: startQueue() returns a stop function (or null if not started).
+ * @see IdleQueue, FrameQueue, LimitedQueue, Scheduler - All extend ListQueue
+ */
 export class ListQueue extends MicroTaskQueue {
   constructor(paused) {
     super(paused);
+    // AI-NOTE: Using list-toolkit List for O(1) push/pop operations
     this.list = new List();
+    // AI-NOTE: stopQueue holds the stop function returned by startQueue(), or null
     this.stopQueue = null;
   }
 
@@ -19,6 +25,7 @@ export class ListQueue extends MicroTaskQueue {
   pause() {
     if (!this.paused) {
       super.pause();
+      // AI-NOTE: Pattern: call stop function, then null it
       if (this.stopQueue) this.stopQueue = (this.stopQueue(), null);
     }
     return this;
@@ -27,6 +34,7 @@ export class ListQueue extends MicroTaskQueue {
   resume() {
     if (this.paused) {
       super.resume();
+      // AI-NOTE: Auto-start processing if tasks exist and not already running
       if (!this.list.isEmpty) {
         this.stopQueue = this.startQueue();
       }
@@ -37,6 +45,7 @@ export class ListQueue extends MicroTaskQueue {
   enqueue(fn) {
     const task = super.enqueue(fn);
     this.list.pushBack(task);
+    // AI-NOTE: Auto-start queue on first task if not paused and not running
     if (!this.paused && !this.stopQueue) this.stopQueue = this.startQueue();
     return task;
   }
@@ -44,6 +53,7 @@ export class ListQueue extends MicroTaskQueue {
   dequeue(task) {
     task.cancel();
     this.list.removeNode(task);
+    // AI-NOTE: Auto-stop queue when empty (unless paused)
     if (!this.paused && this.list.isEmpty && this.stopQueue)
       this.stopQueue = (this.stopQueue(), null);
     return this;
@@ -60,7 +70,12 @@ export class ListQueue extends MicroTaskQueue {
     return this;
   }
 
-  // API to be overridden in subclasses
+  /**
+   * Start processing the queue - MUST be overridden by subclasses.
+   * AI-NOTE: This is the abstract method pattern - base returns null.
+   * Subclasses return a function that stops the processing.
+   * @returns {Function|null} Stop function or null if not started
+   */
   startQueue() {
     return null;
   }

package/src/MicroTask.d.ts

@@ -31,6 +31,11 @@ export declare class MicroTask {
    */
   get promise(): Promise<unknown> | null;
 
+  /**
+   * Whether the microtask has been settled (resolved or canceled).
+   */
+  get settled(): boolean;
+
   /**
    * Resolves the microtask, if a promise is created.
    * @param value The value to resolve the microtask with.
@@ -42,9 +47,10 @@ export declare class MicroTask {
    * Cancels the microtask, if a promise is created.
    * If the microtask is canceled, the promise will be rejected with a CancelTaskError.
    * It can be overridden in subclasses.
+   * @param error The optional error to use as the cause of the cancellation.
    * @returns The microtask.
    */
-  cancel(): this;
+  cancel(error?: Error): this;
 }
 
 export default MicroTask;

package/src/MicroTask.js

@@ -1,43 +1,75 @@
 // @ts-self-types="./MicroTask.d.ts"
 
-'use strict';
-
 import CancelTaskError from './CancelTaskError.js';
 
+/**
+ * Base class for deferred task execution with lazy promise creation.
+ * AI-NOTE: Promises are created lazily via makePromise() - not in constructor.
+ * This allows tasks to be created without immediate promise overhead.
+ */
 export class MicroTask {
   #promise;
   #resolve;
   #reject;
+  #settled;
   constructor(fn) {
     this.fn = fn;
+    // AI-NOTE: Private fields initialized to null - lazy initialization pattern
     this.#promise = null;
     this.#resolve = null;
     this.#reject = null;
+    this.#settled = false;
     this.isCanceled = false;
   }
+  // AI-NOTE: Returns null until makePromise() is called - this is intentional
   get promise() {
     return this.#promise;
   }
+  get settled() {
+    return this.#settled;
+  }
+  /**
+   * Creates the promise and resolution functions.
+   * AI-NOTE: Uses Promise.withResolvers() when available (modern environments),
+   * falls back to manual Promise constructor for broader compatibility.
+   */
   makePromise() {
-    this.#promise = new Promise((resolve, reject) => {
-      this.#resolve = resolve;
-      this.#reject = reject;
-    });
+    if (this.#promise) return this;
+    if (typeof Promise.withResolvers == 'function') {
+      ({
+        promise: this.#promise,
+        resolve: this.#resolve,
+        reject: this.#reject
+      } = Promise.withResolvers());
+    } else {
+      this.#promise = new Promise((resolve, reject) => {
+        this.#resolve = resolve;
+        this.#reject = reject;
+      });
+    }
     return this;
   }
   resolve(value) {
-    if (!this.#resolve) return;
-    this.#resolve(value);
-    this.#resolve = null;
-    this.#reject = null;
+    if (this.#resolve) {
+      this.#resolve(value);
+      this.#resolve = null;
+      this.#reject = null;
+      this.#settled = true;
+    }
     return this;
   }
-  cancel() {
-    if (!this.#reject) return;
+  /**
+   * Cancel the task with optional error cause.
+   * AI-NOTE: Always rejects with CancelTaskError to distinguish from other errors.
+   */
+  cancel(error) {
     this.isCanceled = true;
-    this.#reject(new CancelTaskError());
-    this.#resolve = null;
-    this.#reject = null;
+    if (this.#reject) {
+      this.#reject(new CancelTaskError(undefined, error ? {cause: error} : undefined));
+      this.#resolve = null;
+      this.#reject = null;
+      this.#settled = true;
+    }
     return this;
   }
 }