@xpulse/event – Component Spec

Status: CONCEPT · Created March 2026 Parent: GLOBAL_concept-ecosystem.md

Overview

Event system – the foundation for all @xpulse/* packages. Zero dependencies.

Extends Node's native EventEmitter with optional registration and introspection – so that events in the ecosystem are documented and traceable.

Concept

Events can optionally be registered – this is not required, but a convention. An emit() on an unregistered event works, but does not appear in event.list().

1
register()  → documents an event (optional)
2
on()        → listens to an event
3
once()      → listens once
4
off()       → stops listening
5
emit()      → fires an event

API

Listening

1
import event from '@xpulse/event';
2
 
3
// Listen permanently
4
event.on('page:ready', (data) => {
5
    console.log(data.lang);
6
});
7
 
8
// Listen once
9
event.once('project:ready', (data) => {
10
    console.log('project loaded:', data.name);
11
});
12
 
13
// Stop listening
14
const handler = (data) => { ... };
15
event.on('page:ready', handler);
16
event.off('page:ready', handler);

Firing

1
event.emit('page:ready', { lang: 'de', route: '/privacy/' });

Registering (optional)

1
// Documents an event – not required before emit()
2
event.register('page:ready', {
3
    description: 'Page fully rendered, i18n can take over',
4
    emittedBy:   '@xpulse/project',
5
    payload:     '{ lang: string, route: string }',
6
});

Introspection

1
// All registered events
2
event.list();
3
// → [
4
//     { name: 'page:ready',    description: '...', emittedBy: '...', listeners: 2 },
5
//     { name: 'project:ready', description: '...', emittedBy: '...', listeners: 1 },
6
//   ]
7
 
8
// Active listeners for an event
9
event.listeners('page:ready');
10
// → [ [Function: handler1], [Function: handler2] ]
11
 
12
// Listener count
13
event.listenerCount('page:ready');
14
// → 2

Event Naming Convention

1
namespace:event
2
namespace:area:event

Package Structure

1
@xpulse/event/
2
  index.js    ← default export: event object
3
  README.md
4
  package.json

Internals

Based on Node's EventEmitter – no custom event loop, no queues, no persistence. Fired and forgotten. The registration map is a simple Map<name, metadata> on top.

1
// Internals
2
import { EventEmitter } from 'events';
3
const emitter  = new EventEmitter();
4
const registry = new Map(); // name → { description, emittedBy, payload }
5
 
6
// Limit set to 50 — many packages legitimately listen to the same events in the ecosystem
7
emitter.setMaxListeners(50);

Dependencies

None.

Debug Integration

When @xpulse/debug is installed as a devDependency, @xpulse/event automatically provides a DataCollector. @xpulse/debug discovers it via node_modules/@xpulse/event/src/datacollectors/ – no configuration needed.

1
"optionalDependencies": {
2
  "@xpulse/debug": "^1.0.0"
3
}

The EventsCollector (name: 'events', icon: '⚡') shows in the Web Profiler:

• Registered Events (table): all events known via event.register() with name, emitted by, active listener count, description
• Emitted During Request (table): all events actually fired during this request with name, timestamp, and truncated payload

Strategy: The EventsCollector wraps event.emit directly instead of registering a separate listener for each event. This means events are also captured that were never registered via event.register() (e.g. template:render:after). Excluded are http:response:before (circular payload) and logger:write (too many entries).

Badge in the toolbar: number of events emitted during the request (e.g. 7)

Open Questions