@lambdot/core 0.1.0 → 0.1.1

package/src/stream.ts

@@ -0,0 +1,281 @@
+import type { Disposer } from "./effect.ts";
+
+/**
+ * The one thing plugins exchange: an async iterable. Streams broadcast like
+ * an event bus — every consumer sees every item, in order, at its own pace —
+ * so a namespace value can feed several downstream plugins (a reply stream
+ * consumed by two outputs; a message stream consumed by a feature and a
+ * logger). Sequential per consumer: the per-item `await` in a `mapStream`
+ * mapper or `pumpStream` consumer is the processing-order guarantee.
+ */
+export type Stream<T> = AsyncIterable<T>;
+
+/**
+ * The primitive underneath {@link shareStream}: a pushable buffer bridging
+ * callbacks (sockets, readline, HTTP handlers) into the pull world. Package
+ * authors pushing from callbacks create one channel, wrap `stream` with
+ * `shareStream`, and emit the shared view.
+ */
+export interface Channel<T> {
+    /** Single-consumer stream view of the buffer; wrap with `shareStream` to broadcast. */
+    readonly stream: Stream<T>;
+    /** Buffer an item (or hand it to a waiting consumer). No-op once closed. */
+    push(item: T): void;
+    /** End the stream: consumers finish after draining the buffer. */
+    close(): void;
+}
+
+export function channel<T>(): Channel<T> {
+    const buffer: T[] = [];
+    let waiting: ((result: IteratorResult<T>) => void) | null = null;
+    let closed = false;
+    return {
+        stream: {
+            [Symbol.asyncIterator]() {
+                return {
+                    next(): Promise<IteratorResult<T>> {
+                        if (buffer.length > 0)
+                            return Promise.resolve({ value: buffer.shift() as T, done: false });
+                        if (closed) return Promise.resolve({ value: undefined, done: true });
+                        return new Promise((resolve) => {
+                            waiting = resolve;
+                        });
+                    },
+                };
+            },
+        },
+        push(item) {
+            if (closed) return;
+            if (waiting) {
+                const resolve = waiting;
+                waiting = null;
+                resolve({ value: item, done: false });
+            } else {
+                buffer.push(item);
+            }
+        },
+        close() {
+            closed = true;
+            if (waiting) {
+                const resolve = waiting;
+                waiting = null;
+                resolve({ value: undefined, done: true });
+            }
+        },
+    };
+}
+
+/**
+ * Multicast a stream: every consumer gets every item, in order, at its own
+ * pace. Pulling starts when the first consumer attaches, pauses when the
+ * last one detaches (the source buffers), and resumes on the next attach.
+ * Consumers attaching mid-stream see items from that point on —
+ * subscription semantics, like an event bus listener. A source error ends
+ * the stream: waiting and future reads reject with it (after draining
+ * what was already buffered), so consumers like `pumpStream` can forward
+ * it instead of hanging.
+ */
+export function shareStream<T>(stream: Stream<T>): Stream<T> {
+    interface Consumer {
+        buffer: T[];
+        waiting: {
+            resolve: (result: IteratorResult<T>) => void;
+            reject: (error: unknown) => void;
+        } | null;
+    }
+    const consumers = new Set<Consumer>();
+    let closed = false;
+    let failed = false;
+    let failure: unknown;
+    let pulling = false;
+    let iterator: AsyncIterator<T> | undefined;
+    let held: { value: T } | undefined;
+
+    const push = (item: T): void => {
+        for (const consumer of consumers) {
+            if (consumer.waiting) {
+                const { resolve } = consumer.waiting;
+                consumer.waiting = null;
+                resolve({ value: item, done: false });
+            } else {
+                consumer.buffer.push(item);
+            }
+        }
+    };
+
+    const pull = (): void => {
+        if (pulling || closed) return;
+        pulling = true;
+        void (async () => {
+            try {
+                // One iterator for the stream's lifetime: pausing via `break`
+                // out of `for await` would finish generator-backed sources
+                // permanently, so they could never resume.
+                iterator ??= stream[Symbol.asyncIterator]();
+                const source = iterator;
+                // Deliver an item pulled while the last consumer detached.
+                if (held) {
+                    push(held.value);
+                    held = undefined;
+                }
+                let sourceDone = false;
+                // Check before pulling: with nobody listening, pause (the
+                // source buffers) without consuming an item; the next attach
+                // resumes this same iterator.
+                while (consumers.size > 0) {
+                    const result = await source.next();
+                    if (result.done) {
+                        sourceDone = true;
+                        break;
+                    }
+                    // The last consumer detached while this pull was in
+                    // flight: hold the item instead of dropping it.
+                    if (consumers.size === 0) {
+                        held = { value: result.value };
+                        break;
+                    }
+                    push(result.value);
+                }
+                if (!sourceDone) return;
+                closed = true;
+                for (const consumer of consumers) {
+                    if (consumer.waiting) {
+                        const { resolve } = consumer.waiting;
+                        consumer.waiting = null;
+                        resolve({ value: undefined, done: true });
+                    }
+                }
+            } catch (error) {
+                // A source error ends the stream: settle waiting consumers
+                // with the rejection and fail future next() calls (after
+                // they drain what was already buffered), so consumers like
+                // pumpStream see the error instead of hanging forever.
+                failed = true;
+                failure = error;
+                closed = true;
+                for (const consumer of consumers) {
+                    if (consumer.waiting) {
+                        const { reject } = consumer.waiting;
+                        consumer.waiting = null;
+                        reject(error);
+                    }
+                }
+            } finally {
+                pulling = false;
+            }
+        })();
+    };
+
+    return {
+        [Symbol.asyncIterator]() {
+            const consumer: Consumer = { buffer: [], waiting: null };
+            consumers.add(consumer);
+            pull();
+            return {
+                next(): Promise<IteratorResult<T>> {
+                    if (consumer.buffer.length > 0)
+                        return Promise.resolve({
+                            value: consumer.buffer.shift() as T,
+                            done: false,
+                        });
+                    if (failed) return Promise.reject(failure);
+                    if (closed) return Promise.resolve({ value: undefined, done: true });
+                    return new Promise((resolve, reject) => {
+                        consumer.waiting = { resolve, reject };
+                    });
+                },
+                return(): Promise<IteratorResult<T>> {
+                    consumers.delete(consumer);
+                    if (consumer.waiting) {
+                        const { resolve } = consumer.waiting;
+                        consumer.waiting = null;
+                        resolve({ value: undefined, done: true });
+                    }
+                    return Promise.resolve({ value: undefined, done: true });
+                },
+            };
+        },
+    };
+}
+
+/** Transform each item; the mapper may be async (items stay sequential). */
+export function mapStream<T, U>(stream: Stream<T>, map: (item: T) => U | Promise<U>): Stream<U> {
+    async function* mapped(): AsyncGenerator<U> {
+        for await (const item of stream) yield await map(item);
+    }
+    return shareStream(mapped());
+}
+
+/** Keep only matching items. The type-guard form narrows the item type. */
+export function filterStream<T, U extends T>(
+    stream: Stream<T>,
+    predicate: (item: T) => item is U,
+): Stream<U>;
+export function filterStream<T>(
+    stream: Stream<T>,
+    predicate: (item: T) => boolean | Promise<boolean>,
+): Stream<T>;
+export function filterStream<T>(
+    stream: Stream<T>,
+    predicate: (item: T) => boolean | Promise<boolean>,
+): Stream<T> {
+    async function* filtered(): AsyncGenerator<T> {
+        for await (const item of stream) if (await predicate(item)) yield item;
+    }
+    return shareStream(filtered());
+}
+
+/** Interleave several streams into one, in arrival order. */
+export function mergeStreams<T>(...streams: readonly Stream<T>[]): Stream<T> {
+    async function* merged(): AsyncGenerator<T> {
+        interface Indexed {
+            index: number;
+            result: IteratorResult<T>;
+        }
+        const iterators = streams.map((stream) => stream[Symbol.asyncIterator]());
+        const pending = new Map<number, Promise<Indexed>>();
+        const arm = (index: number): void => {
+            const iterator = iterators[index];
+            if (!iterator) return;
+            pending.set(
+                index,
+                iterator.next().then((result) => ({ index, result })),
+            );
+        };
+        for (let index = 0; index < iterators.length; index++) arm(index);
+        while (pending.size > 0) {
+            const { index, result } = await Promise.race(pending.values());
+            pending.delete(index);
+            if (result.done) continue;
+            arm(index);
+            yield result.value;
+        }
+    }
+    return shareStream(merged());
+}
+
+/**
+ * Consume a stream in the background, sequentially. Errors go to `onError`.
+ * The returned disposer detaches after the in-flight item; with every
+ * consumer detached, the stream pauses until one attaches again.
+ */
+export function pumpStream<T>(
+    stream: Stream<T>,
+    consume: (item: T) => void | Promise<void>,
+    onError: (error: unknown) => void,
+): Disposer {
+    let stopped = false;
+    void (async () => {
+        try {
+            for await (const item of stream) {
+                if (stopped) return;
+                await consume(item);
+            }
+        } catch (error) {
+            if (!stopped) onError(error);
+        }
+    })();
+    return () => {
+        stopped = true;
+    };
+}

