@feelai/stream

A utility library providing a powerful wrapper around TypedEventEmitter. It enhances standard event emitters with promise-based event waiting, cancellation support, and a fluent API.

Features

• Promise-based Event Handling: Wait for specific events using waitFor(event), returning a Promise so you can await it.
• Cancellation: Built-in AbortController support to cancel pending operations with cancel().
• Type Safety: Built on top of typed-emitter for full TypeScript support.
• Fluent API: Chainable on, off, and once methods.
• Completion Helpers: finish() and done() methods to easily await the end of a stream.

Usage

import { createStream } from "@feelai/stream";
import { EventEmitter } from "events";
import TypedEventEmitter from "typed-emitter";

// Define your events
type MyEvents = {
  data: (chunk: string) => void;
  error: (err: Error) => void;
  end: () => void;
};

// Create a typed emitter
const myEmitter = new EventEmitter() as TypedEventEmitter<MyEvents>;

// Wrap it with createStream
const stream = createStream(myEmitter);

// Using standard event listeners (chainable)
stream.on("data", (chunk) => console.log("Received:", chunk)).once("end", () => console.log("Stream ended"));

// Using async/await
async function processStream() {
  try {
    // Wait for a specific event
    const [chunk] = await stream.waitFor("data");
    console.log("First chunk:", chunk);

    // Wait for stream completion
    await stream.finish();
    console.log("Done!");
  } catch (err) {
    console.error("Stream error or cancelled:", err);
  }
}

processStream();

// Cancellation
// stream.cancel(); // This will reject any pending waitFor promises

API Reference

createStream(emitter)

Creates a new Stream instance wrapping the provided TypedEventEmitter.

Class Stream<EM>

Methods

• constructor(emitter: TypedEventEmitter<EM>)
• on(event, listener): Register a listener. Returns this.
• off(event, listener): Remove a listener. Returns this.
• once(event, listener): Register a one-time listener. Returns this.
• waitFor(event): Returns a Promise that resolves with the event arguments when the event is emitted. Rejects if the stream emits "error" or is cancelled.
• cancel(): Aborts the internal controller and rejects all pending waitFor promises.
• finish() / done(): Returns a Promise that resolves when the "end" event is emitted.