# EventEmitter

The type behind `on` and `off`. **There are two emitters, and subscribing to the wrong one is silent.** Document lifecycle events are global and fire on `Kernstra.events`; everything else is per-viewer and fires on `viewer.on(...)`. A handler registered on the wrong emitter never runs and never warns. Each emitter is typed by its own map — `GlobalEventMap` for `Kernstra.events`, `ViewerEventMap` for `viewer.on` — so subscribing to a viewer event on the global emitter, or the reverse, is a compile error rather than a handler that never runs. `SDKEventMap` is both together, for a payload typed by name (`SDKEventMap['pageChanged']`). Every event and its payload is listed under [Events](https://kernstra.com/docs/web-sdk/api/events).

`Kernstra.events` offers `on` and `off` only (the exported `GlobalEvents` type): only the SDK emits on it. `EventEmitter` is exported because it is the type behind `on` and `off`, not as a channel to emit through; its `emit` and `removeAllListeners` are the SDK's own. A handler that throws is logged and does not stop the others. `Kernstra.destroy()` leaves what is subscribed to `Kernstra.events` in place: a handler registered at module level hears the next `init()`'s `initialized` without subscribing again, and `Kernstra.events` is the same emitter for the page's life. No member needs a license feature or a document.

- Kind: class
- Access: `viewer.on() / Kernstra.events.on()`

## Usage

```ts
import { Kernstra } from '@kernstra/pdf-web-sdk';

// Document lifecycle: global.
Kernstra.events.on('documentLoaded', ({ pageCount }) => setPageCount(pageCount));

// Everything else: on the viewer.
viewer.on('pageChanged', ({ pageIndex }) => setCurrentPage(pageIndex));
```

## Subscribing

### `on`

```ts
on<K extends keyof T>(event: K, handler: EventHandler<T[K]>, options?: SubscribeOptions): () => void
```

Subscribe to a typed event. `on()` returns the unsubscribe; `Kernstra.events.on` takes the same options as `viewer.on`.

- Kind: method
- Since: 1.0.0

| Parameter | Type | Description |
| --- | --- | --- |
| `event` | `K` | An event name of this emitter's map: `GlobalEventMap` on `Kernstra.events`, `ViewerEventMap` on a viewer. |
| `handler` | `EventHandler<T[K]>` | Receives the typed payload. One that throws is logged and does not stop the others. |
| `options?` | `SubscribeOptions` | `{ once?: boolean; signal?: AbortSignal }`. `once` hears the next emit only; `signal` unsubscribes when the `AbortSignal` aborts, so one `AbortController` can end every subscription a component made (a signal already aborted subscribes nothing). |

Returns `() => void`: The unsubscribe.

```ts
const stop = viewer.on('pageChanged', ({ pageIndex }) => setCurrentPage(pageIndex));
stop();

const controller = new AbortController();
viewer.on('zoomChanged', ({ scale }) => setZoom(scale), { signal: controller.signal });
viewer.on('documentChanged', () => markDirty(), { signal: controller.signal });
controller.abort(); // both gone

Kernstra.events.on('initialized', ({ version }) => console.log(version), { once: true });
```

Page: https://kernstra.com/docs/web-sdk/api/eventemitter/on

### `off`

```ts
off<K extends keyof T>(event: K, handler: EventHandler<T[K]>): void
```

Unsubscribe from an event. `off(event, handler)` with the same handler reference works as well as the unsubscribe `on()` returned.

- Kind: method
- Since: 1.0.0

| Parameter | Type | Description |
| --- | --- | --- |
| `event` | `K` | The event name. |
| `handler` | `EventHandler<T[K]>` | The same handler reference that was passed to `on()`. |

Returns `void`

```ts
const onLoaded = (data: SDKEventMap['documentLoaded']) => setPageCount(data.pageCount);
Kernstra.events.on('documentLoaded', onLoaded);
Kernstra.events.off('documentLoaded', onLoaded);
```

Page: https://kernstra.com/docs/web-sdk/api/eventemitter/off

## Emitting

### `emit`

```ts
emit<K extends keyof T>(event: K, data: T[K]): void
```

The SDK's own: calls every handler of the event synchronously, in the order they subscribed; one that throws is logged and does not stop the others. `Kernstra.events` exposes `on` and `off` only.

- Kind: method
- Since: 1.0.0

| Parameter | Type | Description |
| --- | --- | --- |
| `event` | `K` | The event name. |
| `data` | `T[K]` | The payload, as the emitter's map types it. |

Returns `void`

Page: https://kernstra.com/docs/web-sdk/api/eventemitter/emit

### `removeAllListeners`

```ts
removeAllListeners(): void
```

The SDK's own: drops every handler of every event, as a viewer's `destroy()` does. `Kernstra.events` exposes `on` and `off` only, so a host cannot drop every other subscriber.

- Kind: method
- Since: 1.0.0

Returns `void`

Page: https://kernstra.com/docs/web-sdk/api/eventemitter/removealllisteners

Web page: https://kernstra.com/docs/web-sdk/api/eventemitter