# @mwillbanks/tuil-events

Source: /tuil/docs/reference/packages/events
Locale: en

Typed observable events and lifecycle signals for tuil applications.



## Overview [#overview]

Typed observable events and lifecycle signals for tuil applications.

`@mwillbanks/tuil-events` is independently installable and also participates in the
umbrella `@mwillbanks/tuil` runtime where applicable.

## Installation [#installation]

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @mwillbanks/tuil-events
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @mwillbanks/tuil-events
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @mwillbanks/tuil-events
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @mwillbanks/tuil-events
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## How it operates [#how-it-operates]

The typed event bus validates declared event names, schedules by priority, supports capture/target/bubble routing, redacts observed payloads, and keeps a bounded diagnostic history.

<Mermaid
  chart="flowchart LR
  S0[&#x22;declare&#x22;]
  S1[&#x22;subscribe&#x22;]
  S2[&#x22;emit&#x22;]
  S3[&#x22;route phases&#x22;]
  S4[&#x22;observe&#x22;]
  S5[&#x22;dispose&#x22;]
  S0 --> S1
  S1 --> S2
  S2 --> S3
  S3 --> S4
  S4 --> S5"
/>

## API [#api]

| API                                                                                          | Signature                            | Description                                |
| -------------------------------------------------------------------------------------------- | ------------------------------------ | ------------------------------------------ |
| [`defineEvents`](/tuil/docs/reference/packages/events/api/define-events)                          | `function defineEvents`              | Public function defineEvents.              |
| [`event`](/tuil/docs/reference/packages/events/api/event)                                         | `function event`                     | Public function event.                     |
| [`EventBus`](/tuil/docs/reference/packages/events/api/event-bus)                                  | `class EventBus`                     | Public class EventBus.                     |
| [`EventDefinition`](/tuil/docs/reference/packages/events/api/event-definition)                    | `interface EventDefinition`          | Public interface EventDefinition.          |
| [`EventDefinitions`](/tuil/docs/reference/packages/events/api/event-definitions)                  | `type EventDefinitions`              | Public type EventDefinitions.              |
| [`EventEmitOptions`](/tuil/docs/reference/packages/events/api/event-emit-options)                 | `interface EventEmitOptions`         | Public interface EventEmitOptions.         |
| [`EventMap`](/tuil/docs/reference/packages/events/api/event-map)                                  | `type EventMap`                      | Public type EventMap.                      |
| [`EventPhase`](/tuil/docs/reference/packages/events/api/event-phase)                              | `type EventPhase`                    | Public type EventPhase.                    |
| [`EventPriority`](/tuil/docs/reference/packages/events/api/event-priority)                        | `type EventPriority`                 | Public type EventPriority.                 |
| [`EventSource`](/tuil/docs/reference/packages/events/api/event-source)                            | `interface EventSource`              | Public interface EventSource.              |
| [`EventSubscriptionOptions`](/tuil/docs/reference/packages/events/api/event-subscription-options) | `interface EventSubscriptionOptions` | Public interface EventSubscriptionOptions. |
| [`EventTarget`](/tuil/docs/reference/packages/events/api/event-target)                            | `interface EventTarget`              | Public interface EventTarget.              |
| [`ObservedEvent`](/tuil/docs/reference/packages/events/api/observed-event)                        | `interface ObservedEvent`            | Public interface ObservedEvent.            |
| [`TuilEvent`](/tuil/docs/reference/packages/events/api/tuil-event)                                | `interface TuilEvent`                | Public interface TuilEvent.                |

## Events and lifecycle [#events-and-lifecycle]

`EventBus.emit()` produces `TuilEvent` objects with source, target, metadata, priority, phase, cancellation, and propagation controls.

All subscriptions and registrations return a disposer or belong to an owning
runtime that disposes them in reverse order.

## Example [#example]

```tsx
import { defineEvents, event, EventBus } from "@mwillbanks/tuil-events";

const events = new EventBus(defineEvents({ "build:done": event<{ id: string }>() }));
await events.emit("build:done", { id: "42" });
```

## Related [#related]

* [Package architecture](/tuil/docs/concepts/packages)
* [Events](/tuil/docs/concepts/events)
* [Testing](/tuil/docs/guides/testing)