package/src/context.ts

@@ -1,120 +0,0 @@
-import type { Disposer } from "./effect.ts";
-import type { BotEvent, EventMap, IngressListener, Listener, OnOptions } from "./events.ts";
-import { INGRESS } from "./events.ts";
-import type { StateView } from "./state.ts";
-
-/**
- * A typed return address. Produced by the input half of a platform pair,
- * consumed by the output half. The core never inspects it beyond the
- * `platform` routing tag.
- */
-export interface Address<TPlatform extends string = string> {
-    readonly platform: TPlatform;
-}
-
-/** An output platform's contract: the addresses it accepts and the content it can send. */
-export interface OutputContract<TAddress = unknown, TContent = unknown> {
-    address: TAddress;
-    content: TContent;
-}
-
-/** platform → contract. Folded across all registered output plugins. */
-export type OutputContractMap = Record<string, OutputContract<any, any>>;
-
-type AllAddresses<TOutputs extends OutputContractMap> = TOutputs[keyof TOutputs]["address"];
-
-/**
- * Content types accepted for a given address: the union of `content` from
- * every registered output whose address type accepts `TAddress`. Resolves to
- * `never` when no output matches — with no outputs registered at all,
- * `send` is simply uncallable.
- */
-export type ContentFor<TOutputs extends OutputContractMap, TAddress> = {
-    [K in keyof TOutputs]: TAddress extends TOutputs[K]["address"] ? TOutputs[K]["content"] : never;
-}[keyof TOutputs];
-
-/**
- * The typed surface every plugin sees. Parameterized by the plugin's own
- * declared needs (event kinds it handles, output platforms it sends to,
- * state schema it owns) — the kernel checks at `use()` time that the fold
- * so far satisfies them — plus the capabilities it provides (`TProvides`),
- * which makes `provide` type-checked for declared names.
- */
-export interface ContextView<
-    TEvents extends EventMap,
-    TOutputs extends OutputContractMap,
-    TState extends object,
-    TProvides extends object = {},
-> {
-    /** Subscribe to ingress middleware (waterfall over every event). */
-    on(kind: typeof INGRESS, listener: IngressListener<TEvents>, options?: OnOptions): Disposer;
-    /** Subscribe to a specific event kind. */
-    on<TKind extends keyof TEvents & string>(
-        kind: TKind,
-        listener: Listener<BotEvent<TKind, TEvents[TKind]["payload"], TEvents[TKind]["address"]>>,
-        options?: OnOptions,
-    ): Disposer;
-
-    emit<TKind extends keyof TEvents & string>(
-        kind: TKind,
-        event: BotEvent<TKind, TEvents[TKind]["payload"], TEvents[TKind]["address"]>,
-    ): void;
-    parallel<TKind extends keyof TEvents & string>(
-        kind: TKind,
-        event: BotEvent<TKind, TEvents[TKind]["payload"], TEvents[TKind]["address"]>,
-    ): Promise<void>;
-    serial<TKind extends keyof TEvents & string>(
-        kind: TKind,
-        event: BotEvent<TKind, TEvents[TKind]["payload"], TEvents[TKind]["address"]>,
-    ): Promise<unknown>;
-    waterfall<TKind extends keyof TEvents & string>(
-        kind: TKind,
-        event: BotEvent<TKind, TEvents[TKind]["payload"], TEvents[TKind]["address"]>,
-        inner: (
-            event: BotEvent<TKind, TEvents[TKind]["payload"], TEvents[TKind]["address"]>,
-        ) => Promise<unknown>,
-    ): Promise<unknown>;
-
-    /**
-     * Send content through the output platform that owns `to`'s address
-     * type. Compile error if the content doesn't match that platform's
-     * contract — or if the platform's output plugin was never registered.
-     */
-    send<TAddress extends AllAddresses<TOutputs>>(
-        to: TAddress,
-        content: ContentFor<TOutputs, TAddress>,
-    ): Promise<void>;
-
-    /**
-     * Typed per-plugin state. `never` unless some plugin declared a state
-     * schema; usable at runtime only while a state backend plugin is active.
-     */
-    readonly state: StateView<TState>;
-
-    /**
-     * Provide a named capability for `inject` gating. Names declared in the
-     * plugin's `TProvides` require a value of the declared type (the value is
-     * attached to the context — the dashboard-plugin pattern — and read back
-     * typed through the kernel's capability fold). Undeclared names take an
-     * optional untyped value: the runtime-only capability path. Returns the
-     * unregistering disposer.
-     */
-    provide<TName extends string>(
-        name: TName,
-        ...value: TName extends keyof TProvides & string
-            ? [value: TProvides[TName]]
-            : [value?: unknown]
-    ): Disposer;
-}
-
-/** Context seen by input plugins: adds the ability to push events into the pipeline. */
-export interface InputContext<
-    TEvents extends EventMap,
-    TProvides extends object = {},
-> extends ContextView<TEvents, {}, {}, TProvides> {
-    ingest<TKind extends keyof TEvents & string>(
-        kind: TKind,
-        payload: TEvents[TKind]["payload"],
-        address: TEvents[TKind]["address"],
-    ): Promise<void>;
-}

