eenext
EventEmitter
for next generation,
which is well-typed in TypeScript and supports Promise
and AsyncIterator
Install
NPM:
$ npm install eenext
Yarn:
$ yarn add eenext
NOTE: this package uses setImmediate
, so you maybe need to use core-js
or
some setImmediate
shim providers to run this on browsers.
Features
- The best™ typed
EventEmitter
in TypeScript Promise
and AsyncIterator
support- Async
emit
The best™ typed EventEmitter
in TypeScript
You can pass Events
type parameter to EventEmitter
.
import EventEmitter from 'eenext';
interface FooEvents {
foo: string;
bar: void;
}
const ee = new EventEmitter<FooEvents>();
ee.on('foo', value => {
console.log(`foo: ${value}`);
});
ee.on('bar', () => {
console.log('bar');
});
ee.emit('foo', 'value');
ee.emit('bar');
NOTE: Currently eenext
does not support two or more arguments event due to TypeScript limitation.
Promise
and AsyncIterator
support
on
method without event listener returns AsyncIterator
, and once
returns Promise
.
const ee = new EventEmitter<FooEvents>({end: 'bar'});
(async () => {
const foo1st = await ee.once('foo');
console.log(`foo 1st: ${foo1st}`);
for await (const foo of ee.on('foo')) {
console.log(`foo: ${foo}`);
}
})();
ee.emit('foo', '1st');
ee.emit('foo', '2nd');
ee.emit('foo', '3rd');
ee.emit('bar');
Async emit
emit
method is asynchronous action.
It returns a promise to wait for real emitting.
const ee = new EventEmitter<FooEvents>();
(async () => {
ee.once('bar', async () => {
console.log('before bar');
await new Promise(resolve => setTimeout(resolve, 1000));
console.log('after bar');
});
console.log('before await');
await ee.emit('bar');
console.log('after await');
ee.once('bar', async () => {
throw new Error('error');
});
try {
await ee.emit('bar');
} catch (err) {
console.error(err);
}
})();
API
import EventEmitter from 'eenext';
import {
Options,
StreamOptions,
WaitOptions,
Listener,
EventStream,
VoidKeys,
NonVoidKeys,
} from 'eenext';
class EventEmitter<Events = any>
An event emitter class.
Type Parameters:
Events
: event names and types.
constructor(opts: Options<Events>)
Create a new EventEmitter
instance with given options.
Arguments:
on<K extends keyof Events>(name: K, listener: Listener<Events[K]>): void
Add event listener.
Arguments:
name
: an event name.listener
: an event listener.
on<K extends keyof Events>(name: K): EventStream<Events[K]>
Return an event stream.
Is is same as this.stream(name)
.
Arguments:
once<K extends keyof Events>(name: K, listener: Listener<Events[K]>): void
Add event listener invoked only once,
Arguments:
name
: an event name.listener
: an event listener.
once<K extends keyof Events>(name: K): Promise<Events[K]>
Return an event promise.
It is same as this.wait(name)
.
Arguments:
off<K extends keyof Events>(name: K, listener: Listener<Events[K]>): void
Remove event listener.
Arguments:
name
: an event name.listener
: an event listener.
stream<K extends Events>(name: K, opts: StreamOptions<Events>): EventStream<Events[K]>
Create an event stream.
Arguments:
next
: an event name.opts
: options.
wait<K extends Events>(name: K, opts: WaitOptions<Events>): EventStream<Events[K]>
Create an event promise.
Arguments:
name
: an event name.opts
: options.
emit<K extends VoidKeys<Events>>(name: K, value?: Events[K]): Promise<void>
Emit an event with or without the given value.
Arguments:
name
: an event name.value
: a value to emit.
emit<K extends NonVoidKeys<Events>>(name: K, value: Events[K]): Promise<void>
Emit an event with the given value.
Arguments:
name
: an event name.value
: a value to emit.
interface Options<Events>
A type of EventEmitter
options.
Type Parameters:
Events
: event names and types.
Properties:
end
: an event name to detect ending (optional).error
: an event name to detect an error (optional).maxBufferSize
: maximum buffer size of stream (optional).
type StreamOptions<Events>
A type of EventEmitter#stream
options.
Type Parameters:
Events
: event names and types.
type StreamOptions<Events> = Partial<Pick<Options<Events>, 'end' | 'error' | 'maxBufferSize'>>;
type WaitOptions<Events>
A type of EventEmitter#wait
options.
Type Parameters:
Events
: event names and types.
Definition:
type WaitOptions<Events> = Partial<Pick<Options<Events>, 'error'>>;
type Lisrener<T>
A type of event listener function.
Type Parameters:
Definition:
type Listener<T> = (value: T) => void | Promise<void>;
interface EventStream<T>
A type of event stream.
It implements AsyncIterator<T>
and AsyncIterable<T>
.
Type Parameters:
T
: a value type of this stream.
Methods:
next(): Promise<IteratorResult<T>>
return(value?: any): Promise<IteratorResult<T>>
throw(reason?: any): Promise<IteratorResult<T>>
[Symbol.asyncIterator](): AsyncIterator<T>
type VoidKeys<T>
Like keyof T
but it only includes void
typed keys.
Type Parameters:
type NonVoidKeys<T>
Like keyof T
but it excludes void
typed keys.
Type Parameters:
License
MIT License.