bubus 1.7.3 → 1.8.1

package/README.md

@@ -1,362 +1,436 @@
-# bubus-ts: Python vs JS Differences (and the tricky parts)
+# `bubus`: 📢 Production-ready multi-language event bus
 
-This README only covers the differences between the Python implementation and this TypeScript port, plus the
-gotchas we uncovered while matching behavior. It intentionally does **not** re-document the full TS API surface.
+<img width="200" alt="image" src="https://github.com/user-attachments/assets/b3525c24-51ba-496c-b327-ccdfe46a7362" align="right" />
 
-## Key Differences vs Python
+[![DeepWiki: Python](https://img.shields.io/badge/DeepWiki-bbus%2FPython-yellow.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/pirate/bbus) ![PyPI - Version](https://img.shields.io/pypi/v/bubus) ![GitHub License](https://img.shields.io/github/license/pirate/bbus) ![GitHub last commit](https://img.shields.io/github/last-commit/pirate/bbus)
 
-### 1) Awaiting events: `event.done()` instead of `await event`
+[![DeepWiki: TS](https://img.shields.io/badge/DeepWiki-bbus%2FTypescript-blue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/pirate/bbus/3-typescript-implementation) ![NPM Version](https://img.shields.io/npm/v/bubus)
 
-- Python: `await event` waits for handlers and can jump the queue when awaited inside a handler.
-- TS: use `await event.done()` for the same behavior.
-- Outside a handler, `done()` just waits for completion (it does not jump the queue).
-- Inside a handler, `done()` triggers immediate processing (queue jump) on **all buses** where the event is queued.
+Bubus is an in-memory event bus library for async Python and TS (node/browser).
 
-### 2) Cross-bus queue jump (forwarding)
+It's designed for quickly building resilient, predictable, complex event-driven apps.
 
-- Python uses a global re-entrant lock to let awaited events process immediately on every bus where they appear.
-- TS optionally uses `AsyncLocalStorage` on Node.js (auto-detected) to capture dispatch context, but falls back gracefully in browsers.
-- `EventBus._all_instances` + the `LockManager` pause mechanism pauses each runloop and processes the same event immediately across buses.
+It "just works" with an intuitive, but powerful event JSON format + dispatch API that's consistent across both languages and scales consistently from one event up to millions:
 
-### 3) `event.bus` is a BusScopedEvent view
+```python
+bus.on(SomeEvent, some_function)
+bus.emit(SomeEvent({some_data: 132}))
+```
 
-- In Python, `event.event_bus` is dynamic (contextvars).
-- In TS, `event.bus` is provided by a **BusScopedEvent** (a Proxy over the original event).
-- That proxy injects a bus-bound `emit/dispatch` to ensure correct parent/child tracking.
+It's async native, has proper automatic nested event tracking, and powerful concurrency control options. The API is inspired by `EventEmitter` or [`emittery`](https://github.com/sindresorhus/emittery) in JS, but it takes it a step further:
 
-### 4) Monotonic timestamps
+- nice Zod / Pydantic schemas for events that can be exchanged between both languages
+- automatic UUIDv7s and monotonic nanosecond timestamps for ordering events globally
+- built in locking options to force strict global FIFO procesing or fully parallel processing
 
-- JS `Date.now()` is not strictly monotonic at millisecond granularity.
-- To keep FIFO tests stable, we generate strictly increasing timestamps via `BaseEvent.nextTimestamp()` (returns `{ date, isostring, ts }`).
+---
 
-### 5) No middleware, no WAL, no SQLite mirrors
+♾️ It's inspired by the simplicity of async and events in `JS` but with baked-in features that allow to eliminate most of the tedious repetitive complexity in event-driven codebases:
 
-- Those Python features were intentionally dropped for the JS version.
+- correct timeout enforcement across multiple levels of events, if a parent times out it correctly aborts all child event processing
+- ability to strongly type hint and enforce the return type of event handlers at compile-time
+- ability to queue events on the bus, or inline await them for immediate execution like a normal function call
+- handles ~5,000 events/sec/core in both languages, with ~2kb/event RAM consumed per event during active processing
 
-### 6) Default timeouts come from the EventBus
+<br/>
 
-- `BaseEvent.event_timeout` defaults to `null`.
-- When dispatched, `EventBus` applies its default `event_timeout` (60s unless configured).
-- You can set `{ event_timeout: null }` on the bus to disable timeouts entirely.
-- Slow handler warnings fire after `event_handler_slow_timeout` (default: `30s`). Slow event warnings fire after `event_slow_timeout` (default: `300s`).
+## 🔢 Quickstart
 
-## EventBus Options
+```bash
+pnpm add bubus
+```
 
-All options are passed to `new EventBus(name, options)`.
+```ts
+import { BaseEvent, EventBus } from 'bubus'
+import { z } from 'zod'
 
-- `max_history_size?: number | null` (default: `100`)
-  - Max number of events kept in history. Set to `null` for unlimited history.
-- `event_concurrency?: "global-serial" | "bus-serial" | "parallel" | "auto"` (default: `"bus-serial"`)
-  - Controls how many **events** can be processed at a time.
-  - `"global-serial"` enforces FIFO across all buses.
-  - `"bus-serial"` enforces FIFO per bus, allows cross-bus overlap.
-  - `"parallel"` allows events to process concurrently.
-  - `"auto"` uses the bus default (mostly useful for overrides).
-- `event_handler_concurrency?: "global-serial" | "bus-serial" | "parallel" | "auto"` (default: `"bus-serial"`)
-  - Controls how many **handlers** run at once for each event.
-  - Same semantics as `event_concurrency`, but applied to handler execution.
-- `event_timeout?: number | null` (default: `60`)
-  - Default handler timeout in seconds, applied when `event.event_timeout` is `null`.
-  - Set to `null` to disable timeouts globally for the bus.
-- `event_handler_slow_timeout?: number | null` (default: `30`)
-  - Warn after this many seconds for slow handlers.
-  - Only warns when the handler's timeout is `null` or greater than this value.
-  - Set to `null` to disable slow handler warnings.
-- `event_slow_timeout?: number | null` (default: `300`)
-  - Warn after this many seconds for slow event processing.
-  - Set to `null` to disable slow event warnings.
+const CreateUserEvent = BaseEvent.extend('CreateUserEvent', {
+  email: z.string(),
+  event_result_schema: z.object({ user_id: z.string() }),
+})
+
+const bus = new EventBus('MyAuthEventBus')
+
+bus.on(CreateUserEvent, async (event) => {
+  const user = await yourCreateUserLogic(event.email)
+  return { user_id: user.id }
+})
+
+const event = bus.emit(CreateUserEvent({ email: 'someuser@example.com' }))
+await event.done()
+console.log(event.first_result) // { user_id: 'some-user-uuid' }
+```
+
+<br/>
+
+---
+
+<br/>
+
+## ✨ Features
 
-## Concurrency Overrides and Precedence
+The features offered in TS are broadly similar to the ones offered in the python library.
 
-You can override concurrency per event and per handler:
+- Typed events with Zod schemas (cross-compatible with Pydantic events from python library)
+- FIFO event queueing with configurable concurrency
+- Nested event support with automatic parent/child tracking
+- Cross-bus forwarding with loop prevention
+- Handler result tracking + validation + timeout enforcement
+- History retention controls (`max_history_size`) for memory bounds
+- Optional `@retry` decorator for easy management of per-handler retries, timeouts, and semaphore-limited execution
+
+See the [Python README](../README.md) for more details.
+
+<br/>
+
+---
+
+<br/>
+
+## 📚 API Documentation
+
+### `EventBus`
+
+Create a bus:
 
 ```ts
-const FastEvent = BaseEvent.extend('FastEvent', {
-  payload: z.string(),
+const bus = new EventBus('MyBus', {
+  max_history_size: 100, // keep small, copy events to external store manually if you want to persist/query long-term logs
+  event_concurrency: 'bus-serial', // 'global-serial' | 'bus-serial' (default) | 'parallel'
+  event_handler_concurrency: 'serial', // 'serial' (default) | 'parallel'
+  event_handler_completion: 'all', // 'all' (default) | 'first' (stop handlers after the first non-undefined result from any handler)
+  event_timeout: 60, // default hard timeout for event handlers before they are marked result.status = 'error' w/ result.error = HandlerTimeoutError(...)
+  event_handler_slow_timeout: 30, // default timeout before a console.warn("Slow event handler bus.on(SomeEvent, someHandler()) has taken more than 30s"
+  event_slow_timeout: 300, // default timeout before a console.warn("Slow event processing: bus.on(SomeEvent, ...4 handlers) have taken more than 300s"
 })
+```
 
-// Per-event override (highest precedence)
-const event = FastEvent({
-  payload: 'x',
-  event_concurrency: 'parallel',
-  event_handler_concurrency: 'parallel',
+Core methods:
+
+- `bus.emit(event)` aka `bus.dispatch(event)`
+- `bus.on(eventKey, handler, options?)`
+- `bus.off(eventKey, handler)`
+- `bus.find(eventKey, options?)`
+- `bus.waitUntilIdle()`
+- `bus.destroy()`
+
+Notes:
+
+- String matching of event types using `bus.on('SomeEvent', ...)` and `bus.on('*', ...)` wildcard matching is supported
+- Prefer passing event class to (`bus.on(MyEvent, handler)`) over string-based maching for strictest type inference
+
+### `BaseEvent`
+
+Define typed events:
+
+```ts
+const MyEvent = BaseEvent.extend('MyEvent', {
+  some_key: z.string(),
+  some_other_key: z.number(),
+  // ...
+  // any other payload fields you want to include can go here
+
+  // fields that start with event_* are reserved for metadata used by the library
+  event_result_schema: z.string().optional(),
+  event_timeout: 60,
+  // ...
 })
 
-// Per-handler override (lower precedence)
-bus.on(FastEvent, handler, { event_handler_concurrency: 'parallel' })
+const pending_event: MyEvent = MyEvent({ some_key: 'abc', some_other_key: 234 })
+const queued_event: MyEvent = bus.emit(pending_event)
+const completed_event: MyEvent = queued_event.done()
 ```
 
-Precedence order (highest → lowest):
+Special fields that change how the event is processed:
+
+- `event_result_schema` defines the type to enforce for handler return values
+- `event_concurrency`, `event_handler_concurrency`, `event_handler_completion`
+- `event_timeout`, `event_handler_timeout`, `event_handler_slow_timeout`
+
+Common methods:
+
+- `await event.done()`
+- `await event.first()`
+- `event.toJSON()` (serialization format is compatible with python library)
+- `event.fromJSON()`
+
+#### `done()`
+
+- Runs the event with completion mode `'all'` and waits for all handlers/buses to finish.
+- Returns the same event instance in completed state so you can inspect `event_results`, `event_errors`, etc.
+- Want to dispatch and await an event like a function call? simply `await event.done()` and it will process immediately, skipping queued events.
+- Want to wait for normal processing in the order it was originally queued? use `await event.waitForCompletion()`
+
+#### `first()`
+
+- Runs the event with completion mode `'first'`.
+- Returns the temporally first non-`undefined` handler result (not registration order).
+- If all handlers return `undefined` (or only error), it resolves to `undefined`.
+- Remaining handlers are cancelled after the winning result is found.
+
+### `EventResult`
+
+Each handler run produces an `EventResult` stored in `event.event_results` with:
+
+- `status`: `pending | started | completed | error`
+- `result: EventType.event_result_schema` or `error: Error | undefined`
+- handler metadata (`handler_id`, `handler_name`, bus metadata)
+- `event_children` list of any sub-events that were emitted during handling
+
+The event aggregates these via `event.event_results` and exposes the values from them via getters like `event.first_result`, `event.event_errors`, and others.
+
+<br/>
+
+---
+
+<br/>
+
+## 🧵 Advanced Concurrency Control
 
-1. Event instance overrides (`event_concurrency`, `event_handler_concurrency`)
-2. Handler options (`event_handler_concurrency`)
-3. Bus defaults (`event_concurrency`, `event_handler_concurrency`)
+### Concurrency Config Options
 
-`"auto"` resolves to the bus default.
+#### Bus-level config options (`new EventBus(name, {...options...})`)
 
-## Handler Options
+- `max_history_size?: number | null` (default: `100`)
+  - Max completed events kept in history. `null` = unlimited. `bus.find(...)` uses this log to query recently completed events
+- `event_concurrency?: 'global-serial' | 'bus-serial' | 'parallel' | null` (default: `'bus-serial'`)
+  - Event-level scheduling policy (`global-serial`: FIFO across all buses, `bus-serial`: FIFO per bus, `parallel`: concurrent events per bus).
+- `event_handler_concurrency?: 'serial' | 'parallel' | null` (default: `'serial'`)
+  - Handler-level scheduling policy for each event (`serial`: one handler at a time per event, `parallel`: all handlers for the event can run concurrently).
+- `event_handler_completion?: 'all' | 'first'` (default: `'all'`)
+  - Completion strategy (`all`: wait for all handlers, `first`: stop after first non-`undefined` result).
+- `event_timeout?: number | null` (default: `60`)
+  - Default handler timeout budget in seconds.
+- `event_handler_slow_timeout?: number | null` (default: `30`)
+  - Slow-handler warning threshold in seconds.
+- `event_slow_timeout?: number | null` (default: `300`)
+  - Slow-event warning threshold in seconds.
 
-Handlers can be configured at registration time:
+#### Event-level config options
+
+Override the bus defaults on a per-event basis by using these special fields in the event:
 
 ```ts
-bus.on(SomeEvent, handler, {
+const event = MyEvent({
+  event_concurrency: 'parallel',
   event_handler_concurrency: 'parallel',
-  handler_timeout: 10, // per-handler timeout in seconds
+  event_handler_completion: 'first',
+  event_timeout: 10,
+  event_handler_timeout: 3,
 })
 ```
 
-- `event_handler_concurrency` allows per-handler concurrency overrides.
-- `handler_timeout` sets a per-handler timeout in seconds (overrides the bus default when lower).
-
-## TypeScript Return Type Enforcement (Edge Cases)
-
-TypeScript can only enforce handler return types when the event type is inferable at compile time.
-
-- `bus.on(EventFactoryOrClass, handler)`:
-  - Return values are type-checked against the event's `event_result_schema` (if defined).
-  - `undefined` (or no return) is always allowed.
-- `bus.on('SomeEventName', handler)`:
-  - Return type checking is best-effort only (treated as unknown in typing).
-  - Use class/factory keys when you want compile-time return-shape enforcement.
-- `bus.on('*', handler)`:
-  - Return type checking is intentionally loose (best-effort only), because wildcard handlers may receive many event types, including forwarded events from other buses.
-  - In practice, wildcard handlers are expected to be side-effect/forwarding handlers and usually return `undefined`.
-
-Runtime behavior is still consistent across all key styles:
-
-- If an event has `event_result_schema` and a handler returns a non-`undefined` value, that value is validated at runtime.
-- If the handler returns `undefined`, schema validation is skipped and the result is accepted.
-
-## Throughput + Memory Behavior (Current)
-
-This section documents the current runtime profile and the important edge cases. It is intentionally conservative:
-we describe what is enforced today, not theoretical best-case behavior.
-
-### Throughput model
-
-- Baseline throughput in tests is gated at `<30s` for:
-  - `50k events within reasonable time`
-  - `50k events with ephemeral on/off handler registration across 2 buses`
-  - `500 ephemeral buses with 100 events each`
-- The major hot-path operations are linear in collection sizes:
-  - Per event, handler matching is `O(total handlers on bus)` (`exact` scan + `*` scan).
-  - `.off()` is `O(total handlers on bus)` for matching/removal.
-  - Queue-jump (`await event.done()` inside handlers) does cross-bus discovery by walking `event_path` and iterating `EventBus._all_instances`, so cost grows with buses and forwarding depth.
-- `waitUntilIdle()` is best used at batch boundaries, not per event:
-  - Idle checks call `isIdle()`, which scans `event_history` and handler results.
-  - There is a fast-path that skips idle scans when no idle waiters exist, which keeps normal dispatch/complete flows fast even with large history.
-- Concurrency settings are a direct throughput limiter:
-  - `global-serial` and `bus-serial` intentionally serialize work.
-  - `parallel` increases throughput but can increase transient memory if producers outpace consumers.
-
-### Memory model
-
-- Per bus, strong references are held for:
-  - `handlers`
-  - `pending_event_queue`
-  - `in_flight_event_ids`
-  - `event_history` (bounded by `max_history_size`, or unbounded if `null`)
-  - active `find()` waiters until match/timeout
-- Per event, retained state includes:
-  - `event_results` (per-handler result objects)
-  - descendant links in `event_results[].event_children`
-- History trimming behavior:
-  - Completed events are evicted first (oldest first).
-  - If still over limit, oldest remaining events are dropped even if pending, and a warning is logged.
-  - Eviction calls `event._gc()` to clear internal references (`event_results`, child arrays, bus/context pointers).
-- Memory is not strictly bounded by only `pending_queue_size + max_history_size`:
-  - A retained parent event can hold references to many children/grandchildren via `event_children`.
-  - So effective retained memory can exceed a simple `event_count * avg_event_size` bound in high fan-out trees.
-- `destroy()` is recommended for deterministic cleanup, but not required for GC safety:
-  - `_all_instances` is WeakRef-based, so unreferenced buses can be collected without calling `.destroy()`.
-  - There is a GC regression test for this (`unreferenced buses with event history are garbage collected without destroy()`).
-- `heapUsed` vs `rss`:
-  - `heapUsed` returning near baseline after GC is the primary leak signal in tests.
-  - `rss` can stay elevated due to V8 allocator high-water behavior and is not, by itself, a proof of leak.
-
-### Practical guidance for high-load deployments
-
-- Keep `max_history_size` finite in production.
-- Avoid very large wildcard handler sets on hot event types.
-- Avoid calling `waitUntilIdle()` for every single event in large streams; prefer periodic/batch waits.
-- Be aware that very deep/high-fan-out parent-child graphs increase retained memory until parent events are evicted.
-- Use `.destroy()` for explicit lifecycle control in request-scoped or short-lived bus patterns.
+Notes:
+
+- `null` means "inherit/fall back to bus default" for event-level concurrency and timeout fields.
+- Forwarded events are processed under the target bus's config; source bus config is not inherited.
+- `event_handler_completion` is independent from handler scheduling mode (`serial` vs `parallel`).
+
+#### Handler-level config options
 
-## Semaphores (how concurrency is enforced)
+Set at registration:
 
-We use four semaphores:
+```ts
+bus.on(MyEvent, handler, { handler_timeout: 2 }) // max time in seconds this handler is allowed to run before it's aborted
+```
 
-- `LockManager.global_event_semaphore`
-- `LockManager.global_handler_semaphore`
-- `bus.locks.bus_event_semaphore`
-- `bus.locks.bus_handler_semaphore`
+#### Precedence and interaction
 
-They are applied centrally when scheduling events and handlers, so concurrency is controlled without scattering
-mutex checks throughout the code.
+Event and handler concurrency precedence:
 
-## Full lifecycle across concurrency modes
+1. Event instance override (`event.event_concurrency`, `event.event_handler_concurrency`)
+2. Bus defaults (`EventBus` options)
+3. Built-in defaults (`bus-serial`, `serial`)
 
-Below is the complete execution flow for nested events, including forwarding across buses, and how it behaves
-under different `event_concurrency` / `event_handler_concurrency` configurations.
+Timeout resolution for each handler run:
 
-### 1) Base execution flow (applies to all modes)
+1. Resolve handler timeout source:
+   - `bus.on(..., { handler_timeout })`
+   - else `event.event_handler_timeout`
+   - else bus `event_timeout`
+2. Apply event cap:
+   - effective timeout is `min(resolved_handler_timeout, event.event_timeout)` when both are non-null
+   - if either is `null`, the non-null value wins; both null means no timeout
 
-**Dispatch (non-awaited):**
+Additional timeout nuance:
 
-1. `dispatch()` normalizes to `original_event`, sets `bus` if missing.
-2. Captures `_dispatch_context` (AsyncLocalStorage if available).
-3. Applies `event_timeout_default` if `event.event_timeout === null`.
-4. If this bus is already in `event_path` (or `bus.hasProcessedEvent()`), return a BusScopedEvent without queueing.
-5. Append bus name to `event_path`, record child relationship (if `event_parent_id` is set).
-6. Add to `event_history` (a `Map<string, BaseEvent>` keyed by event id).
-7. Increment `event_pending_bus_count`.
-8. Push to `pending_event_queue` and `startRunloop()`.
+- `BaseEvent.event_timeout` starts as `null` unless set; dispatch applies bus default timeout when still unset.
+- Bus/event timeouts are outer budgets for handler execution; use `@retry({ timeout })` for per-attempt timeouts.
 
-**Runloop + processing:**
+Use `@retry` for per-handler execution timeout/retry/backoff/semaphore control. Keep bus/event timeouts as outer execution budgets.
 
-1. `runloop()` drains `pending_event_queue`.
-2. Adds event id to `in_flight_event_ids`.
-3. Calls `scheduleEventProcessing()` (async).
-4. `scheduleEventProcessing()` selects the event semaphore and runs `processEvent()`.
-5. `processEvent()`:
-   - `event.markStarted()`
-   - `notifyFindListeners(event)`
-   - creates handler results (`event_results`)
-   - runs handlers (respecting handler semaphore)
-   - decrements `event_pending_bus_count` and calls `event.markCompleted(false)` (completes only if all buses and children are done)
+### Runtime lifecycle (bus -> event -> handler)
 
-### 2) Event concurrency modes (`event_concurrency`)
+Dispatch flow:
 
-- **`global-serial`**: events are serialized across _all_ buses using `LockManager.global_event_semaphore`.
-- **`bus-serial`**: events are serialized per bus; different buses can overlap.
-- **`parallel`**: no event semaphore; events can run concurrently on the same bus.
-- **`auto`**: resolves to the bus default.
+1. `dispatch()` normalizes to original event and captures async context when available.
+2. Bus applies defaults and appends itself to `event_path`.
+3. Event enters `event_history`, `pending_event_queue`, and runloop starts.
+4. Runloop dequeues and calls `processEvent()`.
+5. Event-level semaphore (`event_concurrency`) is applied.
+6. Handler results are created and executed under handler-level semaphore (`event_handler_concurrency`).
+7. Event completion and child completion propagate through `event_pending_bus_count` and result states.
+8. History trimming evicts completed events first; if still over limit, oldest pending events can be dropped (with warning), then cleanup runs.
 
-**Mixed buses:** each bus enforces its own event mode. Forwarding to another bus does not inherit the source bus’s mode.
+Locking model:
 
-### 3) Handler concurrency modes (`event_handler_concurrency`)
+- Global event semaphore: `global-serial`
+- Bus event semaphore: `bus-serial`
+- Per-event handler semaphore: `serial` handler mode
 
-`event_handler_concurrency` controls how handlers run **for a single event**:
+### Queue-jumping (`await event.done()` inside handlers)
 
-- **`global-serial`**: only one handler at a time across all buses using `LockManager.global_handler_semaphore`.
-- **`bus-serial`**: handlers serialize per bus.
-- **`parallel`**: handlers run concurrently for the event.
-- **`auto`**: resolves to the bus default.
+Want to dispatch and await an event like a function call? simply `await event.done()`.
+When called inside a handler, the awaited event is processed immediately (queue-jump behavior) before normal queued work continues.
 
-**Interaction with event concurrency:**
-Even if events are parallel, handlers can still be serialized:
-`event_concurrency: "parallel"` + `event_handler_concurrency: "bus-serial"` means events start concurrently but handler execution on a bus is serialized.
+### `@retry` Decorator
 
-### 4) Forwarding across buses (non-awaited)
+`retry()` adds retry logic and optional semaphore-based concurrency limiting to async functions/handlers.
 
-When a handler on Bus A calls `bus_b.dispatch(event)` without awaiting:
+#### Why retry is handler-level
 
-- Bus A continues running its handler.
-- Bus B queues and processes the event according to **Bus B’s** concurrency settings.
-- No coupling unless both buses use the global semaphores.
+Retry and timeout belong on handlers, not emit sites:
 
-### 5) Queue-jump (`await event.done()` inside handlers)
+- Handlers fail; events are messages.
+- Handler-level retries preserve replay semantics (one event dispatch, internal retry attempts).
+- Bus concurrency and retry concerns are orthogonal and compose cleanly.
 
-When `event.done()` is awaited inside a handler, **queue-jump** happens:
+#### Recommended pattern: `@retry()` on class methods
+
+```ts
+import { retry, EventBus } from 'bubus'
+
+class ScreenshotService {
+  constructor(private bus: InstanceType<typeof EventBus>) {
+    bus.on(ScreenshotRequestEvent, this.onScreenshot.bind(this))
+  }
+
+  @retry({
+    max_attempts: 4,
+    retry_on_errors: [/timeout/i],
+    timeout: 5,
+    semaphore_scope: 'global',
+    semaphore_name: 'Screenshots',
+    semaphore_limit: 2,
+  })
+  async onScreenshot(event: InstanceType<typeof ScreenshotRequestEvent>): Promise<Buffer> {
+    return await takeScreenshot(event.data.url)
+  }
+}
+
+const ev = bus.emit(ScreenshotRequestEvent({ url: 'https://example.com' }))
+await ev.done()
+```
 
-1. `BaseEvent.done()` delegates to `bus.processEventImmediately()`, which detects whether we're inside a handler
-   (via `getActiveHandlerResult()` / `getParentEventResultAcrossAllBusses()`). If not inside a handler, it falls back to `waitForCompletion()`.
-2. `processEventImmediately()` **yields** the parent handler's concurrency semaphore (if held) so child handlers can acquire it.
-3. `processEventImmediately()` removes the event from the pending queue (if present).
-4. `runImmediatelyAcrossBuses()` processes the event immediately on all buses where it is queued.
-5. While immediate processing is active, each affected bus's runloop is paused to prevent unrelated events from running.
-6. Once immediate processing completes, `processEventImmediately()` **re-acquires** the parent handler's semaphore
-   (unless the parent timed out while the child was processing).
-7. Paused runloops resume.
+#### Also works: inline HOF
 
-**Important:** queue-jump bypasses event semaphores but **respects** handler semaphores via yield-and-reacquire.
-This means queue-jumped handlers run serially on a `bus-serial` bus, not in parallel.
+```ts
+bus.on(
+  MyEvent,
+  retry({ max_attempts: 3, timeout: 10 })(async (event) => {
+    await riskyOperation(event.data)
+  })
+)
+```
 
-### 6) Precedence recap
+#### Options
 
-Highest → lowest:
+| Option                 | Type                                      | Default     | Description                                     |
+| ---------------------- | ----------------------------------------- | ----------- | ----------------------------------------------- |
+| `max_attempts`         | `number`                                  | `1`         | Total attempts including first call.            |
+| `retry_after`          | `number`                                  | `0`         | Seconds between retries.                        |
+| `retry_backoff_factor` | `number`                                  | `1.0`       | Multiplier for retry delay.                     |
+| `retry_on_errors`      | `(ErrorClass \| string \| RegExp)[]`      | `undefined` | Retry filter. `undefined` retries on any error. |
+| `timeout`              | `number \| null`                          | `undefined` | Per-attempt timeout in seconds.                 |
+| `semaphore_limit`      | `number \| null`                          | `undefined` | Max concurrent executions sharing semaphore.    |
+| `semaphore_name`       | `string \| ((...args) => string) \| null` | fn name     | Semaphore key.                                  |
+| `semaphore_lax`        | `boolean`                                 | `true`      | Continue if semaphore acquisition times out.    |
+| `semaphore_scope`      | `'global' \| 'class' \| 'instance'`       | `'global'`  | Scope for semaphore identity.                   |
+| `semaphore_timeout`    | `number \| null`                          | `undefined` | Max seconds waiting for semaphore.              |
 
-1. Event instance fields (`event_concurrency`, `event_handler_concurrency`)
-2. Handler options (`event_handler_concurrency`)
-3. Bus defaults
+#### Error types
 
-`"auto"` always resolves to the bus default.
+- `RetryTimeoutError`: per-attempt timeout exceeded.
+- `SemaphoreTimeoutError`: semaphore acquisition timeout (`semaphore_lax=false`).
 
-## Gotchas and Design Choices (What surprised us)
+#### Re-entrancy
 
-### A) Handler attribution without AsyncLocalStorage
+On Node.js/Bun, `AsyncLocalStorage` tracks held semaphores and avoids deadlocks for nested calls using the same semaphore.
+In browsers, this tracking is unavailable, avoid recursive/nested same-semaphore patterns there.
 
-We need to know **which handler emitted a child** to correctly assign:
+#### Interaction with bus concurrency
 
-- `event_parent_id`
-- `event_emitted_by_handler_id`
-- and to attach child events under the correct handler in the tree.
+Execution order when used on bus handlers:
 
-In TS we do this by injecting a **BusScopedEvent** into handlers, which captures the active handler id and
-propagates it via `event_emitted_by_handler_id`. This keeps parentage deterministic even with nested awaits.
+1. Bus acquires handler semaphore (`event_handler_concurrency`)
+2. `retry()` acquires retry semaphore (if configured)
+3. Handler executes (with retries)
+4. `retry()` releases retry semaphore
+5. Bus releases handler semaphore
 
-### B) Why runloop pausing exists
+Use bus/event timeouts for outer deadlines and `retry({ timeout })` for per-handler-attempt deadlines.
 
-When an event is awaited inside a handler, the event must **jump the queue**. If the runloop continues normally,
-it could process unrelated events ("overshoot"), breaking FIFO guarantees.
+#### Discouraged: retrying emit sites
 
-The `LockManager` pause mechanism (`requestPause`/`waitUntilRunloopResumed`) pauses the runloop while we run the awaited
-event immediately. Once the queue-jump completes, the runloop resumes in FIFO order. This matches the Python behavior.
+Avoid wrapping `emit()/done()` in `retry()` unless you intentionally want multiple event dispatches (a new event for every retry).  
+Keep retries on handlers so that your logs represent the original high-level intent, with a single event per call even if handling it took multiple tries.  
+Emitting a new event for each retry is only recommended if you are using the logs for debugging more than for replayability / time-travel.
 
-### C) BusScopedEvent: why it exists and how it works
+<br/>
 
-Forwarding exposes a subtle bug: if you pass the **same event object** to another bus, a naive implementation
-can mutate `event.bus` mid-handler and break parent-child tracking.
+---
 
-To prevent that:
+<br/>
 
-- Handlers always receive a **BusScopedEvent** (Proxy of the original event).
-- Its `bus` property is a proxy over the real `EventBus`.
-- That proxy intercepts `emit/dispatch` to set `event_parent_id` and attach children to the correct handler.
-- The original event object is still the canonical one stored in history.
+## 🏃 Runtimes
 
-### D) Cross-bus immediate processing (forwarding + awaiting)
+`bubus-ts` supports all major JS runtimes.
 
-When you `await event.done()` inside a handler:
+- Node.js (default development and test runtime)
+- Browsers (ESM)
+- Bun
+- Deno
 
-- the system finds all buses that have this event queued (using `EventBus._all_instances` + `event_path`)
-- pauses their runloops
-- processes the event immediately on each bus
-- then resumes the runloops
+### Browser support notes
 
-This gives the same "awaited events jump the queue" semantics as Python, but without a global lock.
+- The package output is ESM (`./dist/esm`) which is supported by all browsers [released after 2018](https://caniuse.com/?search=ESM)
+- `AsyncLocalStorage` is preserved at dispatch and used during handling when availabe (Node/Bun), otel/tracing context will work normally in those environments
 
-### E) Why `event.bus` is required for `done()`
+### Performance comparison (local run, per-event)
 
-`done()` is the signal to run an event immediately when called inside a handler. Without a bus, we can't
-perform the queue jump, so `done()` throws if no bus is attached.
+Measured locally on an `Apple M4 Pro` with:
 
-## Summary
+- `pnpm run perf:node` (`node v22.21.1`)
+- `pnpm run perf:bun` (`bun v1.3.9`)
+- `pnpm run perf:deno` (`deno v2.6.8`)
+- `pnpm run perf:browser` (`chrome v145.0.7632.6`)
 
-The core contract is preserved:
+| Runtime            | 1 bus x 50k events x 1 handler | 500 busses x 100 events x 1 handler | 1 bus x 1 event x 50k parallel handlers | 1 bus x 50k events x 50k one-off handlers | Worst case (N busses x N events x N handlers) |
+| ------------------ | ------------------------------ | ----------------------------------- | --------------------------------------- | ----------------------------------------- | --------------------------------------------- |
+| Node               | `0.015ms/event`, `0.6kb/event` | `0.058ms/event`, `0.1kb/event`      | `0.021ms/handler`, `189792.0kb/event`   | `0.028ms/event`, `0.6kb/event`            | `0.442ms/event`, `0.9kb/event`                |
+| Bun                | `0.011ms/event`, `2.5kb/event` | `0.054ms/event`, `1.0kb/event`      | `0.006ms/handler`, `223296.0kb/event`   | `0.019ms/event`, `2.8kb/event`            | `0.441ms/event`, `3.1kb/event`                |
+| Deno               | `0.018ms/event`, `1.2kb/event` | `0.063ms/event`, `0.4kb/event`      | `0.024ms/handler`, `156752.0kb/event`   | `0.064ms/event`, `2.6kb/event`            | `0.461ms/event`, `7.9kb/event`                |
+| Browser (Chromium) | `0.030ms/event`                | `0.197ms/event`                     | `0.022ms/handler`                       | `0.022ms/event`                           | `1.566ms/event`                               |
 
-- FIFO order
-- child event tracking
-- forwarding
-- await-inside-handler queue jump
+Notes:
 
-But the **implementation details are different** because JS needs browser compatibility and lacks Python's
-contextvars + asyncio primitives. The `LockManager` (runloop pause + semaphore coordination), `HandlerLock`
-(yield-and-reacquire), and `BusScopedEvent` proxy are the key differences that make the behavior match in practice.
+- `kb/event` is peak RSS delta per event during active processing (most representative of OS-visible RAM in Activity Monitor / Task Manager, with `EventBus.max_history_size=1`)
+- In `1 bus x 1 event x 50k parallel handlers` stats are shown per-handler for clarity, `0.02ms/handler * 50k handlers ~= 1000ms` for the entire event
+- Browser runtime does not expose memory usage easily, in practice memory performance in-browser is comparable to Node (they both use V8)
 
-## Publishing to npm (pnpm)
+<br/>
 
-Manual publish from your machine:
+---
 
-1. `cd bubus-ts`
-2. `pnpm install --frozen-lockfile`
-3. `pnpm login --registry https://registry.npmjs.org`
-4. `pnpm run release:check`
-5. `pnpm run release:dry-run`
-6. `pnpm publish --access public`
+<br/>
 
-Auth setup once per machine:
+## 👾 Development
 
-- `pnpm login --registry https://registry.npmjs.org`
+```bash
+git clone https://github.com/pirate/bbus bubus && cd bubus
 
-CI publish is also configured in `.github/workflows/publish-npm.yml` and expects `NPM_TOKEN` in repo secrets.
+cd ./bubus-ts
+pnpm install
+pnpm lint
+pnpm test
+```