bubus 1.8.1 → 2.2.1

package/README.md

@@ -2,15 +2,15 @@
 
 <img width="200" alt="image" src="https://github.com/user-attachments/assets/b3525c24-51ba-496c-b327-ccdfe46a7362" align="right" />
 
-[![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)
+[![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)
 
-[![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)
+[![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)
 
-Bubus is an in-memory event bus library for async Python and TS (node/browser).
+Bubus is an in-memory event bus library for async Python and TS (node/bun/deno/browser).
 
 It's designed for quickly building resilient, predictable, complex event-driven apps.
 
-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:
+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):
 
 ```python
 bus.on(SomeEvent, some_function)
@@ -21,7 +21,7 @@ It's async native, has proper automatic nested event tracking, and powerful conc
 
 - 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
+- built in locking options to force strict global FIFO processing or fully parallel processing
 
 ---
 
@@ -37,7 +37,7 @@ It's async native, has proper automatic nested event tracking, and powerful conc
 ## 🔢 Quickstart
 
 ```bash
-pnpm add bubus
+npm install bubus
 ```
 
 ```ts
@@ -46,7 +46,7 @@ import { z } from 'zod'
 
 const CreateUserEvent = BaseEvent.extend('CreateUserEvent', {
   email: z.string(),
-  event_result_schema: z.object({ user_id: z.string() }),
+  event_result_type: z.object({ user_id: z.string() }),
 })
 
 const bus = new EventBus('MyAuthEventBus')
@@ -58,7 +58,7 @@ bus.on(CreateUserEvent, async (event) => {
 
 const event = bus.emit(CreateUserEvent({ email: 'someuser@example.com' }))
 await event.done()
-console.log(event.first_result) // { user_id: 'some-user-uuid' }
+console.log(event.event_result) // { user_id: 'some-user-uuid' }
 ```
 
 <br/>
@@ -69,6 +69,9 @@ console.log(event.first_result) // { user_id: 'some-user-uuid' }
 
 ## ✨ 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)
@@ -81,6 +84,8 @@ The features offered in TS are broadly similar to the ones offered in the python
 
 See the [Python README](../README.md) for more details.
 
+</details>
+
 <br/>
 
 ---
@@ -89,39 +94,248 @@ See the [Python README](../README.md) for more details.
 
 ## 📚 API Documentation
 
-### `EventBus`
+<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.
 
-Create a bus:
+Constructor:
 
 ```ts
-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"
+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
 })
 ```
 
-Core methods:
+#### 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()`
 
-- `bus.emit(event)` aka `bus.dispatch(event)`
-- `bus.on(eventKey, handler, options?)`
-- `bus.off(eventKey, handler)`
-- `bus.find(eventKey, options?)`
-- `bus.waitUntilIdle()`
-- `bus.destroy()`
+```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:
 
-- 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
+- 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:
 
-### `BaseEvent`
+```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
+}
+```
 
-Define typed events:
+`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', {
@@ -131,53 +345,235 @@ const MyEvent = BaseEvent.extend('MyEvent', {
   // 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_result_type: z.string().optional(),
   event_timeout: 60,
   // ...
 })
 
-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()
+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()
 ```
 
-Special fields that change how the event is processed:
+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`
 
-- `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`
+#### `done()`
 
-Common methods:
+```ts
+done(): Promise<this>
+```
 
-- `await event.done()`
-- `await event.first()`
-- `event.toJSON()` (serialization format is compatible with python library)
-- `event.fromJSON()`
+- 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`.
 
-#### `done()`
+#### `eventCompleted()`
+
+```ts
+eventCompleted(): Promise<this>
+```
 
-- 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()`
+- Waits for completion in normal runloop order.
+- Use inside handlers when you explicitly do not want queue-jump behavior.
 
 #### `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.
+```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>>
+```
+
+- 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 })`
+
+#### `eventResultUpdate(handler, options?)`
+
+```ts
+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`.
 
-### `EventResult`
+</details>
 
-Each handler run produces an `EventResult` stored in `event.event_results` with:
+<details>
+<summary><strong>Review per-handler status, timing, outputs, and captured errors.</strong></summary>
 
-- `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
+Each handler execution creates one `EventResult` stored in `event.event_results`.
 
