@pipedog/asyncio 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2024–2026, Daily
+Copyright (c) 2026, pipedog contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/NOTICE

@@ -0,0 +1,9 @@
+pipedog is an unofficial TypeScript port of Pipecat (https://github.com/pipecat-ai/pipecat),
+a framework for voice and multimodal conversational AI created by Daily.
+
+It is not affiliated with or endorsed by Daily. Pipecat is distributed under
+the BSD 2-Clause License, Copyright (c) 2024–2026, Daily; that copyright notice
+and license are retained in LICENSE, and every ported source file carries a
+header naming the upstream file it was derived from.
+
+The upstream commit each file was ported from is recorded in porting/manifest.json.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./primitives.ts";
+export * from "./task.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,5 @@
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+export * from "./primitives.js";
+export * from "./task.js";
+//# sourceMappingURL=index.js.map

package/dist/primitives.d.ts

@@ -0,0 +1,127 @@
+import { Task, type TaskFn } from "./task.ts";
+/** Monotonic time in seconds (loop.time()). */
+export declare function monotonic(): number;
+/** Monotonic time in nanoseconds (time.monotonic_ns()). */
+export declare function monotonicNs(): number;
+/**
+ * Wall-clock time in seconds (time.time()).
+ *
+ * Sub-millisecond, like Python's: `Date.now()` alone would give successive
+ * readings the same value, so intervals between frames pushed back to back
+ * would measure as zero. Falls back to `Date.now()` where the runtime has no
+ * time origin.
+ */
+export declare function time(): number;
+/** asyncio.sleep(seconds). `sleep(0)` yields to other tasks. */
+export declare function sleep(seconds: number): Promise<void>;
+/** asyncio.Event */
+export declare class Event {
+    #private;
+    isSet(): boolean;
+    set(): void;
+    clear(): void;
+    wait(): Promise<true>;
+}
+export declare class QueueEmpty extends Error {
+    name: string;
+}
+export declare class QueueFull extends Error {
+    name: string;
+}
+export declare class QueueShutDown extends Error {
+    name: string;
+}
+/**
+ * asyncio.Queue. Subclasses override `_init/_put/_get/_size/_items` to change
+ * ordering, as Python's PriorityQueue and LifoQueue do.
+ */
+export declare class Queue<T> {
+    #private;
+    readonly maxsize: number;
+    constructor(maxsize?: number);
+    protected _items: T[];
+    protected _init(): void;
+    protected _put(item: T): void;
+    protected _get(): T;
+    protected _size(): number;
+    qsize(): number;
+    empty(): boolean;
+    full(): boolean;
+    put(item: T): Promise<void>;
+    putNowait(item: T): void;
+    get(): Promise<T>;
+    getNowait(): T;
+    taskDone(): void;
+    join(): Promise<void>;
+    shutdown(immediate?: boolean): void;
+}
+/** asyncio.LifoQueue */
+export declare class LifoQueue<T> extends Queue<T> {
+    protected _get(): T;
+}
+/** Default ordering for PriorityQueue: compares numbers, strings and tuples (arrays) like Python. */
+export declare function pythonCompare(a: unknown, b: unknown): number;
+/** heapq.heappush */
+export declare function heapPush<T>(heap: T[], item: T, compare?: (a: T, b: T) => number): void;
+/** heapq.heappop */
+export declare function heapPop<T>(heap: T[], compare?: (a: T, b: T) => number): T;
+/** asyncio.PriorityQueue backed by a binary heap. Smallest item first. */
+export declare class PriorityQueue<T> extends Queue<T> {
+    protected readonly _compare: (a: T, b: T) => number;
+    constructor(maxsize?: number, compare?: (a: T, b: T) => number);
+    protected _put(item: T): void;
+    protected _get(): T;
+}
+/** asyncio.Lock */
+export declare class Lock {
+    #private;
+    locked(): boolean;
+    acquire(): Promise<true>;
+    release(): void;
+    /** `async with lock:` → `await lock.run(async () => {...})` */
+    run<R>(fn: () => Promise<R> | R): Promise<R>;
+}
+/** asyncio.Semaphore */
+export declare class Semaphore {
+    #private;
+    constructor(value?: number);
+    locked(): boolean;
+    acquire(): Promise<true>;
+    release(): void;
+    run<R>(fn: () => Promise<R> | R): Promise<R>;
+}
+export type Awaitable<T> = TaskFn<T> | Task<T> | PromiseLike<T>;
+/**
+ * asyncio.wait_for(aw, timeout). Pass a function (a "coroutine") so it can
+ * run as a child task that is cancelled on timeout. `timeout` null waits forever.
+ */
+export declare function waitFor<T>(aw: Awaitable<T>, timeout: number | null | undefined): Promise<T>;
+/**
+ * asyncio.gather(*aws). Functions run as child tasks; if the caller is
+ * cancelled, all children are cancelled.
+ */
+export declare function gather<T extends readonly unknown[]>(...aws: {
+    [K in keyof T]: Awaitable<T[K]>;
+}): Promise<T>;
+/** asyncio.gather(*aws, return_exceptions=True) */
+export declare function gatherSettled(...aws: Awaitable<unknown>[]): Promise<unknown[]>;
+export declare const FIRST_COMPLETED = "FIRST_COMPLETED";
+export declare const FIRST_EXCEPTION = "FIRST_EXCEPTION";
+export declare const ALL_COMPLETED = "ALL_COMPLETED";
+export type ReturnWhen = typeof FIRST_COMPLETED | typeof FIRST_EXCEPTION | typeof ALL_COMPLETED;
+/**
+ * asyncio.wait(tasks, timeout, return_when). Does not cancel anything on
+ * timeout. Returns [done, pending].
+ */
+export declare function wait<T>(tasks: Iterable<Task<T>>, options?: {
+    timeout?: number | null;
+    returnWhen?: ReturnWhen;
+}): Promise<[Set<Task<T>>, Set<Task<T>>]>;
+/**
+ * asyncio.timeout(seconds) as a scope: runs `fn` and cancels it on timeout,
+ * raising TimeoutError.
+ */
+export declare function timeout<T>(seconds: number | null, fn: TaskFn<T>): Promise<T>;
+/** asyncio.shield(aw): the caller can be cancelled without cancelling `aw`. */
+export declare function shield<T>(aw: Awaitable<T>): Promise<T>;
+//# sourceMappingURL=primitives.d.ts.map

package/dist/primitives.js

@@ -0,0 +1,492 @@
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// asyncio synchronization primitives and helpers. Every wait here is a
+// cancellation point (see task.ts). Durations are in seconds, as in Python.
+import { CancelledError, createTask, currentTask, suspend, Task, TimeoutError, } from "./task.js";
+/** Monotonic time in seconds (loop.time()). */
+export function monotonic() {
+    return performance.now() / 1000;
+}
+/** Monotonic time in nanoseconds (time.monotonic_ns()). */
+export function monotonicNs() {
+    return Math.round(performance.now() * 1_000_000);
+}
+/**
+ * Wall-clock time in seconds (time.time()).
+ *
+ * Sub-millisecond, like Python's: `Date.now()` alone would give successive
+ * readings the same value, so intervals between frames pushed back to back
+ * would measure as zero. Falls back to `Date.now()` where the runtime has no
+ * time origin.
+ */
+export function time() {
+    const origin = performance.timeOrigin;
+    return origin ? (origin + performance.now()) / 1000 : Date.now() / 1000;
+}
+/** asyncio.sleep(seconds). `sleep(0)` yields to other tasks. */
+export function sleep(seconds) {
+    return suspend((resolve) => {
+        const timer = setTimeout(resolve, Math.max(0, seconds * 1000));
+        return () => clearTimeout(timer);
+    });
+}
+/** asyncio.Event */
+export class Event {
+    #set = false;
+    #waiters = new Set();
+    isSet() {
+        return this.#set;
+    }
+    set() {
+        if (this.#set)
+            return;
+        this.#set = true;
+        const waiters = [...this.#waiters];
+        this.#waiters.clear();
+        for (const waiter of waiters)
+            waiter();
+    }
+    clear() {
+        this.#set = false;
+    }
+    wait() {
+        if (this.#set) {
+            try {
+                currentTask()?.checkpoint();
+            }
+            catch (e) {
+                return Promise.reject(e);
+            }
+            return Promise.resolve(true);
+        }
+        return suspend((resolve) => {
+            const waiter = () => resolve(true);
+            this.#waiters.add(waiter);
+            return () => this.#waiters.delete(waiter);
+        });
+    }
+}
+export class QueueEmpty extends Error {
+    name = "QueueEmpty";
+}
+export class QueueFull extends Error {
+    name = "QueueFull";
+}
+export class QueueShutDown extends Error {
+    name = "QueueShutDown";
+}
+/**
+ * asyncio.Queue. Subclasses override `_init/_put/_get/_size/_items` to change
+ * ordering, as Python's PriorityQueue and LifoQueue do.
+ */
+export class Queue {
+    maxsize;
+    #getters = [];
+    #putters = [];
+    #unfinished = 0;
+    #finished = new Event();
+    #shutdown = false;
+    constructor(maxsize = 0) {
+        this.maxsize = maxsize;
+        this._init();
+        this.#finished.set();
+    }
+    // Storage hooks.
+    _items = [];
+    _init() {
+        this._items = [];
+    }
+    _put(item) {
+        this._items.push(item);
+    }
+    _get() {
+        return this._items.shift();
+    }
+    _size() {
+        return this._items.length;
+    }
+    qsize() {
+        return this._size();
+    }
+    empty() {
+        return this._size() === 0;
+    }
+    full() {
+        return this.maxsize > 0 && this._size() >= this.maxsize;
+    }
+    async put(item) {
+        // A cancellation point even when it doesn't block: after an interruption,
+        // a task resuming from a foreign await must not push stale items.
+        currentTask()?.checkpoint();
+        while (this.full()) {
+            if (this.#shutdown)
+                throw new QueueShutDown();
+            await suspend((resolve) => {
+                this.#putters.push(resolve);
+                return () => {
+                    const i = this.#putters.indexOf(resolve);
+                    if (i >= 0)
+                        this.#putters.splice(i, 1);
+                };
+            });
+        }
+        this.putNowait(item);
+    }
+    putNowait(item) {
+        if (this.#shutdown)
+            throw new QueueShutDown();
+        if (this.full())
+            throw new QueueFull();
+        this._put(item);
+        this.#unfinished++;
+        this.#finished.clear();
+        this.#wakeGetter();
+    }
+    async get() {
+        if (!this.empty() && this.#getters.length === 0) {
+            currentTask()?.checkpoint();
+            return this.getNowait();
+        }
+        if (this.#shutdown && this.empty())
+            throw new QueueShutDown();
+        return suspend((resolve, reject) => {
+            const getter = { resolve, reject };
+            this.#getters.push(getter);
+            // Item may already be available if getters were queued before us.
+            this.#wakeGetter();
+            return () => {
+                const i = this.#getters.indexOf(getter);
+                if (i >= 0)
+                    this.#getters.splice(i, 1);
+            };
+        });
+    }
+    getNowait() {
+        if (this.empty()) {
+            if (this.#shutdown)
+                throw new QueueShutDown();
+            throw new QueueEmpty();
+        }
+        const item = this._get();
+        this.#wakePutter();
+        return item;
+    }
+    taskDone() {
+        if (this.#unfinished <= 0)
+            throw new Error("task_done() called too many times");
+        this.#unfinished--;
+        if (this.#unfinished === 0)
+            this.#finished.set();
+    }
+    async join() {
+        if (this.#unfinished > 0)
+            await this.#finished.wait();
+    }
+    shutdown(immediate = false) {
+        this.#shutdown = true;
+        if (immediate) {
+            while (!this.empty()) {
+                this._get();
+                if (this.#unfinished > 0)
+                    this.#unfinished--;
+            }
+            if (this.#unfinished === 0)
+                this.#finished.set();
+        }
+        for (const getter of this.#getters.splice(0))
+            getter.reject(new QueueShutDown());
+        for (const putter of this.#putters.splice(0))
+            putter();
+    }
+    #wakeGetter() {
+        while (this.#getters.length > 0 && !this.empty()) {
+            const getter = this.#getters.shift();
+            const item = this._get();
+            getter.resolve(item);
+            this.#wakePutter();
+        }
+    }
+    #wakePutter() {
+        const putter = this.#putters.shift();
+        putter?.();
+    }
+}
+/** asyncio.LifoQueue */
+export class LifoQueue extends Queue {
+    _get() {
+        return this._items.pop();
+    }
+}
+/** Default ordering for PriorityQueue: compares numbers, strings and tuples (arrays) like Python. */
+export function pythonCompare(a, b) {
+    if (Array.isArray(a) && Array.isArray(b)) {
+        const n = Math.min(a.length, b.length);
+        for (let i = 0; i < n; i++) {
+            const c = pythonCompare(a[i], b[i]);
+            if (c !== 0)
+                return c;
+        }
+        return a.length - b.length;
+    }
+    if (typeof a === "number" && typeof b === "number")
+        return a - b;
+    if (typeof a === "string" && typeof b === "string")
+        return a < b ? -1 : a > b ? 1 : 0;
+    if (typeof a === "bigint" && typeof b === "bigint")
+        return a < b ? -1 : a > b ? 1 : 0;
+    throw new TypeError(`'<' not supported between ${typeof a} and ${typeof b}`);
+}
+/** heapq.heappush */
+export function heapPush(heap, item, compare = pythonCompare) {
+    heap.push(item);
+    let i = heap.length - 1;
+    while (i > 0) {
+        const parent = (i - 1) >> 1;
+        if (compare(heap[i], heap[parent]) >= 0)
+            break;
+        [heap[i], heap[parent]] = [heap[parent], heap[i]];
+        i = parent;
+    }
+}
+/** heapq.heappop */
+export function heapPop(heap, compare = pythonCompare) {
+    const top = heap[0];
+    const last = heap.pop();
+    if (heap.length > 0) {
+        heap[0] = last;
+        let i = 0;
+        for (;;) {
+            const l = 2 * i + 1;
+            const r = l + 1;
+            let m = i;
+            if (l < heap.length && compare(heap[l], heap[m]) < 0)
+                m = l;
+            if (r < heap.length && compare(heap[r], heap[m]) < 0)
+                m = r;
+            if (m === i)
+                break;
+            [heap[i], heap[m]] = [heap[m], heap[i]];
+            i = m;
+        }
+    }
+    return top;
+}
+/** asyncio.PriorityQueue backed by a binary heap. Smallest item first. */
+export class PriorityQueue extends Queue {
+    _compare;
+    constructor(maxsize = 0, compare = pythonCompare) {
+        super(maxsize);
+        this._compare = compare;
+    }
+    _put(item) {
+        heapPush(this._items, item, this._compare);
+    }
+    _get() {
+        return heapPop(this._items, this._compare);
+    }
+}
+/** asyncio.Lock */
+export class Lock {
+    #locked = false;
+    #waiters = [];
+    locked() {
+        return this.#locked;
+    }
+    async acquire() {
+        if (!this.#locked && this.#waiters.length === 0) {
+            this.#locked = true;
+            return true;
+        }
+        await suspend((resolve) => {
+            this.#waiters.push(resolve);
+            return () => {
+                const i = this.#waiters.indexOf(resolve);
+                if (i >= 0)
+                    this.#waiters.splice(i, 1);
+            };
+        });
+        this.#locked = true;
+        return true;
+    }
+    release() {
+        if (!this.#locked)
+            throw new Error("Lock is not acquired.");
+        this.#locked = false;
+        const next = this.#waiters.shift();
+        if (next) {
+            // Hand over directly so no one can barge in.
+            this.#locked = true;
+            next();
+            // `acquire` sets locked again after resuming; keep it consistent.
+        }
+    }
+    /** `async with lock:` → `await lock.run(async () => {...})` */
+    async run(fn) {
+        await this.acquire();
+        try {
+            return await fn();
+        }
+        finally {
+            this.release();
+        }
+    }
+}
+/** asyncio.Semaphore */
+export class Semaphore {
+    #value;
+    #waiters = [];
+    constructor(value = 1) {
+        this.#value = value;
+    }
+    locked() {
+        return this.#value === 0;
+    }
+    async acquire() {
+        if (this.#value > 0 && this.#waiters.length === 0) {
+            this.#value--;
+            return true;
+        }
+        await suspend((resolve) => {
+            this.#waiters.push(resolve);
+            return () => {
+                const i = this.#waiters.indexOf(resolve);
+                if (i >= 0)
+                    this.#waiters.splice(i, 1);
+            };
+        });
+        return true;
+    }
+    release() {
+        const next = this.#waiters.shift();
+        if (next)
+            next();
+        else
+            this.#value++;
+    }
+    async run(fn) {
+        await this.acquire();
+        try {
+            return await fn();
+        }
+        finally {
+            this.release();
+        }
+    }
+}
+function toTask(aw, name) {
+    if (aw instanceof Task)
+        return aw;
+    if (typeof aw === "function")
+        return createTask(aw, name);
+    return createTask(() => aw, name);
+}
+/**
+ * asyncio.wait_for(aw, timeout). Pass a function (a "coroutine") so it can
+ * run as a child task that is cancelled on timeout. `timeout` null waits forever.
+ */
+export async function waitFor(aw, timeout) {
+    const child = toTask(aw, "wait_for");
+    if (timeout === null || timeout === undefined)
+        return await child;
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        child.cancel();
+    }, Math.max(0, timeout * 1000));
+    try {
+        return await child;
+    }
+    catch (e) {
+        if (timedOut && e instanceof CancelledError && !(currentTask()?.cancelling() ?? 0)) {
+            throw new TimeoutError();
+        }
+        throw e;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * asyncio.gather(*aws). Functions run as child tasks; if the caller is
+ * cancelled, all children are cancelled.
+ */
+export async function gather(...aws) {
+    const tasks = aws.map((aw) => toTask(aw));
+    return (await suspend((resolve, reject) => {
+        Promise.all(tasks.map((t) => t.promise)).then(resolve, reject);
+        return () => { };
+    }, () => {
+        for (const t of tasks)
+            t.cancel();
+    }));
+}
+/** asyncio.gather(*aws, return_exceptions=True) */
+export async function gatherSettled(...aws) {
+    const tasks = aws.map((aw) => toTask(aw));
+    return await suspend((resolve) => {
+        Promise.allSettled(tasks.map((t) => t.promise)).then((results) => resolve(results.map((r) => (r.status === "fulfilled" ? r.value : r.reason))));
+        return () => { };
+    }, () => {
+        for (const t of tasks)
+            t.cancel();
+    });
+}
+export const FIRST_COMPLETED = "FIRST_COMPLETED";
+export const FIRST_EXCEPTION = "FIRST_EXCEPTION";
+export const ALL_COMPLETED = "ALL_COMPLETED";
+/**
+ * asyncio.wait(tasks, timeout, return_when). Does not cancel anything on
+ * timeout. Returns [done, pending].
+ */
+export function wait(tasks, options = {}) {
+    const all = [...tasks];
+    const returnWhen = options.returnWhen ?? ALL_COMPLETED;
+    const result = () => [
+        new Set(all.filter((t) => t.done())),
+        new Set(all.filter((t) => !t.done())),
+    ];
+    return suspend((resolve) => {
+        let timer;
+        const check = () => {
+            const done = all.filter((t) => t.done());
+            const finished = done.length === all.length ||
+                (returnWhen === FIRST_COMPLETED && done.length > 0) ||
+                (returnWhen === FIRST_EXCEPTION &&
+                    done.some((t) => !t.cancelled() && t.exception() !== undefined));
+            if (finished) {
+                if (timer)
+                    clearTimeout(timer);
+                resolve(result());
+            }
+        };
+        for (const t of all)
+            t.addDoneCallback(check);
+        if (options.timeout !== undefined && options.timeout !== null) {
+            timer = setTimeout(() => resolve(result()), options.timeout * 1000);
+        }
+        check();
+        return () => {
+            if (timer)
+                clearTimeout(timer);
+            for (const t of all)
+                t.removeDoneCallback(check);
+        };
+    });
+}
+/**
+ * asyncio.timeout(seconds) as a scope: runs `fn` and cancels it on timeout,
+ * raising TimeoutError.
+ */
+export function timeout(seconds, fn) {
+    return waitFor(fn, seconds);
+}
+/** asyncio.shield(aw): the caller can be cancelled without cancelling `aw`. */
+export function shield(aw) {
+    const task = toTask(aw);
+    return suspend((resolve, reject) => {
+        task.promise.then(resolve, reject);
+        return () => { };
+    });
+}
+//# sourceMappingURL=primitives.js.map

package/dist/task.d.ts

@@ -0,0 +1,85 @@
+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 Waiter = (error: CancelledError) => void;
+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> {
+    #private;
+    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. */
+    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.
+     */
+    cancel(message?: string): boolean;
+    /**
+     * Throw CancelledError if a cancellation request is pending. Every
+     * primitive calls this before suspending.
+     */
+    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;
+}
+/**
+ * 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,293 @@
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// asyncio-style tasks with cooperative cancellation.
+//
+// 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:
+//
+//   - 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;
+//   - `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 { AsyncLocalStorage } from "node:async_hooks";
+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;
+}
+const storage = new AsyncLocalStorage();
+/** The task the caller is running in, if any (asyncio.current_task). */
+export function currentTask() {
+    return storage.getStore();
+}
+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 {
+    #controller = new AbortController();
+    #promise;
+    #waiters = new Set();
+    #doneCallbacks = [];
+    #name;
+    #state = "pending";
+    #result;
+    #error;
+    #mustCancel = false;
+    #cancelMessage;
+    #cancelRequests = 0;
+    constructor(fn, name) {
+        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();
+        });
+        this.#promise.then((value) => this.#settle("fulfilled", value, undefined), (error) => this.#settle(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. */
+    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;
+    }
+    uncancel() {
+        if (this.#cancelRequests > 0)
+            this.#cancelRequests--;
+        if (this.#cancelRequests === 0)
+            this.#mustCancel = false;
+        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;
+    }
+    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;
+    }
+    /**
+     * 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;
+        }
+        return true;
+    }
+    /**
+     * Throw CancelledError if a cancellation request is pending. Every
+     * primitive calls this before suspending.
+     */
+    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);
+    }
+    /** A promise that settles with the task, without being a cancellation point. */
+    get promise() {
+        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;
+                });
+            }
+        }
+    }
+}
+/**
+ * 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 function suspend(register, onCancel) {
+    const task = currentTask();
+    try {
+        task?.checkpoint();
+    }
+    catch (e) {
+        return Promise.reject(e);
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let dispose = () => { };
+        const waiter = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            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);
+        });
+    });
+}
+/** 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;
+}
+/** 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) {
+    return suspend((resolve, reject) => {
+        promise.then(resolve, reject);
+        return () => { };
+    });
+}
+/** 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.1.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).