# Events API reference

> Current emitted signatures and options for @db3.ai/app/events.

- Package: `@db3.ai/app/events`
- Canonical page: [https://db3.ai/docs/events-api](https://db3.ai/docs/events-api)
- Markdown: [https://db3.ai/docs/events-api.md](https://db3.ai/docs/events-api.md)
- Framework source of truth: `packages/app/src/events/README.md`

<a id="start"></a>

## Imports and examples

Import supported APIs from `@db3.ai/app/events`. These signatures come from the staged package used by consumers. Relative filenames in declarations describe type dependencies; they are not extra supported deep imports.

Use the guide for setup, executable examples, failure handling and ownership. A signature is not proof that every deployment or provider has been exercised.

- [Guide, examples and testing](https://db3.ai/docs/events.md)

<a id="events"></a>

## Dispatcher

### Dispatcher

```typescript
import type * as events from './contracts/index.js';
/**
 * Typed in-process dispatcher for application and framework events.
 *
 * Event classes are runtime keys, so listeners infer the correct event shape
 * without requiring a global string-to-payload registry. Dispatch is
 * intentionally synchronous from the caller's perspective: listeners run in
 * registration order and asynchronous listeners are awaited.
 *
 * @example
 * const unsubscribe = app().events.listen(WebsiteCrawled, async event => {
 * 	await indexWebsite(event.websiteId);
 * });
 *
 * await app().events.dispatch(new WebsiteCrawled(websiteId));
 * unsubscribe();
 */
export declare class Events {
    #private;
    /**
     * Registers a listener for exactly one event class.
     *
     * Subclasses are independent event types and do not automatically invoke
     * listeners registered for a parent class.
     *
     * @param eventType - Event class used as the listener key.
     * @param listener - Consumer invoked for subsequent event instances.
     * @returns Idempotent function that removes this registration.
     */
    listen<TEvent extends object>(eventType: events.EventConstructor<TEvent>, listener: events.EventListener<TEvent>): events.EventUnsubscribe;
    /**
     * Registers a listener that removes itself before its first invocation.
     *
     * Removing the registration before calling the listener guarantees that
     * overlapping dispatches cannot invoke the one-shot listener twice.
     *
     * @param eventType - Event class used as the listener key.
     * @param listener - Consumer invoked at most once.
     * @returns Idempotent function that removes the pending registration.
     */
    once<TEvent extends object>(eventType: events.EventConstructor<TEvent>, listener: events.EventListener<TEvent>): events.EventUnsubscribe;
    /**
     * Dispatches one class instance to its current listeners.
     *
     * Listeners run sequentially in registration order. If a listener throws or
     * rejects, dispatch rejects immediately and later listeners are not invoked.
     * Callers therefore control whether listener completion is part of their
     * operation or should be delegated to a durable queued job.
     *
     * @param event - Class instance containing event data.
     */
    dispatch<TEvent extends object>(event: TEvent): Promise<void>;
    /**
     * Returns whether an event class currently has one or more listeners.
     *
     * @param eventType - Exact event class to inspect.
     * @returns True when at least one listener is registered.
     */
    hasListeners<TEvent extends object>(eventType: events.EventConstructor<TEvent>): boolean;
    /**
     * Removes every listener registered for one event class.
     *
     * @param eventType - Exact event class whose registrations should be removed.
     */
    forget<TEvent extends object>(eventType: events.EventConstructor<TEvent>): void;
    /**
     * Removes all listener registrations owned by this dispatcher.
     */
    clear(): void;
}
```

<a id="identity"></a>

## Event identity

### Event identity

```typescript
/**
 * Runtime class token used to register a listener for one event type.
 *
 * The constructor is used only as an identity key. Applications create and
 * dispatch their event instances themselves.
 */
export interface EventConstructor<TEvent extends object = object> {
    /** Human-readable class name used in diagnostics and tooling. */
    readonly name: string;
    /** Event instance shape represented by this class token. */
    readonly prototype: TEvent;
}
```

<a id="listener"></a>

## Listener callback

### Listener callback

```typescript
/**
 * Synchronous or asynchronous consumer of one application event type.
 *
 * @param event - Event instance dispatched by application or framework code.
 */
export type EventListener<TEvent extends object> = (event: TEvent) => void | Promise<void>;
```

<a id="unsubscribe"></a>

## Unsubscribe function

### Unsubscribe function

```typescript
/**
 * Idempotent function that removes one event listener registration.
 */
export type EventUnsubscribe = () => void;
```

## Related documentation
- [React to a saved note](https://db3.ai/docs/events.md): Use typed, in-process events for small reactions while keeping delivery and failure behavior visible.

## Guidance for AI tools
Use the documented public import `@db3.ai/app/events` and its exported types. Prefer the source-backed examples and behavioural outcomes above over invented APIs or source-relative internal imports.