@xpulse/event – Component Spec

Status: CONCEPT · Erstellt März 2026 Übergeordnet: GLOBAL_concept-ecosystem.md

Übersicht

Event-System – Fundament für alle @xpulse/* Pakete. Zero dependencies.

Erweitert Node's nativen EventEmitter um optionale Registrierung und Introspection – damit Events im Ökosystem dokumentiert und nachvollziehbar sind.

Konzept

Events können optional registriert werden – das ist keine Pflicht, aber eine Konvention. Ein emit() auf einem nicht-registrierten Event funktioniert, taucht aber nicht in event.list() auf.

1
register()  → dokumentiert ein Event (optional)
2
on()        → lauscht auf ein Event
3
once()      → lauscht einmalig
4
off()       → hört auf zu lauschen
5
emit()      → feuert ein Event

API

Lauschen

1
import event from '@xpulse/event';
2
 
3
// Dauerhaft lauschen
4
event.on('page:ready', (data) => {
5
    console.log(data.lang);
6
});
7
 
8
// Einmalig lauschen
9
event.once('project:ready', (data) => {
10
    console.log('project geladen:', data.name);
11
});
12
 
13
// Aufhören zu lauschen
14
const handler = (data) => { ... };
15
event.on('page:ready', handler);
16
event.off('page:ready', handler);

Feuern

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

Registrieren (optional)

1
// Dokumentiert ein Event – kein Pflichtaufruf vor emit()
2
event.register('page:ready', {
3
    description: 'Seite fertig gerendert, i18n kann übernehmen',
4
    emittedBy:   '@xpulse/project',
5
    payload:     '{ lang: string, route: string }',
6
});

Introspection

1
// Alle registrierten Events
2
event.list();
3
// → [
4
//     { name: 'page:ready',    description: '...', emittedBy: '...', listeners: 2 },
5
//     { name: 'project:ready', description: '...', emittedBy: '...', listeners: 1 },
6
//   ]
7
 
8
// Aktive Listener für ein Event
9
event.listeners('page:ready');
10
// → [ [Function: handler1], [Function: handler2] ]
11
 
12
// Anzahl Listener
13
event.listenerCount('page:ready');
14
// → 2

Event-Naming Convention

1
namespace:event
2
namespace:area:event

Paket-Struktur

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

Intern

Basiert auf Node's EventEmitter – kein eigener Event-Loop, keine Queues, kein Persistence. Fired and forgotten. Die Registrierungs-Map ist ein einfaches Map<name, metadata> on top.

1
// Intern
2
import { EventEmitter } from 'events';
3
const emitter  = new EventEmitter();
4
const registry = new Map(); // name → { description, emittedBy, payload }
5
 
6
// Limit auf 50 — im Ökosystem hören viele Packages auf dieselben Events
7
emitter.setMaxListeners(50);

Dependencies

Keine.

Debug Integration

Wenn @xpulse/debug als devDependency installiert ist, stellt @xpulse/event automatisch einen DataCollector bereit. @xpulse/debug discovert ihn via node_modules/@xpulse/event/src/datacollectors/ – keine Konfiguration nötig.

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

Der EventsCollector (name: 'events', icon: '⚡') zeigt im Web Profiler:

• Registered Events (table): alle via event.register() bekannten Events mit Name, Emitted By, aktiver Listener-Anzahl, Description
• Emitted During Request (table): alle tatsächlich gefeuerten Events während dieses Requests mit Name, Timestamp und gekürztem Payload

Strategie: Der EventsCollector umschließt event.emit direkt, statt für jedes Event einen eigenen Listener zu registrieren. Damit werden auch Events erfasst die nie via event.register() registriert wurden (z.B. template:render:after). Ausgenommen sind http:response:before (zirkuläre Payload) und logger:write (zu viele Einträge).

Badge in der Toolbar: Anzahl emittierter Events während des Requests (z.B. 7)

Offene Fragen