@altostra/core
Version:
Core library for shared types and logic
274 lines (273 loc) • 10.2 kB
TypeScript
export interface EventsEmitter<Definition extends EventsDefinition> {
/**
* Adds the `listener` function to the end of the listeners array for the
* event named `eventName`. \
* No checks are made to see if the `listener` has already been added. \
* Multiple calls passing the same combination of `eventName`and `listener` will
* result in the `listener` being added, and called, multiple
* times. \
*
* @example
* ```js
* server.on('connection', (stream) => {
* console.log('someone connected!');
* });
* ```
*
* Returns a reference to the `EventEmitter`, so that calls can be chained.
*
* By default, event listeners are invoked in the order they are added.
*
* @param event The name of the event.
* @param handler The callback function
*/
addListener<T extends EventName<Definition>>(event: T, handler: EventHandler<Definition, T>): this;
/**
* Adds the `listener` function to the end of the listeners array for the
* event named `eventName`. \
* No checks are made to see if the `listener` has already been added. \
* Multiple calls passing the same combination of `eventName`and `listener` will
* result in the `listener` being added, and called, multiple
* times. \
*
* @example
* ```js
* server.on('connection', (stream) => {
* console.log('someone connected!');
* });
* ```
*
* Returns a reference to the `EventEmitter`, so that calls can be chained.
*
* By default, event listeners are invoked in the order they are added.
*
* @param event The name of the event.
* @param handler The callback function
*/
on<T extends EventName<Definition>>(event: T, handler: EventHandler<Definition, T>): this;
/**
* Adds a **one-time**`listener` function for the event named `eventName`. \
* The next time `eventName` is triggered, this listener is removed and then invoked. \
*
* @example
* ```js
* server.once('connection', (stream) => {
* console.log('Ah, we have our first user!');
* });
* ```
*
* Returns a reference to the `EventEmitter`, so that calls can be chained.
*
* By default, event listeners are invoked in the order they are added.
* @param event The name of the event.
* @param handler The callback function
*/
once<T extends EventName<Definition>>(event: T, handler: EventHandler<Definition, T>): this;
/**
* Removes the specified `listener` from the listener array for the event named`eventName`.
*
* @example
* ```js
* const callback = (stream) => {
* console.log('someone connected!');
* };
* server.on('connection', callback);
* // ...
* server.removeListener('connection', callback);
* ```
*
* `removeListener()` will remove, at most, one instance of a listener from the
* listener array. \
* If any single listener has been added multiple times to the listener array for \
* the specified `eventName`, then `removeListener()` must be called multiple \
* times to remove each instance.
*
* Once an event is emitted, all listeners attached to it at the time of emitting
* are called in order. \
* This implies that any`removeListener()` or `removeAllListeners()` calls _after_
* emitting and_before_ the last listener finishes execution will not remove them
* from`emit()` in progress. Subsequent events behave as expected.
*
* @example
* ```js
* const myEmitter = new MyEmitter();
*
* const callbackA = () => {
* console.log('A');
* myEmitter.removeListener('event', callbackB);
* };
*
* const callbackB = () => {
* console.log('B');
* };
*
* myEmitter.on('event', callbackA);
*
* myEmitter.on('event', callbackB);
*
* // callbackA removes listener callbackB but it will still be called.
* // Internal listener array at time of emit [callbackA, callbackB]
* myEmitter.emit('event');
* // Prints:
* // A
* // B
*
* // callbackB is now removed.
* // Internal listener array [callbackA]
* myEmitter.emit('event');
* // Prints:
* // A
* ```
*
* Because listeners are managed using an internal array, calling this will change
* the position indices of any listener registered _after_ the listener * being
* removed. \
* This will not impact the order in which listeners are called, but it means
* that any copies of the listener array as returned by the `emitter.listeners()`
* method will need to be recreated.
*
* When a single function has been added as a handler multiple times for a single
* event (as in the example below), `removeListener()` will remove the most recently
* added instance. \
* In the example the `once('ping')`listener is removed:
*
* @example
* ```js
* const ee = new EventEmitter();
*
* function pong() {
* console.log('pong');
* }
*
* ee.on('ping', pong);
* ee.once('ping', pong);
* ee.removeListener('ping', pong);
*
* ee.emit('ping');
* ee.emit('ping');
* ```
*
* Returns a reference to the `EventEmitter`, so that calls can be chained.
* @param event The name of the event.
* @param handler The callback function to remove from the listeners list.
*/
removeListener<T extends EventName<Definition>>(event: T, handler: EventHandler<Definition, T>): this;
/**
* Removes the specified `listener` from the listener array for the event named`eventName`.
*
* @example
* ```js
* const callback = (stream) => {
* console.log('someone connected!');
* };
* server.on('connection', callback);
* // ...
* server.removeListener('connection', callback);
* ```
*
* `removeListener()` will remove, at most, one instance of a listener from the
* listener array. \
* If any single listener has been added multiple times to the listener array for \
* the specified `eventName`, then `removeListener()` must be called multiple \
* times to remove each instance.
*
* Once an event is emitted, all listeners attached to it at the time of emitting
* are called in order. \
* This implies that any`removeListener()` or `removeAllListeners()` calls _after_
* emitting and_before_ the last listener finishes execution will not remove them
* from`emit()` in progress. Subsequent events behave as expected.
*
* @example
* ```js
* const myEmitter = new MyEmitter();
*
* const callbackA = () => {
* console.log('A');
* myEmitter.removeListener('event', callbackB);
* };
*
* const callbackB = () => {
* console.log('B');
* };
*
* myEmitter.on('event', callbackA);
*
* myEmitter.on('event', callbackB);
*
* // callbackA removes listener callbackB but it will still be called.
* // Internal listener array at time of emit [callbackA, callbackB]
* myEmitter.emit('event');
* // Prints:
* // A
* // B
*
* // callbackB is now removed.
* // Internal listener array [callbackA]
* myEmitter.emit('event');
* // Prints:
* // A
* ```
*
* Because listeners are managed using an internal array, calling this will change
* the position indices of any listener registered _after_ the listener * being
* removed. \
* This will not impact the order in which listeners are called, but it means
* that any copies of the listener array as returned by the `emitter.listeners()`
* method will need to be recreated.
*
* When a single function has been added as a handler multiple times for a single
* event (as in the example below), `removeListener()` will remove the most recently
* added instance. \
* In the example the `once('ping')`listener is removed:
*
* @example
* ```js
* const ee = new EventEmitter();
*
* function pong() {
* console.log('pong');
* }
*
* ee.on('ping', pong);
* ee.once('ping', pong);
* ee.removeListener('ping', pong);
*
* ee.emit('ping');
* ee.emit('ping');
* ```
*
* Returns a reference to the `EventEmitter`, so that calls can be chained.
* @param event The name of the event.
* @param handler The callback function to remove from the listeners list.
*/
off<T extends EventName<Definition>>(event: T, handler: EventHandler<Definition, T>): this;
/**
* Removes all listeners, or those of the specified `event`.
*
* It is bad practice to remove listeners added elsewhere in the code, particularly
* when the `EventEmitter` instance was created by some other component or module
* (e.g. sockets or file streams).
*
* Returns a reference to the `EventEmitter`, so that calls can be chained.
* @param event When specified, removes all the listener of the specified `event`. \
* Otherwise, removes all event listeners
*/
removeAllListeners(event?: EventName<Definition>): this;
}
/**
* An object-type where the keys are event-names and the values are the corresponding
* payload of the event
*/
export declare type EventsDefinition = object;
/**
* Event names from an event-definition
*/
export declare type EventName<T extends EventsDefinition> = keyof T;
/**
* Event names from an event-definition and event-name
*/
export declare type EventPayload<Definition extends EventsDefinition, Event extends EventName<Definition>> = Definition[Event];
/**
* Event-handler for the specified event
*/
export declare type EventHandler<Definition extends EventsDefinition, Event extends EventName<Definition>> = (event: EventPayload<Definition, Event>) => unknown;