Class OEvent<T>

Event handling class.

This class manages event listeners and their invocation. Listeners are registered with the listen method - or better by using the () operator of this class - and can be invoked with one of the emit* methods:

  • emit(args): Use when the emitter doesn't care about the result of the execution of the listeners.
  • emitAll(args): Use when the emitter is interested in the results of the listeners execution or if the emitter wants to wait until all listeners have completed their execution.
  • emitRace(args): Use when the emitter is interested only in the first settled promise from the listeners.

Executing handlers sequentially vs parallel:

emit & emitAll offer the possibility to execute the listeners handlers in parallel or sequentially.This is configurable through the 'executeSequentially' optional parameter in the constructor. 'executeSequentially' defaults to true.

  • executeSequentially === true: If an event handler is disconnected from another event handler then the other handler will not be called if it didn't run, yet. If a new one is connected it will be executed as last event handler.
  • executeSequentially === false: If an event handler is disconnected from another event handler then the other handler will still be called (it already started because of being executed in parallel) - If one is connected in another event handler it will not be called.

Usage:

 class CoffeeMachine {

     // Event that signals when the coffee machine is powered on / off.
     // state: true when powered on, false when powered off.
     public onPowerChange = new OEvent<(state: boolean) => void>();

     // Turns the coffee machine on
     public turnOn() {
         //..
         this.onPowerChange.emit(true);
     }

     // Turns the coffee machine off
     public turnOff() {
         //..
         this.onPowerChange.emit(false);
     }
 }

 const coffeeMachine = new CoffeeMachine();

 // Register onListenListener
 const disconnectOnListen = coffeeMachine.onPowerChange.onListen( () => {
     console.log('Somebody started listening for the powerChange events.')
 })

 // Register onStopListenListener
 const disconnectOnStopListen = coffeeMachine.onPowerChange.onStopListen( () => {
     console.log('Somebody stopped listening for the powerChange events.')
 })

 // Use the events provided by the class:
 const disconnect = coffeeMachine.onPowerChange(state => {
     if (state) {
         console.log('Coffee machine was turned on')
     } else {
         console.log('Coffee machine was turned off')
     }
 }); // This will print 'Somebody started listening for the powerChange events.'

 coffeeMachine.turnOn(); // This will print 'Coffee machine was turned on'
 coffeeMachine.turnOff(); // This will print 'Coffee machine was turned off'
 disconnect(); // This will disconnect the connection and will print 'Somebody stopped
 listening for the powerChange events.'
 coffeeMachine.turnOn(); // This will print nothing
 coffeeMachine.turnOff(); // This will print nothing

OEvent is chosen as class name over Event, because the second option is reserved.

Type Parameters

  • T extends ((...arg: any) => any)

    The expected type (function signature) of the event listeners.

Hierarchy (view full)

  • Functor<((listener: ((...args: Parameters<T>) => Promise<ReturnType<T>> | ReturnType<T>)) => (() => void))>
    • OEvent
  • OEvent(...args): (() => void)

  • Parameters

    • Rest...args: [listener: ((...args: Parameters<T>) => ReturnType<T> | Promise<ReturnType<T>>)]

    Returns (() => void)

      • (): void

      • Returns void

Constructors

constructor

Properties

onError

Methods

emit emitAll emitRace listen listenerCount onListen onStopListen

Constructors

constructor

  • new OEvent<T>(type?, executeSequentially?): OEvent<T>

  • Create an OEvent object.

    Type Parameters

    • T extends ((...arg: any) => any)

    Parameters

    • type: EventTypes = EventTypes.Default

      The type of the event.

    • executeSequentially: boolean = true

      Type of execution. See class descriptions for more detail.

    Returns OEvent<T>

Properties

onError

onError: null | ((err: any) => void) = null

Methods

emit

  • emit(...listenerArguments): void

  • Invokes all event listeners.

    If a listener throws an error - or a listener returns a promise that rejects - the following will happen:

    1. All remaining event handlers will still be executed
    2. If onError callback exists: The onError callback will be called with the error
    3. Else: The errors will be logged with console.error()

    The listeners will be executed in parallel or sequentially based on the executeSequentially flag set in the constructor.

    Parameters

    • Rest...listenerArguments: Parameters<T>

      Arguments are passed to the invoked listeners.

    Returns void

emitAll

  • emitAll(...listenerArguments): Promise<ReturnType<T>[]>

  • Invokes all event listeners and returns the results of all listeners.

    Even if the listeners have a return value of void / Promise this function is useful. The returned promise of emitAll resolves after all event listeners have been executed, so this method can be used to wait for the execution of all event handlers.

    It behaves like Promise.all() over all event listeners.

    Parameters

    • Rest...listenerArguments: Parameters<T>

      Arguments are passed to the invoked listeners.

    Returns Promise<ReturnType<T>[]>

    Throws

    If only one listener throws, then the error is thrown directly, if multiple errors are thrown, then a new error object is created that has an errors field with all errors stored in an array.

emitRace

  • emitRace(...listenerArguments): Promise<ReturnType<T>>

  • Invoke all listeners and return the result of the first resolved promise.

    All event listeners will be executed in parallel - even if executeSequentially is set to true. It just does not make sense to have a race between listeners and then invoke them sequentially.

    It behaves like Promise.race() over all event listeners.

    Parameters

    • Rest...listenerArguments: Parameters<T>

      Arguments are passed to the invoked listeners.

    Returns Promise<ReturnType<T>>

listen

  • listen(listener): (() => void)

  • Registers a listener to be executed when the event is emitted.

    Parameters

    • listener: ((...args: Parameters<T>) => ReturnType<T> | Promise<ReturnType<T>>)

      The callback to be executed when the event is emitted.

        • (...args): ReturnType<T> | Promise<ReturnType<T>>

        • Parameters

          • Rest...args: Parameters<T>

          Returns ReturnType<T> | Promise<ReturnType<T>>

    Returns (() => void)

    a function that disconnects the listener. If executeSequentially is true: No further calls to the event listener will be made after this call. If executeSequentially is false: Further calls might happen when the disconnect happens in another event listener.

      • (): void

      • Returns void

listenerCount

  • listenerCount(): number

  • Returns the number of registered event listeners.

    Returns number

onListen

  • onListen(onListenListenerHandler): (() => void)

  • Register a listener to be triggered when a new listener is registered for this event.

    Parameters

    • onListenListenerHandler: (() => void | Promise<void>)
        • (): void | Promise<void>

        • Returns void | Promise<void>

    Returns (() => void)

      • (): void

      • Returns void

onStopListen

  • onStopListen(onStopListenListenerHandler): (() => void)

  • Register a listener to be triggered when a listener is unregistered from this event.

    Parameters

    • onStopListenListenerHandler: (() => void | Promise<void>)
        • (): void | Promise<void>

        • Returns void | Promise<void>

    Returns (() => void)

      • (): void

      • Returns void

Settings

Member Visibility

On This Page

Executing handlers sequentially vs parallel:Usage:
Constructors
Properties
Methods