lua-events

Current version: v1.0.0 (stable)
Compatible Lua version: 5.1.x

Table of Contents

1. Overiew
2. Installation
3. APIs

1. Overview

lua-events is an EventEmitter class that provides you with APIs in node.js style.

I am using this module with my own nodemcu project on ESP8266 WiFi Soc. It helps me write my code in event-driven style. I often grab a emitter from this module and use the emitter as an event hub in my application to control my program flow. Try it on nodemcu, it won't let you down.

If you like to code something in an asynchronous manner on nodemcu, might I sugguest nodemcu-timer? They are working well with each other to help arrange your asynchronous flow, e.g. your function can defer its callback and return right away.

2. Installation

Clone from github

$ git clone https://github.com/simenkid/lua-events.git

or use npm install

$ npm install lua-eventemitter

Just include the file events.lua or use the minified one events_min.lua in your project.
If you are with the nodemcu on ESP8266, it would be good for you to compile *.lua text file into *.lc bytecode to further reduce memory usage.

• FS/Memory footprint

  • events.lua: ~5.1 KB(file size) / ~17 KB (heap available after loaded)
  • events_min.lua: ~2.9 KB(size) / ~17 KB (heap)
  • events.lc: ~4.0 KB(size) / ~24 KB (heap)
  • timer.lc + events.lc: ~17.7 KB (heap)

3. APIs

• EventEmitter:new()
• emitter:emit()
• emitter:on()
• emitter:once()
• emitter:addListener()
• emitter:removeListener()
• emitter:removeAllListeners()
• emitter:getMaxListeners()
• emitter:listenerCount()
• emitter:listeners()
• emitter:setMaxListeners()

EventEmitter Class

Exposed by require 'events'

local EventEmitter = require 'events'  -- or 'events_min'

EventEmitter:new([table])

Create an instance of event emitter. If a table (or an object) is given, the table will inherit EventEmitter class and itself will be an event emiiter.

Arguments:

1. table (table): If given, the table (or an object) itself will be returned as an event emitter. If not given, a new emitter will be returned.

Returns:

• (object) emitter

Examples:

local EventEmitter = require 'events'

-- Inheritance
local myObject = {
    name = 'foo',
    greet = function ()
        print('Hello!')
    end
}

myObject = EventEmitter:new(myObject)

myObject:on('knock', function ()
    print('knock, knock!')
end)

myObject:emit('knock')

-- A simple emitter
local hub = EventEmitter:new()

hub:on('sing', function (who)
    print(who .. ' is singing.')
end)

hub:emit('sing', 'John')

emitter:emit(event[, ...])

Calls each of the listeners in order with the given arguments.

Arguments:

1. event (string): Event name.
2. ... (variadic arguments): The parameters pass along with the event.

Returns:

• (boolean) Returns true if listeners exist, false otherwise.

Examples:

local greet = 'hello'
local name = 'John Doe'
emitter:emit('knock', greet, name)

emitter:emit('tick')

emitter:on(event, listener)

Adds a listener to the listeners table of the specified event.

Arguments:

1. event (string): Event name.
2. listener (listener): Event handler.

Returns:

• (object) emitter

Examples:

emitter:on('knock', function () {
    print('Someone knocks.')
});

emitter:once(event, listener)

Attaches a one time listener to the specified event. This listener will be removed after invoked.

Arguments:

1. event (string): Event name.
2. listener (listener): Event handler.

Returns:

• (object) emitter

Examples:

emitter:once('knock', function () {
    print('First visitor comes.')
});

emitter:addListener(event, listener)

This is an alias of emitter.on(event, listener).

emitter:removeListener(event, listener)

Removes a listener from the listener table of the specified event.

Arguments:

1. event (string): Event name.
2. listener (function): Event handler

Returns:

• (object) emitter

Examples:

local callback = function (something)
    print('Someone says ' .. greet)
end

emitter:on('greeting', callback)
-- ...
emitter:removeListener('greeting', callback)

emitter:removeAllListeners([event])

Removes all listeners, or those of the specified event.

Arguments:

1. event (string): This is optional. If given, all listeners attached to the specified event will be removed. If not given, all listeners of the emiiter will be removed.

Returns:

• (object) emitter

Examples:

emitter:removeAllListeners('foo_event')

emitter:getMaxListeners()

Returns the current max listener value of the emitter.

Arguments:

1. none

Returns:

• (number) Number of current max listeners.

emitter:listenerCount(event)

Returns the number of listeners listening to the specified event.

Arguments:

1. event (string): Event name.

Returns:

• (number) Total number of the listeners.

Examples:

local numOfListeners = emitter:listenerCount('knock')

emitter:listeners(event)

Returns a shallow copy of listener table for the specified event.

Arguments:

1. event (string): Event name.

Returns:

• (table) table of listeners

Examples:

local knockHandlers = emitter:listeners('knock')

emitter:setMaxListeners(n)

The emitter will print a warning if more than 10 listeners are added to a event. This method let you increase the maximum number of listeners attached to a event.

Arguments:

1. n (number): Maximum number of listeners attached to a event.

Returns:

• (object) emitter