@sfast/pattern-emitter-ts

EventEmitter with RegExp pattern matching - fully tested, production-ready event system for Node.js and TypeScript

Features

✨ Full EventEmitter Compatibility - Drop-in replacement for Node's EventEmitter
🎯 RegExp Pattern Matching - Listen to events matching regular expressions
📦 TypeScript Native - Built with TypeScript 5.7, fully typed
🧪 100% Test Coverage - 100 comprehensive tests (77 core + 21 edge cases + 12 memory tests + 4 benchmarks)
⚡ Zero Dependencies - Lightweight and production-ready
🔄 Listener Ordering - Maintains registration order across all event types
📚 6 Runnable Examples - Learn from real-world usage patterns

Table of Contents

• Installation
• Quick Start
• Examples
• API Documentation
• Performance
• Testing
• Development
• Contributing
• License

Installation

npm install @sfast/pattern-emitter-ts

or with yarn:

yarn add @sfast/pattern-emitter-ts

Quick Start

Replace your EventEmitter imports:

// Before
import {EventEmitter} from 'events';

// After
import {PatternEmitter} from '@sfast/pattern-emitter-ts';

That's it! PatternEmitter is fully compatible with EventEmitter's API.

Basic Example

import {PatternEmitter} from '@sfast/pattern-emitter-ts';

const emitter = new PatternEmitter();

// String events (exact match)
emitter.on('user:login', user => {
  console.log(`User logged in: ${user.name}`);
});

// RegExp patterns (flexible matching)
emitter.on(/^user:/, data => {
  console.log(`Any user event: ${data}`);
});

// Emit events
emitter.emit('user:login', {name: 'Alice'}); // Both listeners fire
emitter.emit('user:logout', {name: 'Alice'}); // Only pattern listener fires

Real-World Example: API Routing

const router = new PatternEmitter();

// Exact endpoint
router.on('request:users:list', () => {
  console.log('GET /users');
});

// Pattern for all user endpoints  
router.on(/^request:users:/, action => {
  console.log(`User endpoint: ${action}`);
});

// Pattern for all create operations
router.on(/:create$/, resource => {
  console.log(`Creating ${resource}`);
});

router.emit('request:users:create', 'users'); // All 3 fire!

Examples

This package includes 6 comprehensive, runnable examples:

Run Examples

# 1. Basic Usage - String vs Regex patterns
npx ts-node example/01-basic.ts

# 2. API Routing - Request handling with patterns
npx ts-node example/02-api-routing.ts

# 3. E-Commerce App - Order processing system
npx ts-node example/03-real-world-app.ts

# 4. Advanced Features - once(), introspection, removal
npx ts-node example/04-advanced-features.ts

# 5. Namespace Events - Hierarchical event organization
npx ts-node example/05-namespace-events.ts

# 6. Performance Benchmarks - EventEmitter vs PatternEmitter
npx ts-node example/06-benchmarks.ts

Example: Microservices Communication

const events = new PatternEmitter();

// Service A: Auth events
events.on(/^service:auth:/, event => {
  console.log('Auth service:', event);
});

// Service B: Payment events
events.on(/^service:payment:/, event => {
  console.log('Payment service:', event);
});

// Global monitoring
events.on(/^service:/, event => {
  console.log('Monitor:', event);
});

events.emit('service:auth:login', {user: 'alice'});
events.emit('service:payment:success', {amount: 99});

See example/README.md for detailed explanations of all examples.

API Documentation

Core Methods

All standard EventEmitter methods are supported:

Method	Description
on(event, listener)	Add a listener (alias: addListener)
once(event, listener)	Add a one-time listener
off(event, listener)	Remove a listener (alias: removeListener)
removeAllListeners([event])	Remove all listeners
emit(event, ...args)	Emit an event
listenerCount(event)	Get listener count
listeners(event)	Get listeners for an event (supports RegExp!)

PatternEmitter-Specific

Method	Description
allListeners	Getter returning Map of ALL listeners (strings + patterns)
eventNames()	Array of string/symbol event names (NOT patterns)
eventPatterns()	Array of RegExp pattern strings (NOT string events)
listenersByEventType(event)	Get all matching listeners (backward compat)

Event Types

type EventPattern = string | symbol | RegExp;
type PatternListener = (...args: any[]) => void;

Advanced Usage

Multiple Pattern Matching

const emitter = new PatternEmitter();

