Class EventbusProxy

EventbusProxy provides a protected proxy of another Eventbus instance.

The main use case of EventbusProxy is to allow indirect access to an eventbus. This is handy when it comes to managing the event lifecycle for a plugin system. When a plugin is added it could receive a callback, perhaps named onPluginLoaded, which contains an EventbusProxy instance rather than the direct eventbus. This EventbusProxy instance is associated in the management system controlling plugin lifecycle. When a plugin is removed / unloaded the management system can automatically unregister all events for the plugin without requiring the plugin author doing it correctly if they had full control. IE This allows to plugin system to guarantee no dangling listeners.

EventbusProxy provides the on / off, before, once, and trigger methods with the same signatures as found in Eventbus. However, the proxy tracks all added event bindings which is used to proxy between the target eventbus which is passed in from the constructor. All registration methods (on / off / once) proxy. In addition, there is a destroy method which will unregister all of proxied events and remove references to the managed eventbus. Any further usage of a destroyed EventbusProxy instance results in a ReferenceError thrown.

Finally, the EventbusProxy only allows events registered through it to be turned off providing a buffer between any consumers such that they can not turn off other registrations made on the eventbus or other proxy instances.

Constructors

constructor

Accessors

callbackCount eventCount isDestroyed name proxyCallbackCount proxyEventCount

Methods

before createProxy destroy entries getOptions getType isGuarded keys keysWithOptions off on once proxyEntries proxyKeys proxyKeysWithOptions trigger triggerAsync triggerDefer triggerSync

Constructors

constructor

  • new EventbusProxy(eventbus): EventbusProxy

  • Creates the event proxy with an existing instance of Eventbus.

    Parameters

    • eventbus: Eventbus

      The target eventbus instance.

    Returns EventbusProxy

Accessors

callbackCount

  • get callbackCount(): number

  • Returns the current proxied eventbus callback count.

    Returns number

    Returns the current proxied callback count.

eventCount

  • get eventCount(): number

  • Returns the current proxied eventbus event count.

    Returns number

    Returns the current proxied event count.

isDestroyed

  • get isDestroyed(): boolean

  • Returns whether this EventbusProxy has already been destroyed.

    Returns boolean

    Is destroyed state.

name

  • get name(): string

  • Returns the target eventbus name.

    Returns string

    The target eventbus name.

proxyCallbackCount

  • get proxyCallbackCount(): number

  • Returns the current proxied callback count.

    Returns number

    Returns the current proxied callback count.

proxyEventCount

  • get proxyEventCount(): number

  • Returns the current proxied event count.

    Returns number

    Returns the current proxied event count.

Methods

before

  • before(count, name, callback, context?, options?): EventbusProxy

  • Just like on, but causes the bound callback to fire several times up to the count specified before being removed. When multiple events are passed in using the space separated syntax, the event will fire count times for every event you passed in, not once for a combination of all events.

    Parameters

    • count: number

      Number of times the function will fire before being removed.

    • name: string | EventMap

      Event name(s) or event map.

    • callback: object | Function

      Event callback function or context for event map.

    • Optionalcontext: object

      Event context

    • Optionaloptions: EventOptions | EventOptionsOut

      Event registration options.

    Returns EventbusProxy

    This EventbusProxy instance.

createProxy

  • createProxy(): EventbusProxy

  • Creates an EventbusProxy wrapping the backing Eventbus instance. An EventbusProxy proxies events allowing all listeners added to be easily removed from the wrapped Eventbus.

    Returns EventbusProxy

    A new EventbusProxy for this eventbus.

destroy

  • destroy(): void

  • Unregisters all proxied events from the target eventbus and removes any local references. All subsequent calls after destroy has been called result in a ReferenceError thrown.

    Returns void

entries

  • entries(regex?): Generator<[string, Function, object, EventOptionsOut], void, unknown>

  • Returns an iterable for all events from the proxied eventbus yielding an array with event name, callback function, and event context.

    Parameters

    • Optionalregex: RegExp

      Optional regular expression to filter event names.

    Returns Generator<[string, Function, object, EventOptionsOut], void, unknown>

    Generator

    Yields

getOptions

  • getOptions(name): EventOptionsOut

  • Returns the options of an event name.

    Parameters

    • name: string

      Event name(s) to verify.

    Returns EventOptionsOut

    The event options.

getType

  • getType(name): string

  • Returns the trigger type of event name. Note: if trigger type is not set then undefined is returned for type otherwise 'sync' or 'async' is returned.

    Parameters

    • name: string

      Event name(s) to verify.

    Returns string

    The trigger type.

isGuarded

  • isGuarded(name, data?): boolean

  • Returns whether an event name is guarded.

    Parameters

    • name: string | EventMap

      Event name(s) or event map to verify.

    • Optionaldata: object

      Stores the output of which names are guarded.

    Returns boolean

    Whether the given event name is guarded.

