Wondering what’s next for npm?Check out our public roadmap! »

    lua-eventemitter

    1.0.3 • Public • Published

    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 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

    ********************************************
    ## License MIT

    Install

    npm i lua-eventemitter

    DownloadsWeekly Downloads

    5

    Version

    1.0.3

    License

    MIT

    Last publish

    Collaborators

    • avatar