# Nitt

> Small functional event emitter / pubsub.

*   **Microscopic:** weighs less than 200 bytes gzipped
*   **Useful:** a wildcard `"*"` event type listens to all events
*   **Familiar:** same names & ideas as [Node's EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)

nitt was made for the browser, but works in any JavaScript runtime. It has no dependencies and supports IE9+.

## Table of Contents

*   [Install](#install)
*   [Usage](#usage)
*   [Examples & Demos](#examples--demos)
*   [API](#api)
*   [Contribute](#contribute)
*   [License](#license)

## Install

This project uses [node](http://nodejs.org) and [npm](https://npmjs.com). Go check them out if you don't have them locally installed.

```sh
$ npm install --save nitt
```

Then with a module bundler like [rollup](http://rollupjs.org/) or [webpack](https://webpack.js.org/), use as you would anything else:

```javascript
// using ES6 modules
import nitt from 'nitt'

// using CommonJS modules
var nitt = require('nitt')
```

The [UMD](https://github.com/umdjs/umd) build is also available on [unpkg](https://unpkg.com):

```html
<script src="https://unpkg.com/nitt/dist/nitt.umd.js"></script>
```

You can find the library on `window.nitt`.

## Usage

```js
import nitt from 'nitt'

const emitter = nitt()

// listen to an event
emitter.on('foo', e => console.log('foo', e) )

// listen to all events
emitter.on('*', (type, e) => console.log(type, e) )

// fire an event
emitter.emit('foo', { a: 'b' })

// clearing all events
emitter.all.clear()

// working with handler references:
function onFoo() {}
emitter.on('foo', onFoo)   // listen
emitter.off('foo', onFoo)  // unlisten
```

### Typescript

Set `"strict": true` in your tsconfig.json to get improved type inference for `nitt` instance methods.

```ts
import nitt from 'nitt';

type Events = {
  foo: string;
  bar?: number;
};

const emitter = nitt<Events>(); // inferred as emitter<Events>

emitter.on('foo', (e) => {}); // 'e' has inferred type 'string'

emitter.emit('foo', 42); // Error: Argument of type 'number' is not assignable to parameter of type 'string'. (2345)
```

Alternatively, you can use the provided `emitter` type:

```ts
import nitt, { emitter } from 'nitt';

type Events = {
  foo: string;
  bar?: number;
};

const emitter: emitter<Events> = nitt<Events>();
```

## API

<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

#### Table of Contents

*   [nitt](#nitt)
*   [all](#all)
*   [on](#on)
    *   [Parameters](#parameters)
*   [off](#off)
    *   [Parameters](#parameters-1)
*   [emit](#emit)
    *   [Parameters](#parameters-2)
*   [once](#once)
    *   [Parameters](#parameters-3)
*   [when](#when)
    *   [Parameters](#parameters-4)

### nitt

Nitt: Tiny (~200b) functional event emitter / pubsub.

Returns **Nitt**&#x20;

### all

A Map of event names to registered handler functions.

### on

Register an event handler for the given type.

#### Parameters

*   `type` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | [symbol](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Symbol))** Type of event to listen for, or `'*'` for all events
*   `handler` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** Function to call in response to given event

### off

Remove an event handler for the given type.
If `handler` is omitted, all handlers of the given type are removed.

#### Parameters

*   `type` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | [symbol](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Symbol))** Type of event to unregister `handler` from (`'*'` to remove a wildcard handler)
*   `handler` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)?** Handler function to remove

### emit

Invoke all handlers for the given type.
If present, `'*'` handlers are invoked after type-matched handlers.

Note: Manually firing '\*' handlers is not supported.

#### Parameters

*   `type` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | [symbol](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Symbol))** The event type to invoke
*   `evt` **Any?** Any value (object is recommended and powerful), passed to each handler

### once

Register an event handler that is executed just once for the given type.

#### Parameters

*   `type` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | [symbol](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Symbol))** Type of event to listen for, or `'*'` for all events
*   `handler` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** Function to call in response to given event

### when

Returns a promise for a single event

#### Parameters

*   `type` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Type of event to listen for, or `"*"` for any event

Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<any>**&#x20;

## Contribute

For reporting issues and submitting patches, send an email.

## License

[MIT License](https://opensource.org/licenses/MIT)