Nano Events

Simple and tiny (144 bytes) event emitter library for JavaScript

PubSub
ai/nanoeventsnanoevents

README

Nano Events


Simple and tiny event emitter library for JavaScript.

Only 152 bytes (minified and gzipped).
  It uses [Size Limit] to control size.
on method returns unbind function. You don’t need to save
  callback to variable for removeListener.
TypeScript and ES modules support.
No aliases, just emit and on methods.
  No Node.js [EventEmitter] compatibility.

  1. ``` js
  2. import { createNanoEvents } from 'nanoevents'

  4. const emitter = createNanoEvents()

  6. const unbind = emitter.on('tick', volume => {
  7.   summary += volume
  8. })

  10. emitter.emit('tick', 2)
  11. summary //=> 2

  13. unbind()
  14. emitter.emit('tick', 2)
  15. summary //=> 2
  16. ```

[EventEmitter]: https://nodejs.org/api/events.html
[Size Limit]:   https://github.com/ai/size-limit

  <img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg"
       alt="Sponsored by Evil Martians" width="236" height="54">


Table of Contents


Install
TypeScript
Mixing to Object
Add Listener
Remove Listener
Execute Listeners
Events List
Once
Remove All Listeners


Install


  1. ```sh
  2. npm install nanoevents
  3. ```


TypeScript


Nano Events accepts interface with event name
to listener argument types mapping.

  1. ```ts
  2. interface Events {
  3.   set: (name: string, count: number) => void,
  4.   tick: () => void
  5. }

  7. const emitter = createNanoEvents<Events>()

  9. // Correct calls:
  10. emitter.emit('set', 'prop', 1)
  11. emitter.emit('tick')

  13. // Compilation errors:
  14. emitter.emit('set', 'prop', '1')
  15. emitter.emit('tick', 2)
  16. ```


Mixing to Object


Because Nano Events API has only just 2 methods,
you could just create proxy methods in your class
or encapsulate them entirely.

  1. ``` js
  2. class Ticker {
  3.   constructor () {
  4.     this.emitter = createNanoEvents()
  5.     this.internal = setInterval(() => {
  6.       this.emitter.emit('tick')
  7.     }, 100)
  8.   }

  10.   stop () {
  11.     clearInterval(this.internal)
  12.     this.emitter.emit('stop')
  13.   }

  15.   on (event, callback) {
  16.     return this.emitter.on(event, callback)
  17.   }
  18. }
  19. ```

With Typescript:

  1. ```ts
  2. import { createNanoEvents, Emitter } from "nanoevents"

  4. interface Events {
  5.   start: (startedAt: number) => void
  6. }

  8. class Ticker {
  9.   emitter: Emitter

  11.   constructor () {
  12.     this.emitter = createNanoEvents<Events>()
  13.   }

  15.   on<E extends keyof Events>(event: E, callback: Events[E]) {
  16.     return this.emitter.on(event, callback)
  17.   }
  18. }
  19. ```


Add Listener


Use on method to add listener for specific event:

  1. ``` js
  2. emitter.on('tick', number => {
  3.   console.log(number)
  4. })

  6. emitter.emit('tick', 1)
  7. // Prints 1
  8. emitter.emit('tick', 5)
  9. // Prints 5
  10. ```

In case of your listener relies on some particular context
(if it uses this within itself) you have to bind required
context explicitly before passing function in as a callback.

  1. ``` js
  2. var app = {
  3.   userId: 1,
  4.   getListener () {
  5.     return () => {
  6.       console.log(this.userId)
  7.     }
  8.   }
  9. }
  10. emitter.on('print', app.getListener())
  11. ```

Note: binding with use of the .bind() method won’t work as you might expect
and therefore is not recommended.


Remove Listener


Methods on returns unbind function. Call it and this listener
will be removed from event.

  1. ``` js
  2. const unbind = emitter.on('tick', number => {
  3.   console.log('on ' + number)
  4. })

  6. emitter.emit('tick', 1)
  7. // Prints "on 1"

  9. unbind()
  10. emitter.emit('tick', 2)
  11. // Prints nothing
  12. ```


Execute Listeners


Method emit will execute all listeners. First argument is event name, others
will be passed to listeners.

  1. ``` js
  2. emitter.on('tick', (a, b) => {
  3.   console.log(a, b)
  4. })
  5. emitter.emit('tick', 1, 'one')
  6. // Prints 1, 'one'
  7. ```


Events List


You can get used events list by events property.

  1. ``` js
  2. const unbind = emitter.on('tick', () => { })
  3. emitter.events //=> { tick: [ [Function] ] }
  4. ```


Once


If you need add event listener only for first event dispatch,
you can use this snippet:

  1. ``` js
  2. class Ticker {
  3.   constructor () {
  4.     this.emitter = createNanoEvents()
  5.   }
  6.   …
  7.   once (event, callback) {
  8.     const unbind = this.emitter.on(event, (...args) => {
  9.       unbind()
  10.       callback(...args)
  11.     })
  12.     return unbind
  13.   }
  14. }
  15. ```


Remove All Listeners


  1. ``` js
  2. emitter.on('event1', () => { })
  3. emitter.on('event2', () => { })

  5. emitter.events = { }
  6. ```