eenext
EventEmitter
for next generation, which is well-typed in TypeScript and supportsPromise
andAsyncIterator
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
andAsyncIterator
support- Async
emit
EventEmitter
in TypeScript
The best™ typed You can pass Events
type parameter to EventEmitter
.
; // `Events` type: it is mapper of event name to type. ; // It can be compiled because `'foo'` is known event name in `FooEvents`:ee.on'foo', ; // It can be compiled too:ee.on'bar',; // But it cannot be compiled because `'baz'` is not known:// ee.on('baz', () => {// console.log('baz');// }); ee.emit'foo', 'value';ee.emit'bar'; // You can omit a value when event type is `void`. // Also they cannot be compiled:// ee.emit('foo'); // value is needed.// ee.emit('foo', 42); // value type is not matched.// ee.emit('baz', 'value'); // unknown event type.
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
.
// `FooEvents` is defined in above example. // Pass option to set `'bar'` as end event of stream returned by `on` method.; ; // Emit events.ee.emit'foo', '1st';ee.emit'foo', '2nd';ee.emit'foo', '3rd';ee.emit'bar';
emit
Async emit
method is asynchronous action.
It returns a promise to wait for real emitting.
; ;
API
; ;
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:
opts
: a options.
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:
name
: an event name.
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:
name
: an event name.
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 WaitOptions<Events>
A type of EventEmitter#wait
options.
Type Parameters:
Events
: event names and types.
Definition:
;
type Lisrener<T>
A type of event listener function.
Type Parameters:
T
: an event type.
Definition:
;
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:
T
: a type.
type NonVoidKeys<T>
Like keyof T
but it excludes void
typed keys.
Type Parameters:
T
: a type.
License
MIT License.