Typevents NPM | npm.io

📖 About

Many projects today have an event-oriented architecture, in which certain types of objects, called emitters, emit named events that cause functions, the listeners, to be called.

We offer the same logic as many other event modules, but with improvements and new ideas, such as the strong typing of events, code written in typescript and open for contributions.

This package does not rely at dependency to work. Compatible to NodeJS and Browser code. The code is analyzed by ESLint and tested with Jest.

⬇️ Downloading

This module has few dependencies, so, this means that we are super light and quick to install, as you can see by downloading it with Npm:

$ npm i --save typevents

Or with Yarn:

$ yarn add typevents

💻 Contributing

This is a small project, and I don't have any specific rules for contributions, you can modify anything and then make a pull-request and i'll analyze. Just be careful not to run away from the main idea of the package.

📚 Examples

Since this module is focused on type checking, using it with a Typescript application is more favorable, but that does not mean that you cannot use its benefits with Javascript.

If you have seen any typos in the documentation, feel free to send a PR about, as I am not fluent in English and did not spend a lot of time writing it.

These examples are sufficient to accompany the package, since it is just a different implementation, but don't worry, the code is compiled with your TSDoc, where most of the documentation is done.

TypeScript Example:

import { EmitterEvents, EventEmitter } from 'typevents';

interface MyEvents extends EmitterEvents<MyEvents> {
  login: { username: string; password: string };
}

const emitter = new EventEmitter<MyEvents>();

emitter.on('login', event => {
  // Typeof event === { username: string; password: string }
  console.log(`A new user has joined! Say hello to '${event.username}'`);
});

// @ts-expect-error
// Throws a type assertion error because we don't know the event `unknown-event`
emitter.on('unknown-event', event => {
  console.log('I do not know that event!');
});

// @ts-expect-error
// Throws a type assertion error because the `login` event exists and this is not its type.
emitter.emit('login', { unknownType: true });

// Prints: "A new user has joined! Say hello to 'typevents'"
emitter.emit('login', { username: 'typevents', password: 'typevents' });

JavaScript Example:

⚠ Enable type checking adding @ts-check at the top of your code!

// @ts-check
import { EventEmitter } from 'typevents';

/**
 * @typedef {{
 *   login: { username: string; password: string };
 * }} Events
 *
 * @typedef {Events & import('typevents').EmitterEvents<Events>} MyEvents
 */

/**
 * @type {EventEmitter<MyEvents>}
 */
const emitter = new EventEmitter();

emitter.on('login', event => {
  // Typeof event === { username: string; password: string }
  console.log(`A new user has joined! Say hello to '${event.username}'`);
});

// @ts-expect-error
// Throws a type assertion error because we don't know the event `unknown-event`.
emitter.on('unknown-type', event => {
  console.log('I do not know that event!');
});

// @ts-expect-error
// Do not throws a type assertion error because the `login` event exists and this is not its type.
emitter.emit('login', { unknownType: true });

// Prints: "A new user has joined! Say hello to 'typevents'"
emitter.emit('login', { username: 'typevents', password: 'typevents' });