boot-express

@alt-javascript/boot-express

Express adapter for the @alt-javascript framework. Bridges CDI-managed controllers to Express routes with a CDI middleware pipeline for cross-cutting concerns.

Inspired by Spring MVC @RestController / @RequestMapping and Spring Security's filter chain.

Part of the @alt-javascript monorepo.

Install

npm install @alt-javascript/boot-express express

Usage

Define a controller with __routes metadata and boot with expressStarter():

import { Boot } from '@alt-javascript/boot';
import { Context, Singleton } from '@alt-javascript/cdi';
import { expressStarter } from '@alt-javascript/boot-express';

class TodoController {
  static __routes = [
    { method: 'GET',    path: '/todos',     handler: 'list'   },
    { method: 'POST',   path: '/todos',     handler: 'create' },
    { method: 'GET',    path: '/todos/:id', handler: 'get'    },
    { method: 'DELETE', path: '/todos/:id', handler: 'remove' },
  ];

  constructor() { this.todoService = null; } // autowired

  async list(req)   { return this.todoService.findAll(); }
  async create(req) { return this.todoService.create(req.body); }
  async get(req)    { return this.todoService.findById(req.params.id); }
  async remove(req) { return this.todoService.delete(req.params.id); }
}

const context = new Context([
  ...expressStarter(),
  new Singleton(TodoService),
  new Singleton(TodoController),
]);

await Boot.boot({ contexts: [context] });
// Express is listening on server.port (default 3000)

The adapter discovers all CDI beans with __routes, binds handlers to Express routes, and makes the CDI context available as req.app.locals.ctx.

Controller Patterns

Declarative (__routes)

Handlers receive the native Express (req, res, next) arguments:

async greet(req, res) {
  const message = this.greetingService.greet(req.params.name);
  res.json({ message });
}

Imperative (routes(app, ctx))

class ImperativeController {
  routes(app, ctx) {
    app.get('/custom', (req, res) => {
      res.json({ from: ctx.get('myService').doSomething() });
    });
  }
}

Middleware Pipeline

expressStarter() registers three built-in middleware components via the CDI middleware pipeline — the equivalent of Spring Security's filter chain:

Component	Order	Behaviour
RequestLoggerMiddleware	10	Logs [METHOD] /path → status (Xms)
ErrorHandlerMiddleware	20	Converts thrown errors to JSON error responses
NotFoundMiddleware	30	Returns 404 for unmatched routes

Add custom middleware by declaring static __middleware = { order: N } on any CDI component:

class AuthMiddleware {
  static __middleware = { order: 5 }; // runs outermost — before RequestLoggerMiddleware

  constructor() { this.logger = null; } // autowired

  async handle(request, next) {
    const token = request.headers.authorization?.replace('Bearer ', '');
    if (!token) return { statusCode: 401, body: { error: 'Unauthorized' } };
    return next({ ...request, user: { token } });
  }
}

const context = new Context([
  ...expressStarter(),
  new Singleton(AuthMiddleware), // auto-detected — no extra wiring
  new Singleton(TodoController),
]);

Disable a built-in middleware via config:

{ "middleware": { "requestLogger": { "enabled": false } } }

Replace a built-in by registering a component with the same name before the starter:

new Context([
  { name: 'errorHandlerMiddleware', Reference: MyErrorHandler, scope: 'singleton' },
  ...expressStarter(),
])

Configuration

Key	Default	Description
server.port	3000	Port to listen on
server.host	0.0.0.0	Host to bind
middleware.requestLogger.enabled	true	Enable request logging
middleware.errorHandler.enabled	true	Enable error handler
middleware.notFound.enabled	true	Enable 404 handler

Testing

Use supertest and expressAdapter.app to test without binding a port:

import supertest from 'supertest';
import { expressStarter, ExpressAdapter } from '@alt-javascript/boot-express';

const appCtx = /* boot context with run: false */;
const app = appCtx.get('expressAdapter').app;

const res = await supertest(app).get('/todos');
assert.equal(res.status, 200);

Spring Attribution

The __routes convention maps to Spring MVC's @RequestMapping / @GetMapping. The static __middleware = { order: N } convention maps to Spring Security's Filter + FilterRegistrationBean(setOrder(n)). expressStarter() maps to a Spring Boot auto-configuration class.

License

MIT