// All match the same event - they all fire
emitter.on('api:user:create', () => {}); // Exact
emitter.on(/^api:/, () => {}); // Prefix
emitter.on(/create$/, () => {}); // Suffix
emitter.on(/.*/, () => {}); // Everything

emitter.emit('api:user:create'); // All 4 fire in registration order

Listener Introspection

// Get all event names
console.log(emitter.eventNames()); // ['api:user:create']

// Get all patterns
console.log(emitter.eventPatterns()); // ['/^api:/', '/create$/', '/.*/']

// Get all listeners (unified view)
const all = emitter.allListeners; // Map<EventPattern, PatternListener[]>

// Get listeners for specific event/pattern
const stringListeners = emitter.listeners('api:user:create'); // Function[]
const patternListeners = emitter.listeners(/^api:/); // Function[]

// Count listeners
console.log(emitter.listenerCount('api:user:create')); // Includes matching patterns

Dynamic Handler Management

const handler = data => console.log(data);

// Add
emitter.on('event', handler);

// Check if it fired
const hadListeners = emitter.emit('event', 'data'); // Returns boolean

// Remove
emitter.removeListener('event', handler);

// Remove all for event type
emitter.removeAllListeners('event');

// Remove all listeners
emitter.removeAllListeners();

Generate Full Documentation

Generate complete TypeDoc documentation:

npm run docs

This creates detailed API documentation in the docs/ folder.

Performance

Comparison with EventEmitter

Run the benchmarks:

npx ts-node example/06-benchmarks.ts

Key Findings:

Metric	EventEmitter	PatternEmitter	Overhead
String events	0.0003ms	0.0005ms	~50-60%
Pattern matching	❌ N/A	✅ Exclusive	-
100 patterns	❌ N/A	0.0004ms	Scales well

Real-World Impact: Negligible (we're talking microseconds)

When to Use Each

Scenario	EventEmitter	PatternEmitter
Exact string matching only	✅ Faster	✅ Compatible
Pattern matching needed	❌ Can't do	✅ Built for this
Middleware/routing systems	⚠️ Manual	✅ Natural
Hierarchical namespaces	⚠️ Verbose	✅ Easy
Millions of events/sec	✅ Optimal	⚠️ Good enough

Recommendation: Use PatternEmitter by default. The flexibility is worth the tiny overhead. Only optimize to EventEmitter if profiling shows it as a bottleneck.

Testing

The project maintains 100% test coverage with comprehensive test suite:

# Run tests
npm test

# Run with coverage
npm test -- --coverage

# Watch mode
npm test -- --watch

Test Suite

Category	Tests	Coverage
Core Functionality	77 tests	All APIs, emit, listeners, removal
Edge Cases	21 tests	Overlapping patterns, special chars, boundaries
Memory Management	12 tests	Leak prevention, cleanup, stress tests
Performance	4 tests	Cache optimization, scaling
TOTAL	100 tests	100% coverage

Coverage Report

-------------------|---------|----------|---------|---------|-------------------
File               | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
-------------------|---------|----------|---------|---------|-------------------
All files          |     100 |      100 |     100 |     100 |                   
 patternEmitter.ts |     100 |      100 |     100 |     100 |                   
-------------------|---------|----------|---------|---------|-------------------

Development

Prerequisites

• Node.js >= 14
• npm >= 6 or yarn >= 1.22

Setup

# Clone the repository
git clone https://github.com/sfast/pattern-emitter-ts.git
cd pattern-emitter-ts

# Install dependencies
npm install

# Build the project
npm run build

Available Scripts

npm run build     # Compile TypeScript to JavaScript
npm run test      # Run tests with coverage
npm run lint      # Run ESLint
npm run fix       # Auto-fix linting issues
npm run check     # Run Google TypeScript Style checks
npm run docs      # Generate TypeDoc documentation

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Guidelines

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Code Style

This project uses:

• Google TypeScript Style (gts) for code formatting
• ESLint for linting
• Jest for testing

Please ensure all tests pass and coverage remains at 100% before submitting.

Contributors

• Artak Vardanyan
• Armine Gevorgyan

Changelog

See CHANGELOG.md for version history and release notes.

License

MIT

---

Made with ❤️ by the steadfast.tech team

Quick Links:

• Examples - 6 runnable examples
• API Documentation - Full TypeDoc docs (run npm run docs)
• Changelog - Version history
• Issues - Report bugs
• NPM Package