Emitter

Event emitter.

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

Usage example:

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

You can create your own emitters:

1import {Emitter} from '@wonderlandengine/api';
2
3const emitter = new Emitter();

You can notify listeners in to your emitter using notify:

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

• Emitter
  • .constructor<T>() ⇒ Emitter
  • .isEmpty
  • .listenerCount
  • .add(listener, opts) ⇒ Emitter
  • .has(listener) ⇒ boolean
  • .notify(…data) ⇒ void
  • .notifyUnsafe(…data) ⇒ void
  • .once(listener) ⇒ Emitter
  • .promise() ⇒ Promise
  • .push(…listeners) ⇒ Emitter
  • .remove(listener) ⇒ Emitter

.constructor<T>() ⇒ Emitter 

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

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

Register a new listener to be triggered on notify.

Basic usage:

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

Automatically remove the listener when an event is received:

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

Returns: Reference to self (for method chaining)

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

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

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

.once(listener: ListenerCallback) ⇒ Emitter 

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:

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

Returns: Reference to self (for method chaining).

.promise() ⇒ Promise 

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[][]) ⇒ Emitter 

Equivalent to add.

Returns: Reference to self (for method chaining).

Deprecated: Please use add instead.

.remove(listener: any) ⇒ Emitter 

Remove a registered listener.

Usage with a callback:

1const listener = (data) => console.log(data);
2emitter.add(listener);
3
4// Remove using the callback reference:
5emitter.remove(listener);

Usage with an id:

1emitter.add((data) => console.log(data), {id: 'my-callback'});
2
3// Remove using the id:
4emitter.remove('my-callback');

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

1emitter.add((data) => console.log(data), {id: 'non-unique'});
2// This second listener could be added by a third-party library.
3emitter.add((data) => console.log('Hello From Library!'), {id: 'non-unique'});
4
5// Ho Snap! This also removed the library listener!
6emitter.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:

1emitter.add(() => console.log('Hello'), {id: {value: 42}});
2emitter.add(() => console.log('World!'), {id: {value: 42}});
3emitter.remove({value: 42}); // None of the above listeners match!
4emitter.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:

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

Returns: Reference to self (for method chaining)