npm package: @irrelon/emitter
Description: Simple JavaScript event emitter with some powerful features.
Author: Rob Evans - Irrelon Software Limited
Latest version: 6.2.0

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

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

```js
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:

```bash
npm i @irrelon/emitter
```

```bash
yarn add @irrelon/emitter
```

### Include in Your Application

```js
import {Emitter} from "@irrelon/emitter";
```
or
```js
var Emitter = require("@irrelon/emitter");
```

### Browser

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

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