@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
• Acknowledgements
• 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 {
  EventDispatcherPrototype,
  EventListener,
} from '@amandaghassaei/event-dispatcher';

// Define events and class event types.
const THING_A_CHANGE_EVENT = 'THING_A_CHANGE_EVENT';
const THING_A_FINISHED_EVENT = 'THING_A_FINISHED_EVENT';
const THING_A_REMOVED_EVENT = 'THING_A_REMOVED_EVENT';
type ThingAEventType =
  typeof THING_A_CHANGE_EVENT |
  typeof THING_A_FINISHED_EVENT |
  typeof THING_A_REMOVED_EVENT;
const THING_B_CHANGE_EVENT = 'THING_B_CHANGE_EVENT';
const THING_B_FINISHED_EVENT = 'THING_B_FINISHED_EVENT';
const THING_B_REMOVED_EVENT = 'THING_B_REMOVED_EVENT';
type ThingBEventType =
  typeof THING_B_CHANGE_EVENT |
  typeof THING_B_FINISHED_EVENT |
  typeof THING_B_REMOVED_EVENT;

// Create a custom EventDispatcher subclass.
// Use function overloads to define correct typing of subclass event/listener pairs.
// Event listeners may accept an optional parameter.
class EventDispatcher<T> extends EventDispatcherPrototype<T> {
  addOneTimeEventListener(type: typeof THING_A_REMOVED_EVENT, listener: () => void): void;
  addOneTimeEventListener(type: typeof THING_B_REMOVED_EVENT, listener: () => void): void;
  addOneTimeEventListener(type: any, listener: EventListener) {
    this._prototype_addOneTimeEventListener(type, listener);
  }

  addEventListener(type: typeof THING_A_CHANGE_EVENT, listener: (object: ThingA) => void): void;
  addEventListener(type: typeof THING_A_FINISHED_EVENT, listener: (object: ThingA) => void): void;
  addEventListener(type: typeof THING_B_CHANGE_EVENT, listener: (object: ThingB) => void): void;
  addEventListener(type: typeof THING_B_FINISHED_EVENT, listener: (object: ThingB) => void): void;
  addEventListener(type: any, listener: EventListener) {
    this._prototype_addEventListener(type, listener);
  }

  removeEventListener(type: typeof THING_A_CHANGE_EVENT, listener: (object: ThingA) => void): void;
  removeEventListener(type: typeof THING_A_FINISHED_EVENT, listener: (object: ThingA) => void): void;
  removeEventListener(type: typeof THING_B_CHANGE_EVENT, listener: (object: ThingB) => void): void;
  removeEventListener(type: typeof THING_B_FINISHED_EVENT, listener: (object: ThingB) => void): void;
  removeEventListener(type: any, listener: EventListener) {
    this._prototype_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 THING_A_CHANGE_EVENT, object: ThingA): void;
  protected dispatchEvent(type: typeof THING_A_FINISHED_EVENT, object: ThingA): void;
  protected dispatchEvent(type: typeof THING_B_CHANGE_EVENT, object: ThingB): void;
  protected dispatchEvent(type: typeof THING_B_FINISHED_EVENT, object: ThingB): void;
  protected dispatchEvent(type: typeof THING_A_REMOVED_EVENT): void;
  protected dispatchEvent(type: typeof THING_B_REMOVED_EVENT): void;
  protected dispatchEvent(type: any, object?: any) {
    this._prototype_dispatchEvent(type, object);
  }
}

// Define your EventListener subclasses.
class ThingA extends EventDispatcher<ThingAEventType>{
  ...
}
class ThingB extends EventDispatcher<ThingBEventType>{
  ...
}

License

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

Acknowledgements

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