-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.
+#### 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/>
 
@@ -185,6 +581,8 @@ The event aggregates these via `event.event_results` and exposes the values from
 
 <br/>
 
+</details>
+
 ## 🧵 Advanced Concurrency Control
 
 ### Concurrency Config Options
@@ -192,7 +590,11 @@ The event aggregates these via `event.event_results` and exposes the values from
 #### Bus-level config options (`new EventBus(name, {...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
+  - 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'`)
@@ -254,21 +656,21 @@ Timeout resolution for each handler run:
 
 Additional timeout nuance:
 
-- `BaseEvent.event_timeout` starts as `null` unless set; dispatch applies bus default timeout when still unset.
+- `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.
 
 Use `@retry` for per-handler execution timeout/retry/backoff/semaphore control. Keep bus/event timeouts as outer execution budgets.
 
 ### Runtime lifecycle (bus -> event -> handler)
 
-Dispatch flow:
+Emit flow:
 
-1. `dispatch()` normalizes to original event and captures async context when available.
-2. Bus applies defaults and appends itself to `event_path`.
+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`).
+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.
 
@@ -280,7 +682,7 @@ Locking model:
 
 ### Queue-jumping (`await event.done()` inside handlers)
 
-Want to dispatch and await an event like a function call? simply `await event.done()`.
+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.
 
 ### `@retry` Decorator
@@ -292,7 +694,7 @@ When called inside a handler, the awaited event is processed immediately (queue-
 Retry and timeout belong on handlers, not emit sites:
 
 - Handlers fail; events are messages.
-- Handler-level retries preserve replay semantics (one event dispatch, internal retry attempts).
+- Handler-level retries preserve replay semantics (one event emit, internal retry attempts).
 - Bus concurrency and retry concerns are orthogonal and compose cleanly.
 
 #### Recommended pattern: `@retry()` on class methods
@@ -372,7 +774,7 @@ Use bus/event timeouts for outer deadlines and `retry({ timeout })` for per-hand
 
 #### Discouraged: retrying emit sites
 
-Avoid wrapping `emit()/done()` in `retry()` unless you intentionally want multiple event dispatches (a new event for every retry).  
+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.
 
@@ -382,6 +784,35 @@ Emitting a new event for each retry is only recommended if you are using the log
 
 <br/>
 
+## Bridges
+
+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.
+
+Bridges all expose a very simple bus-like API with only `.emit()` and `.on()`.
+
+**Example usage: link a bus to a redis pub/sub channel**
+
+```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
+```
+
+- `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')`
+
+<br/>
+
+---
+
+<br/>
+
 ## 🏃 Runtimes
 
 `bubus-ts` supports all major JS runtimes.
@@ -394,7 +825,7 @@ Emitting a new event for each retry is only recommended if you are using the log
 ### Browser support notes
 
 - 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
+- `AsyncLocalStorage` is preserved at emit and used during handling when available (Node/Bun), otel/tracing context will work normally in those environments
 
 ### Performance comparison (local run, per-event)
 
@@ -405,18 +836,18 @@ Measured locally on an `Apple M4 Pro` with:
 - `pnpm run perf:deno` (`deno v2.6.8`)
 - `pnpm run perf:browser` (`chrome v145.0.7632.6`)
 
-| 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`                               |
+| 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`                              |
 
 Notes:
 
 - `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)
+- Browser runtime does not expose memory usage directly, in practice memory performance in-browser is comparable to Node (they both use V8)
 
 <br/>
 
@@ -431,6 +862,10 @@ git clone https://github.com/pirate/bbus bubus && cd bubus
 
 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
 ```