npm package: @poppinss/events
Description: Event emitter with asynchronous events
Author: virk,poppinss
Latest version: 1.0.2
Deprecated: Use @adonisjs/events instead

<div align="center">
  <img src="https://res.cloudinary.com/adonisjs/image/upload/q_100/v1557762307/poppinss_iftxlt.jpg" width="600px">
</div>

# Event emitter
> Async event emitter with support for typed events

[![circleci-image]][circleci-url] [![npm-image]][npm-url] ![][typescript-image] [![license-image]][license-url]

This module is extracted from [AdonisJs](https://adonisjs.com). It is an Async event emitter with support for Typed events when using typescript.

## Features
- Asynchronous
- Support for Typed events (when using Typescript)
- Comes with fake emitter for testing

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
## Table of contents

- [Usage](#usage)
- [Asynchronous](#asynchronous)
- [Typed events](#typed-events)
- [Fake emitter](#fake-emitter)
    - [Application code](#application-code)
    - [Test](#test)
- [AdonisJs usage](#adonisjs-usage)
- [API](#api)
- [Maintainers](#maintainers)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Usage
Install the package from npm registry as follows:

```sh
npm i @poppinss/events

# yarn
yarn add @poppinss/events
```

And then use it as follows:

```ts
import { Emitter } from '@poppinss/events'
const emitter = new Emitter()

emitter.on('signup', async (data) => {
  // 
})

emitter.emit('signup', { id: 1, email: 'foo@bar.com' })
```

## Asynchronous
Node.js inbuilt event emitter is synchronous and blocks the event loop while emitting events. On the other hand, this module relies on [emittery](https://github.com/sindresorhus/emittery) to emit events asynchronously.

## Typed events
When using Typescript, you can attach data types to a event name and the Typescript compiler will complain, if types aren't the same.

```ts
import { Emitter } from '@poppinss/events'

type EventsMap = {
  'new:user': { id: number },
}

const emitter = new Emitter<EventsMap>()

emitter.emit('new:user', { id: 1 }) // works
emitter.emit('new:user', 1) // compiler error
```

Just like the `emit` method, all other methods enforce types on typed events.

```ts
const emitter = new Emitter<EventsMap>()

emitter.on('new:user', (user) => {
})

emitter.once('new:user', (user) => {
})
```

## Fake emitter
When writing tests, you may want to suppress the events and instead run assertions to ensure that your code is emitting right events with correct data.

You can do this by using the `FakeEmitter` instance during tests.

#### Application code
```ts
import { EmitterContract } from '@poppinss/events'

export default class UserController {
  constructor (protected emitter) {}

  create () {
    const user = makeSomeDbCall()
    this.emitter.emit('new:user', user)
  }
}
```

When writing tests, you can pass the `FakeEmitter`, instead of the real emitter instance.

#### Test

```ts
import { FakeEmitter } from '@poppinss/events'
import UserController from './UserController'

const emitter = new FakeEmitter()
new UserController(emitter).create()

assert.deepEqual(emitter.events, [{
  event: 'new:user',
  data: user,
}])

// Clear stored events inside memory
emitter.clear()
```

## AdonisJs usage
When using with AdonisJs, you can also define listeners as a reference to the IoC container binding. For example:

```ts
// Add event listener
Event.on('new:user', 'User.signup')

// Remove event listener
Event.off('new:user', 'User.signup')
```

AdonisJs will make an instance of `app/Listeners/User.ts` file and will call the signup method on it. This keeps your events file clean, since you can abstract the listeners code to dedicated files.

Also, you can define a custom namespace to lookup listeners from.

```ts
Event.namespace('App/MyListeners')
```

Now AdonisJs will look inside the `MyListeners` directory vs `Listeners`.

## API
Following are the autogenerated files via Typedoc

* [API](docs/README.md)

## Maintainers
[Harminder virk](https://github.com/thetutlage)

[circleci-image]: https://img.shields.io/circleci/project/github/poppinss/events/master.svg?style=for-the-badge&logo=circleci
[circleci-url]: https://circleci.com/gh/poppinss/events "circleci"

[npm-image]: https://img.shields.io/npm/v/@poppinss/events.svg?style=for-the-badge&logo=npm
[npm-url]: https://npmjs.org/package/@poppinss/events "npm"
[typescript-image]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript

[license-url]: LICENSE.md
[license-image]: https://img.shields.io/aur/license/pac.svg?style=for-the-badge