@ad-execute-manager/event

A collection of event-related utilities for JavaScript applications including EventEmitter and PubSub implementations.

Installation

npm install @ad-execute-manager/event

Features

• EventEmitter: A powerful event emitter with support for once events, max listeners, and event queuing
• PubSub: A simple publish-subscribe pattern implementation with automatic unsubscribe function
• Event Queuing: Automatically queue events when no listeners are present
• Listener Limits: Set maximum listeners per event to prevent memory leaks
• Once Events: Support for events that only fire once
• Error Handling: Built-in error handling for event listeners
• TypeScript Support: Includes TypeScript type definitions
• Singleton Support: EventEmitter includes static getInstance method for singleton pattern

Usage

EventEmitter

import { EventEmitter } from '@ad-execute-manager/event';

// Create an event emitter instance
const emitter = new EventEmitter({
  maxListeners: 10,
  maxQueueSize: 5,
  maxOnceEvents: 5
});

// Register event listener
emitter.on('userLoggedIn', (userData) => {
  console.log('User logged in:', userData);
});

// Register once event listener
emitter.once('appStarted', (appData) => {
  console.log('App started:', appData);
  // This listener will be automatically removed after first execution
});

// Emit events
emitter.emit('userLoggedIn', { id: 1, name: 'John' });
emitter.emit('appStarted', { version: '1.0.0' });

// Remove event listener
function onDataReceived(data) {
  console.log('Data received:', data);
}

emitter.on('dataReceived', onDataReceived);
emitter.off('dataReceived', onDataReceived);

// Remove all listeners for an event
emitter.removeAllListeners('userLoggedIn');

// Remove all listeners
// emitter.removeAllListeners();

// Using singleton pattern
const singletonEmitter = EventEmitter.getInstance({
  maxListeners: 15
});

PubSub

import { PubSub } from '@ad-execute-manager/event';

// Create a PubSub instance
const pubsub = new PubSub();

// Subscribe to an event
const unsubscribe = pubsub.on('message', (data) => {
  console.log('Message received:', data);
});

// Publish an event
pubsub.emit('message', { text: 'Hello, world!' });

// Unsubscribe using the returned function
unsubscribe();

// Subscribe to an event only once
pubsub.once('notification', (notification) => {
  console.log('Notification:', notification);
  // This listener will be automatically removed after first execution
});

// Publish the notification event
pubsub.emit('notification', { title: 'New Message', body: 'You have a new message' });

// Check listener count
const listenerCount = pubsub.listenerCount('message');
console.log('Message listeners:', listenerCount);

// Remove all listeners
// pubsub.removeAllListeners();

API

EventEmitter

Constructor

new EventEmitter(options)

• options (Object): Configuration options
  • maxListeners (Number): Maximum listeners per event, default 5
  • maxQueueSize (Number): Maximum queue size for events with no listeners, default 1
  • maxOnceEvents (Number): Maximum once events per event, default 5

Methods

• on(event, listener): Register an event listener

  • event (String): Event name
  • listener (Function): Event listener function

• once(event, listener): Register a one-time event listener

  • event (String): Event name
  • listener (Function): Event listener function

• emit(event, ...args): Emit an event

  • event (String): Event name
  • ...args (Any): Arguments to pass to listeners

• off(event, listenerToRemove): Remove an event listener

  • event (String): Event name
  • listenerToRemove (Function): Listener function to remove

• removeAllListeners(event): Remove all listeners for an event

  • event (String, optional): Event name, omit to remove all listeners

• static getInstance(args): Get singleton instance

  • args (Object): Constructor options
  • returns (EventEmitter): Singleton instance

PubSub

Constructor

new PubSub()

Methods

• on(eventName, callback): Subscribe to an event

  • eventName (String): Event name
  • callback (Function): Event callback function
  • returns (Function): Unsubscribe function

• off(eventName, callback): Unsubscribe from an event

  • eventName (String): Event name
  • callback (Function): Callback function to remove

• emit(eventName, ...args): Publish an event

  • eventName (String): Event name
  • ...args (Any): Arguments to pass to callbacks

