# Emitter

Source: https://developers.inkdrop.app/event-subscription/emitter

Utility class to be used when implementing event-based APIs that allows for handlers registered via `::on` to be invoked with calls to `::emit`.
Instances of this class are intended to be used internally by classes that expose an event-based API.
You can use it by requiring [event-kit](https://github.com/atom/event-kit) module.

```js
import { Emitter } from 'event-kit'

class User {
  constructor() {
    this.emitter = new Emitter()
  }

  onDidChangeName(callback) {
    this.emitter.on('did-change-name', callback)
  }

  setName(name) {
    if (name !== this.name) {
      this.name = name
      this.emitter.emit('did-change-name', name)
    }

    return this.name
  }
}
```

---

## Construction `constructor()`

Construct an emitter.

```js
const emitter = new Emitter();
```

---

## Destruction `dispose()`

Unsubscribe all handlers.

```js
emitter.dispose();
```

---

## Clear subscribers `clear()`

Clear out any existing subscribers.

```js
emitter.clear();
```

---

## Event Subscription: Repeated execution `on<T>(eventName, handler)`

Register the given handler function to be invoked whenever events by the given name are emitted via `::emit`.

### Parameters

- **eventName** (string, required)

  String naming the event that you want to invoke the handler when emitted.
- **handler** ((value?: T) => void, required)

  Function to invoke when `::emit` is called with the given event name.
  `T` is the type of the value passed when calling `::emit`.

### Return value

Returns a [Disposable][disposable].

```js
emitter.on(
    'did-change-name', 
    (value) => console.log(value)
);
```

---

## Event Subscription: One-time execution `once<T>(eventName, handler)`

Register the given handler function to be invoked the next time an events with the given name is emitted via `::emit`.

### Parameters

- **eventName** (string, required)

  String naming the event that you want to invoke the handler when emitted.
- **handler** ((value?: T) => void, required)

  Function to invoke when `::emit` is called with the given event name.
  `T` is the type of the value passed when calling `::emit`.

### Return value

Returns a [Disposable][disposable].

```js
emitter.once(
    'did-change-name',
    (value) => console.log("Once", value)
);
```

---

## Event Subscription: Prioritized execution `preempt<T>(eventName, handler)`

Register the given handler function to be invoked *before* all other handlers existing at the time of subscription whenever events by the given name are emitted via `::emit`.

Use this method when you need to be the first to handle a given event. This could be required when a data structure in a parent object needs to be updated before third-party event handlers registered on a child object via a public API are invoked.
Your handler could itself be preempted via subsequent calls to this method, but this can be controlled by keeping methods based on `::preempt` private.

### Parameters

- **eventName** (string, required)

  String naming the event that you want to invoke the handler when emitted.
- **handler** ((value?: T) => void, required)

  Function to invoke when `::emit` is called with the given event name.
  `T` is the type of the value passed when calling `::emit`.

### Return value

Returns a [Disposable][disposable].

```js
emitter.preempt(
    'did-change-name',
    (value) => console.log("First", value)
);
```

---

## Event Emission `emit<T>(eventName, value)`

Invoke all handlers registered for the given event name.

### Parameters

- **eventName** (string, required)

  The name of the event to emit. Handlers registered for the same name will be invoked.
- **value** (T, required)

  Callbacks will be invoked with this value as an argument.

```js
emitter.emit('did-change-name', "string value");
```

[disposable]: https://developers.inkdrop.app/event-subscription/disposable