or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

index.mddocs/

Component Emitter

Component Emitter is a simple and lightweight event emitter library for JavaScript environments. It provides core event handling functionality including event registration, removal, emission, and listener management. The library supports both standalone usage as an Emitter instance and as a mixin to add event capabilities to existing objects or prototypes.

Package Information

  • Package Name: component-emitter
  • Package Type: npm
  • Language: JavaScript with TypeScript definitions
  • Installation: npm install component-emitter

Core Imports

// ES Module import
import Emitter from 'component-emitter';

// CommonJS require
const Emitter = require('component-emitter');

Basic Usage

import Emitter from 'component-emitter';

// As a standalone instance
const emitter = new Emitter();

emitter.on('data', (value) => {
  console.log('Received:', value);
});

emitter.emit('data', 'Hello World');

// As a mixin on existing object
const user = { name: 'alice' };
Emitter(user);

user.on('login', () => {
  console.log(`${user.name} logged in`);
});

user.emit('login');

// As a prototype mixin
function MyClass() {}
Emitter(MyClass.prototype);

const instance = new MyClass();
instance.on('ready', () => console.log('Ready!'));
instance.emit('ready');

Architecture

Component Emitter is built around a simple but flexible architecture:

  • Core Map Storage: Uses a Map internally to store event callbacks for optimal performance and memory usage
  • Mixin Pattern: Provides three usage patterns:
    • Standalone Instance: new Emitter() creates a dedicated event emitter
    • Object Enhancement: Emitter(object) adds event capabilities to existing objects
    • Prototype Extension: Emitter(Constructor.prototype) adds event capabilities to all instances of a class
  • Method Chaining: All mutating methods return the emitter instance for fluent API usage
  • Alias Support: Provides DOM-style method names (addEventListener, removeEventListener) for familiarity

Capabilities

Constructor

Creates a new emitter instance or applies mixin functionality to an existing object.

/**
 * Create a new emitter instance or mixin to existing object
 * @param {object} [object] - Optional object to mixin functionality
 * @returns {Emitter} Emitter instance or mixed-in object
 */
function Emitter(object?: object): Emitter;

Event Registration

Register event handlers that listen to specified events.

/**
 * Register an event handler that listens to a specified event
 * @param {string} event - The name of the event to listen to
 * @param {function} listener - The function to execute when the event is emitted
 * @returns {Emitter} The Emitter instance for method chaining
 */
on(event: string, listener: (...args: any[]) => void): Emitter;

/**
 * Register a one-time event handler for a specified event
 * @param {string} event - The name of the event to listen to
 * @param {function} listener - The function to execute once when the event is emitted
 * @returns {Emitter} The Emitter instance for method chaining
 */
once(event: string, listener: (...args: any[]) => void): Emitter;

Usage Examples:

const emitter = new Emitter();

// Regular event listener
emitter.on('message', (data) => {
  console.log('Message received:', data);
});

// One-time listener
emitter.once('ready', () => {
  console.log('System ready - this runs only once');
});

// Method chaining
emitter
  .on('start', () => console.log('Starting...'))
  .on('progress', (percent) => console.log(`Progress: ${percent}%`))
  .on('complete', () => console.log('Complete!'));

Event Removal

Remove event handlers with flexible options.

/**
 * Remove a specific event handler for a specified event
 * @param {string} event - The name of the event
 * @param {function} listener - The specific handler function to remove
 * @returns {Emitter} The Emitter instance for method chaining
 */
off(event: string, listener: (...args: any[]) => void): Emitter;

/**
 * Remove all event handlers for a specified event
 * @param {string} event - The name of the event for which to remove all handlers
 * @returns {Emitter} The Emitter instance for method chaining
 */
off(event: string): Emitter;

/**
 * Remove all event handlers for all events
 * @returns {Emitter} The Emitter instance for method chaining
 */
off(): Emitter;

Usage Examples:

const emitter = new Emitter();

function handler(data) {
  console.log('Handler:', data);
}

emitter.on('test', handler);

// Remove specific handler
emitter.off('test', handler);

