# moeru-ai/eventa architecture

> Architecture diagram of the GitHub repository moeru-ai/eventa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/moeru-ai/eventa
- Repository: https://github.com/moeru-ai/eventa

## Overview

#### 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.

Main entry points: [`src/context.ts`](https://github.com/moeru-ai/eventa/blob/main/src/context.ts) (Context), [`src/index.ts`](https://github.com/moeru-ai/eventa/blob/main/src/index.ts) (Package entry), [`src/invoke-shared.ts`](https://github.com/moeru-ai/eventa/blob/main/src/invoke-shared.ts) (Invocation protocol), [`src/eventa.ts`](https://github.com/moeru-ai/eventa/blob/main/src/eventa.ts) (Event definitions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core event model"]
  node_entry["Package entry<br/>public API<br/>[index.ts]"]
  node_events["Event definitions<br/>typed contracts<br/>[eventa.ts]"]
  node_context["Context<br/>event runtime<br/>[context.ts]"]
  node_hooks["Context hooks<br/>lifecycle extension<br/>[context-hooks.ts]"]
  node_errors["Library errors<br/>error model<br/>[error.ts]"]
end

subgraph group_rpc["RPC protocol"]
  node_invoke["Unary invocation<br/>RPC API<br/>[invoke.ts]"]
  node_remote_methods["Remote methods<br/>RPC bindings"]
  node_invoke_shared["Invocation protocol<br/>request correlation<br/>[invoke-shared.ts]"]
  node_stream["Streaming RPC<br/>stream protocol<br/>[stream.ts]"]
  node_transfer["Transfer extensions<br/>structured-clone support"]
end

subgraph group_transport["Bridging and adapters"]
  node_channel{{"Channel routing<br/>context bridge<br/>[channel.ts]"}}
  node_local_adapters["Local event adapters<br/>adapter family<br/>[index.ts]"]
  node_boundary_adapters["Window and worker adapters<br/>adapter family<br/>[index.ts]"]
  node_desktop_adapters["Desktop shell adapters<br/>adapter family<br/>[main.ts]"]
  node_websocket_adapters["WebSocket adapters<br/>adapter family<br/>[index.ts]"]
end

subgraph group_delivery["Build and delivery"]
  node_package["npm package<br/>package manifest<br/>[package.json]"]
  node_build["Bundle build<br/>build pipeline<br/>[tsdown.config.ts]"]
  node_ci["CI<br/>automation<br/>[ci.yml]"]
  node_publish["Publish workflow<br/>release automation<br/>[publish.yml]"]
end

node_entry -->|"exports"| node_events
node_entry -->|"exports"| node_context
node_entry -->|"exports"| node_invoke
node_entry -->|"exports"| node_stream
node_events -->|"defines dispatched events"| node_context
node_hooks -->|"extends lifecycle"| node_context
node_context -->|"reports failures"| node_errors
node_invoke -->|"binds methods"| node_remote_methods
node_remote_methods -->|"uses protocol"| node_invoke_shared
node_invoke_shared -->|"sends internal events"| node_context
node_stream -->|"extends invocation"| node_invoke_shared
node_transfer -->|"extends payload handling"| node_invoke_shared
node_channel -->|"connects contexts"| node_context
node_local_adapters -->|"creates contexts"| node_context
node_boundary_adapters -->|"creates contexts"| node_context
node_desktop_adapters -->|"creates contexts"| node_context
node_websocket_adapters -->|"creates contexts"| node_context
node_package -->|"builds with"| node_build
node_ci -->|"runs"| node_build
node_publish -->|"publishes"| node_package

click node_entry "https://github.com/moeru-ai/eventa/blob/main/src/index.ts"
click node_events "https://github.com/moeru-ai/eventa/blob/main/src/eventa.ts"
click node_context "https://github.com/moeru-ai/eventa/blob/main/src/context.ts"
click node_hooks "https://github.com/moeru-ai/eventa/blob/main/src/context-hooks.ts"
click node_errors "https://github.com/moeru-ai/eventa/blob/main/src/error.ts"
click node_invoke "https://github.com/moeru-ai/eventa/blob/main/src/invoke.ts"
click node_remote_methods "https://github.com/moeru-ai/eventa/blob/main/src/invoke-remote-methods.ts"
click node_invoke_shared "https://github.com/moeru-ai/eventa/blob/main/src/invoke-shared.ts"
click node_stream "https://github.com/moeru-ai/eventa/blob/main/src/stream.ts"
click node_transfer "https://github.com/moeru-ai/eventa/blob/main/src/invoke-extension-transfer.ts"
click node_channel "https://github.com/moeru-ai/eventa/blob/main/src/channel.ts"
click node_local_adapters "https://github.com/moeru-ai/eventa/blob/main/src/adapters/event-target/index.ts"
click node_boundary_adapters "https://github.com/moeru-ai/eventa/blob/main/src/adapters/window-message/index.ts"
click node_desktop_adapters "https://github.com/moeru-ai/eventa/blob/main/src/adapters/electron/main.ts"
click node_websocket_adapters "https://github.com/moeru-ai/eventa/blob/main/src/adapters/websocket/native/index.ts"
click node_package "https://github.com/moeru-ai/eventa/blob/main/package.json"
click node_build "https://github.com/moeru-ai/eventa/blob/main/tsdown.config.ts"
click node_ci "https://github.com/moeru-ai/eventa/blob/main/.github/workflows/ci.yml"
click node_publish "https://github.com/moeru-ai/eventa/blob/main/.github/workflows/publish.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_events,node_context,node_hooks,node_errors toneBlue
class node_invoke,node_remote_methods,node_invoke_shared,node_stream,node_transfer toneAmber
class node_channel,node_local_adapters,node_boundary_adapters,node_desktop_adapters,node_websocket_adapters toneMint
class node_package,node_build,node_ci,node_publish toneRose
```

## Components

### Core event model

- [Package entry](https://github.com/moeru-ai/eventa/blob/main/src/index.ts): public API · Exports the library surface. · `src/index.ts`
- [Event definitions](https://github.com/moeru-ai/eventa/blob/main/src/eventa.ts): typed contracts · Typed event IDs and payload contracts. · `src/eventa.ts`
- [Context](https://github.com/moeru-ai/eventa/blob/main/src/context.ts): event runtime · Transport-neutral registration, dispatch, lifecycle, and abort boundary. · `src/context.ts`
- [Context hooks](https://github.com/moeru-ai/eventa/blob/main/src/context-hooks.ts): lifecycle extension · `src/context-hooks.ts`
- [Library errors](https://github.com/moeru-ai/eventa/blob/main/src/error.ts): error model · `src/error.ts`

### RPC protocol

- [Unary invocation](https://github.com/moeru-ai/eventa/blob/main/src/invoke.ts): RPC API · Creates Promise-based clients and handler registrations. · `src/invoke.ts`
- [Remote methods](https://github.com/moeru-ai/eventa/blob/main/src/invoke-remote-methods.ts): RPC bindings · Maps invocation events to client functions and handlers. · `src/invoke-remote-methods.ts`
- [Invocation protocol](https://github.com/moeru-ai/eventa/blob/main/src/invoke-shared.ts): request correlation · Correlates requests and responses, failures, and cancellation. · `src/invoke-shared.ts`
- [Streaming RPC](https://github.com/moeru-ai/eventa/blob/main/src/stream.ts): stream protocol · Client-streaming and duplex RPC over web streams and async iteration. · `src/stream.ts`
- [Transfer extensions](https://github.com/moeru-ai/eventa/blob/main/src/invoke-extension-transfer.ts): structured-clone support · Supports transfer-oriented invocation payloads. · `src/invoke-extension-transfer.ts`

### Bridging and adapters

- [Channel routing](https://github.com/moeru-ai/eventa/blob/main/src/channel.ts): context bridge · Pipes or links contexts with per-edge plugins and abort propagation. · `src/channel.ts`
- [Local event adapters](https://github.com/moeru-ai/eventa/blob/main/src/adapters/event-target/index.ts): adapter family · EventTarget, EventEmitter, and BroadcastChannel contexts. · `src/adapters/event-target/index.ts`
- [Window and worker adapters](https://github.com/moeru-ai/eventa/blob/main/src/adapters/window-message/index.ts): adapter family · Window messaging plus browser and Node worker boundaries. · `src/adapters/window-message/index.ts`
- [Desktop shell adapters](https://github.com/moeru-ai/eventa/blob/main/src/adapters/electron/main.ts): adapter family · Electron main/renderer and Tauri webview contexts. · `src/adapters/electron/main.ts`
- [WebSocket adapters](https://github.com/moeru-ai/eventa/blob/main/src/adapters/websocket/native/index.ts): adapter family · Native clients and H3/Hono server WebSocket contexts. · `src/adapters/websocket/native/index.ts`

### Build and delivery

- [npm package](https://github.com/moeru-ai/eventa/blob/main/package.json): package manifest · pnpm-managed publishable package. · `package.json`
- [Bundle build](https://github.com/moeru-ai/eventa/blob/main/tsdown.config.ts): build pipeline · TypeScript compilation and package bundling. · `tsdown.config.ts`
- [CI](https://github.com/moeru-ai/eventa/blob/main/.github/workflows/ci.yml): automation · Builds and tests the package. · `.github/workflows/ci.yml`
- [Publish workflow](https://github.com/moeru-ai/eventa/blob/main/.github/workflows/publish.yml): release automation · Publishes package releases. · `.github/workflows/publish.yml`

## Connections

- Package entry → Event definitions: exports
- Package entry → Context: exports
- Package entry → Unary invocation: exports
- Package entry → Streaming RPC: exports
- Event definitions → Context: defines dispatched events
- Context hooks → Context: extends lifecycle
- Context → Library errors: reports failures
- Unary invocation → Remote methods: binds methods
- Remote methods → Invocation protocol: uses protocol
- Invocation protocol → Context: sends internal events
- Streaming RPC → Invocation protocol: extends invocation
- Transfer extensions → Invocation protocol: extends payload handling
- Channel routing → Context: connects contexts
- Local event adapters → Context: creates contexts
- Window and worker adapters → Context: creates contexts
- Desktop shell adapters → Context: creates contexts
- WebSocket adapters → Context: creates contexts
- npm package → Bundle build: builds with
- CI → Bundle build: runs
- Publish workflow → npm package: publishes