Pages

Contents

@xpulse/controller – Component Spec

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

Overview

Controller discovery and base class for the xPulse MVC stack.

One responsibility: find controllers, derive routes, call views – nothing more.

Discovers src/controllers/**/*.js, derives routes from file path and method name, registers them with @xpulse/router, and provides the Controller base class.

Dependencies

1 @xpulse/controller
2   ├── @xpulse/router    ← register routes
3   ├── @xpulse/template  ← this.render() delegates here
4   └── @xpulse/event     ← listen to template:render:before

API

Initialising

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

Recursively discovers src/controllers/**/*.js, derives routes and registers them with @xpulse/router. Called by @xpulse/app.

Filesystem Routing

The file path determines the base route of the controller. The method name determines the sub-route.

Rules

index() method → no URL suffix (root of the controller route)
Other methods → method name becomes the URL suffix
define() → optional override for individual method routes
Subdirectories → become part of the route

Mapping Examples

1 src/controllers/
2   index.js              →  IndexController
3     index()             →  GET /
4  
5   info.js               →  InfoController
6     index()             →  GET /info
7     team()              →  GET /info/team
8     bla()               →  GET /info/bla
9  
10   tool/
11     chat.js             →  ChatController
12       index()           →  GET /tool/chat
13       guide()           →  GET /tool/chat/guide
14  
15   contact.js            →  ContactController
16     index()             →  GET  /contact
17     submit()            →  POST /contact

Response Object

All controller methods return a Response Object – @xpulse/http is the only one that actually sends it. The controller describes the response, it never sends it directly.

1 // Internally – all helpers return this format:
2 {
3     status:  200,
4     headers: { 'Content-Type': 'text/html' },
5     body:    '<html>...',
6 }

Controller Base Class

1 import { Controller } from '@xpulse/controller';
2  
3 // File: src/controllers/info.js
4 // Base route: /info
5  
6 export default class InfoController extends Controller {
7  
8     define() {
9         this.overrideRoute('team', '/info/ueber-uns');
10         this.overrideMethod('submit', 'POST');
11     }
12  
13     // → GET /info
14     async index() {
15         return this.render('info/index', {
16             title: 'Info',
17         });
18     }
19  
20     // → GET /info/bla
21     async bla() {
22         return this.render('info/bla', {
23             title: 'Bla',
24             items: ['a', 'b', 'c'],
25         });
26     }
27  
28     // → GET /info/ueber-uns (via overrideRoute)
29     async team() {
30         return this.render('info/team', {
31             title: 'Über uns',
32         });
33     }
34 }

POST + JSON Example

1 // File: src/controllers/contact.js
2  
3 export default class ContactController extends Controller {
4  
5     define() {
6         this.overrideMethod('submit', 'POST');
7     }
8  
9     // → GET /contact
10     async index() {
11         return this.render('contact/index', {
12             title: 'Kontakt',
13         });
14     }
15  
16     // → POST /contact
17     async submit() {
18         const { name, message } = this.req.body;
19  
20         if (!name || !message) {
21             return this.render('contact/index', {
22                 title: 'Kontakt',
23                 error: 'Bitte alle Felder ausfüllen.',
24             });
25         }
26  
27         return this.redirect('/contact/danke');
28     }
29  
30     // → GET /contact/api – JSON response without template
31     async api() {
32         return this.json({ status: 'ok' });
33     }
34 }

Controller Base Class API

Response helpers – always return a Response Object:

Method	Description
`this.render(view, data)`	Render template via `@xpulse/template` → Response Object
`this.response(html, options?)`	Custom HTML → Response Object, no template
`this.json(data, options?)`	JSON → Response Object, no template
`this.redirect(url)`	Redirect → Response Object (`301`)

Route overrides – only inside define():

Method	Description
`this.overrideRoute(method, path)`	Override the route for a method
`this.overrideMethod(method, httpMethod)`	Override the HTTP method for a handler

Request access:

Property	Description
`this.req.path`	Current URL path – `/info/bla`
`this.req.params`	URL parameters – `{ page: 'bla' }`
`this.req.query`	Query string – `{ lang: 'de' }`
`this.req.method`	HTTP method – `GET`, `POST`
`this.req.body`	Request body – parsed for POST requests
`this.req.headers`	Request headers

Automatic Route Info in Template Data

@xpulse/controller listens to template:render:before and injects _route into the template data – without manual effort in every view method, and without @xpulse/template needing to know about the controller.

1 // Internally in @xpulse/controller – once during init:
2 event.on('template:render:before', ({ view, data }) => {
3     data._route = {
4         path:   this.req.path,
5         params: this.req.params,
6         query:  this.req.query,
7         method: this.req.method,
8     };
9 });

Available in the template at runtime – useful for debugging and for active navigation states:

1 <!-- Mark the active nav link -->
2 <a href="/info" class="{{ _route.path === '/info' ? 'active' : '' }}">Info</a>
3  
4 <!-- Debug info -->
5 <p>Route: {{ _route.path }}</p>

The _ prefix signals: system value, not user data.

Emitted Events

Event	Payload	When
`controller:init`	`{ root }`	Discovery begins
`controller:discovered`	`{ name, routes }`	Controller found
`controller:ready`	`{ count, routes }`	All registered
`controller:called`	`{ traceId, controller, action, method, path, name }`	Handler called
`controller:navigation:collected`	`{ items }`	Navigation items collected
`controller:navigation:ready`	`{ items }`	Navigation ready

