RetainEmitter

RetainEmitter 

Event emitter that retains event data when notified.

After a notification happens, subsequent calls to add will get automatically notified.

You can use another emitter in order to cancel the last retained event:

1
2
3
4
5
6

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

const onStart = new RetainedEmitter();

onStart.notify(42);
onStart.add((data) => console.log(data)) // Prints '42'.

You can reset the state of the emitter, i.e., making it forget about the last event using:

1
2
3
4
5
6
7
8
9

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

const onStart = new RetainedEmitter();
onStart.notify(42);
onStart.add((data) => console.log(data)) // Prints '42'.

// Reset the state of the emitter.
onStart.reset();
onStart.add((data) => console.log(data)) // Doesn't print anything.

For more information about emitters, please have a look at the base Emitter class.

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

.constructor<T>() ⇒ RetainEmitter 

.data 

Returns the retained data, or undefined if no data was retained.

.isDataRetained 

true if data is retained from the last event, false otherwise.

.isEmpty 

true if it has no listeners, false otherwise.

.listenerCount 

Number of listeners.

.add(listener: ListenerCallback, opts: Partial<RetainListenerOptions>) ⇒ RetainEmitter 

.has(listener: any) ⇒ boolean 

Check whether the listener is registered.

Note: This method performs a linear search.

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

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

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

.once(listener: ListenerCallback, immediate: boolean) ⇒ RetainEmitter 

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

Equivalent to add.

Returns: Reference to self (for method chaining).

Deprecated: Please use add instead.

.remove(listener: any) ⇒ RetainEmitter 

Remove a registered listener.

Usage with a callback:

1
2
3
4
5

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

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

Usage with an id:

1
2
3
4

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

1
2
3
4
5
6

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:

1
2
3
4

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:

1
2
3
4
5

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)

.reset() ⇒ RetainEmitter 

Reset the state of the emitter.

Further call to add will not automatically resolve, until a new call to notify is performed.

Returns: Reference to self (for method chaining)