@pipedog/asyncio 0.0.0 → 0.2.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,4 @@
+export { callLater, callSoon, Handle } from "./loop.ts";
+export * from "./primitives.ts";
+export * from "./task.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

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

package/dist/loop.d.ts

@@ -0,0 +1,26 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+/** @internal The task the code is running in (see task.ts). */
+export declare const taskStorage: AsyncLocalStorage<unknown>;
+/** A callback scheduled with `callSoon()` / `callLater()` (asyncio.Handle). */
+export declare class Handle {
+    #private;
+    constructor(callback: () => void);
+    /** Cancel the callback. Does nothing if it already ran. */
+    cancel(): void;
+    cancelled(): boolean;
+    /** @internal */
+    _setTimer(timer: ReturnType<typeof setTimeout>): void;
+    /** @internal */
+    _clearTimer(): void;
+    /** @internal */
+    _run(): void;
+}
+/**
+ * Schedule `callback` to run on a later turn of the loop, after the code
+ * running now (and every callback scheduled before it) has run up to its
+ * next suspension (loop.call_soon). Runs with no current task.
+ */
+export declare function callSoon(callback: () => void): Handle;
+/** Schedule `callback` after `delay` seconds (loop.call_later). */
+export declare function callLater(delay: number, callback: () => void): Handle;
+//# sourceMappingURL=loop.d.ts.map

package/dist/loop.js

