Event Interceptors for EventEmitter

Common errors

• Error: Maximum number of interceptors exceeded

  cause More than 10 interceptors (default limit) were added to a single event type, which the library flags as a potential memory leak.
  fix If this is intentional, increase the limit: `emitter.setMaxInterceptors(N)` where `N` is your desired limit (0 for no limit). If unintentional, review your code to identify and remove redundant interceptors.

• RangeError: Maximum call stack size exceeded

  cause An interceptor for an event is re-emitting the *same* event, leading to an uncontrolled recursive loop of interception and emission.
  fix Inspect interceptors for the affected event. Ensure that `this.emit('eventName', ...)` inside an interceptor does not re-emit the `eventName` that triggered the interceptor itself. Emit a *different* event, or implement logic to prevent re-emission.

Warnings

• breaking The `events-intercept` package has been abandoned since 2015 and is no longer maintained. It does not receive security updates, bug fixes, or new features. Using it in new projects is strongly discouraged, and existing projects should consider migration.
  Fix: Consider alternatives like custom event systems, state management libraries, or modern middleware patterns for stream/message processing that are actively maintained and support modern JavaScript features.
• breaking This package is CommonJS-only and lacks native ES Module (ESM) support. It cannot be directly `import`ed in ESM contexts without relying on Node.js's CJS interoperability layers, which can lead to issues or suboptimal performance in modern build environments.
  Fix: For CommonJS-only environments, use `require()`. For ES Module projects, evaluate if the functionality is critical enough to warrant using a legacy CJS module, or seek out an ESM-compatible alternative.
• gotcha Re-emitting the *same* event within its own interceptor can lead to an infinite loop, causing stack overflow errors or exhausting system resources.
  Fix: Avoid `this.emit(event)` for the currently intercepted `event` within an interceptor. If you need to trigger subsequent events, emit a *different* event or ensure there's a conditional break in the interception chain.
• gotcha By default, a warning is emitted if more than 10 interceptors are added to a single event type, indicating a potential memory leak. While `setMaxInterceptors(n)` can change this limit (0 for no limit), a large number of interceptors can still impact performance and maintainability.
  Fix: Monitor for 'MaxInterceptorsExceededWarning'. If legitimate, increase the limit using `emitter.setMaxInterceptors(n)`. Otherwise, refactor your event handling to reduce the number of interceptors or consolidate related logic into fewer, more comprehensive interceptors.

Install

• npm install events-intercept npm
• yarn add events-intercept yarn
• pnpm add events-intercept pnpm

Imports

• EventEmitter
  wrong:

  import { EventEmitter } from 'events-intercept';

  correct:

  const EventEmitter = require('events-intercept').EventEmitter;

  This package is CommonJS-only and does not support ES Module `import` syntax. Attempting to use `import` will result in a syntax error or a runtime error.
• eventsIntercept
  wrong:

  import eventsIntercept from 'events-intercept';

  correct:

  const eventsIntercept = require('events-intercept');

  The entire module can be required, exposing the `EventEmitter` constructor as a property of the resulting object. This is a CommonJS module only.

Quickstart

This quickstart demonstrates how to set up `EventEmitter` with multiple interceptors for an event, showing how data can be transformed in a pipeline. It also illustrates how an interceptor can prevent the original event's handlers from being called while emitting new events.

const EventEmitter = require('events-intercept').EventEmitter;
const emitter = new EventEmitter();

emitter
  .on('data', function(arg) {
    console.log(`Handler received: ${arg}`);
  })
  .intercept('data', function(arg, done) {
    // Interceptor 1: Modify data
    console.log(`Interceptor 1 received: ${arg}`);
    return done(null, 'intercepted_1_' + arg);
  })
  .intercept('data', function(arg, done) {
    // Interceptor 2: Further modify data
    console.log(`Interceptor 2 received: ${arg}`);
    return done(null, 'intercepted_2_' + arg);
  });

console.log('Emitting event with initial data...');
emitter.emit('data', 'initial data');
// Expected output:
// Emitting event with initial data...
// Interceptor 1 received: initial data
// Interceptor 2 received: intercepted_1_initial data
// Handler received: intercepted_2_initial data

console.log('\nEmitting another event, but intercepting to prevent original handler...');
emitter.intercept('no-callback-event', function(arg, done) {
    console.log(`Interceptor for 'no-callback-event' received: ${arg}. Not calling done().`);
    // Do not call done(), so the original 'no-callback-event' handler is never invoked.
    this.emit('alternative-event', 'transformed ' + arg);
});
emitter.on('no-callback-event', () => console.log('This should not log!'));
emitter.on('alternative-event', (arg) => console.log(`Alternative event handler received: ${arg}`));
emitter.emit('no-callback-event', 'original data');