@pipedog/asyncio 0.1.0 → 0.2.0

package/dist/task.d.ts

@@ -19,48 +19,77 @@ export declare function isCancelledError(e: unknown): e is CancelledError;
 export declare function rethrowIfCancelled(e: unknown): void;
 /** The task the caller is running in, if any (asyncio.current_task). */
 export declare function currentTask(): Task<unknown> | undefined;
-type Waiter = (error: CancelledError) => void;
+type FutureState = "pending" | "fulfilled" | "rejected" | "cancelled";
+/**
+ * asyncio.Future: a result that becomes available later. Awaiting it (it is
+ * thenable) suspends the current task until it is done, unless it already is.
+ * Done callbacks run on the ready queue, never synchronously.
+ */
+export declare class Future<T = unknown> implements PromiseLike<T> {
+    #private;
+    done(): boolean;
+    cancelled(): boolean;
+    result(): T;
+    exception(): unknown;
+    setResult(value: T): void;
+    setException(error: unknown): void;
+    /** Cancel the future. Returns false if it is already done. */
+    cancel(message?: string): boolean;
+    addDoneCallback(callback: (future: this) => void): void;
+    removeDoneCallback(callback: (future: this) => void): number;
+    then<R1 = T, R2 = never>(onfulfilled?: ((value: T) => R1 | PromiseLike<R1>) | null, onrejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null): Promise<R1 | R2>;
+    /** @internal The CancelledError a cancelled future raises. */
+    _makeCancelledError(): CancelledError;
+    /** @internal Mark the future done and schedule its callbacks. */
+    _setDone(state: Exclude<FutureState, "pending">, value: T | undefined, error: unknown): void;
+}
+/**
+ * Await `future` from the current task (Future.__await__ plus the task's
+ * wakeup). A done future returns at once, without suspending. Otherwise the
+ * task resumes on the ready queue once the future is done, and cancelling
+ * the task meanwhile cancels the future.
+ */
+export declare function awaitFuture<T>(future: Future<T>): Promise<T>;
 export type TaskFn<T> = () => Promise<T> | T;
 /**
  * A unit of concurrent work, like asyncio.Task. Created with `createTask()`.
  * Awaiting a Task (it is thenable) is a cancellation point; cancelling the
  * awaiting task also cancels the awaited one, as in asyncio.
  */
