@pipedog/asyncio 0.0.0 → 0.2.0

package/dist/task.d.ts

@@ -0,0 +1,114 @@
+export declare class CancelledError extends Error {
+    name: string;
+    constructor(message?: string);
+}
+export declare class TimeoutError extends Error {
+    name: string;
+    constructor(message?: string);
+}
+export declare class InvalidStateError extends Error {
+    name: string;
+}
+/** Whether `e` is a cancellation. Use it to re-throw in broad `catch` blocks. */
+export declare function isCancelledError(e: unknown): e is CancelledError;
+/**
+ * Re-throw `e` if it is a cancellation. Python's `except Exception` does not
+ * catch `CancelledError` (it is a BaseException); JavaScript's `catch` catches
+ * everything, so ported `except Exception` blocks start with this call.
+ */
+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 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> 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.
+     * Once every request is withdrawn with `uncancel()`, a fresh signal is used.
+     */
+    get signal(): AbortSignal;
+    /** Number of pending cancellation requests (asyncio Task.cancelling()). */
+    cancelling(): number;
+    uncancel(): number;
+    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. 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;
+    /** A promise that settles with the task, without being a cancellation point. */
+    get promise(): Promise<T>;
+    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
+ * wait a cancellation point. `register` returns a disposer that undoes the
+ * 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 declare function suspend<T>(register: (resolve: (value: T) => void, reject: (error: unknown) => void) => () => void, onCancel?: () => void): Promise<T>;
+/** Create and schedule a task (asyncio.create_task). */
+export declare function createTask<T>(fn: TaskFn<T>, name?: string): Task<T>;
+/** Throw if the current task has a pending cancellation (an explicit `await asyncio.sleep(0)`). */
+export declare function checkCancelled(): void;
+/**
+ * Await a foreign promise (fetch, SDK call...) as a cancellation point: if the
+ * current task is cancelled while waiting, this rejects with CancelledError.
+ * The foreign operation keeps running unless it was also given `task.signal`.
+ */
+export declare function abortable<T>(promise: PromiseLike<T>): Promise<T>;
+/** The current task's abort signal, or a never-aborting one outside tasks. */
+export declare function currentSignal(): AbortSignal;
+export {};
+//# sourceMappingURL=task.d.ts.map

package/dist/task.js

@@ -0,0 +1,386 @@
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// 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 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 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()`.
+//
+// The current task is tracked with AsyncLocalStorage, which Bun, Node, Deno
+// and Cloudflare Workers (nodejs_compat) all provide.
+/// <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 { callSoon, taskStorage } from "./loop.js";
+export class CancelledError extends Error {
+    name = "CancelledError";
+    constructor(message = "Task cancelled") {
+        super(message);
+    }
+}
+export class TimeoutError extends Error {
+    name = "TimeoutError";
+    constructor(message = "Timed out") {
+        super(message);
+    }
+}
+export class InvalidStateError extends Error {
+    name = "InvalidStateError";
+}
+/** Whether `e` is a cancellation. Use it to re-throw in broad `catch` blocks. */
+export function isCancelledError(e) {
+    return e instanceof CancelledError;
+}
+/**
+ * Re-throw `e` if it is a cancellation. Python's `except Exception` does not
+ * catch `CancelledError` (it is a BaseException); JavaScript's `catch` catches
+ * everything, so ported `except Exception` blocks start with this call.
+ */
+export function rethrowIfCancelled(e) {
+    if (e instanceof CancelledError)
+        throw e;
+}
+/** The task the caller is running in, if any (asyncio.current_task). */
+export function currentTask() {
+    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;
+/**
+ * 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 class Task extends Future {
+    #controller = new AbortController();
+    #name;
+    #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}`;
+        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();
+        });
+        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;
+    }
+    /** asyncio Task.get_name() */
+    getName() {
+        return this.#name;
+    }
+    setName(name) {
+        this.#name = name;
+    }
+    /**
+     * 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;
+    }
+    /** Number of pending cancellation requests (asyncio Task.cancelling()). */
+    cancelling() {
+        return this.#cancelRequests;
+    }
+    uncancel() {
+        if (this.#cancelRequests > 0)
+            this.#cancelRequests--;
+        if (this.#cancelRequests === 0) {
+            this.#mustCancel = false;
+            if (this.#controller.signal.aborted)
+                this.#controller = new AbortController();
+        }
+        return this.#cancelRequests;
+    }
+    setResult(_value) {
+        throw new InvalidStateError("Task does not support setResult()");
+    }
+    setException(_error) {
+        throw new InvalidStateError("Task does not support setException()");
+    }
+    /** Request cancellation. Returns false if the task is already done. */
+    cancel(message) {
+        if (this.done())
+            return false;
+        this.#cancelRequests++;
+        if (!this.#controller.signal.aborted) {
+            this.#controller.abort(new CancelledError(message));
+        }
+        // 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. 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() {
+        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;
+    }
+    toString() {
+        return this.#name;
+    }
+    /** @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;
+    }
+}
+/**
+ * Suspend the current task until `register` resolves or rejects, making the
+ * wait a cancellation point. `register` returns a disposer that undoes the
+ * 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 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 {
+        return await awaitFuture(future);
+    }
+    catch (e) {
+        if (future.cancelled()) {
+            dispose();
+            onCancel?.();
+        }
+        throw e;
+    }
+}
+/** Create and schedule a task (asyncio.create_task). */
+export function createTask(fn, name) {
+    return new Task(fn, name);
+}
+/** Throw if the current task has a pending cancellation (an explicit `await asyncio.sleep(0)`). */
+export function checkCancelled() {
+    currentTask()?.checkpoint();
+}
+/**
+ * Await a foreign promise (fetch, SDK call...) as a cancellation point: if the
+ * current task is cancelled while waiting, this rejects with CancelledError.
+ * The foreign operation keeps running unless it was also given `task.signal`.
+ */
+export function abortable(promise) {
+    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() {
+    return currentTask()?.signal ?? new AbortController().signal;
+}
+//# sourceMappingURL=task.js.map

package/package.json

@@ -1,12 +1,38 @@
 {
   "name": "@pipedog/asyncio",
-  "version": "0.0.0",
-  "description": "Placeholder for @pipedog/asyncio. Releases are published from GitHub Actions; see https://github.com/polvallverdu/pipedog/tree/main/packages/asyncio#readme",
+  "version": "0.2.0",
+  "description": "asyncio-style tasks, cancellation, queues and events for JavaScript runtimes (Bun, Node, Workers).",
   "license": "BSD-2-Clause",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/polvallverdu/pipedog.git",
     "directory": "packages/asyncio"
   },
-  "homepage": "https://github.com/polvallverdu/pipedog/tree/main/packages/asyncio#readme"
+  "homepage": "https://github.com/polvallverdu/pipedog/tree/main/packages/asyncio#readme",
+  "bugs": {
+    "url": "https://github.com/polvallverdu/pipedog/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "pipecat": {
+    "runtimes": [
+      "bun",
+      "node",
+      "deno",
+      "workerd"
+    ]
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
 }

package/README.md

@@ -1,5 +0,0 @@
-# @pipedog/asyncio
-
-Placeholder version. Install a released version instead: `npm install @pipedog/asyncio@latest`.
-
-Part of [pipedog](https://github.com/polvallverdu/pipedog).