Interaction in the Request Flow

1 @xpulse/http       receives GET /info/bla
2   ↓
3 @xpulse/router     matched → InfoController@bla
4   ↓
5 @xpulse/controller calls InfoController.bla()
6   ↓
7 InfoController     this.render('info/bla', { title: 'Bla' })
8   ↓
9 @xpulse/template   renders HTML
10   ↓
11 controller         returns Response Object { status: 200, body: html }
12   ↓
13 @xpulse/http       sends response

Debug Integration

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

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

The ControllerCollector (name: 'controller', icon: '⚙️') shows in the Web Profiler:

This Request (kv): Controller, Action, Route, Dispatch Time
All Controllers (table): all discovered controller routes

Dispatch Time measures the time from http:request to controller:called – this includes routing and dispatch, not the pure handler execution time. This is indicated in the panel as (request start → controller called).

The ControllerCollector also writes a Waterfall Span (kind: 'controller') for the dispatch time.

Badge in the toolbar: InfoController@index · 3ms

Package Structure

1 @xpulse/controller/
2   src/
3     index.js        ← default export: controller object
4     discovery.js    ← recursive loading from src/controllers/
5     resolver.js     ← derive route from filesystem path
6     base.js         ← Controller base class
7   test/
8     discovery.test.js
9     resolver.test.js
10     base.test.js
11   docs/
12     index.md
13     api.md
14     _meta.json
15   Dockerfile
16   Makefile
17   README.md
18   package.json
19   xpulse.json

1	@xpulse/controller
2	├── @xpulse/router ← register routes
3	├── @xpulse/template ← this.render() delegates here
4	└── @xpulse/event ← listen to template:render:before

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

1	src/controllers/
2	index.js → IndexController
3	index() → GET /
4
5	info.js → InfoController
6	index() → GET /info
7	team() → GET /info/team
8	bla() → GET /info/bla
9
10	tool/
11	chat.js → ChatController
12	index() → GET /tool/chat
13	guide() → GET /tool/chat/guide
14
15	contact.js → ContactController
16	index() → GET /contact
17	submit() → POST /contact

1	// Internally – all helpers return this format:
2	{
3	status: 200,
4	headers: { 'Content-Type': 'text/html' },
5	body: '<html>...',
6	}

1	import { Controller } from '@xpulse/controller';
2
3	// File: src/controllers/info.js
4	// Base route: /info
5
6	export default class InfoController extends Controller {
7
8	define() {
9	this.overrideRoute('team', '/info/ueber-uns');
10	this.overrideMethod('submit', 'POST');
11	}
12
13	// → GET /info
14	async index() {
15	return this.render('info/index', {
16	title: 'Info',
17	});
18	}
19
20	// → GET /info/bla
21	async bla() {
22	return this.render('info/bla', {
23	title: 'Bla',
24	items: ['a', 'b', 'c'],
25	});
26	}
27
28	// → GET /info/ueber-uns (via overrideRoute)
29	async team() {
30	return this.render('info/team', {
31	title: 'Über uns',
32	});
33	}
34	}

1	// File: src/controllers/contact.js
2
3	export default class ContactController extends Controller {
4
5	define() {
6	this.overrideMethod('submit', 'POST');
7	}
8
9	// → GET /contact
10	async index() {
11	return this.render('contact/index', {
12	title: 'Kontakt',
13	});
14	}
15
16	// → POST /contact
17	async submit() {
18	const { name, message } = this.req.body;
19
20	if (!name \|\| !message) {
21	return this.render('contact/index', {
22	title: 'Kontakt',
23	error: 'Bitte alle Felder ausfüllen.',
24	});
25	}
26
27	return this.redirect('/contact/danke');
28	}
29
30	// → GET /contact/api – JSON response without template
31	async api() {
32	return this.json({ status: 'ok' });
33	}
34	}

1	// Internally in @xpulse/controller – once during init:
2	event.on('template:render:before', ({ view, data }) => {
3	data._route = {
4	path: this.req.path,
5	params: this.req.params,
6	query: this.req.query,
7	method: this.req.method,
8	};
9	});

1	<!-- Mark the active nav link -->
2	<a href="/info" class="{{ _route.path === '/info' ? 'active' : '' }}">Info</a>
3
4	<!-- Debug info -->
5	<p>Route: {{ _route.path }}</p>

1	@xpulse/http receives GET /info/bla
2	↓
3	@xpulse/router matched → InfoController@bla
4	↓
5	@xpulse/controller calls InfoController.bla()
6	↓
7	InfoController this.render('info/bla', { title: 'Bla' })
8	↓
9	@xpulse/template renders HTML
10	↓
11	controller returns Response Object { status: 200, body: html }
12	↓
13	@xpulse/http sends response

1	@xpulse/controller/
2	src/
3	index.js ← default export: controller object
4	discovery.js ← recursive loading from src/controllers/
5	resolver.js ← derive route from filesystem path
6	base.js ← Controller base class
7	test/
8	discovery.test.js
9	resolver.test.js
10	base.test.js
11	docs/
12	index.md
13	api.md
14	_meta.json
15	Dockerfile
16	Makefile
17	README.md
18	package.json
19	xpulse.json