@pipedog/asyncio 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,3 +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

@@ -1,5 +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

@@ -1,4 +1,4 @@
-import { Task, type TaskFn } from "./task.ts";
+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()). */
@@ -12,7 +12,10 @@ export declare function monotonicNs(): number;
  * time origin.
  */
 export declare function time(): number;
-/** asyncio.sleep(seconds). `sleep(0)` yields to other tasks. */
+/**
+ * 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 {
@@ -32,7 +35,7 @@ export declare class QueueShutDown extends Error {
     name: string;
 }
 /**
- * asyncio.Queue. Subclasses override `_init/_put/_get/_size/_items` to change
+ * asyncio.Queue. Subclasses override `_init/_put/_get/_size` to change
  * ordering, as Python's PriorityQueue and LifoQueue do.
  */
 export declare class Queue<T> {
@@ -40,10 +43,13 @@ export declare class Queue<T> {
     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;
@@ -85,17 +91,25 @@ export declare class Lock {
 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>;
 }
-export type Awaitable<T> = TaskFn<T> | Task<T> | PromiseLike<T>;
+/** 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). Pass a function (a "coroutine") so it can
- * run as a child task that is cancelled on timeout. `timeout` null waits forever.
+ * 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.
@@ -113,15 +127,12 @@ export type ReturnWhen = typeof FIRST_COMPLETED | typeof FIRST_EXCEPTION | typeo
  * 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?: {
+export declare function wait<F extends Future<any>>(tasks: Iterable<F>, 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>;
+}): 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