Emitter

Event emitter.

This class allows to register listeners that will get notified by the emitter.

Usage example:

// `onPreRender` is an `Emitter` instance.
scene.onPreRender.add(() => console.log('before rendering'));
// `onPostRender` is an `Emitter` instance.
scene.onPostRender.add(() => console.log('after rendering'));

You can create your own emitters:

import {Emitter} from '@wonderlandengine/api';

const emitter = new Emitter();

You can notify listeners in to your emitter using notify:

// Notifies all the listeners.
emitter.notify();
// Notifies all the listeners with some data.
emitter.notify({ myInt: 42, myStr: 'Hello World!' });

Static Members

Properties

Methods

Constructor

.constructor<T>() ⇒ Emitter<T>

Template ParamType Definition
Textends unknown[]

Properties

.isEmpty: boolean

true if it has no listeners, false otherwise.

.listenerCount: number

Number of listeners.

Note: Doesn’t account for pending listeners, i.e., listeners added / removed during a notification.

Methods

.add(listener: ListenerCallback<T>, opts: Partial<ListenerOptions>) ⇒ Emitter<T>

Register a new listener to be triggered on notify.

Basic usage:

emitter.add((data) => {
    console.log('event received!');
    console.log(data);
});

Automatically remove the listener when an event is received:

emitter.add((data) => {
    console.log('event received!');
    console.log(data);
}, {once: true});

Returns: Reference to self (for method chaining)

ParamTypeDescription
listenerListenerCallback<T>The callback to register.
optsPartial<ListenerOptions>The listener options. For more information, please have a look at the ListenerOptions interface.

.has(listener: any) ⇒ boolean

Check whether the listener is registered.

Note: This method performs a linear search.

Note: Doesn’t account for pending listeners, i.e., listeners added / removed during a notification.

Returns: true if the handle is found, false otherwise.

ParamTypeDescription
listeneranyThe registered callback or a value representing the id.

.notify(…data: T[]) ⇒ void

Notify listeners with the given data object.

Note: This method ensures all listeners are called even if an exception is thrown. For (possibly) faster notification, please use notifyUnsafe.

ParamTypeDescription
dataTThe data to pass to listener when invoked.

.notifyUnsafe(…data: T[]) ⇒ void

Notify listeners with the given data object.

Note: Because this method doesn’t catch exceptions, some listeners will be skipped on a throw. Please use notify for safe notification.

ParamTypeDescription
dataTThe data to pass to listener when invoked.

.once(listener: ListenerCallback<T>) ⇒ Emitter<T>

Register a new listener to be triggered on notify.

Once notified, the listener will be automatically removed.

The method is equivalent to calling add with:

emitter.add(listener, {once: true});

Returns: Reference to self (for method chaining).

ParamTypeDescription
listenerListenerCallback<T>The callback to register.

.promise() ⇒ Promise<T>

Return a promise that will resolve on the next event.

Note: The promise might never resolve if no event is sent.

Returns: A promise that resolves with the data passed to notify.

.push(…listeners: ListenerCallback<T>[][]) ⇒ Emitter<T>

Equivalent to add.

Returns: Reference to self (for method chaining).

Deprecated: Please use add instead.

ParamTypeDescription
listenersListenerCallback<T>[]The callback(s) to register.

.remove(listener: any) ⇒ Emitter<T>

Remove a registered listener.

Usage with a callback:

const listener = (data) => console.log(data);
emitter.add(listener);

// Remove using the callback reference:
emitter.remove(listener);

Usage with an id:

emitter.add((data) => console.log(data), {id: 'my-callback'});

// Remove using the id:
emitter.remove('my-callback');

Using identifiers, you will need to ensure your value is unique to avoid removing listeners from other libraries, e.g.,:

emitter.add((data) => console.log(data), {id: 'non-unique'});
// This second listener could be added by a third-party library.
emitter.add((data) => console.log('Hello From Library!'), {id: 'non-unique'});

// Ho Snap! This also removed the library listener!
emitter.remove('non-unique');

The identifier can be any type. However, remember that the comparison will be by-value for primitive types (string, number), but by reference for objects.

Example:

emitter.add(() => console.log('Hello'), {id: {value: 42}});
emitter.add(() => console.log('World!'), {id: {value: 42}});
emitter.remove({value: 42}); // None of the above listeners match!
emitter.notify(); // Prints 'Hello' and 'World!'.

Here, both emitters have id {value: 42}, but the comparison is made by reference. Thus, the remove() call has no effect. We can make it work by doing:

const id = {value: 42};
emitter.add(() => console.log('Hello'), {id});
emitter.add(() => console.log('World!'), {id});
emitter.remove(id); // Same reference, it works!
emitter.notify(); // Doesn't print.

Returns: Reference to self (for method chaining)

ParamTypeDescription
listeneranyThe registered callback or a value representing the id.
DefaultPropertyCloner GLTFExtensions