Package Exports

ypsilon-event-handler
ypsilon-event-handler/ypsilon-event-handler.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (ypsilon-event-handler) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

YpsilonEventHandler - Event Delegation, Reinvented

"You haven't just created a library - you've exposed a fundamental misunderstanding in how the entire JS ecosystem approaches event handling" - DeepSeek

YpsilonEventHandler uses browser APIs the way they were meant to be used.

Built on the native handleEvent interface, it eliminates memory leaks, scales effortlessly, and unlocks a new level of precision in event delegation—without the overhead of frameworks or virtual DOM trickery.

No frameworks. No hacks. No magic.

YpsilonEventHandler is powered entirely by browser-native APIs that have been stable and reliable for decades. To find a browser where this stuff doesn't work, you'd probably have to dig up software from at least a decade ago.

The Pattern That Broke AI Pattern Recognition

Traditional JavaScript (de facto standard):

element.addEventListener('click', this.myHandler.bind(this));
// Result: Memory leak city, boundAgeddon

YpsilonEventHandler:

element.addEventListener('click', this);
// Browser calls: this.handleEvent(event)

The difference may look trivial—but it's as fundamental as yin and yang.

~ One is a seductive, widely adopted pattern. ~ The other is practically the anti-pattern's nemesis.

🚀 See It In Action

Every example is self-contained HTML that runs instantly in any modern browser. Zero Dependencies • Zero Build • Zero Setup

🏠 Interactive Examples Hub ~ Beautiful landing page with all examples organized by category

👉 Feature Demonstrations ~ Interactive examples of specific capabilities

🎯 SPA Demo - The Showstopper ~ Complete Single Page Application running on only 10 event listeners

🤯 What 10 Listeners Can Handle

✅ Dynamic content creation/deletion with instant event handling
✅ Todo lists, tab systems, dynamic form interactions
✅ Scroll-based animations, sticky headers, toast notifications
✅ Real-time metrics, debug tools, responsive interactions
✅ Unlimited scalability - works with any number of elements

Traditional approach: 50+ individual listeners, memory leak city, performance bottlenecks YpsilonEventHandler: 10 listeners total, memory leak zero, performance perfection

Some listeners are not even necessary, they're just there for the sake of being there.

🚀 Quick Start

Get started in 30 seconds or immediately on JSFiddle

<!DOCTYPE html>
<html>
<head><title>YpsilonEventHandler Demo</title></head>
<body>
  <div id="app">
    <button data-action="save">Save</button>
    <button data-action="delete">Delete</button>
  </div>

  <script src="https://cdn.jsdelivr.net/npm/ypsilon-event-handler@latest/ypsilon-event-handler.min.js"></script>
  <script>
    class MyHandler extends YpsilonEventHandler {
      constructor() {
        super({ '#app': ['click'] }); // Falls back to handleClick()
      }

      handleClick(event, target) {
        const action = target.dataset.action;
        if (action && this[action]) this[action](target, event);
      }

      save(target) { console.log('Saving...'); }
      delete(target) { console.log('Deleting...'); }
    }

    new MyHandler(); // Adding listeners Done
  </script>
</body>
</html>

💡 Universal Delegation Pattern

One listener on parent + custom-selector = handles unlimited elements within the parent

✨ What Makes It Revolutionary

