eenext
v1.0.1
Published
EventEmitter for next generation, which is well-typed in TypeScript and supports Promise and AsyncIterator
Downloads
1
Readme
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
The best™ typed EventEmitter
in TypeScript
You can pass Events
type parameter to EventEmitter
.
import EventEmitter from 'eenext';
// `Events` type: it is mapper of event name to type.
interface FooEvents {
foo: string;
bar: void;
}
const ee = new EventEmitter<FooEvents>();
// It can be compiled because `'foo'` is known event name in `FooEvents`:
ee.on('foo', value => {
console.log(`foo: ${value}`);
});
// It can be compiled too:
ee.on('bar', () => {
console.log('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.
const ee = new EventEmitter<FooEvents>({end: 'bar'});
(async () => {
// Wait `'foo'` event.
const foo1st = await ee.once('foo');
console.log(`foo 1st: ${foo1st}`);
// Show `'foo'` event value until `'bar'` event emitted.
for await (const foo of ee.on('foo')) {
console.log(`foo: ${foo}`);
}
})();
// Emit events.
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 () => {
// Pass async function as event listener:
ee.once('bar', async () => {
console.log('before bar');
await new Promise(resolve => setTimeout(resolve, 1000));
console.log('after bar');
});
// Wait 1sec to go.
console.log('before await');
await ee.emit('bar');
console.log('after await');
// Handle error in event listener.
ee.once('bar', async () => {
throw new Error('error');
});
try {
await ee.emit('bar');
} catch (err) {
console.error(err); // => Error: error
}
})();
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:
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 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:
T
: an event type.
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:
T
: a type.
type NonVoidKeys<T>
Like keyof T
but it excludes void
typed keys.
Type Parameters:
T
: a type.
License
MIT License.