-export declare class Task<T> implements PromiseLike<T> {
+export declare class Task<T> extends Future<T> {
     #private;
+    /** @internal The future this task is suspended on (Task._fut_waiter). */
+    _futWaiter: Future<unknown> | null;
     constructor(fn: TaskFn<T>, name?: string);
     get name(): string;
     /** asyncio Task.get_name() */
     getName(): string;
     setName(name: string): void;
-    /** Aborted when cancellation is requested. Pass it to fetch() and friends. */
+    /**
+     * Aborted when cancellation is requested. Pass it to fetch() and friends.
+     * Once every request is withdrawn with `uncancel()`, a fresh signal is used.
+     */
     get signal(): AbortSignal;
-    done(): boolean;
-    cancelled(): boolean;
     /** Number of pending cancellation requests (asyncio Task.cancelling()). */
     cancelling(): number;
     uncancel(): number;
-    result(): T;
-    exception(): unknown;
-    addDoneCallback(callback: (task: Task<T>) => void): void;
-    removeDoneCallback(callback: (task: Task<T>) => void): number;
-    /**
-     * Request cancellation. Returns false if the task is already done.
-     */
+    setResult(_value: T): void;
+    setException(_error: unknown): void;
+    /** Request cancellation. Returns false if the task is already done. */
     cancel(message?: string): boolean;
     /**
-     * Throw CancelledError if a cancellation request is pending. Every
-     * primitive calls this before suspending.
+     * Throw CancelledError if a cancellation request is pending. Primitives
+     * call this on their fast paths, so a task that resumes from a foreign
+     * await after being cancelled stops at the next one.
      */
     checkpoint(): void;
-    /** @internal Register the rejecter of the await this task is suspended on. */
-    _addWaiter(waiter: Waiter): void;
-    /** @internal */
-    _removeWaiter(waiter: Waiter): void;
     /** A promise that settles with the task, without being a cancellation point. */
     get promise(): Promise<T>;
-    then<R1 = T, R2 = never>(onfulfilled?: ((value: T) => R1 | PromiseLike<R1>) | null, onrejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null): Promise<R1 | R2>;
     toString(): string;
+    /** @internal Consume a pending cancellation request, returning its error. */
+    _takeCancelRequest(): CancelledError | undefined;
+    /** @internal The task suspends on `future` (Task.__step yielding a future). */
+    _block(future: Future<unknown>): void;
 }
 /**
  * Suspend the current task until `register` resolves or rejects, making the

package/dist/task.js

@@ -1,18 +1,27 @@
 // Copyright (c) 2026, pipedog contributors
 // SPDX-License-Identifier: BSD-2-Clause
 //
-// asyncio-style tasks with cooperative cancellation.
+// asyncio-style futures and tasks with cooperative cancellation.
+//
+// Scheduling follows asyncio (see loop.ts): a task runs until it awaits a
+// future that is not done. Completing a future queues its waiters' wakeups on
+// the ready queue instead of resuming them, so every fast path (awaiting a
+// done future, `get()` on a non-empty queue, `put()` on an unbounded one,
+// `wait()` on a set event) completes without letting another task run.
 //
 // Python delivers `CancelledError` *into* a coroutine at the await it is
 // suspended on. JavaScript cannot interrupt an arbitrary await, so we emulate
-// it: every primitive in this package (sleep, Event.wait, Queue.get, awaiting a
-// Task, waitFor, gather...) is a "cancellation point". When a task is
-// cancelled:
+// it. Every await on a Future (and so on every primitive in this package:
+// sleep, Event.wait, Queue.get, awaiting a Task, waitFor, gather...) is a
+// "cancellation point". When a task is cancelled:
 //
-//   - if it is suspended on a cancellation point, that await rejects with
-//     CancelledError right away (the request is consumed, as in asyncio);
-//   - otherwise the request stays pending and the next cancellation point the
-//     task reaches throws it;
+//   - if it is suspended on a future, that future is cancelled and the task
+//     resumes (on the ready queue, as in asyncio) with CancelledError; if it
+//     awaits another task, that task is cancelled and this one resumes when it
+//     finishes;
+//   - otherwise the request stays pending: a task already woken up gets the
+//     CancelledError when it resumes, and a task inside a foreign await gets
+//     it at the next cancellation point it reaches;
 //   - `task.signal` is aborted, so foreign awaits (fetch, WebSocket, SDKs) can
 //     be made cancellable by passing the signal or wrapping them in
 //     `abortable()`.
@@ -22,7 +31,7 @@
 /// <reference path="./async-hooks.d.ts" />
 // (The reference keeps the declaration with this file: packages that compile
 // it from source through the workspace exports don't include async-hooks.d.ts.)
-import { AsyncLocalStorage } from "node:async_hooks";
+import { callSoon, taskStorage } from "./loop.js";
 export class CancelledError extends Error {
     name = "CancelledError";
     constructor(message = "Task cancelled") {
@@ -51,10 +60,131 @@ export function rethrowIfCancelled(e) {
     if (e instanceof CancelledError)
         throw e;
 }
-const storage = new AsyncLocalStorage();
 /** The task the caller is running in, if any (asyncio.current_task). */
 export function currentTask() {
-    return storage.getStore();
+    return taskStorage.getStore();
+}
+/**
+ * asyncio.Future: a result that becomes available later. Awaiting it (it is
+ * thenable) suspends the current task until it is done, unless it already is.
+ * Done callbacks run on the ready queue, never synchronously.
+ */
+export class Future {
+    #state = "pending";
+    #result;
+    #error;
+    #cancelMessage;
+    #callbacks = [];
+    done() {
+        return this.#state !== "pending";
+    }
+    cancelled() {
+        return this.#state === "cancelled";
+    }
+    result() {
+        if (this.#state === "pending")
+            throw new InvalidStateError("Result is not set.");
+        if (this.#state === "fulfilled")
+            return this.#result;
+        if (this.#state === "cancelled")
+            throw this._makeCancelledError();
+        throw this.#error;
+    }
+    exception() {
+        if (this.#state === "pending")
+            throw new InvalidStateError("Exception is not set.");
+        if (this.#state === "cancelled")
+            throw this._makeCancelledError();
+        return this.#state === "rejected" ? this.#error : undefined;
+    }
+    setResult(value) {
+        if (this.#state !== "pending")
+            throw new InvalidStateError(`invalid state: ${this.#state}`);
+        this._setDone("fulfilled", value, undefined);
+    }
+    setException(error) {
+        if (this.#state !== "pending")
+            throw new InvalidStateError(`invalid state: ${this.#state}`);
+        this._setDone("rejected", undefined, error);
+    }
+    /** Cancel the future. Returns false if it is already done. */
+    cancel(message) {
+        if (this.#state !== "pending")
+            return false;
+        this.#cancelMessage = message;
+        this._setDone("cancelled", undefined, undefined);
+        return true;
+    }
+    addDoneCallback(callback) {
+        if (this.#state !== "pending") {
+            callSoon(() => callback(this));
+        }
+        else {
+            this.#callbacks.push(callback);
+        }
+    }
+    removeDoneCallback(callback) {
+        const before = this.#callbacks.length;
+        this.#callbacks = this.#callbacks.filter((c) => c !== callback);
+        return before - this.#callbacks.length;
+    }
+    // biome-ignore lint/suspicious/noThenProperty: Futures are awaitable by design, like asyncio.
+    then(onfulfilled, onrejected) {
+        return awaitFuture(this).then(onfulfilled, onrejected);
+    }
+    /** @internal The CancelledError a cancelled future raises. */
+    _makeCancelledError() {
+        if (this.#error instanceof CancelledError)
+            return this.#error;
+        return new CancelledError(this.#cancelMessage);
+    }
+    /** @internal Mark the future done and schedule its callbacks. */
+    _setDone(state, value, error) {
+        this.#state = state;
+        this.#result = value;
+        this.#error = error;
+        const callbacks = this.#callbacks;
+        this.#callbacks = [];
+        for (const callback of callbacks)
+            callSoon(() => callback(this));
+    }
+}
+/**
+ * Await `future` from the current task (Future.__await__ plus the task's
+ * wakeup). A done future returns at once, without suspending. Otherwise the
+ * task resumes on the ready queue once the future is done, and cancelling
+ * the task meanwhile cancels the future.
+ */
+export function awaitFuture(future) {
+    if (future.done()) {
+        try {
+            return Promise.resolve(future.result());
+        }
+        catch (e) {
+            return Promise.reject(e);
+        }
+    }
+    const task = currentTask();
+    return new Promise((resolve, reject) => {
+        future.addDoneCallback(() => {
+            if (task) {
+                task._futWaiter = null;
+                // A cancellation requested after the wakeup was queued wins (Task.__step).
+                const cancelled = task._takeCancelRequest();
+                if (cancelled) {
+                    reject(cancelled);
+                    return;
+                }
+            }
+            try {
+                resolve(future.result());
+            }
+            catch (e) {
+                reject(e);
+            }
+        });
+        task?._block(future);
+    });
 }
 let taskCounter = 0;
 /**
@@ -62,28 +192,44 @@ let taskCounter = 0;
  * Awaiting a Task (it is thenable) is a cancellation point; cancelling the
  * awaiting task also cancels the awaited one, as in asyncio.
  */
-export class Task {
+export class Task extends Future {
     #controller = new AbortController();
-    #promise;
-    #waiters = new Set();
-    #doneCallbacks = [];
     #name;
-    #state = "pending";
-    #result;
-    #error;
     #mustCancel = false;
     #cancelMessage;
     #cancelRequests = 0;
+    #promise;
+    /** @internal The future this task is suspended on (Task._fut_waiter). */
+    _futWaiter = null;
     constructor(fn, name) {
+        super();
         this.#name = name ?? `Task-${++taskCounter}`;
-        this.#promise = storage.run(this, async () => {
-            // Like asyncio, a task never starts running synchronously in the
-            // caller: it starts once the caller yields.
-            await Promise.resolve();
-            this.checkpoint();
-            return await fn();
+        let start;
+        const started = new Promise((resolve, reject) => {
+            start = { resolve, reject };
+        });
+        // Like asyncio, a task never starts running synchronously in the caller:
+        // its first step is scheduled on the ready queue.
+        callSoon(() => {
+            const cancelled = this._takeCancelRequest();
+            if (cancelled)
+                start.reject(cancelled);
+            else
+                start.resolve();
         });
-        this.#promise.then((value) => this.#settle("fulfilled", value, undefined), (error) => this.#settle(error instanceof CancelledError ? "cancelled" : "rejected", undefined, error));
+        taskStorage
+            .run(this, async () => {
+            await started;
+            return await fn();
+        })
+            .then((value) => {
+            // Cancelled right before returning: the task ends cancelled.
+            const cancelled = this._takeCancelRequest();
+            if (cancelled)
+                this._setDone("cancelled", undefined, cancelled);
+            else
+                this._setDone("fulfilled", value, undefined);
+        }, (error) => this._setDone(error instanceof CancelledError ? "cancelled" : "rejected", undefined, error));
     }
     get name() {
         return this.#name;
@@ -95,16 +241,13 @@ export class Task {
     setName(name) {
         this.#name = name;
     }
-    /** Aborted when cancellation is requested. Pass it to fetch() and friends. */
+    /**
+     * Aborted when cancellation is requested. Pass it to fetch() and friends.
+     * Once every request is withdrawn with `uncancel()`, a fresh signal is used.
+     */
     get signal() {
         return this.#controller.signal;
     }
-    done() {
-        return this.#state !== "pending";
-    }
-    cancelled() {
-        return this.#state === "cancelled";
-    }
     /** Number of pending cancellation requests (asyncio Task.cancelling()). */
     cancelling() {
         return this.#cancelRequests;
@@ -112,115 +255,78 @@ export class Task {
     uncancel() {
         if (this.#cancelRequests > 0)
             this.#cancelRequests--;
-        if (this.#cancelRequests === 0)
+        if (this.#cancelRequests === 0) {
             this.#mustCancel = false;
+            if (this.#controller.signal.aborted)
+                this.#controller = new AbortController();
+        }
         return this.#cancelRequests;
     }
-    result() {
-        if (this.#state === "pending")
-            throw new InvalidStateError("Result is not set.");
-        if (this.#state === "fulfilled")
-            return this.#result;
-        throw this.#error;
-    }
-    exception() {
-        if (this.#state === "pending")
-            throw new InvalidStateError("Exception is not set.");
-        if (this.#state === "cancelled")
-            throw this.#error;
-        return this.#state === "rejected" ? this.#error : undefined;
+    setResult(_value) {
+        throw new InvalidStateError("Task does not support setResult()");
     }
-    addDoneCallback(callback) {
-        if (this.done()) {
-            queueMicrotask(() => callback(this));
-        }
-        else {
-            this.#doneCallbacks.push(callback);
-        }
-    }
-    removeDoneCallback(callback) {
-        const before = this.#doneCallbacks.length;
-        for (let i = this.#doneCallbacks.length - 1; i >= 0; i--) {
-            if (this.#doneCallbacks[i] === callback)
-                this.#doneCallbacks.splice(i, 1);
-        }
-        return before - this.#doneCallbacks.length;
+    setException(_error) {
+        throw new InvalidStateError("Task does not support setException()");
     }
-    /**
-     * Request cancellation. Returns false if the task is already done.
-     */
+    /** Request cancellation. Returns false if the task is already done. */
     cancel(message) {
         if (this.done())
             return false;
         this.#cancelRequests++;
-        this.#cancelMessage = message;
         if (!this.#controller.signal.aborted) {
             this.#controller.abort(new CancelledError(message));
         }
-        if (this.#waiters.size > 0) {
-            // Deliver to the await the task is suspended on; consumed.
-            const waiters = [...this.#waiters];
-            this.#waiters.clear();
-            for (const waiter of waiters)
-                waiter(new CancelledError(message));
-        }
-        else {
-            this.#mustCancel = true;
-        }
+        // Cancel what the task is suspended on; it resumes with the outcome.
+        if (this._futWaiter?.cancel(message))
+            return true;
+        // Running, woken up but not resumed yet, or inside a foreign await.
+        this.#mustCancel = true;
+        this.#cancelMessage = message;
         return true;
     }
     /**
-     * Throw CancelledError if a cancellation request is pending. Every
-     * primitive calls this before suspending.
+     * Throw CancelledError if a cancellation request is pending. Primitives
+     * call this on their fast paths, so a task that resumes from a foreign
+     * await after being cancelled stops at the next one.
      */
     checkpoint() {
-        if (this.#mustCancel) {
-            this.#mustCancel = false;
-            throw new CancelledError(this.#cancelMessage);
-        }
-    }
-    /** @internal Register the rejecter of the await this task is suspended on. */
-    _addWaiter(waiter) {
-        this.#waiters.add(waiter);
-    }
-    /** @internal */
-    _removeWaiter(waiter) {
-        this.#waiters.delete(waiter);
+        const cancelled = this._takeCancelRequest();
+        if (cancelled)
+            throw cancelled;
     }
     /** A promise that settles with the task, without being a cancellation point. */
     get promise() {
+        if (!this.#promise) {
+            this.#promise = new Promise((resolve, reject) => {
+                this.addDoneCallback(() => {
+                    try {
+                        resolve(this.result());
+                    }
+                    catch (e) {
+                        reject(e);
+                    }
+                });
+            });
+            // Errors are observed through the task; never an unhandled rejection.
+            this.#promise.catch(() => { });
+        }
         return this.#promise;
     }
-    // biome-ignore lint/suspicious/noThenProperty: Tasks are awaitable by design, like asyncio.
-    then(onfulfilled, onrejected) {
-        const awaited = suspend((resolve, reject) => {
-            this.#promise.then(resolve, reject);
-            return () => { };
-        }, () => {
-            // asyncio: cancelling a task that awaits another task cancels the latter.
-            this.cancel();
-        });
-        return awaited.then(onfulfilled, onrejected);
-    }
     toString() {
         return this.#name;
     }
-    #settle(state, value, error) {
-        this.#state = state;
-        this.#result = value;
-        this.#error = error;
-        this.#waiters.clear();
-        const callbacks = this.#doneCallbacks.splice(0);
-        for (const callback of callbacks) {
-            try {
-                callback(this);
-            }
-            catch (e) {
-                queueMicrotask(() => {
-                    throw e;
-                });
-            }
-        }
+    /** @internal Consume a pending cancellation request, returning its error. */
+    _takeCancelRequest() {
+        if (!this.#mustCancel)
+            return undefined;
+        this.#mustCancel = false;
+        return new CancelledError(this.#cancelMessage);
+    }
+    /** @internal The task suspends on `future` (Task.__step yielding a future). */
+    _block(future) {
+        this._futWaiter = future;
+        if (this.#mustCancel && future.cancel(this.#cancelMessage))
+            this.#mustCancel = false;
     }
 }
 /**
@@ -229,47 +335,29 @@ export class Task {
  * registration (clear a timer, remove a listener...) when the wait is
  * cancelled. `onCancel` runs after the disposer, e.g. to cancel a child task.
  */
-export function suspend(register, onCancel) {
-    const task = currentTask();
+export async function suspend(register, onCancel) {
+    const future = new Future();
+    const dispose = register((value) => {
+        if (!future.done())
+            future.setResult(value);
+    }, (error) => {
+        if (!future.done())
+            future.setException(error);
+    });
     try {
-        task?.checkpoint();
+        return await awaitFuture(future);
     }
     catch (e) {
-        return Promise.reject(e);
-    }
-    return new Promise((resolve, reject) => {
-        let settled = false;
-        let dispose = () => { };
-        const waiter = (error) => {
-            if (settled)
-                return;
-            settled = true;
+        if (future.cancelled()) {
             dispose();
             onCancel?.();
-            reject(error);
-        };
-        task?._addWaiter(waiter);
-        dispose = register((value) => {
-            if (settled)
-                return;
-            settled = true;
-            task?._removeWaiter(waiter);
-            resolve(value);
-        }, (error) => {
-            if (settled)
-                return;
-            settled = true;
-            task?._removeWaiter(waiter);
-            reject(error);
-        });
-    });
+        }
+        throw e;
+    }
 }
 /** Create and schedule a task (asyncio.create_task). */
 export function createTask(fn, name) {
-    const task = new Task(fn, name);
-    // Errors are observed through the task; never surface as unhandled rejections.
-    task.promise.catch(() => { });
-    return task;
+    return new Task(fn, name);
 }
 /** Throw if the current task has a pending cancellation (an explicit `await asyncio.sleep(0)`). */
 export function checkCancelled() {
@@ -281,10 +369,15 @@ export function checkCancelled() {
  * The foreign operation keeps running unless it was also given `task.signal`.
  */
 export function abortable(promise) {
-    return suspend((resolve, reject) => {
-        promise.then(resolve, reject);
-        return () => { };
+    const future = new Future();
+    promise.then((value) => {
+        if (!future.done())
+            future.setResult(value);
+    }, (error) => {
+        if (!future.done())
+            future.setException(error);
     });
+    return awaitFuture(future);
 }
 /** The current task's abort signal, or a never-aborting one outside tasks. */
 export function currentSignal() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipedog/asyncio",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "asyncio-style tasks, cancellation, queues and events for JavaScript runtimes (Bun, Node, Workers).",
   "license": "BSD-2-Clause",
   "repository": {