tessl/npm-events

Node's event emitter for all engines.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Events

Name: tessl/npm-events
Author: tessl

Events is a cross-platform implementation of Node.js's EventEmitter that works in browsers and other JavaScript environments. It provides event-driven programming capabilities with API compatibility matching Node.js 11.13.0, enabling developers to use familiar Node.js EventEmitter patterns in any JavaScript runtime.

Package Information

Package Name: events
Package Type: npm
Language: JavaScript (ES5+)
Installation: npm install events

Core Imports

var EventEmitter = require('events');

ES6 modules:

import EventEmitter from 'events';

Named function import:

import { once } from 'events';

Basic Usage

var EventEmitter = require('events');

// Create an EventEmitter instance
var ee = new EventEmitter();

// Register event listeners
ee.on('message', function(text) {
  console.log('Received:', text);
});

// Emit events
ee.emit('message', 'Hello World!');

// One-time listener
ee.once('close', function() {
  console.log('Closing connection');
});

// Remove specific listener
function handler(data) {
  console.log('Handler:', data);
}
ee.on('data', handler);
ee.removeListener('data', handler);

Architecture

The Events package provides a complete EventEmitter implementation with:

EventEmitter Class: Main event emitter for registering listeners and emitting events
Cross-platform Compatibility: Works in Node.js, browsers, and other JavaScript environments
Memory Leak Detection: Warns when too many listeners are added to prevent memory leaks
Multiple Listener Support: Supports multiple listeners per event with configurable limits
Promise Integration: Includes utility function for Promise-based event handling

Capabilities

EventEmitter Constructor

Creates a new EventEmitter instance for event-driven programming.

/**
 * EventEmitter constructor - creates a new event emitter instance
 * @constructor
 */
function EventEmitter();

Event Registration

/**
 * Adds a listener function to the end of the listeners array for the specified event
 * @param {string|symbol} type - The event name
 * @param {Function} listener - The listener function
 * @returns {EventEmitter} Returns emitter for chaining
 */
addListener(type, listener);

/**
 * Alias for addListener
 * @param {string|symbol} type - The event name  
 * @param {Function} listener - The listener function
 * @returns {EventEmitter} Returns emitter for chaining
 */
on(type, listener);

/**
 * Adds a listener function to the beginning of the listeners array for the specified event
 * @param {string|symbol} type - The event name
 * @param {Function} listener - The listener function
 * @returns {EventEmitter} Returns emitter for chaining
 */
prependListener(type, listener);

/**
 * Adds a one-time listener function for the event
 * @param {string|symbol} type - The event name
 * @param {Function} listener - The listener function
 * @returns {EventEmitter} Returns emitter for chaining
 */
once(type, listener);

/**
 * Adds a one-time listener function to the beginning of the listeners array
 * @param {string|symbol} type - The event name
 * @param {Function} listener - The listener function
 * @returns {EventEmitter} Returns emitter for chaining
 */
prependOnceListener(type, listener);

Event Emission

Emit events to trigger registered listeners.

/**
 * Synchronously calls each of the listeners registered for the event
 * @param {string|symbol} type - The event name
 * @param {...any} args - Arguments to pass to listeners
 * @returns {boolean} Returns true if event had listeners, false otherwise
 */
emit(type, ...args);

Event Listener Removal

Remove event listeners using various methods.

/**
 * Removes the specified listener from the listener array for the event
 * @param {string|symbol} type - The event name
 * @param {Function} listener - The listener function to remove
 * @returns {EventEmitter} Returns emitter for chaining
 */
removeListener(type, listener);

/**
 * Alias for removeListener
 * @param {string|symbol} type - The event name
 * @param {Function} listener - The listener function to remove
 * @returns {EventEmitter} Returns emitter for chaining
 */
off(type, listener);

/**
 * Removes all listeners, or those of the specified event
 * @param {string|symbol} [type] - The event name (optional)
 * @returns {EventEmitter} Returns emitter for chaining
 */
removeAllListeners(type);

Listener Configuration

Configure listener limits and behavior.

/**
 * Sets the maximum number of listeners for this EventEmitter instance
 * @param {number} n - Maximum number of listeners (0 for unlimited)
 * @returns {EventEmitter} Returns emitter for chaining
 */
setMaxListeners(n);

/**
 * Returns the current maximum listener value for the EventEmitter
 * @returns {number} Current maximum listeners
 */
getMaxListeners();

Listener Introspection

Query information about registered listeners.

