strict-event-emitter - npm Package Compare versions

Comparing version 0.2.0 to 0.2.1

lib/StrictEventEmitter.d.ts

		/// <reference types="node" />
		import { EventEmitter } from 'events';
		export declare class StrictEventEmitter<EventsMap extends Record<string \| symbol, any>> extends EventEmitter {
		export declare class StrictEventEmitter<EventMap extends Record<string \| symbol, any>> extends EventEmitter {
		constructor();
		on<K extends keyof EventsMap>(event: K, listener: EventsMap[K]): this;
		once<K extends keyof EventsMap>(event: K, listener: EventsMap[K]): this;
		off<K extends keyof EventsMap>(event: K, listener: EventsMap[K]): this;
		emit<K extends keyof EventsMap>(event: K, ...data: Parameters<EventsMap[K]>): boolean;
		addListener<K extends keyof EventsMap>(event: K, listener: EventsMap[K]): this;
		removeListener<K extends keyof EventsMap>(event: K, listener: EventsMap[K]): this;
		on<K extends keyof EventMap>(event: K, listener: EventMap[K]): this;
		once<K extends keyof EventMap>(event: K, listener: EventMap[K]): this;
		off<K extends keyof EventMap>(event: K, listener: EventMap[K]): this;
		emit<K extends keyof EventMap>(event: K, ...data: Parameters<EventMap[K]>): boolean;
		addListener<K extends keyof EventMap>(event: K, listener: EventMap[K]): this;
		removeListener<K extends keyof EventMap>(event: K, listener: EventMap[K]): this;
		eventNames(): Array<keyof EventMap>;
		listeners<K extends keyof EventMap>(event: K): Function[];
		rawListeners<K extends keyof EventMap>(event: K): Function[];
		listenerCount<K extends keyof EventMap>(event: K): number;
		}

lib/StrictEventEmitter.js

		@@ -52,4 +52,17 @@ "use strict";
		};
		// @ts-ignore Cannot cast a narrower return type.
		StrictEventEmitter.prototype.eventNames = function () {
		return _super.prototype.eventNames.call(this);
		};
		StrictEventEmitter.prototype.listeners = function (event) {
		return _super.prototype.listeners.call(this, event.toString());
		};
		StrictEventEmitter.prototype.rawListeners = function (event) {
		return _super.prototype.rawListeners.call(this, event.toString());
		};
		StrictEventEmitter.prototype.listenerCount = function (event) {
		return _super.prototype.listenerCount.call(this, event.toString());
		};
		return StrictEventEmitter;
		}(events_1.EventEmitter));
		exports.StrictEventEmitter = StrictEventEmitter;

package.json

		{
		"name": "strict-event-emitter",
		"version": "0.2.0",
		"version": "0.2.1",
		"description": "Type-safe \"EventEmitter\" for everyday use",
		@@ -5,0 +5,0 @@ "main": "lib/index.js",

README.md

		@@ -5,8 +5,21 @@ # Strict Event Emitter

		## Features

		- Restricts emitting of the unknown event types.
		- Infers emitted data types from the listener's call signature.

		## Motivation

		The type definitions for the native `EventEmitter` class of `events` accepts a general string as the event type, making it hard to ensure an unknown event hasn't been dispatched or subscribed to.
		The native `EventEmitter` class uses a generic `string` to describe what type of events can be emitted. In most cases you design a strict set of events that you expect your emitter to emit/listen to. This package helps you to type-annotate an emitter instance to produce type violations if an unknown event is emitted/listened to.

		Strict Event Emitter is a 100% compatible extension of the native `EventEmitter` that comes with an enhanced type definitions to support restricting of event types an emitter can emit and create listeners.
		```js
		const emitter = new EventEmitter()

		emitter.addListener('ping', (n: number) => {})

		// The "pong" event is not expected, but will be emitted anyway.
		// The data passed to the event is incompatible with the expected type.
		emitter.emit('pong', 'not a number')
		```

		```ts
		@@ -16,26 +29,48 @@ import { StrictEventEmitter } from 'strict-event-emitter'
		interface EventsMap {
		'request': (req: Request) => void
		'response': (res: Response) => void
		ping: (n: number) => void
		}

		const emitter = new StrictEventEmitter<EventsMap>()
		emitter.addListener('ping', (n) => {
		// "n" argument type is inferred as "number'.
		})

		emitter.emit('request', new Request()) // OK
		emitter.emit('request', 2) // ERROR!
		emitter.emit('unknown-event') // ERROR!

		emitter.addListener('response', (res) => { ... }) // OK
		emitter.addListener('unknown-event') // ERROR!
		emitter.emit('ping', 10) // OK
		emitter.emit('ping', 'wait, not a number') // TypeError
		emitter.emit('unknown', 10) // TypeError
		```

		> Note that `strict-event-emitter` is a type extension and does not provide any value validation on runtime.
		This library is a superset class of the native `EventEmitter` with only the type definition logic attached. There's no additional functionality present.

		## Getting started

		### Install

		```bash
		$ npm install strict-event-emitter
		npm install strict-event-emitter
		```

		### Use

		```ts
		import { StrictEventEmitter } from 'strict-event-emitter'

		// 1. Define an interface that describes your events.
		// Set event names as the keys, and their listner functions as the values.
		interface EventsMap {
		connect: (id: string) => void
		disconnect: (id: string) => void
		}

		// 2. Create a strict emitter and pass the previously defined "EventsMap"
		// as its first generic argument.
		const emitter = new StrictEventEmitter<EventsMap>()

		// 3. Use the "emitter" the same way you'd use the regular "EventEmitter" instance.
		emitter.addListner('connect', (id) => {})
		emitter.emit('connect', 'abc-123')
		```

		## License

		MIT

strict-event-emitter - npm Package Compare versions

New alerts

Fixed alerts

Improved metrics