package/src/events.ts

@@ -1,147 +0,0 @@
-/**
- * An event kind's contract: the payload an input produces and the typed
- * return address that routes replies back through a matching output.
- */
-export interface EventDef<TPayload = unknown, TAddress = unknown> {
-    payload: TPayload;
-    address: TAddress;
-}
-
-/** kind → contract. Folded across all registered input plugins. */
-export type EventMap = Record<string, EventDef<any, any>>;
-
-/**
- * The single unit that flows through the framework. The core envelope is
- * deliberately free of platform semantics: no reply references, no channel
- * vocabulary — `address` is opaque to the core and meaningful only to the
- * output whose platform produced it.
- */
-export interface BotEvent<TKind extends string = string, TPayload = unknown, TAddress = unknown> {
-    readonly kind: TKind;
-    readonly payload: TPayload;
-    readonly address: TAddress;
-    /** Unique id for dedup and tracing. */
-    readonly id: string;
-    /** Unix epoch milliseconds. */
-    readonly at: number;
-}
-
-/** Union over every registered event kind, narrowing `payload`/`address` per kind. */
-export type AnyBotEvent<TEvents extends EventMap> = {
-    [K in keyof TEvents & string]: BotEvent<K, TEvents[K]["payload"], TEvents[K]["address"]>;
-}[keyof TEvents & string];
-
-/** Reserved kind: every ingested event passes through this waterfall first. */
-export const INGRESS = "bot/ingress" as const;
-
-/** Continue a waterfall chain. Call with no argument to pass the event through unchanged. */
-export type NextFn<TEvent> = (event?: TEvent) => Promise<unknown>;
-
-/**
- * A listener. Plain observation listeners simply ignore `next`; waterfall
- * (middleware) listeners MUST call `next()` to delegate — returning without
- * calling it short-circuits the chain.
- */
-export type Listener<TEvent> = (event: TEvent, next: NextFn<TEvent>) => unknown;
-
-/** Listener for the ingress waterfall; receives the union of all registered event kinds. */
-export type IngressListener<TEvents extends EventMap> = Listener<AnyBotEvent<TEvents>>;
-
-export interface OnOptions {
-    /** Run before ordinary (non-prepended) registrations. */
-    prepend?: boolean;
-}
-
-interface Registration {
-    listener: Listener<any>;
-}
-
-const noopNext: NextFn<any> = () => Promise.resolve(undefined);
-
-/**
- * The runtime event bus. Untyped internally; the typed surface is layered on
- * by the kernel's context view. Modes:
- *
- * - `emit`      fire-and-forget observation
- * - `parallel`  await all listeners (rejects with AggregateError)
- * - `serial`    await in order until a listener returns a non-undefined bail value
- * - `waterfall` around-middleware: each listener receives `next`
- */
-export class EventBus {
-    private readonly listeners = new Map<string, Registration[]>();
-
-    constructor(private readonly onError: (error: unknown) => void) {}
-
-    on(kind: string, listener: Listener<any>, options?: OnOptions): () => void {
-        const regs = this.listeners.get(kind) ?? [];
-        const reg: Registration = { listener };
-        if (options?.prepend) regs.unshift(reg);
-        else regs.push(reg);
-        this.listeners.set(kind, regs);
-        return () => {
-            const current = this.listeners.get(kind);
-            if (!current) return;
-            const index = current.indexOf(reg);
-            if (index >= 0) current.splice(index, 1);
-            if (current.length === 0) this.listeners.delete(kind);
-        };
-    }
-
-    emit(kind: string, event: unknown): void {
-        const regs = this.listeners.get(kind);
-        if (!regs) return;
-        // snapshot: listeners may unregister themselves during dispatch
-        for (const reg of regs.slice()) {
-            try {
-                const result = reg.listener(event, noopNext);
-                if (result instanceof Promise) result.catch(this.onError);
-            } catch (error) {
-                this.onError(error);
-            }
-        }
-    }
-
-    async parallel(kind: string, event: unknown): Promise<void> {
-        const regs = this.listeners.get(kind);
-        if (!regs) return;
-        const results = await Promise.allSettled(
-            [...regs].map((reg) => reg.listener(event, noopNext)),
-        );
-        const errors = results
-            .filter((result): result is PromiseRejectedResult => result.status === "rejected")
-            .map((result) => result.reason);
-        if (errors.length > 0)
-            throw new AggregateError(errors, `parallel dispatch of "${kind}" failed`);
-    }
-
-    async serial(kind: string, event: unknown): Promise<unknown> {
-        const regs = this.listeners.get(kind);
-        if (!regs) return undefined;
-        // snapshot: listeners may unregister themselves during dispatch
-        for (const reg of regs.slice()) {
-            const result = await reg.listener(event, noopNext);
-            if (result !== undefined) return result;
-        }
-        return undefined;
-    }
-
-    async waterfall(
-        kind: string,
-        event: unknown,
-        inner: (event: any) => Promise<unknown>,
-    ): Promise<unknown> {
-        const regs = this.listeners.get(kind);
-        if (!regs || regs.length === 0) return inner(event);
-        const stack = [...regs];
-        const dispatch = (index: number, current: unknown): Promise<unknown> => {
-            const reg = stack[index];
-            if (!reg) return inner(current);
-            return Promise.resolve(
-                reg.listener(current, (nextEvent?: unknown) =>
-                    dispatch(index + 1, nextEvent ?? current),
-                ),
-            );
-        };
-        return dispatch(0, event);
-    }
-}

