How to Create a Custom Priority Event Emitter in Node.js

Setup:

Libraries Installation and Setup

npm i -d @types/node tsx typescript
npx tsc --init

Change tsconfig.json and package.json

// tsconfig.json
{
  "compilerOptions": {
    "target": "es2016",
    "module": "ES6",
    "moduleResolution": "nodenext",
    "allowImportingTsExtensions": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "sourceMap": true,
    "outDir": "./dist",
    "types": ["node"]
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules"]
}

// package.json
{
  "name": "node-starter",
  "version": "0.0.0",
  "type": "module", // This should be set to "module" for using ES6 modules
  "scripts": {
    "test": "jest"
  },
  "devDependencies": {
    "@types/jest": "^29.5.14",
    "jest": "^29.7.0",
    "typescript": "^5.7.2"
  },
  "dependencies": {
    "@types/node": "^22.10.2",
    "tsx": "^4.19.2"
  }
}

---

Understanding EventEmitter in Node.js

Node.js uses EventEmitter as a fundamental class for handling events in asynchronous programming. This class allows you to register listeners for specific events and emit those events when needed. By default, EventEmitter processes events in the order that the listeners were added. However, sometimes we might want to prioritize the execution of certain listeners over others. That’s where we can introduce a priority-based event system.

Steps to Create a Priority EventEmitter

1. Inheriting from EventEmitter:
   To create a custom event emitter with priority handling, we need to extend the built-in EventEmitter class. This gives us access to all the built-in methods like on, emit, and removeListener.
   

   import EventEmitter from 'events';
   
   export class PriorityEmitter extends EventEmitter {
     private _listeners: Record<
       string,
       { listener: (...args: any[]) => void; priority: number }[]
     >;
   
     constructor() {
       super();
       this._listeners = {};
     }
   }
   

- `PriorityEmitter` extends `EventEmitter`, so it inherits all of its functionality.
- We introduce a new internal property `_listeners` to store listeners along with their priorities.

1. Overriding the on Method:
   By overriding the on method, we can add custom logic to store the listeners along with their priorities and sort them based on their priority.
   

   on(event: string, listener: (...args: any[]) => void, priority = 0) {
     if (!this._listeners[event]) this._listeners[event] = [];
     this._listeners[event].push({ listener, priority });
     this._listeners[event].sort((a, b) => b.priority - a.priority);
     return this;
   }
   

- For production usage, consider using other data structures instead of arrays, which maintain order.
- When a listener is added using `on`, we push the listener and its priority into the `_listeners` array.
- We then sort the listeners in descending order based on the priority. This ensures that higher-priority listeners are executed first.
- The default priority is `0` if not specified.

1. Overriding the emit Method:
   The emit method triggers the event and executes the listeners. In the overridden method, we first process the listeners from _listeners based on their priority.
   

   emit(event: string, ...args: any[]) {
     if (this._listeners[event]) {
       for (const { listener } of this._listeners[event]) {
         listener(...args);
       }
     }
     return super.emit(event, ...args);
   }
   

- For the given event, we iterate over the sorted listeners and call each listener.
- After handling the custom priority-based logic, we call the parent class’s `emit` method to ensure the standard behavior is also preserved.

1. Overriding the removeListener Method:
   The removeListener method is overridden to ensure that listeners are correctly removed based on their reference. Since we store listeners along with their priorities, we filter out the correct listener.
   

   removeListener(event: string, listener: (...args: any[]) => void) {
     if (this._listeners[event]) {
       this._listeners[event] = this._listeners[event].filter(
         (stored_listener) => stored_listener.listener !== listener
       );
     }
     super.removeListener(event, listener);
     return this;
   }
   

- We filter the listener array to remove the listener with the exact reference.
- Then we call `super.removeListener` to ensure proper cleanup and avoid memory leaks.

---

How the PriorityEmitter Works

• When an event is emitted, listeners are invoked in the order of their priority. The higher the priority, the earlier it will be executed.
• Listeners with equal priority are executed in the order they were added.

Example Usage

Here’s an example to demonstrate how the PriorityEmitter works in practice:

const pe = new PriorityEmitter();

// Listener with higher priority
pe.on('greet', (name: string) => {
  console.log(`Hello ${name}!`);
}, 2);

// Listener with lower priority
pe.on('greet', (name: string) => {
  console.log(`Hi, ${name}!`);
}, 1);

// Emitting the event
pe.emit('greet', 'Alice');

Output:

-- Run using this command
❯ npx tsx PriorityEvent.ts
Hello Alice!
Hi, Alice!

• The listener with priority 2 (Hello Alice!) is called first.
• The listener with priority 1 (Hi, Alice!) is called next.

---

Performance Considerations

• Data Structure Choice: In this basic example, we are using an array to store listeners and sorting them every time a listener is added. This can become inefficient when there are a large number of listeners. A better solution for handling priorities in a performance-critical environment would be to use a max-heap, which allows for efficient insertion and removal operations.
• Use in Production: For production-level applications, consider using more advanced data structures or external libraries that provide priority queues to handle large numbers of events more efficiently.

---

Complete Code

// This a basic example of priority Event emitter, for production use heaps instead of sorting in 
// each insertion we can use maxHeap to always choose the max priority first.
import EventEmitter from 'events';

export class PriorityEmitter extends EventEmitter {
  // This field will store a map of all the events string with assigned listeners to them.
  // Without custom logic, nodejs invokes the listeners in the order in which they were registered.
  // So we add custom logic by overriding the on and emit methods of the EventEmitter class.  
  private _listeners: Record<
    string,
    { listener: (...args: any[]) => void; priority: number }[]
  >;

  constructor() {
    super();
    this._listeners = {};
  }

  // Override the on method with our custom logic for ordering.  
  on(event: string, listener: (...args: any[]) => void, priority = 0) {
    if (!this._listeners[event]) this._listeners[event] = [];
    this._listeners[event].push({ listener, priority });
    this._listeners[event].sort((a, b) => b.priority - a.priority);
    return this;
  }

  // Override the emit method  
  emit(event: string, ...args: any[]) {
    if (this._listeners[event]) {
      for (const { listener } of this._listeners[event]) {
        listener(...args);
      }
    }
    return super.emit(event, ...args);
  }

  // Override the remove listener method    
  removeListener(event: string, listener: (...args: any[]) => void) {
    if (this._listeners[event]) {
      this._listeners[event] = this._listeners[event].filter(
        (stored_listener) => stored_listener.listener !== listener
      );
    }
    super.removeListener(event, listener);
    return this;
  }
}

const pe = new PriorityEmitter();

// This will be invoked first as this has higher priority.
pe.on(
  'greet',
  (name: string) => {
    console.log(`Hello ${name}!`);
  },
  2
);

// This will be invoked later on as this has lower priority.
pe.on(
  'greet',
  (name: string) => {
    console.log(`Hi, ${name}!`);
  },
  1
);

// Here we emit the event by passing the name as parameter, it will invoke all the listeners by
// priority.
pe.emit('greet', 'Alice');