Skip to main content
Version: v1.1.0

Class: NexoEmitter

Defined in: src/events/NexoEmitter.ts:35

A minimal, synchronous event emitter for proxy-related instrumentation.

Remarks​

NexoEmitter is a purpose-built event manager designed for performance-critical environments such as JavaScript Proxy traps. It executes listeners synchronously and supports event cancellation (defaultPrevented) and return value capture (returnValue).

This emitter intentionally does not support async listener chaining, and errors thrown by listeners will crash the app unless an 'error' handler is attached.

Usage Notes​

  • Use on(event, fn) to attach listeners.
  • Use off(event, fn) to remove them.
  • Use emit(event, data) to dispatch a NexoEvent or Error.

Behavior​

  • If an Error is passed to emit() (and the event is not "error"), it is re-emitted on "error".
  • If no "error" listener exists, the app will throw to ensure fail-fast behavior.
  • If a NexoEvent is emitted and defaultPrevented is false, listeners' returnValue will be ignored.

Example​

const emitter = new NexoEmitter();
emitter.on("proxy.set", (event) => {
  if (event.key === "password") event.preventDefault();
});

emitter.emit("proxy.set", new NexoEvent({ key: "password" }));

Extended by​

Constructors​

new NexoEmitter()​

new NexoEmitter(): NexoEmitter

Returns​

NexoEmitter

Methods​

emit()​

emit<Event>(eventName, data, ...args): boolean

Defined in: src/events/NexoEmitter.ts:104

Emits an event and synchronously triggers all associated listeners.

Type Parameters​

• Event extends NexoEvent

Parameters​

eventName​

ObjectKey

The name of the event to emit.

data​

A NexoEvent or an Error.

Error | Event

args​

...ArrayLike

Additional arguments passed to each listener.

Returns​

boolean

true if any listeners were triggered; false otherwise.

Remarks​

Listeners are executed immediately. If a listener throws, the error is re-emitted via the 'error' event.

If data is an Error and the event name is not 'error', it will be forwarded to the 'error' listeners.

off()​

off(event, listener): this

Defined in: src/events/NexoEmitter.ts:84

Unregisters a listener from the specified event.

Parameters​

event​

ObjectKey

The event name to stop listening to.

listener​

FunctionLike

The function to remove from the event's listener list.

Returns​

this

The current instance for chaining.

Remarks​

If the listener is not registered for the given event, this method does nothing. Only the exact function reference passed to on() can be removed.

Removing a listener helps avoid memory leaks and unnecessary processing.

Example​

const handler = (event) => console.log('Accessed:', event.key);
emitter.on('proxy.get', handler);
emitter.off('proxy.get', handler);

on()​

on(event, listener): this

Defined in: src/events/NexoEmitter.ts:58

Registers a listener for the specified event.

Parameters​

event​

ObjectKey

The event name to listen for.

listener​

FunctionLike

The function to call when the event is emitted.

Returns​

this

The current instance for chaining.

Remarks​

The listener will be called every time the event is emitted. Multiple listeners can be registered for the same event, and they will be executed in the order in which they were added.

This method does not check for duplicates — adding the same function multiple times will result in multiple calls.

Example​

emitter.on('proxy.set', (event) => {
  console.log('Property set:', event.key);
});