bubus 1.7.3 → 2.2.1

package/README.md

@@ -1,362 +1,871 @@
-# 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)](https://pypi.org/project/bubus/) [![GitHub License](https://img.shields.io/github/license/pirate/bbus)](https://github.com/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)](https://www.npmjs.com/package/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/bun/deno/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 + emit API that's consistent across both languages and scales consistently from one event to millions (~0.2ms/event):
 
-### 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 processing 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
+npm install 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_type: 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.event_result) // { user_id: 'some-user-uuid' }
+```
+
+<br/>
+
+---
+
+<br/>
+
+## ✨ Features
+
+<details>
+<summary><strong>See the core TypeScript features and how they map to Python.</strong></summary>
+
+The features offered in TS are broadly similar to the ones offered in the python library.
+
+- 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.
+
+</details>
+
+<br/>
+
+---
+
+<br/>
 
-## Concurrency Overrides and Precedence
+## 📚 API Documentation
 
-You can override concurrency per event and per handler:
+<details>
+<summary><strong>Review bus construction, defaults, and core lifecycle methods.</strong></summary>
+
+The main bus class that registers handlers, schedules events, and tracks results.
+
+Constructor:
 
 ```ts
-const FastEvent = BaseEvent.extend('FastEvent', {
-  payload: z.string(),
+new EventBus(name?: string, options?: {
+  id?: string
+  max_history_size?: number | null
+  event_concurrency?: 'global-serial' | 'bus-serial' | 'parallel' | null
+  event_timeout?: number | null
+  event_slow_timeout?: number | null
+  event_handler_concurrency?: 'serial' | 'parallel' | null
+  event_handler_completion?: 'all' | 'first'
+  event_handler_slow_timeout?: number | null
+  event_handler_detect_file_paths?: boolean
 })
+```
 
-// Per-event override (highest precedence)
-const event = FastEvent({
-  payload: 'x',
-  event_concurrency: 'parallel',
-  event_handler_concurrency: 'parallel',
+#### Constructor options
+
+| Option                            | Type                                                    | Default        | Purpose                                                                                                                                                              |
+| --------------------------------- | ------------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                              | `string`                                                | `uuidv7()`     | Override bus UUID (mostly for serialization/tests).                                                                                                                  |
+| `max_history_size`                | `number \| null`                                        | `100`          | Max events kept in `event_history`; `null` = unbounded; `0` = keep only in-flight events and drop completed events immediately.                                      |
+| `max_history_drop`                | `boolean`                                               | `false`        | If `true`, when history is full drop oldest history entries (including uncompleted if needed). If `false`, reject new emits when history reaches `max_history_size`. |
+| `event_concurrency`               | `'global-serial' \| 'bus-serial' \| 'parallel' \| null` | `'bus-serial'` | Event-level scheduling policy.                                                                                                                                       |
+| `event_handler_concurrency`       | `'serial' \| 'parallel' \| null`                        | `'serial'`     | Per-event handler scheduling policy.                                                                                                                                 |
+| `event_handler_completion`        | `'all' \| 'first'`                                      | `'all'`        | Event completion mode if event does not override it.                                                                                                                 |
+| `event_timeout`                   | `number \| null`                                        | `60`           | Default per-handler timeout budget in seconds (unless overridden).                                                                                                   |
+| `event_handler_slow_timeout`      | `number \| null`                                        | `30`           | Slow handler warning threshold (seconds).                                                                                                                            |
+| `event_slow_timeout`              | `number \| null`                                        | `300`          | Slow event warning threshold (seconds).                                                                                                                              |
+| `event_handler_detect_file_paths` | `boolean`                                               | `true`         | Capture source file:line for handlers (slower, better logs).                                                                                                         |
+
+#### Runtime state properties
+
+- `id: string`
+- `name: string`
+- `label: string` (`${name}#${id.slice(-4)}`)
+- `handlers: Map<string, EventHandler>`
+- `handlers_by_key: Map<string, string[]>`
+- `event_history: Map<string, BaseEvent>`
+- `pending_event_queue: BaseEvent[]`
+- `in_flight_event_ids: Set<string>`
+- `locks: LockManager`
+
+#### `on()`
+
+```ts
+on<T extends BaseEvent>(
+  event_pattern: string | '*' | EventClass<T>,
+  handler: EventHandlerCallable<T>,
+  options?: Partial<EventHandler>
+): EventHandler
+```
+
+Use during startup/composition to register handlers.
+
+Advanced `options` fields, these can be used to override defaults per-handler if needed:
+
+- `handler_timeout?: number | null` hard delay before handler execution is aborted with a `HandlerTimeoutError`
+- `handler_slow_timeout?: number | null` delay before emitting a slow handler warning log line
+- `handler_name?: string` optional name to use instead of `anonymous` if handler is an unnamed arrow function
+- `handler_file_path?: string | null` optional path/to/source/file.js:lineno where the handler is defined, used for logging only
+- `id?: string` unique UUID for the handler (normally a hash of bus_id + event_pattern + handler_name + handler_registered_at)
+
+Notes:
+
+- Prefer class/factory keys (`bus.on(MyEvent, handler)`) for typed payload/result inference.
+- String and `'*'` matching are supported (`bus.on('MyEvent', ...)`, `bus.on('*', ...)`).
+- Returns an `EventHandler` object you can later pass to `off()` to de-register the handler if needed.
+
+#### `off()`
+
+```ts
+off<T extends BaseEvent>(
+  event_pattern: EventPattern<T> | '*',
+  handler?: EventHandlerCallable<T> | string | EventHandler
+): void
+```
+
+Use when tearing down subscriptions (tests, plugin unload, hot-reload).
+
+- Omit `handler` to remove all handlers for `event_pattern`.
+- Pass handler function reference to remove one by function identity.
+- Pass handler id (`string`) or `EventHandler` object to remove by id.
+- use `bus.off('*')` to remove _all_ registered handlers from the bus
+
+#### `emit()`
+
+```ts
+emit<T extends BaseEvent>(event: T): T
+```
+
+Behavior notes:
+
+- Per-event config fields stay on the event as provided; when unset (`null`/`undefined`), each bus resolves its own defaults at processing time.
+- If same event ends up forwarded through multiple buses, it is loop-protected using `event_path`.
+- Emit is synchronous and returns immediately with the same event object (`event.event_status` is initially `'pending'`).
+
+Normal lifecycle:
+
+1. Create event instance (`const event = MyEvent({...})`).
+2. Emit (`const queued = bus.emit(event)`).
+3. Await with `await queued.done()` (immediate/queue-jump semantics) or `await queued.eventCompleted()` (bus queue order).
+4. Inspect `queued.event_results`, `queued.event_result`, `queued.event_errors`, etc. if you need to access handler return values
+
+#### `find()`
+
+```ts
+find<T extends BaseEvent>(event_pattern: EventPattern<T> | '*', options?: FindOptions): Promise<T | null>
+find<T extends BaseEvent>(
+  event_pattern: EventPattern<T> | '*',
+  where: (event: T) => boolean,
+  options?: FindOptions
+): Promise<T | null>
+```
+
+Where:
+
+```ts
+type FindOptions = {
+  past?: boolean | number // true to look through all past events, or number in seconds to filter time range
+  future?: boolean | number // true to wait for event to appear indefinitely, or number in seconds to wait for event to appear
+  child_of?: BaseEvent | null // filter to only match events that are a child_of: some_parent_event
+} & {
+  // event_status: 'pending' | 'started' | 'completed'
+  // event_id: 'some-exact-event-uuid-here',
+  // event_started_at: string | null (exact iso datetime string or null)
+  // ... any event field can be passed to filter events using simple equality checks
+  [key: string]: unknown
+}
+```
+
+`bus.find()` returns the first matching event (in emit timestamp order).
+To find multiple matching events, iterate through `bus.event_history.filter((event) => ...some condition...)` manually.
+
+`where` behavior:
+Any filter predicate function in the form of `(event) => true | false`, returning true to consider the event a match.
+
+```ts
+const matching_event = bus.find(SomeEvent, (event) => event.some_field == 123)
+// or to match all event types:
+const matching_event = bus.find('*', (event) => event.some_field == 123)
+```
+
+`past` behavior:
+
+- `true`: search all history.
+- `false`: skip searching past event history.
+- `number`: search events emitted within last `N` seconds.
+
+`future` behavior:
+
+- `true`: wait forever for future match.
+- `false`: do not wait.
+- `number`: wait up to `N` seconds.
+
+Lifecycle use:
+
+- Use for idempotency / de-dupe before emit (`past: ...`).
+- Use for synchronization/waiting (`future: ...`).
+- Combine both to "check recent then wait".
+- Add `child_of` to constrain by parent/ancestor event chain.
+- Add any event field (e.g. `event_status`, `event_id`, `event_timeout`, `user_id`) to filter by strict equality.
+- Use wildcard matching with predicates when you want to search all event types: `bus.find('*', (event) => ...)`.
+
+Debouncing expensive events with `find()`:
+
+```ts
+const some_expensive_event = (await bus.find(ExpensiveEvent, { past: 15, future: 5 })) ?? bus.emit(ExpensiveEvent({}))
+await some_expensive_event.done()
+```
+
+Important semantics:
+
+- Past lookup matches any emitted events, not just completed events.
+- Past/future matches resolve as soon as event is emitted. If you need the completed event, await `event.done()` or pass `{event_status: 'completed'}` to filter only for completed events.
+- If both `past` and `future` are omitted, defaults are `past: true, future: false`.
+- If both `past` and `future` are `false`, it returns `null` immediately.
+- Detailed behavior matrix is covered in `bubus-ts/tests/eventbus_find.test.ts`.
+
+#### `waitUntilIdle(timeout?)`
+
+`await bus.waitUntilIdle()` is the normal "drain bus work" call to wait until bus is done processing everything queued.
+Pass an optional timeout in seconds (`await bus.waitUntilIdle(5)`) for a bounded wait.
+
+```ts
+bus.emit(OneEvent(...))
+bus.emit(TwoEvent(...))
+bus.emit(ThreeEvent(...))
+await bus.waitUntilIdle()   // this resolves once all three events have finished processing
+await bus.waitUntilIdle(5)  // wait up to 5 seconds, then continue even if work is still in-flight
+```
+
+#### Parent/child/event lookup helpers
+
+```ts
+eventIsChildOf(child_event: BaseEvent, paret_event: BaseEvent): boolean
+eventIsParentOf(parent_event: BaseEvent, child_event: BaseEvent): boolean
+findEventById(event_id: string): BaseEvent | null
+```
+
+#### `toString()` / `toJSON()` / `fromJSON()`
+
+```ts
+toString(): string
+toJSON(): EventBusJSON
+EventBus.fromJSON(data: unknown): EventBus
+```
+
+- `toString()` returns `BusName#abcd` style labels used in logs/errors.
+- `toJSON()` exports full bus state snapshot (config, handlers, indexes, event_history, pending queue, in-flight ids, find-waiter snapshots).
+- `fromJSON()` restores a new bus instance from that payload (handler functions are restored as no-op stubs).
+
+#### `logTree()`
+
+```ts
+logTree(): string
+```
+
+- `logTree()` returns a full event log hierarchy tree diagram for debugging.
+
+#### `destroy()`
+
+```ts
+destroy(): void
+```
+
+- `destroy()` clears handlers/history/locks and removes this bus from global weak registry.
+- `destroy()`/GC behavior is exercised in `bubus-ts/tests/eventbus.test.ts` and `bubus-ts/tests/eventbus_performance.test.ts`.
+
+</details>
+
+<details>
+<summary><strong>Review event fields, runtime state, and helper methods.</strong></summary>
+
+Base class + factory builder for typed event models.
+
+Define your own strongly typed events with `BaseEvent.extend('EventName', {...zod fields...})`:
+
+```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_type: z.string().optional(),
+  event_timeout: 60,
+  // ...
 })
 
-// Per-handler override (lower precedence)
-bus.on(FastEvent, handler, { event_handler_concurrency: 'parallel' })
+const pending_event = MyEvent({ some_key: 'abc', some_other_key: 234 })
+const queued_event = bus.emit(pending_event)
+const completed_event = await queued_event.done()
+```
+
+API behavior and lifecycle examples:
+
+- `bubus-ts/examples/simple.ts`
+- `bubus-ts/examples/immediate_event_processing.ts`
+- `bubus-ts/examples/forwarding_between_busses.ts`
+- `bubus-ts/tests/eventbus.test.ts`
+- `bubus-ts/tests/eventbus_find.test.ts`
+- `bubus-ts/tests/event_handler_first.test.ts`
+- `bubus-ts/tests/base_event_event_bus_proxy.test.ts`
+- `bubus-ts/tests/eventbus_timeout.test.ts`
+- `bubus-ts/tests/event_result.test.ts`
+
+#### Event configuration fields
+
+Special configuration fields you can set on each event to control processing:
+
+- `event_result_type?: z.ZodTypeAny | String | Number | Boolean | Array | Object`
+- `event_version?: string` (default: `'0.0.1'`; useful for your own schema/data migrations)
+- `event_timeout?: number | null`
+- `event_handler_timeout?: number | null`
+- `event_handler_slow_timeout?: number | null`
+- `event_concurrency?: 'global-serial' | 'bus-serial' | 'parallel' | null`
+- `event_handler_concurrency?: 'serial' | 'parallel' | null`
+- `event_handler_completion?: 'all' | 'first'`
+
+#### Runtime state fields
+
+- `event_id`, `event_type`, `event_version`
+- `event_path: string[]` (bus labels like `BusName#ab12`)
+- `event_parent_id: string | null`
+- `event_emitted_by_handler_id: string | null`
+- `event_status: 'pending' | 'started' | 'completed'`
+- `event_results: Map<string, EventResult>`
+- `event_pending_bus_count: number`
+- `event_created_at: string`
+- `event_started_at: string | null`
+- `event_completed_at: string | null`
+
+#### Read-only attributes
+
+- `event_parent` -> `BaseEvent | undefined`
+- `event_children` -> `BaseEvent[]`
+- `event_descendants` -> `BaseEvent[]`
+- `event_errors` -> `Error[]`
+- `event_result` -> `EventResultType<this> | undefined`
+
+#### `done()`
+
+```ts
+done(): Promise<this>
 ```
 
-Precedence order (highest → lowest):
+- If called from inside a running handler, it queue-jumps child processing immediately.
+- If called outside handler context, it waits for normal completion (or processes immediately if already next).
+- Rejects if event is not attached to a bus (`event has no bus attached`).
+- Queue-jump behavior is demonstrated in `bubus-ts/examples/immediate_event_processing.ts` and `bubus-ts/tests/base_event_event_bus_proxy.test.ts`.
 
-1. Event instance overrides (`event_concurrency`, `event_handler_concurrency`)
-2. Handler options (`event_handler_concurrency`)
-3. Bus defaults (`event_concurrency`, `event_handler_concurrency`)
+#### `eventCompleted()`
 
-`"auto"` resolves to the bus default.
+```ts
+eventCompleted(): Promise<this>
+```
+
+- Waits for completion in normal runloop order.
+- Use inside handlers when you explicitly do not want queue-jump behavior.
+
+#### `first()`
+
+```ts
+first(): Promise<EventResultType<this> | undefined>
+```
+
+- Forces `event_handler_completion = 'first'` for this run.
+- Returns temporally first non-`undefined` successful handler result.
+- Cancels pending/running losing handlers on the same bus.
+- Returns `undefined` when no handler produces a successful non-`undefined` value.
+- Cancellation and winner-selection behavior is covered in `bubus-ts/tests/event_handler_first.test.ts`.
+
+#### `eventResultsList(include?, options?)`
+
+```ts
+eventResultsList(
+  include?: (result: EventResultType<this> | undefined, event_result: EventResult<this>) => boolean,
+  options?: {
+    timeout?: number | null
+    include?: (result: EventResultType<this> | undefined, event_result: EventResult<this>) => boolean
+    raise_if_any?: boolean
+    raise_if_none?: boolean
+  }
+): Promise<Array<EventResultType<this> | undefined>>
+```
 
-## Handler Options
+- Returns handler result values in `event_results` order.
+- Default filter includes completed non-`null`/non-`undefined` non-error, non-forwarded (`BaseEvent`) values.
+- `raise_if_any` defaults to `true` and throws when any handler result has an error.
+- `raise_if_none` defaults to `true` and throws when no results match `include`.
+- `timeout` is in seconds and bounds how long to wait for completion.
+- Examples:
+  - `await event.eventResultsList({ raise_if_any: false, raise_if_none: false })`
+  - `await event.eventResultsList((result) => typeof result === 'object', { raise_if_any: false })`
 
-Handlers can be configured at registration time:
+#### `eventResultUpdate(handler, options?)`
 
 ```ts
-bus.on(SomeEvent, handler, {
+eventResultUpdate(
+  handler: EventHandler | EventHandlerCallable<this>,
+  options?: {
+    eventbus?: EventBus
+    status?: 'pending' | 'started' | 'completed' | 'error'
+    result?: EventResultType<this> | BaseEvent | undefined
+    error?: unknown
+  }
+): EventResult<this>
+```
+
+- Creates (if missing) or updates one `event_results` entry for the given handler id.
+- Useful for deterministic seeding/rehydration paths before resuming normal dispatch.
+- Example:
+  - `const seeded = event.eventResultUpdate(handler_entry, { eventbus: bus, status: 'pending' })`
+  - `seeded.update({ status: 'completed', result: 'seeded' })`
+
+#### `reset()`
+
+```ts
+reset(): this
+```
+
+- Returns a fresh event copy with runtime state reset to pending so it can be emitted again safely.
+- Original event object is unchanged.
+- Generates a new UUIDv7 `event_id` for the returned copy.
+- Clears runtime completion state (`event_results`, status/timestamps, captured async context, done signal, local bus binding).
+
+#### `toString()` / `toJSON()` / `fromJSON()`
+
+```ts
+toString(): string
+toJSON(): BaseEventData
+BaseEvent.fromJSON(data: unknown): BaseEvent
+EventFactory.fromJSON?.(data: unknown): TypedEvent
+```
+
+- JSON format is cross-language compatible with Python implementation.
+- `event_result_type` is serialized as JSON Schema when possible and rehydrated on `fromJSON`.
+- In TypeScript-only usage, `event_result_type` can be any Zod schema shape or base type like `number | string | boolean | etc.`. For cross-language roundtrips, object-like schemas (including Python `TypedDict`/`dataclass`-style shapes) are reconstructed on Python as Pydantic models, JSON object keys are always strings, and some fine-grained string-shape constraints may be normalized between Zod and Pydantic.
+- Round-trip coverage is in `bubus-ts/tests/event_result_typed_results.test.ts` and `bubus-ts/tests/eventbus.test.ts`.
+
+</details>
+
+<details>
+<summary><strong>Review per-handler status, timing, outputs, and captured errors.</strong></summary>
+
+Each handler execution creates one `EventResult` stored in `event.event_results`.
+
+#### Main fields
+
+- `id: string` (uuidv7 string)
+- `status: 'pending' | 'started' | 'completed' | 'error'`
+- `event: BaseEvent`
+- `handler: EventHandler`
+- `result: EventResultType<this> | undefined`
+- `error: unknown | undefined`
+- `started_at: string | null` (ISO datetime string)
+- `completed_at: string | null` (ISO datetime string)
+- `event_children: BaseEvent[]`
+
+#### Read-only getters
+
+- `event_id` -> `string` uuiv7 of the event the result is for
+- `bus` -> `EventBus` instance it's associated with
+- `handler_id` -> `string` uuidv5 of the `EventHandler`
+- `handler_name` -> `string | 'anonymous'` function name of the handler method
+- `handler_file_path` -> `string | null` path/to/file.js:lineno where the handler method is defined
+- `eventbus_name` -> `string` name, same as `this.bus.name`
+- `eventbus_id` -> `string` uuidv7, same as `this.bus.id`
+- `eventbus_label` -> `string` label, same as `this.bus.label`
+- `value` -> `EventResultType<this> | undefined` alias of `this.result`
+- `raw_value` -> `any` raw result value before schema validation, available when handler return value validation fails
+- `handler_timeout` -> `number` seconds before handler execution is aborted (precedence: handler config -> event config -> bus level defaults)
+- `handler_slow_timeout` -> `number` seconds before logging a slow execution warning (same prececence as `handler_timeout`)
+
+#### `toString()` / `toJSON()` / `fromJSON()`
+
+```ts
+toString(): string
+toJSON(): EventResultJSON
+EventResult.fromJSON(event, data): EventResult
+```
+
+</details>
+
+<details>
+<summary><strong>Review handler metadata, registration fields, and serialization helpers.</strong></summary>
+
+Represents one registered handler entry on a bus. You usually get these from `bus.on(...)`, then pass them to `bus.off(...)` to remove.
+
+#### Main fields
+
+- `id` unique handler UUIDv5 (deterministic hash from bus/event/handler metadata unless overridden)
+- `handler` function reference that executes for matching events
+- `handler_name` function name (or `'anonymous'`)
+- `handler_file_path` detected source path (`~/path/file.ts:line`) or `null`
+- `handler_timeout` optional timeout override in seconds (`null` disables timeout limit)
+- `handler_slow_timeout` optional slow-warning threshold in seconds (`null` disables slow warning)
+- `handler_registered_at` ISO timestamp
+- `event_pattern` subscribed key (`'SomeEvent'` or `'*'`)
+- `eventbus_name` bus name where this handler was registered
+- `eventbus_id` bus UUID where this handler was registered
+
+#### `toString()` / `toJSON()` / `fromJSON()`
+
+```ts
+toString(): string
+toJSON(): EventHandlerJSON
+EventHandler.fromJSON(data: unknown, handler?: EventHandlerCallable): EventHandler
+```
+
+- `toString()` returns `handlerName() (path:line)` when path/name are available, otherwise `function#abcd()`.
+- `toJSON()` emits only serializable handler metadata (never function bodies).
+- `fromJSON()` reconstructs the handler entry and accepts an optional real function to re-bind execution behavior.
+
+<br/>
+
+---
+
+<br/>
+
+</details>
+
+## 🧵 Advanced Concurrency Control
+
+### Concurrency Config Options
+
+#### Bus-level config options (`new EventBus(name, {...options...})`)
+
+- `max_history_size?: number | null` (default: `100`)
+  - Max events kept in history. `null` = unlimited. `bus.find(...)` uses this log to query recently emitted events
+  - `0` keeps only pending/in-flight events; each event is removed from history immediately after completion.
+- `max_history_drop?: boolean` (default: `false`)
+  - If `true`, drop oldest history entries when history is full (including uncompleted entries if needed).
+  - If `false`, reject new emits when history is full.
+- `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.
+
+#### Event-level config options
+
+Override the bus defaults on a per-event basis by using these special fields in the event:
+
+```ts
+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.
+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
+
+Set at registration:
+
+```ts
+bus.on(MyEvent, handler, { handler_timeout: 2 }) // max time in seconds this handler is allowed to run before it's aborted
+```
+
+#### Precedence and interaction
+
+Event and handler concurrency precedence:
+
+1. Event instance override (`event.event_concurrency`, `event.event_handler_concurrency`)
+2. Bus defaults (`EventBus` options)
+3. Built-in defaults (`bus-serial`, `serial`)
+
+Timeout resolution for each handler run:
 
-### Practical guidance for high-load deployments
+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
 
-- 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.
+Additional timeout nuance:
 
-## Semaphores (how concurrency is enforced)
+- `BaseEvent.event_timeout` starts as `null` unless set; each processing bus resolves its own `event_timeout` default when still unset.
+- Bus/event timeouts are outer budgets for handler execution; use `@retry({ timeout })` for per-attempt timeouts.
 
-We use four semaphores:
+Use `@retry` for per-handler execution timeout/retry/backoff/semaphore control. Keep bus/event timeouts as outer execution budgets.
 
-- `LockManager.global_event_semaphore`
-- `LockManager.global_handler_semaphore`
-- `bus.locks.bus_event_semaphore`
-- `bus.locks.bus_handler_semaphore`
+### Runtime lifecycle (bus -> event -> handler)
 
-They are applied centrally when scheduling events and handlers, so concurrency is controlled without scattering
-mutex checks throughout the code.
+Emit flow:
 
-## Full lifecycle across concurrency modes
+1. `emit()` normalizes to original event and captures async context when available.
+2. Bus appends itself to `event_path` and records runtime ownership for this processing pass.
+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`), with timeout/concurrency defaults resolved at processing time on the current bus when event fields are unset.
+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.
 
-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.
+Locking model:
 
-### 1) Base execution flow (applies to all modes)
+- Global event semaphore: `global-serial`
+- Bus event semaphore: `bus-serial`
+- Per-event handler semaphore: `serial` handler mode
 
-**Dispatch (non-awaited):**
+### Queue-jumping (`await event.done()` inside handlers)
 
-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()`.
+Want to emit 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.
 
-**Runloop + processing:**
+### `@retry` Decorator
 
-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)
+`retry()` adds retry logic and optional semaphore-based concurrency limiting to async functions/handlers.
 
-### 2) Event concurrency modes (`event_concurrency`)
+#### Why retry is handler-level
 
-- **`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.
+Retry and timeout belong on handlers, not emit sites:
 
-**Mixed buses:** each bus enforces its own event mode. Forwarding to another bus does not inherit the source bus’s mode.
+- Handlers fail; events are messages.
+- Handler-level retries preserve replay semantics (one event emit, internal retry attempts).
+- Bus concurrency and retry concerns are orthogonal and compose cleanly.
 
-### 3) Handler concurrency modes (`event_handler_concurrency`)
+#### Recommended pattern: `@retry()` on class methods
 
-`event_handler_concurrency` controls how handlers run **for a single event**:
+```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()
+```
+
+#### Also works: inline HOF
+
+```ts
+bus.on(
+  MyEvent,
+  retry({ max_attempts: 3, timeout: 10 })(async (event) => {
+    await riskyOperation(event.data)
+  })
+)
+```
 
-- **`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.
+#### Options
 
-**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.
+| 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.              |
 
-### 4) Forwarding across buses (non-awaited)
+#### Error types
 
-When a handler on Bus A calls `bus_b.dispatch(event)` without awaiting:
+- `RetryTimeoutError`: per-attempt timeout exceeded.
+- `SemaphoreTimeoutError`: semaphore acquisition timeout (`semaphore_lax=false`).
 
-- 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.
+#### Re-entrancy
 
-### 5) Queue-jump (`await event.done()` inside handlers)
+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.
 
-When `event.done()` is awaited inside a handler, **queue-jump** happens:
+#### Interaction with bus concurrency
 
-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.
+Execution order when used on bus handlers:
 
-**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.
+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
 
-### 6) Precedence recap
+Use bus/event timeouts for outer deadlines and `retry({ timeout })` for per-handler-attempt deadlines.
 
-Highest → lowest:
+#### Discouraged: retrying emit sites
 
-1. Event instance fields (`event_concurrency`, `event_handler_concurrency`)
-2. Handler options (`event_handler_concurrency`)
-3. Bus defaults
+Avoid wrapping `emit()/done()` in `retry()` unless you intentionally want multiple event emits (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.
 
-`"auto"` always resolves to the bus default.
+<br/>
 
-## Gotchas and Design Choices (What surprised us)
+---
 
-### A) Handler attribution without AsyncLocalStorage
+<br/>
 
-We need to know **which handler emitted a child** to correctly assign:
+## Bridges
 
-- `event_parent_id`
-- `event_emitted_by_handler_id`
-- and to attach child events under the correct handler in the tree.
+Bridges are optional extra connectors provided that allow you to send/receive events from an external service, and you do not need to use a bridge to use bubus since it's normally purely in-memory. These are just simple helpers to forward bubus events JSON to storage engines / other processes / other machines; they prevent loops automatically, but beyond that it's only basic forwarding with no handler pickling or anything fancy.
 
-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.
+Bridges all expose a very simple bus-like API with only `.emit()` and `.on()`.
 
-### B) Why runloop pausing exists
+**Example usage: link a bus to a redis pub/sub channel**
 
-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.
+```ts
+const bridge = new RedisEventBridge('redis://redis@localhost:6379')
+
+bus.on('*', bridge.emit) // listen for all events on bus and send them to redis channel
+bridge.on('*', bus.emit) // listen for new events in redis channel and emit them on our bus
+```
 
-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.
+- `new SocketEventBridge('/tmp/bubus_events.sock')`
+- `new HTTPEventBridge({ send_to: 'https://127.0.0.1:8001/bubus_events', listen_on: 'http://0.0.0.0:8002/bubus_events' })`
+- `new JSONLEventBridge('/tmp/bubus_events.jsonl')`
+- `new SQLiteEventBridge('/tmp/bubus_events.sqlite3')`
+- `new PostgresEventBridge('postgresql://user:pass@localhost:5432/dbname/bubus_events')`
+- `new RedisEventBridge('redis://user:pass@localhost:6379/1/bubus_events')`
+- `new NATSEventBridge('nats://localhost:4222', 'bubus_events')`
 
-### 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 emit and used during handling when available (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 buses 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 buses x N events x N handlers) |
+| ------------------ | ------------------------------ | ---------------------------------- | --------------------------------------- | ----------------------------------------- | -------------------------------------------- |
+| Node               | `0.015ms/event`, `0.6kb/event` | `0.058ms/event`, `0.1kb/event`     | `0.021ms/handler`, `3.8kb/handler`      | `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`, `4.5kb/handler`      | `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`, `3.1kb/handler`      | `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 directly, 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
+
+prek install           # install pre-commit hooks
+prek run --all-files   # run pre-commit hooks on all files manually
+
+pnpm lint
+pnpm test
+```