@xpulse/router – Component Spec

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

Overview

URL matching and route management for the xPulse ecosystem.

One responsibility: match a URL to a handler – nothing more.

Has no knowledge of controller logic, templates, or the HTTP server directly. Accepts routes (from @xpulse/controller or manually) and registers them with @xpulse/http.

Dependencies

1 @xpulse/router
2   ├── @xpulse/http     ← registers matched handlers with the server
3   └── @xpulse/event    ← emit router:registered

API

Initialising

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

Registers all known routes with @xpulse/http. Called by @xpulse/app after @xpulse/controller – once all routes are known.

Registering a route

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

Called internally by @xpulse/controller – but can also be used manually for routes without a controller.

404 Handler

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

Without an explicit notFound handler the router returns a plain 404 Not Found plain-text response.

URL Pattern Matching

Supported patterns analogous to @xpulse/http:

1 /                       ← exact match
2 /info                   ← exact match
3 /info/:page             ← required parameter
4 /info/:page?            ← optional parameter
5 /tool/:tool/:page?      ← multiple parameters, last one optional

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

Emitted Events

Event	Payload	When
`router:registered`	`{ method, path }`	when a route is registered
`router:matched`	`{ method, path, params }`	when a route is matched
`router:not-found`	`{ method, path }`	when no route matches

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

Interaction with @xpulse/controller

@xpulse/controller calls router.register() for every discovered controller method – the router does not need to know about controllers:

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

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

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

The RouterCollector (name: 'router', icon: '🔀') shows in the Web Profiler:

Matched Route (kv): Method, Path, Name, Params (as JSON if present)
Registered Routes (table): all routes known via router.register() with Method, Path, Name

No toolbar badge (no quantifiable value per request).

Package Structure

1 @xpulse/router/
2   src/
3     index.js      ← default export: router object
4     matcher.js    ← URL pattern matching logic
5     registry.js   ← route management (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 ← registers matched handlers with the server
3	└── @xpulse/event ← emit router:registered

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	/ ← exact match
2	/info ← exact match
3	/info/:page ← required parameter
4	/info/:page? ← optional parameter
5	/tool/:tool/:page? ← multiple parameters, last one optional

1	// Example: /tool/chat/guide
2	router.register('GET', '/tool/:tool/:page?', handler);
3	// → req.params = { tool: 'chat', page: 'guide' }
4
5	// Example: /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	// automatically logged by @xpulse/logger
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 object
4	matcher.js ← URL pattern matching logic
5	registry.js ← route management (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