@xpulse/router – Component Spec

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

Übersicht

URL-Matching und Route-Verwaltung für das xPulse Ökosystem.

Eine Aufgabe: URL auf Handler matchen – nicht mehr.

Kennt keine Controller-Logik, kein Template, kein HTTP-Server direkt. Nimmt Routes entgegen (von @xpulse/controller oder manuell) und registriert sie bei @xpulse/http.

Dependencies

1 @xpulse/router
2   ├── @xpulse/http     ← registriert gematchte Handler beim Server
3   └── @xpulse/event    ← router:registered feuern

API

Initialisieren

1 import router from '@xpulse/router';
2  
3 await router.init();

Registriert alle bekannten Routes bei @xpulse/http. Wird von @xpulse/app nach @xpulse/controller aufgerufen – wenn alle Routes bekannt sind.

Route registrieren

1 router.register('GET',  '/',            handler);
2 router.register('GET',  '/info',        handler);
3 router.register('GET',  '/info/:page?', handler);
4 router.register('POST', '/contact',     handler);

Wird intern von @xpulse/controller aufgerufen – kann aber auch manuell genutzt werden für Routen ohne Controller.

404 Handler

1 router.notFound((req, res) => {
2     res.status(404).send('<h1>Seite nicht gefunden</h1>');
3 });

Ohne expliziten notFound Handler gibt der Router eine schlichte 404 Not Found Plain-Text Response zurück.

URL-Pattern Matching

Unterstützte Pattern analog zu @xpulse/http:

1 /                       ← exakter Match
2 /info                   ← exakter Match
3 /info/:page             ← Pflicht-Parameter
4 /info/:page?            ← optionaler Parameter
5 /tool/:tool/:page?      ← mehrere Parameter, letzter optional

1 // Beispiel: /tool/chat/guide
2 router.register('GET', '/tool/:tool/:page?', handler);
3 // → req.params = { tool: 'chat', page: 'guide' }
4  
5 // Beispiel: /tool/chat
6 // → req.params = { tool: 'chat', page: undefined }

Gefeuerte Events

Event	Payload	Wann
`router:registered`	`{ method, path }`	wenn eine Route registriert wird
`router:matched`	`{ method, path, params }`	wenn eine Route gematched wird
`router:not-found`	`{ method, path }`	wenn keine Route matched

1 import event from '@xpulse/event';
2  
3 event.on('router:not-found', ({ method, path }) => {
4     // wird von @xpulse/logger automatisch geloggt
5 });

Zusammenspiel mit @xpulse/controller

@xpulse/controller ruft router.register() für jede gefundene Controller-Methode auf – der Router muss Controller nicht kennen:

1 @xpulse/controller  →  router.register('GET', '/info',     InfoController@index)
2 @xpulse/controller  →  router.register('GET', '/info/bla', InfoController@bla)
3 @xpulse/router      →  http.route('GET', '/info',     handler)
4 @xpulse/router      →  http.route('GET', '/info/bla', handler)

Debug Integration

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

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

Der RouterCollector (name: 'router', icon: '🔀') zeigt im Web Profiler:

Matched Route (kv): Method, Path, Name, Params (als JSON wenn vorhanden)
Registered Routes (table): alle via router.register() bekannten Routen mit Method, Path, Name

Kein Toolbar-Badge (kein quantifizierbarer Wert pro Request).

Paket-Struktur

1 @xpulse/router/
2   src/
3     index.js      ← default export: router-Objekt
4     matcher.js    ← URL-Pattern matching Logik
5     registry.js   ← Route-Verwaltung (register, notFound)
6   test/
7     matcher.test.js
8     registry.test.js
9   docs/
10     index.md
11     api.md
12     _meta.json
13   Dockerfile
14   Makefile
15   README.md
16   package.json
17   xpulse.json

1	@xpulse/router
2	├── @xpulse/http ← registriert gematchte Handler beim Server
3	└── @xpulse/event ← router:registered feuern

1	router.register('GET', '/', handler);
2	router.register('GET', '/info', handler);
3	router.register('GET', '/info/:page?', handler);
4	router.register('POST', '/contact', handler);

1	router.notFound((req, res) => {
2	res.status(404).send('<h1>Seite nicht gefunden</h1>');
3	});

1	/ ← exakter Match
2	/info ← exakter Match
3	/info/:page ← Pflicht-Parameter
4	/info/:page? ← optionaler Parameter
5	/tool/:tool/:page? ← mehrere Parameter, letzter optional

1	// Beispiel: /tool/chat/guide
2	router.register('GET', '/tool/:tool/:page?', handler);
3	// → req.params = { tool: 'chat', page: 'guide' }
4
5	// Beispiel: /tool/chat
6	// → req.params = { tool: 'chat', page: undefined }

1	import event from '@xpulse/event';
2
3	event.on('router:not-found', ({ method, path }) => {
4	// wird von @xpulse/logger automatisch geloggt
5	});

1	@xpulse/controller → router.register('GET', '/info', InfoController@index)
2	@xpulse/controller → router.register('GET', '/info/bla', InfoController@bla)
3	@xpulse/router → http.route('GET', '/info', handler)
4	@xpulse/router → http.route('GET', '/info/bla', handler)

1	@xpulse/router/
2	src/
3	index.js ← default export: router-Objekt
4	matcher.js ← URL-Pattern matching Logik
5	registry.js ← Route-Verwaltung (register, notFound)
6	test/
7	matcher.test.js
8	registry.test.js
9	docs/
10	index.md
11	api.md
12	_meta.json
13	Dockerfile
14	Makefile
15	README.md
16	package.json
17	xpulse.json