keys

  • keys(regex?): Generator<string, void, unknown>

  • Returns an iterable for the event names / keys of proxied eventbus event listeners.

    Parameters

    • Optionalregex: RegExp

      Optional regular expression to filter event names.

    Returns Generator<string, void, unknown>

    Yields

keysWithOptions

  • keysWithOptions(regex?): Generator<[string, EventOptionsOut], void, unknown>

  • Returns an iterable for the event names / keys of registered event listeners along with event options.

    Parameters

    • Optionalregex: RegExp

      Optional regular expression to filter event names.

    Returns Generator<[string, EventOptionsOut], void, unknown>

    Generator

    Yields

off

  • off(name?, callback?, context?): EventbusProxy

  • Remove a previously-bound proxied event binding.

    Please see Eventbus#off.

    Parameters

    • Optionalname: string | EventMap

      Event name(s) or event map.

    • Optionalcallback: Function

      Event callback function

    • Optionalcontext: object

      Event context

    Returns EventbusProxy

    This EventbusProxy

on

  • on(name, callback, context?, options?): EventbusProxy

  • Bind a callback function to an object. The callback will be invoked whenever the event is fired. If you have a large number of different events on a page, the convention is to use colons to namespace them: poll:start, or change:selection.

    Please see Eventbus#on.

    Parameters

    • name: string | EventMap

      Event name(s) or event map.

    • callback: object | Function

      Event callback function or context for event map.

    • Optionalcontext: object

      Event context.

    • Optionaloptions: EventOptions | EventOptionsOut

      Event registration options.

    Returns EventbusProxy

    This EventbusProxy

once

  • once(name, callback, context?, options?): EventbusProxy

  • Just like on, but causes the bound callback to fire only once before being removed. Handy for saying "the next time that X happens, do this". When multiple events are passed in using the space separated syntax, the event will fire once for every event you passed in, not once for a combination of all events

    Parameters

    • name: string | EventMap

      Event name(s) or event map.

    • callback: object | Function

      Event callback function or context for event map.

    • Optionalcontext: object

      Event context

    • Optionaloptions: EventOptions | EventOptionsOut

      Event registration options.

    Returns EventbusProxy

    This EventbusProxy instance.

proxyEntries

  • proxyEntries(regex?): Generator<[string, Function, object, EventOptionsOut], void, unknown>

  • Returns an iterable for all stored locally proxied events yielding an array with event name, callback function, and event context.

    Parameters

    • Optionalregex: RegExp

      Optional regular expression to filter event names.

    Returns Generator<[string, Function, object, EventOptionsOut], void, unknown>

    Generator

    Yields

proxyKeys

  • proxyKeys(regex?): Generator<string, void, unknown>

  • Returns an iterable for the event names / keys of the locally proxied event names.

    Parameters

    • Optionalregex: RegExp

      Optional regular expression to filter event names.

    Returns Generator<string, void, unknown>

    Yields

proxyKeysWithOptions

  • proxyKeysWithOptions(regex?): Generator<[string, EventOptionsOut], void, unknown>

  • Returns an iterable for the event names / keys of the locally proxied event names with event options.

    Note: The event options returned will respect all the event options from a registered event on the main eventbus if applicable.

    Parameters

    • Optionalregex: RegExp

      Optional regular expression to filter event names.

    Returns Generator<[string, EventOptionsOut], void, unknown>

    Generator

    Yields

trigger

  • trigger(name, ...args): EventbusProxy

  • Trigger callbacks for the given event, or space-delimited list of events. Subsequent arguments to trigger will be passed along to the event callbacks.

    Parameters

    • name: string

      Event name(s)

    • Rest...args: any[]

      Additional arguments passed to the event function(s).

    Returns EventbusProxy

    This EventbusProxy.

triggerAsync

  • triggerAsync(name, ...args): Promise<any>

  • Provides trigger functionality, but collects any returned Promises from invoked targets and returns a single Promise generated by Promise.resolve for a single value or Promise.all for multiple results. This is a very useful mechanism to invoke asynchronous operations over an eventbus.

    Parameters

    • name: string

      Event name(s)

    • Rest...args: any[]

      Additional arguments passed to the event function(s).

    Returns Promise<any>

    A Promise returning any results.

triggerDefer

  • triggerDefer(name, ...args): EventbusProxy

  • Defers invoking trigger. This is useful for triggering events in the next clock tick.

    Parameters

    • name: string

      Event name(s)

    • Rest...args: any[]

      Additional arguments passed to the event function(s).

    Returns EventbusProxy

    This EventbusProxy.

triggerSync

  • triggerSync(name, ...args): any

  • Provides trigger functionality, but collects any returned result or results from invoked targets as a single value or in an array and passes it back to the callee in a synchronous manner.

    Parameters

    • name: string

      Event name(s)

    • Rest...args: any[]

      Additional arguments passed to the event function(s).

    Returns any

    An Array of returned results.

Settings

Member Visibility

On This Page

Constructors
Accessors
Methods