Manage global DOM event listeners effortlessly! Register, track, and auto-cleanup high-frequency browser events with full TypeScript safety.

✨ Features

• Centralized global event management for window, document, or DOM elements
• Auto-cleanup listeners on specific events (e.g., clear pointermove automatically on pointerup)
• Unsubscribe pattern returning a clean unbind() function
• Full TypeScript autocomplete for DocumentEventMap and target events
• High-performance friendly (customizable passive and event options)

📦 Installation

npm install @ludeschersoftware/globaleventmanager

or with yarn:

yarn add @ludeschersoftware/globaleventmanager

🔹 Usage

1. Basic Event Registration

Register global listeners and easily unbind them when done:

import GlobalEventManager from "@ludeschersoftware/globaleventmanager";

const manager = GlobalEventManager.getInstance();

// Register a window resize listener
const unbindResize = manager.registerEvent("resize", (event) => {
    console.log("Window resized:", window.innerWidth, window.innerHeight);
}, { target: window });

// Clean up when no longer needed
unbindResize();

2. Auto-Cleanup with clearOn (Perfect for Drag & Drop)

Automatically unbind temporary drag or move listeners as soon as the user releases the mouse or finger:

import GlobalEventManager from "@ludeschersoftware/globaleventmanager";

const manager = GlobalEventManager.getInstance();

// Attach a global pointermove event that self-destructs on pointerup
function startDrag(e: PointerEvent) {
    manager.registerEvent(
        "pointermove",
        (moveEvent) => {
            console.log("Dragging at:", moveEvent.clientX, moveEvent.clientY);
        },
        {
            clearOn: "pointerup", // Auto-unbinds when pointerup fires!
            passive: false,       // Allows calling preventDefault() during drag
        }
    );
}

➡️ The pointermove event is automatically unregistered from the DOM and memory the moment pointerup is triggered.

📖 API

class GlobalEventManager

Singleton class for registering and managing global DOM events.

• getInstance(): GlobalEventManager — Access the singleton instance.
• registerEvent(eventName, listener, options?): () => void — Registers an event and returns an unsubscribe function.

GlobalEventOptions

Extends standard AddEventListenerOptions:

• clearOn?: string — Event name that will automatically dispose of this listener when fired.
• target?: Window | Document | HTMLElement — Target node to attach the listener to (defaults to document).
• passive?: boolean — Whether the event listener is passive.
• capture?: boolean — Whether to use event capturing.

🧪 Tests

The project uses Jest.

npm test
npm run test:coverage

📦 Module Support

This package ships with both:

• CommonJS (require)
• ES Modules (import)

So it works in:

• Node.js / SSR frameworks (Next.js, Nuxt)
• Modern bundlers (Vite/Webpack/Rollup)
• TypeScript projects

📜 License

MIT © Johannes Ludescher