@@ -0,0 +1,179 @@
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// The ready queue: asyncio's event loop scheduling, for JavaScript.
+//
+// In asyncio a task runs until it genuinely suspends (awaits a future that is
+// not done). Completing a future does not resume its waiters: their wakeups
+// are queued with `loop.call_soon()` and run later, one after another, in FIFO
+// order. So `await queue.get()` on a non-empty queue, `await queue.put()` on
+// an unbounded one or awaiting a coroutine that never suspends all complete
+// without letting any other task run.
+//
+// JavaScript resumes an awaiting function one microtask after its promise
+// settles, so naive promise-based primitives interleave tasks at every
+// `await`. Here, every wakeup (a future's done callbacks, a task's first step,
+// `sleep(0)`, timers) is a `callSoon()` callback instead, and callbacks run
+// one per macrotask: the microtask queue (the resumed task's run up to its next
+// real suspension, plus anything it set off) drains completely before the
+// next callback runs. Pending callbacks keep the process alive, like a running
+// loop.
+//
+// The macrotask source is picked per runtime: a MessageChannel on Node
+// (setImmediate there goes through a full libuv loop iteration per callback),
+// setImmediate on Bun and Deno, a body read on Cloudflare Workers (its
+// setImmediate and timers wait about a millisecond; MessageChannel messages
+// are delivered without draining microtasks in between) and MessageChannel or
+// setTimeout elsewhere.
+import { AsyncLocalStorage } from "node:async_hooks";
+/** @internal The task the code is running in (see task.ts). */
+export const taskStorage = new AsyncLocalStorage();
+/** A callback scheduled with `callSoon()` / `callLater()` (asyncio.Handle). */
+export class Handle {
+    #callback;
+    #timer;
+    constructor(callback) {
+        this.#callback = callback;
+    }
+    /** Cancel the callback. Does nothing if it already ran. */
+    cancel() {
+        this.#callback = null;
+        if (this.#timer !== undefined) {
+            clearTimeout(this.#timer);
+            this.#timer = undefined;
+        }
+    }
+    cancelled() {
+        return this.#callback === null;
+    }
+    /** @internal */
+    _setTimer(timer) {
+        this.#timer = timer;
+    }
+    /** @internal */
+    _clearTimer() {
+        this.#timer = undefined;
+    }
+    /** @internal */
+    _run() {
+        const callback = this.#callback;
+        if (callback === null)
+            return;
+        this.#callback = null;
+        callback();
+    }
+}
+// FIFO of ready handles: an array consumed from `head`, compacted lazily.
+let ready = [];
+let head = 0;
+let trigger;
+let armed = false;
+/**
+ * Schedule `callback` to run on a later turn of the loop, after the code
+ * running now (and every callback scheduled before it) has run up to its
+ * next suspension (loop.call_soon). Runs with no current task.
+ */
+export function callSoon(callback) {
+    const handle = new Handle(callback);
+    enqueue(handle);
+    return handle;
+}
+/** Schedule `callback` after `delay` seconds (loop.call_later). */
+export function callLater(delay, callback) {
+    const handle = new Handle(callback);
+    // As in asyncio, a due timer only moves its callback to the ready queue.
+    handle._setTimer(setTimeout(() => {
+        handle._clearTimer();
+        if (!handle.cancelled())
+            enqueue(handle);
+    }, Math.max(0, delay * 1000)));
+    return handle;
+}
+function enqueue(handle) {
+    ready.push(handle);
+    if (!armed) {
+        armed = true;
+        trigger ??= makeTrigger(runOne);
+        trigger.arm();
+    }
+}
+/** One loop turn: run the oldest ready callback, then let microtasks drain. */
+function runOne() {
+    armed = false;
+    const handle = ready[head];
+    if (handle === undefined) {
+        trigger?.idle();
+        return;
+    }
+    ready[head] = undefined;
+    head++;
+    if (head === ready.length) {
+        ready = [];
+        head = 0;
+    }
+    else if (head >= 1024 && head * 2 >= ready.length) {
+        ready = ready.slice(head);
+        head = 0;
+    }
+    if (head < ready.length) {
+        armed = true;
+        trigger.arm();
+    }
+    else {
+        trigger.idle();
+    }
+    try {
+        // Callbacks run outside any task, as in asyncio (current_task() is None).
+        taskStorage.run(undefined, () => handle._run());
+    }
+    catch (e) {
+        // asyncio logs callback errors and keeps the loop going; surface it the
+        // way JavaScript reports an uncaught error, without stopping the queue.
+        queueMicrotask(() => {
+            throw e;
+        });
+    }
+}
+function makeTrigger(run) {
+    const g = globalThis;
+    const noop = () => { };
+    if (g.navigator?.userAgent === "Cloudflare-Workers" && typeof g.Response === "function") {
+        // A body read settles from the runtime's event loop, after microtasks.
+        const Response = g.Response;
+        return { arm: () => void new Response("").arrayBuffer().then(run), idle: noop };
+    }
+    const isNode = typeof g.process?.versions?.node === "string" && !g.Bun && !g.Deno;
+    if (isNode && typeof g.MessageChannel === "function") {
+        const { port1, port2 } = new g.MessageChannel();
+        port1.onmessage = run;
+        // Only pending callbacks keep the process alive.
+        port1.unref?.();
+        let referenced = false;
+        return {
+            arm: () => {
+                if (!referenced) {
+                    referenced = true;
+                    port1.ref?.();
+                }
+                port2.postMessage(null);
+            },
+            idle: () => {
+                if (referenced) {
+                    referenced = false;
+                    port1.unref?.();
+                }
+            },
+        };
+    }
+    if (typeof g.setImmediate === "function") {
+        const setImmediate = g.setImmediate;
+        return { arm: () => void setImmediate(run), idle: noop };
+    }
+    if (typeof g.MessageChannel === "function") {
+        const { port1, port2 } = new g.MessageChannel();
+        port1.onmessage = run;
+        return { arm: () => port2.postMessage(null), idle: noop };
+    }
+    return { arm: () => void setTimeout(run, 0), idle: noop };
+}
+//# sourceMappingURL=loop.js.map

package/dist/primitives.d.ts

@@ -0,0 +1,138 @@
+import { Future, 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 once: the task goes to the back
+ * of the ready queue, so everything already scheduled runs first.
+ */
+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` 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 _head: number;
+    protected _init(): void;
+    protected _put(item: T): void;
+    protected _get(): T;
+    protected _size(): number;
+    /** The queued items in storage order (for subclasses that inspect them). */
+    protected _queued(): readonly T[];
+    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);
+    /** Due to state, or FIFO rules (must allow others to run first). */
+    locked(): boolean;
+    acquire(): Promise<true>;
+    release(): void;
+    run<R>(fn: () => Promise<R> | R): Promise<R>;
+}
+/** Something to await: a function (a "coroutine"), a Task or Future, or a foreign promise. */
+export type Awaitable<T> = TaskFn<T> | Future<T> | PromiseLike<T>;
+/**
+ * asyncio.wait_for(aw, timeout). A function (a "coroutine") or a foreign
+ * promise is awaited in the current task, a Task is awaited (and cancelled on
+ * timeout). `timeout` null waits forever.
+ */
+export declare function waitFor<T>(aw: Awaitable<T>, timeout: number | null | undefined): Promise<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.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<F extends Future<any>>(tasks: Iterable<F>, options?: {
+    timeout?: number | null;
+    returnWhen?: ReturnWhen;
+}): Promise<[Set<F>, Set<F>]>;
+/** asyncio.shield(aw): the caller can be cancelled without cancelling `aw`. */
+export declare function shield<T>(aw: Awaitable<T>): Promise<T>;
+/** Whether `value` is a Future or Task (asyncio.isfuture). */
+export declare function isFuture(value: unknown): value is Future<unknown>;
+//# sourceMappingURL=primitives.d.ts.map