Seiten

Inhalt

@xpulse/controller – Component Spec

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

Übersicht

Controller-Discovery und Basis-Klasse für das xPulse MVC Stack.

Eine Aufgabe: Controller finden, Routes ableiten, Views aufrufen – nicht mehr.

Discovert src/controllers/**/*.js, leitet Routes aus Dateipfad und Methodenname ab, meldet sie bei @xpulse/router an und stellt die Controller Basis-Klasse bereit.

Dependencies

1 @xpulse/controller
2   ├── @xpulse/router    ← Routes anmelden
3   ├── @xpulse/template  ← this.render() delegiert hierhin
4   └── @xpulse/event     ← auf template:render:before lauschen

API

Initialisieren

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

Discovert rekursiv src/controllers/**/*.js, leitet Routes ab und registriert sie bei @xpulse/router. Wird von @xpulse/app aufgerufen.

Filesystem-Routing

Der Dateipfad bestimmt die Basis-Route des Controllers. Der Methodenname bestimmt die Sub-Route.

Regeln

index() Methode → kein URL-Suffix (Root der Controller-Route)
Andere Methoden → Methodenname wird zum URL-Suffix
define() → optionaler Override für einzelne Methoden-Routes
Unterordner → werden Teil der Route

Mapping-Beispiele

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

Alle Controller-Methoden geben ein Response Object zurück – @xpulse/http ist der einzige der es tatsächlich sendet. Der Controller beschreibt die Response, nie sendet er sie direkt.

1 // Intern – alle Helper geben dieses Format zurück:
2 {
3     status:  200,
4     headers: { 'Content-Type': 'text/html' },
5     body:    '<html>...',
6 }

Controller Basis-Klasse

1 import { Controller } from '@xpulse/controller';
2  
3 // Datei: src/controllers/info.js
4 // Basis-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 Beispiel

1 // Datei: 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 ohne Template
31     async api() {
32         return this.json({ status: 'ok' });
33     }
34 }

Controller Basis-Klasse API

Response Helper – geben immer ein Response Object zurück:

Methode	Beschreibung
`this.render(view, data)`	Template rendern via `@xpulse/template` → Response Object
`this.response(html, options?)`	Eigenes HTML → Response Object, kein Template
`this.json(data, options?)`	JSON → Response Object, kein Template
`this.redirect(url)`	Redirect → Response Object (`301`)

Route Overrides – nur in define():

Methode	Beschreibung
`this.overrideRoute(method, path)`	Route für eine Methode überschreiben
`this.overrideMethod(method, httpMethod)`	HTTP-Methode für einen Handler überschreiben

Request Zugriff:

Eigenschaft	Beschreibung
`this.req.path`	Aktueller URL-Pfad – `/info/bla`
`this.req.params`	URL-Parameter – `{ page: 'bla' }`
`this.req.query`	Query-String – `{ lang: 'de' }`
`this.req.method`	HTTP-Methode – `GET`, `POST`
`this.req.body`	Request Body – bei POST geparst
`this.req.headers`	Request Headers

Automatische Route-Info in Template-Daten

@xpulse/controller lauscht auf template:render:before und injiziert _route in die Template-Daten – ohne manuellen Aufwand in jeder View-Methode, und ohne dass @xpulse/template den Controller kennen muss.

1 // Intern in @xpulse/controller – einmalig beim 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 });

Im Template abrufbar zur Laufzeit – praktisch zum Debuggen und für aktive Navigation-States:

1 <!-- Aktiven Nav-Link markieren -->
2 <a href="/info" class="{{ _route.path === '/info' ? 'active' : '' }}">Info</a>
3  
4 <!-- Debug-Info -->
5 <p>Route: {{ _route.path }}</p>

_ Prefix signalisiert: System-Wert, kein User-Daten.

Gefeuerte Events

Event	Payload	Wann
`controller:init`	`{ root }`	Discovery beginnt
`controller:discovered`	`{ name, routes }`	Controller gefunden
`controller:ready`	`{ count, routes }`	Alle registriert
`controller:called`	`{ traceId, controller, action, method, path, name }`	Handler aufgerufen
`controller:navigation:collected`	`{ items }`	Navigation-Items gesammelt
`controller:navigation:ready`	`{ items }`	Navigation bereit

Zusammenspiel im Request Flow

1 @xpulse/http       empfängt GET /info/bla
2   ↓
3 @xpulse/router     matched → InfoController@bla
4   ↓
5 @xpulse/controller ruft InfoController.bla() auf
6   ↓
7 InfoController     this.render('info/bla', { title: 'Bla' })
8   ↓
9 @xpulse/template   rendert HTML
10   ↓
11 controller         gibt Response Object zurück { status: 200, body: html }
12   ↓
13 @xpulse/http       sendet Response

Debug Integration

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

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

Der ControllerCollector (name: 'controller', icon: '⚙️') zeigt im Web Profiler:

This Request (kv): Controller, Action, Route, Dispatch Time
All Controllers (table): alle discoverten Controller-Routen

Dispatch Time misst die Zeit von http:request bis controller:called – das schließt Routing und Dispatch ein, nicht die reine Handler-Execution-Zeit. Dies ist im Panel als (request start → controller called) ausgewiesen.

Außerdem schreibt der ControllerCollector einen Waterfall-Span (kind: 'controller') für die Dispatch-Zeit.

Badge in der Toolbar: InfoController@index · 3ms

Paket-Struktur

1 @xpulse/controller/
2   src/
3     index.js        ← default export: controller-Objekt
4     discovery.js    ← rekursives Laden aus src/controllers/
5     resolver.js     ← Filesystem-Pfad → Route ableiten
6     base.js         ← Controller Basis-Klasse
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 ← Routes anmelden
3	├── @xpulse/template ← this.render() delegiert hierhin
4	└── @xpulse/event ← auf template:render:before lauschen

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	// Intern – alle Helper geben dieses Format zurück:
2	{
3	status: 200,
4	headers: { 'Content-Type': 'text/html' },
5	body: '<html>...',
6	}

1	import { Controller } from '@xpulse/controller';
2
3	// Datei: src/controllers/info.js
4	// Basis-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	// Datei: 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 ohne Template
31	async api() {
32	return this.json({ status: 'ok' });
33	}
34	}

1	// Intern in @xpulse/controller – einmalig beim 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	<!-- Aktiven Nav-Link markieren -->
2	<a href="/info" class="{{ _route.path === '/info' ? 'active' : '' }}">Info</a>
3
4	<!-- Debug-Info -->
5	<p>Route: {{ _route.path }}</p>

1	@xpulse/http empfängt GET /info/bla
2	↓
3	@xpulse/router matched → InfoController@bla
4	↓
5	@xpulse/controller ruft InfoController.bla() auf
6	↓
7	InfoController this.render('info/bla', { title: 'Bla' })
8	↓
9	@xpulse/template rendert HTML
10	↓
11	controller gibt Response Object zurück { status: 200, body: html }
12	↓
13	@xpulse/http sendet Response

1	@xpulse/controller/
2	src/
3	index.js ← default export: controller-Objekt
4	discovery.js ← rekursives Laden aus src/controllers/
5	resolver.js ← Filesystem-Pfad → Route ableiten
6	base.js ← Controller Basis-Klasse
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