moeru-ai/eventa

Purpose and Public Surface

Eventa is a transport-agnostic TypeScript library for typed events, unary RPC, and bidirectional streaming RPC. The package entry point is src/index.ts; core event definitions originate in src/eventa.ts. Consumers create local or transport-backed contexts, then emit/listen or define callable remote methods.

Context and Event Dispatch

src/context.ts implements the central context abstraction: event registration, emission, listener lifecycle, and abort semantics. src/context-hooks.ts extends context lifecycle behavior. Event definitions from src/eventa.ts provide typed IDs/payload contracts, while src/error.ts defines library-level error representation. This layer is transport-neutral and is the boundary adapters target.

RPC Protocol Layer

Unary invocation is built across src/invoke.ts, src/invoke-remote-methods.ts, and src/invoke-shared.ts. It converts invocation event definitions into Promise-returning client functions and handler registrations, correlates requests/responses, propagates handler failures, and supports cancellation through AbortSignal/handler abort controllers. This is an event protocol over a context rather than a fixed JSON-RPC transport.

Streaming and Transfer Semantics

src/stream.ts implements streamed invocation input/output, including client-streaming and duplex patterns based on web streams and async iteration. src/invoke-extension-transfer.ts supports transfer-oriented invocation extensions, important for worker/browser structured-clone transport cases. Streaming remains layered on the same context event pipeline, so transport capability and payload validity are adapter/edge responsibilities.

Context Bridging and Routing

src/channel.ts connects contexts without requiring them to share an underlying transport. It provides directed pipes and fully connected bidirectional links, forwards both ordinary and internal invoke events, applies per-edge plugins for filtering/transformation, and can propagate aborts across connected contexts. This is the composition boundary for multi-hop flows such as iframe → WebSocket → server.

Transport Adapter Families

Adapters wrap native messaging APIs into Eventa contexts:

• Browser/local event systems: src/adapters/event-target/index.ts, src/adapters/event-emitter/index.ts, src/adapters/broadcast-channel/index.ts.

• Window and worker boundaries: src/adapters/window-message/index.ts, src/adapters/webworkers/index.ts, src/adapters/worker-threads/index.ts.

• Desktop shells: src/adapters/electron/main.ts, src/adapters/electron/renderer.ts, src/adapters/tauri/index.ts.

• Network/server WebSockets: src/adapters/websocket/native/index.ts, src/adapters/websocket/h3/index.ts, src/adapters/websocket/hono/index.ts.

Adapters isolate runtime-specific listener registration, serialization/transfer behavior, peer lifecycle, and transport errors. Relevant runtimes include browsers, Node.js worker threads/EventEmitter, Electron, Tauri webviews, native WebSocket clients, and H3/Hono WebSocket servers.

Build and Delivery

The project is an npm package managed with pnpm (package.json, pnpm-workspace.yaml), compiled/bundled through tsdown.config.ts, and written in TypeScript (tsconfig.json). CI and publishing are separated in .github/workflows/ci.yml and .github/workflows/publish.yml, making package build/test and release the primary infrastructure paths.