Irrelon Emitter

What Is It?

It's an event emitter that supports some very powerful and useful features.

Why Not Just Use window.dispatchEvent()?

This library is more flexible and operates in both Node.js and the browser with the same interface. This is useful because it allows you to maintain the same code patterns on both the backend and frontend of your application.

This event emitter also supports many more features than the basic event system built into browsers.

Usage

JavaScript

import { Emitter } from "@irrelon/emitter";
const emitter = new Emitter();

// When the emit() call is made at the end of this
// example this listener will be called with
// `isEnabled = true` and `id = "1234"`. You can pass
// any number of arguments when calling emit() and
// they will be recieved in the same order by your
// event listeners
emitter.on("someEvent", (isEnabled, id) => {
    return "someReturnValue1";
});

// Lets register another listener on the same event
// that returns a slightly different value
emitter.on("someEvent", (isEnabled, id) => {
	return "someReturnValue2";
});

// The `results` will contain the return values from
// all the event listeners registered for the event
// so in this case ["someReturnValue1", "someReturnValue2"]
const results = emitter.emit("someEvent", true, "1234");

TypeScript Compatibility

TypeScript based projects can benefit from type safety if you declare the event listener function signatures via an interface as shown below

import { Emitter } from "@irrelon/emitter";

interface MyEvents {
    event1: (name: string) => number;
}

// Pass your interface to the Emitter instantiation
const emitter = new Emitter<MyEvents>();

// This will show a typescript error because the
// first argument of the event1 listener should be
// a string, and the listener should return a number
// instead of void.
emitter.on("event1", (isEnabled: boolean) => {
    return;
});

// This will not error as it satisfies the
// MyEvents.event1 event listener signature
emitter.on("event1", (name: string) => {
    return 18;
});

// This will error because a string argument is
// expected and none is provided to the call
emitter.emit("event1");

// This will not error as you are passing the
// expected string argument
emitter.emit("event1", "John Smith");

// This will correctly infer the type of `result`
// as a number since the return type was defined
// in the MyEvents.event1 interface
const result = emitter.emit("event1", "John Smith");

Extending The Emitter Class

import { Emitter } from "@irrelon/emitter";

class MyClass extends Emitter {
    async someAsyncFunc () {
        await this.emit('myEvent', myData, myOtherData);
    }

    someFunc () {
        this.emit('myEvent', myData, myOtherData);
    }
};

Your class now inherits the emitter methods:

• on
• off
• once
• emit
• emitId
• emitStatic
• emitStaticId
• cancelStatic
• deferEmit
• willEmit
• rpc
• rpcId

EcmaScript Modules and CommonJS Modules

The package includes both ESM and CJS modules for ease of use. Use import to get the ESM version, and require() to get the CJS version.

Install via NPM / Yarn:

npm i @irrelon/emitter

yarn add @irrelon/emitter

Include in Your Application

import {Emitter} from "@irrelon/emitter";

or

var Emitter = require("@irrelon/emitter");

Browser

Include the Emitter.js file in your HTML (the path depends on where you've put the file)

<script src="./dist/esm/src/Emitter.js" type="module"></script>