• once(eventName, callback): Subscribe to an event once

  • eventName (String): Event name
  • callback (Function): Event callback function

• listenerCount(eventName): Get listener count for an event

  • eventName (String): Event name
  • returns (Number): Listener count

• removeAllListeners(): Remove all listeners

Examples

Example 1: Application Event Bus

import { EventEmitter } from '@ad-execute-manager/event';

// Create global event bus
const eventBus = EventEmitter.getInstance({
  maxListeners: 20
});

// User service
function loginUser(userData) {
  // Login logic
  console.log('Logging in user:', userData.username);
  
  // Emit login event
  eventBus.emit('userLoggedIn', {
    user: userData,
    timestamp: new Date().toISOString()
  });
}

// Notification service
function setupNotifications() {
  eventBus.on('userLoggedIn', (loginData) => {
    console.log('Sending welcome notification to:', loginData.user.username);
    // Send welcome notification
  });
  
  eventBus.on('userLoggedOut', (logoutData) => {
    console.log('Updating user status to offline:', logoutData.userId);
    // Update user status
  });
}

// Analytics service
function setupAnalytics() {
  eventBus.once('appStarted', (appData) => {
    console.log('Recording app start event:', appData.version);
    // Record app start analytics
  });
  
  eventBus.on('userLoggedIn', (loginData) => {
    console.log('Recording login event:', loginData.user.username);
    // Record login analytics
  });
}

// Setup services
setupNotifications();
setupAnalytics();

// Start app
eventBus.emit('appStarted', { version: '1.0.0' });

// Login user
loginUser({ id: 1, username: 'john_doe', email: '[email protected]' });

Example 2: Component Communication

import { PubSub } from '@ad-execute-manager/event';

// Create pubsub instance for component communication
const componentBus = new PubSub();

// Header component
function Header() {
  // Subscribe to user changes
  const unsubscribe = componentBus.on('userChanged', (user) => {
    console.log('Header: Updating user display:', user.name);
    // Update header with user info
  });
  
  // Subscribe to theme changes
  componentBus.on('themeChanged', (theme) => {
    console.log('Header: Updating theme:', theme);
    // Update header theme
  });
  
  // Cleanup function
  return () => {
    unsubscribe();
    console.log('Header: Unsubscribed from events');
  };
}

// User profile component
function UserProfile() {
  // Subscribe to user changes
  const unsubscribe = componentBus.on('userChanged', (user) => {
    console.log('UserProfile: Updating user profile:', user.name);
    // Update user profile
  });
  
  // Cleanup function
  return () => {
    unsubscribe();
    console.log('UserProfile: Unsubscribed from events');
  };
}

// Settings component
function Settings() {
  // Update user
  function updateUser(userData) {
    console.log('Settings: Updating user');
    componentBus.emit('userChanged', userData);
  }
  
  // Change theme
  function changeTheme(theme) {
    console.log('Settings: Changing theme to:', theme);
    componentBus.emit('themeChanged', theme);
  }
  
  return {
    updateUser,
    changeTheme
  };
}

// Initialize components
const cleanupHeader = Header();
const cleanupUserProfile = UserProfile();
const settings = Settings();

// Simulate user update
settings.updateUser({ id: 1, name: 'John Doe', email: '[email protected]' });

// Simulate theme change
settings.changeTheme('dark');

// Cleanup components
// cleanupHeader();
// cleanupUserProfile();

Example 3: Event Queueing

import { EventEmitter } from '@ad-execute-manager/event';

// Create event emitter with queueing
const emitter = new EventEmitter({
  maxQueueSize: 10
});

// Emit events before listeners are registered
console.log('Emitting events before listeners...');
emitter.emit('data', { value: 1 });
emitter.emit('data', { value: 2 });
emitter.emit('data', { value: 3 });

// Register listener - will receive queued events
console.log('Registering listener...');
emitter.on('data', (data) => {
  console.log('Received data:', data);
});

// Emit more events
console.log('Emitting more events...');
emitter.emit('data', { value: 4 });
emitter.emit('data', { value: 5 });

License

MIT