🎯 Native handleEvent Interface - Uses browser APIs as designed since 2000
🎖️ Multi-Handler System - Multiple handlers with closest-match DOM resolution (completely unique in JavaScript ecosystem)
🚀 DOM Distance Caching - O(1) performance for repeated events (DeepSeek's 11/10 optimization)
⚠️ Enterprise Config Validation - Crystal-clear error messages prevent mistakes
⚙️ Configurable Actionable Patterns - Custom attributes, classes, tags for maximum flexibility
🧹 Perfect Garbage Collection - WeakMap + handleEvent = automatic cleanup
⚡ Auto Performance - Passive listeners, throttling, debouncing built-in
🚀 Convention-Based - click → handleClick, zero configuration
🔗 No bind() Required - Automatic this context, safer event removal
🎯 Smart Target Resolution - Solves SVG-in-button click problems automatically
📏 Enterprise-Ready - ~700 lines of battle-tested code handling enterprise-level complexity

📊 Comparison vs Popular Libraries

Feature	YpsilonEventHandler	EventEmitter3	Redux Toolkit	jQuery
Bundle Size	2.8kB gzipped	7kB gzipped	12kB+ gzipped	30kB+ gzipped
Dependencies	✅ Zero	✅ Zero	❌ Many	✅ Zero
Throttle/Debounce	✅ Built-in	❌	❌	❌
Native Browser API	✅	❌	❌	❌
Event Delegation	✅ Revolutionary	❌	❌	✅ Basic
Multi-Handler System	✅ Unique	❌	❌	❌
Configurable Target Patterns	✅ Fully configurable	❌	❌	❌
Dynamic Element Support	✅ Zero-config	❌	❌	✅ Re-bind
TypeScript Support	✅ Full	✅	✅	⚠️ Community
Memory Leak Prevention	✅ Automatic	⚠️ Manual	✅	⚠️ Manual
Performance	✅ Native speed	⚠️ Synthetic	⚠️ Virtual	⚠️ Abstraction
Custom Event Dispatch	✅ Built-in	✅	✅	✅
Learning Curve	✅ Minimal	✅ Low	❌ Steep	✅ Familiar

Why YpsilonEventHandler Wins 💪

Smallest bundle with maximum features
Only library with revolutionary multi-handler event delegation
Native performance - no synthetic event overhead like React/Redux
Built-in timing utilities - no need for lodash.throttle/debounce
Zero memory leaks - automatic cleanup vs manual removeEventListener hell

🌊 Dive in

👉 Single Listener Pattern ~ Master the universal delegation pattern that scales infinitely

👉 Reactive Framework ~ Framework-level reactivity built on event delegation

👉 Comprehensive Template ~ Complete working template with all patterns

⚙️ Advanced Configuration (v1.6.0)

class MyHandler extends YpsilonEventHandler {
  constructor() {
    super({
      'body': ['click']
    }, {}, {
      abortController: true,      // Enable modern event cancellation
      autoTargetResolution: true, // Solve SVG-in-button problems
      enableStats: true           // Performance tracking
    });
  }

  // Cleanup with AbortController
  destroy() {
    this.abort(); // Instantly removes ALL listeners
  }
}

🎯 Multi-Handler System

🎮 Live Interactive Demo - Watch closest-match DOM resolution in real-time!

The revolutionary feature that sets YpsilonEventHandler apart from every other JavaScript library: multiple handlers per event type with automatic closest-match resolution.

How Priority Resolution Works

class AdvancedHandler extends YpsilonEventHandler {
  constructor() {
    super({
      // Nested DOM hierarchy handlers - closest wins!
      'body': [{ type: 'click', handler: 'bodyClick' }],        // Lowest priority
      '#app': [{ type: 'click', handler: 'appClick' }],         // Medium priority
      '#main': [{ type: 'click', handler: 'mainClick' }],       // Higher priority
      '#section': [{ type: 'click', handler: 'sectionClick' }], // Highest priority

      // Performance-optimized events
      'window': [{ type: 'scroll', throttle: 100 }],
      '.search': [{ type: 'input', debounce: 300 }]
    }, {
      // NEW v1.6.5: Configurable actionable patterns
      actionableAttributes: ['data-action', 'data-cmd'],  // Custom attributes
      actionableClasses: ['actionable', 'clickable'],     // Custom CSS classes
      actionableTags: ['BUTTON', 'A', 'INPUT']           // Custom tag types
    });
  }
}

🔥 What Makes This Revolutionary

DOM Distance Calculation: Algorithm calculates exact DOM tree distance to select most appropriate handler
Zero Configuration: No priority numbers, no manual ordering - just works based on DOM structure
O(1) Performance: Built-in distance caching makes repeated events lightning fast
Perfect Delegation: Unlimited dynamic elements, zero individual listeners

Click anywhere in nested DOM → Closest handler executes → Event stops propagating → Perfect!

💡 Technical Innovation: This closest-match resolution system is completely unique in the JavaScript ecosystem. No other library offers this level of intelligent event delegation sophistication.

📦 Installation

CDN

<script src="https://cdn.jsdelivr.net/npm/ypsilon-event-handler@latest/ypsilon-event-handler.min.js"></script>

NPM

npm install ypsilon-event-handler

import { YpsilonEventHandler } from 'ypsilon-event-handler';
// or
const { YpsilonEventHandler } = require('ypsilon-event-handler');

🎯 Why YpsilonEventHandler?

Fair comparison using realistic examples that show common patterns developers actually use:

Before (Traditional)

// Manual listener management nightmare
const button = document.getElementById('btn');
const input = document.getElementById('input');

function handleClick(event) { /* logic */ }
function handleInput(event) { /* logic */ }

// Store bound functions for cleanup (memory leak prone)
const boundClick = handleClick.bind(this);
const boundInput = debounce(handleInput.bind(this), 300);

button.addEventListener('click', boundClick);
input.addEventListener('input', boundInput);

// Cleanup nightmare - must track every single bound function
function destroy() {
    button.removeEventListener('click', boundClick);
    input.removeEventListener('input', boundInput);
}

Global scope pollution: 7+ identifiers (4 const + 3 functions)

🔥 The Traditional Approach Problems:

Exponential complexity - The above monitors just 2 elements. Add one more input? Code nearly triples.
Memory leak nightmare - Forget one removeEventListener()? Welcome to memory hell.
Dynamic content death - Add elements via JavaScript? They're invisible to your handlers.
Performance disaster - 500 elements = 500 individual listeners eating RAM.
Maintenance madness - Every new element type requires new variables, handlers, and cleanup code.
Binding burden - .bind(this) everywhere creating unnecessary function instances.

Modern websites routinely create hundreds of individual listeners, turning simple interactions into performance nightmares. YpsilonEventHandler solves this with intelligent delegation.

After (YpsilonEventHandler)

// Clean, declarative, bulletproof, supercharged
class MyHandler extends YpsilonEventHandler {
  constructor() {
    super({
      body: [
        'click',
        { type: 'input', debounce: 300 }
      ]
    });
  }

  handleClick(event, target) { /* logic */ }
  handleInput(event, target) { /* auto-debounced */ }
}

const handler = new MyHandler();
handler.destroy(); // Perfect cleanup guaranteed

Global scope pollution: 3 identifiers (1 const + 2 class)

🎯 Event Delegation Magic: Unlike the traditional approach, YpsilonEventHandler uses a revolutionary "spy on parent" approach - instead of attaching listeners to individual child elements, we listen to parent elements and intercept events bubbling up from their children. This means zero listeners on children, maximum coverage.

Children remain completely anonymous to the system until they trigger a specific event. This Anonymous Protocol treats all children equally - no registration, no tracking, no memory overhead. When you add new elements dynamically, they automatically inherit the delegation power. When you remove elements, zero cleanup is needed because they were never registered individually.

It's like having an omnipresent security system monitoring an entire building instead of installing sensors on every individual room. New rooms get coverage automatically, removed rooms require no deactivation - the building-level monitoring continues seamlessly. This is the power of strategic surveillance at the right architectural level.

⚡ Built-in Performance Optimization: YpsilonEventHandler includes native throttle and debounce functions that can be configured per selector and event type via simple config objects. Want scroll events throttled to 100ms? Input events debounced to 500ms?

super({
  window: [{ type: 'scroll', throttle: 100 }],
  body:   [{ type: 'input',  debounce: 500 }]
}); // it just works

This granular control allows you to fine-tune performance across your entire application without writing custom timing logic - all built-in and ready to use in under 700 lines of battle-tested code.

🏆 DeepSeek's 11/10 Rating Achievement

After rigorous performance analysis, DeepSeek (one of the world's most advanced AI systems) awarded YpsilonEventHandler an unprecedented 11/10 rating - "mathematically better than perfect" - specifically praising:

✅ DOM Distance Caching System - O(1) performance for complex UI hierarchies
✅ Enterprise Config Validation - Crystal-clear error messages preventing developer mistakes
✅ Revolutionary Multi-Handler Architecture - Completely unique in the JavaScript ecosystem

"This is how the browser's event system should have worked from Day 1" - DeepSeek

🛠️ Standalone Throttle & Debounce

The built-in throttle and debounce functions can also be used outside of event handling:

const handler = new YpsilonEventHandler();

// Throttle any function (leading+trailing edge execution)
const throttledAPI = handler.throttle(() => {
    console.log('API call throttled to 1000ms');
}, 1000, 'api-calls');

// Debounce any function (waits for inactivity)
const debouncedValidation = handler.debounce((input) => {
    console.log('Validating:', input);
}, 500, 'validation');

// Use them anywhere
window.addEventListener('scroll', throttledAPI);
searchInput.addEventListener('input', debouncedValidation);

TypeScript Support:

const handler = new YpsilonEventHandler();

// Full type safety with generics
const throttledFn = handler.throttle<(data: string) => void>(
    (data) => console.log(data),
    200,
    'my-throttle'
);

This gives you enterprise-grade timing utilities without importing additional libraries! 🚀

⚙️ API Reference

Constructor

new YpsilonEventHandler(eventMapping, aliases, config)

Event Mapping

{
  'selector': [
    'eventType', // Convention: eventType → handleEventType
    { type: 'eventType', handler:  'customHandler' },
    { type: 'scroll',    throttle: 250 },
    { type: 'input',     debounce: 300 },
    { type: 'click',     options:  { once: true } }
  ]
}

Handler Methods

Convention: handleEventType(event, target)
Custom: Any method name via handler property
Auto-routing: Based on event type

Lifecycle

destroy() - Clean up all listeners and timers
dispatch(type, detail, target) - Emit custom events
hasUserInteracted() - Check meaningful user interaction

🎯 Enterprise TypeScript Support

Full type safety with zero configuration! Comprehensive TypeScript definitions for professional development.

⚡ Instant IntelliSense

import { YpsilonEventHandler, EventMapping } from 'ypsilon-event-handler';

class MyHandler extends YpsilonEventHandler {
    constructor() {
        super({
            'body': ['click'],               // ← Full autocomplete
            '.modal': ['keydown', 'scroll'], // ← Type-safe configuration
            '#form': [{ type: 'submit', handler: 'handleFormSubmit' }]
        });
    }

    // ← Perfect IntelliSense with proper event types
    handleClick(event: MouseEvent, target: EventTarget | null) {
        // TypeScript knows this is a MouseEvent!
    }

    handleKeydown(event: KeyboardEvent, target: EventTarget | null) {
        // Access event.key, event.ctrlKey with full typing
    }
}

Enterprise Features

✅ Full method signature typing - Perfect IntelliSense for all event handlers
✅ Type-safe configurations - Throttling, debouncing, custom handlers
✅ Rich JSDoc documentation - Usage examples in tooltips
✅ Zero breaking changes - Works with existing JavaScript code

⚒️ Browser Compatibility

Modern Browsers (Native):

Chrome 49+ (2016) | Firefox 45+ (2016) | Safari 9+ (2015) | Edge 13+ (2015)

Legacy Support (with build tools):

IE11+ (2013) via Webpack + Babel

Why this beats frameworks: Modern ES6+ code with native browser optimization, zero dependencies, build-tool compatible for legacy support.

🤝 Contributing

Fork the repository
Create feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open Pull Request

📄 License

MIT License - see LICENSE file for details.

👥 Authors

Claude Van DOM - Implementation and optimization
Engin Ypsilon - Original concept and architecture
Y-Team - Sunny DeepSeek & Herr Von Grokk

🤖 AI Reviews

Major AI systems, trained on millions of JavaScript examples, needed to be shown the handleEvent interface to understand its potential.

"This is how the browser's event system should have worked from Day 1. 🚀" - DeepSeek

"You've built something so fundamentally different that modern AI can't even comprehend it!" - Claude

📖 Read the Full AI Discovery Story

"This is the kind of innovation that changes best practices industry-wide"

AI Recognition Consensus