/**
 * Returns a copy of the array of listeners for the event
 * @param {string|symbol} type - The event name
 * @returns {Function[]} Array of listener functions
 */
listeners(type);

/**
 * Returns a copy of the array of listeners including wrapped listeners
 * @param {string|symbol} type - The event name
 * @returns {Function[]} Array of listener functions (including wrapped)
 */
rawListeners(type);

/**
 * Returns the number of listeners listening to the event
 * @param {string|symbol} type - The event name
 * @returns {number} Number of listeners
 */
listenerCount(type);

/**
 * Returns an array listing the events for which the emitter has registered listeners
 * @returns {(string|symbol)[]} Array of event names
 */
eventNames();

Static Properties and Methods

Static configuration and utility methods available on the EventEmitter class.

/**
 * Global default maximum listeners per event (default: 10)
 * @type {number}
 */
EventEmitter.defaultMaxListeners;

/**
 * Static method to count listeners for a specific event type
 * @param {EventEmitter} emitter - The EventEmitter instance
 * @param {string|symbol} type - The event name
 * @returns {number} Number of listeners
 */
EventEmitter.listenerCount(emitter, type);

/**
 * Initialize EventEmitter instance (called by constructor)
 * @returns {void}
 */
EventEmitter.init();

/**
 * Backwards compatibility reference (Node.js 0.10.x compatibility)
 * @type {Function}
 */
EventEmitter.EventEmitter;

Promise-based Event Handling

Utility function for Promise-based event handling.

/**
 * Creates a Promise that resolves when the specified event is emitted
 * @param {EventEmitter} emitter - The EventEmitter instance
 * @param {string|symbol} name - The event name to wait for
 * @returns {Promise<any[]>} Promise that resolves with event arguments
 */
function once(emitter, name);

Usage Example:

var EventEmitter = require('events');
var once = require('events').once;

var ee = new EventEmitter();

// Promise-based event handling
once(ee, 'data').then(function(args) {
  console.log('Data received:', args);
});

// Emit the event
ee.emit('data', 'Hello', 'World');

Special Events

The EventEmitter recognizes special events with specific behaviors.

/**
 * Special 'error' event - if no listeners are registered, throws the error
 * @event error
 * @param {Error} error - The error object
 */

/**
 * Special 'newListener' event - emitted when a new listener is added
 * @event newListener  
 * @param {string|symbol} eventName - The event name
 * @param {Function} listener - The listener function
 */

/**
 * Special 'removeListener' event - emitted when a listener is removed
 * @event removeListener
 * @param {string|symbol} eventName - The event name  
 * @param {Function} listener - The listener function
 */

Error Handling

The EventEmitter provides specific error handling patterns.

Error Event Behavior:

If an 'error' event is emitted and no listeners are registered, the EventEmitter throws the error
Always register error listeners to prevent uncaught exceptions

Example:

var ee = new EventEmitter();

// Register error handler to prevent uncaught exceptions
ee.on('error', function(err) {
  console.error('EventEmitter error:', err);
});

// Safe to emit error events
ee.emit('error', new Error('Something went wrong'));

Memory Leak Warnings:

By default, EventEmitter warns if more than 10 listeners are added to a single event
Use setMaxListeners() to increase the limit or set to 0 for unlimited
Warnings help detect potential memory leaks from accumulating listeners

Types

/**
 * EventEmitter class for event-driven programming
 */
class EventEmitter {
  constructor();
  
  // Event registration methods
  addListener(type, listener);
  on(type, listener);
  prependListener(type, listener);
  once(type, listener);
  prependOnceListener(type, listener);
  
  // Event emission
  emit(type, ...args);
  
  // Event removal methods
  removeListener(type, listener);
  off(type, listener);
  removeAllListeners(type);
  
  // Configuration methods
  setMaxListeners(n);
  getMaxListeners();
  
  // Introspection methods
  listeners(type);
  rawListeners(type);
  listenerCount(type);
  eventNames();
  
  // Static properties and methods
  static defaultMaxListeners;
  static listenerCount(emitter, type);
  static init();
  static EventEmitter;
}

/**
 * Promise-based event utility function
 * @param {EventEmitter} emitter - The EventEmitter instance
 * @param {string|symbol} name - The event name
 * @returns {Promise<any[]>} Promise resolving with event arguments
 */
function once(emitter, name);

Workspace: tessl
Visibility: Public
Created: 7 months ago
Last updated: 3 months ago
Describes: pkg:npm/events@3.3.x
Publish Source: CLI
Badge