@amandaghassaei/event-dispatcher

@amandaghassaei/event-dispatcher

Parent class to support custom event listeners.

• Written in TypeScript with exported type declarations.
• Includes unit tests with 100% coverage.

Table of Contents:

• Installation
• Use
• License
• Acknowledgments
• Development

Installation

Install via NPM

npm install @amandaghassaei/event-dispatcher

Then import via:

import { EventDispatcherPrototype } from '@amandaghassaei/event-dispatcher';

Use

See full API documentation in docs/.

import { EventDispatcher, Listener } from '../src/index';

// Define events and class event types.
const ADDED_EVENT = 'ADDED_EVENT';
const CHANGE_EVENT = 'CHANGE_EVENT';
const FINISHED_EVENT = 'FINISHED_EVENT';
const REMOVED_EVENT = 'REMOVED_EVENT';
type MyClassEventType =
    | typeof ADDED_EVENT
    | typeof CHANGE_EVENT
    | typeof FINISHED_EVENT
    | typeof REMOVED_EVENT;

// Create an EventDispatcher subclass.
// Use function overloads to define correct typing of subclass event/listener pairs.
// Event listeners may accept an optional parameter.
class MyClass extends EventDispatcher<MyClassEventType> {
    addOneTimeEventListener(type: typeof ADDED_EVENT, listener: () => void): () => void;
    addOneTimeEventListener(type: typeof REMOVED_EVENT, listener: () => void): () => void;
    addOneTimeEventListener<S extends MyClassEventType>(type: S, listener: () => void) {
        return super.addOneTimeEventListener(type, listener);
    }

    addEventListener(type: typeof CHANGE_EVENT, listener: (object: MyClass) => void): () => void;
    addEventListener(type: typeof FINISHED_EVENT, listener: (object: MyClass) => void): () => void;
    addEventListener<S extends MyClassEventType>(type: S, listener: Listener) {
        return super.addEventListener(type, listener);
    }

    removeEventListener(type: typeof CHANGE_EVENT, listener: (object: MyClass) => void): void;
    removeEventListener(type: typeof FINISHED_EVENT, listener: (object: MyClass) => void): void;
    removeEventListener<S extends MyClassEventType>(type: S, listener: Listener) {
        super.removeEventListener(type, listener);
    }

    // You may decide to make dispatchEvent a protected function,
    // which can only be called from within the subclass.
    protected _dispatchEvent(type: typeof CHANGE_EVENT, object: MyClass): void;
    protected _dispatchEvent(type: typeof FINISHED_EVENT, object: MyClass): void;
    protected _dispatchEvent(type: typeof REMOVED_EVENT): void;
    protected _dispatchEvent<S extends MyClassEventType>(type: S, object?: any) {
        super._dispatchEvent(type, object);
    }
}

const instance = new MyClass();
const listener = (object) => {
    console.log('instance changed:', object);
}
const removeListenerFunction = instance.addEventListener(CHANGE_EVENT, listener);

// Remove the event listener by calling the returned function:
removeListenerFunction()
// or by calling removeEventListener directly:
instance.removeEventListener(CHANGE_EVENT, listener);

// The following will throw type errors:

// REMOVED_EVENT is not a valid event type for MyClass.addEventListener().
// instance.addEventListener(REMOVED_EVENT, (object) => {});

// The object parameter must be of type MyClass.
// instance.addEventListener(CHANGE_EVENT, (object: number) => {});

License

This work is distributed under an MIT license. It has no dependencies.

Acknowledgments

Inspired by Three.js's EventDispatcher class.

Development

Install dev-dependencies:

npm install

Build from src to dist and compile docs:

npm run build

Test with code coverage:

npm run test-with-coverage