@refinio/one.models
    Preparing search index...

    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.

    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.
     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 Summary)

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

    • Parameters

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

      Returns () => void

    Index

    Constructors

    constructor

    Properties

    onError

    Methods

    emit emitAll emitRace listen listenerCount onListen onStopListen

    Constructors

    • 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: null | ((err: any) => void) = null

    Methods

    • 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

      • ...listenerArguments: Parameters<T>

        Arguments are passed to the invoked listeners.

      Returns void

    • 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

      • ...listenerArguments: Parameters<T>

        Arguments are passed to the invoked listeners.

      Returns Promise<ReturnType<T>[]>

      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.

    • 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

      • ...listenerArguments: Parameters<T>

        Arguments are passed to the invoked listeners.

      Returns Promise<ReturnType<T>>

    • 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.

      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.

    • Returns the number of registered event listeners.

      Returns number

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

      Parameters

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

      Returns () => void

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

      Parameters

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

      Returns () => void

    Settings

    Member Visibility

    On This Page

    Executing handlers sequentially vs parallel:Usage:
    Constructors
    Properties
    Methods