package/src/fiber.ts

@@ -1,41 +0,0 @@
-import { runDisposers, type Disposer } from "./effect.ts";
-import type { AnyPlugin } from "./plugin.ts";
-
-export type FiberState = "pending" | "activating" | "active" | "disposed";
-
-/**
- * One plugin application. Owns the disposers the plugin's effects produced.
- * A fiber whose injected capabilities disappear is disposed back to
- * `pending`, and reactivates when they return — activation order is derived
- * from `inject`, never from boot sequencing.
- */
-export class Fiber {
-    state: FiberState = "pending";
-    private readonly disposers: Disposer[] = [];
-
-    constructor(
-        readonly plugin: AnyPlugin,
-        readonly config: unknown,
-    ) {}
-
-    get name(): string {
-        return this.plugin.name;
-    }
-
-    addDisposer(disposer: Disposer): void {
-        if (this.state !== "active") {
-            throw new Error(`cannot register disposer on ${this.state} fiber "${this.name}"`);
-        }
-        this.disposers.push(disposer);
-    }
-
-    async dispose(
-        nextState: "pending" | "disposed",
-        onError: (error: unknown) => void,
-    ): Promise<void> {
-        if (this.state !== "active") return;
-        this.state = nextState;
-        const disposers = this.disposers.splice(0);
-        await runDisposers(disposers, onError);
-    }
-}