// Remove all handlers for an event
emitter.off('test');

// Remove all handlers for all events
emitter.off();

Event Emission

Emit events to invoke registered handlers.

/**
 * Emit an event, invoking all handlers registered for it
 * @param {string} event - The name of the event to emit
 * @param {...any} args - Arguments to pass to the event handlers
 * @returns {Emitter} The Emitter instance for method chaining
 */
emit(event: string, ...args: any[]): Emitter;

Usage Examples:

const emitter = new Emitter();

emitter.on('data', (message, timestamp) => {
  console.log(`[${timestamp}] ${message}`);
});

// Emit with multiple arguments
emitter.emit('data', 'Hello World', new Date().toISOString());

// Emit without arguments
emitter.emit('ready');

Event Introspection

Query and inspect registered event handlers.

/**
 * Retrieve the event handlers registered for a specific event
 * @param {string} event - The name of the event
 * @returns {Array<function>} An array of functions registered as handlers for the event
 */
listeners(event: string): Array<(...args: any[]) => void>;

/**
 * Get the count of listeners for a specific event
 * @param {string} event - The name of the event
 * @returns {number} The number of listeners for the event
 */
listenerCount(event: string): number;

/**
 * Get the count of all listeners across all events
 * @returns {number} The total number of listeners
 */
listenerCount(): number;

/**
 * Check if there are any handlers registered for a specific event
 * @param {string} event - The name of the event
 * @returns {boolean} true if there are one or more handlers, false otherwise
 */
hasListeners(event: string): boolean;

/**
 * Check if there are any handlers registered for any event
 * @returns {boolean} true if there are one or more handlers for any event, false otherwise
 */
hasListeners(): boolean;

Usage Examples:

const emitter = new Emitter();

emitter.on('test', () => {});
emitter.on('test', () => {});
emitter.on('other', () => {});

// Get listeners array
console.log(emitter.listeners('test')); // Array of 2 functions

// Count listeners
console.log(emitter.listenerCount('test')); // 2
console.log(emitter.listenerCount()); // 3 (total across all events)

// Check if listeners exist
console.log(emitter.hasListeners('test')); // true
console.log(emitter.hasListeners('nonexistent')); // false
console.log(emitter.hasListeners()); // true (any event has listeners)

Method Aliases

Alternative method names for compatibility and convenience.

/**
 * Alias for on() method
 */
addEventListener(event: string, listener: (...args: any[]) => void): Emitter;

/**
 * Alias for off() method
 */
removeListener(event: string, listener: (...args: any[]) => void): Emitter;

/**
 * Alias for off() method
 */
removeEventListener(event: string, listener: (...args: any[]) => void): Emitter;

/**
 * Alias for off() method - removes specific listener, all listeners for event, or all listeners
 */
removeAllListeners(event: string, listener: (...args: any[]) => void): Emitter;
removeAllListeners(event: string): Emitter;
removeAllListeners(): Emitter;

Types

interface Emitter {
  on(event: string, listener: (...args: any[]) => void): Emitter;
  once(event: string, listener: (...args: any[]) => void): Emitter;
  off(event: string, listener: (...args: any[]) => void): Emitter;
  off(event: string): Emitter;
  off(): Emitter;
  emit(event: string, ...args: any[]): Emitter;
  listeners(event: string): Array<(...args: any[]) => void>;
  listenerCount(event: string): number;
  listenerCount(): number;
  hasListeners(event: string): boolean;
  hasListeners(): boolean;
  
  // Aliases
  addEventListener(event: string, listener: (...args: any[]) => void): Emitter;
  removeListener(event: string, listener: (...args: any[]) => void): Emitter;
  removeEventListener(event: string, listener: (...args: any[]) => void): Emitter;
  removeAllListeners(event: string, listener: (...args: any[]) => void): Emitter;
  removeAllListeners(event: string): Emitter;
  removeAllListeners(): Emitter;
}

interface EmitterConstructor {
  new (object?: object): Emitter;
  <T extends object>(object: T): T & Emitter;
  prototype: Emitter;
}