Soap Express

This page and the plugin itself are still in development, a lot will change.

@soapjs/soap-express is the HTTP layer for SoapJS on Express — controllers, routing, middleware, auth guards, and CQRS wiring — assembled with a single bootstrap() call.

Current version: 0.3.x. Requires @soapjs/soap ≥ 0.10.

Install

npm install @soapjs/soap @soapjs/soap-express reflect-metadata express

Bootstrap

bootstrap() wires Express, middleware, routing, auth and CQRS in one call:

import 'reflect-metadata';
import { bootstrap } from '@soapjs/soap-express';

const app = await bootstrap({
  port: 3000,
  container,                 // your pre-wired DIContainer
  controllers: [CharactersController, AuthController],
  middleware: { cors: true, helmet: true, logging: true, compression: true },
  auth: jwtStrategy,         // guards @Auth() routes
  cqrs: true,                // wire CommandBus + QueryBus
  healthCheck: true,
});

Controllers & routes

import { Controller, Get, Post, Auth, AdminOnly, ResultMapper } from '@soapjs/soap-express';

@Controller('/characters')
export class CharactersController {
  constructor(@Inject('QueryBus') private readonly queryBus: QueryBus) {}

  @Get('/')
  async list(req: Request, res: Response): Promise<void> {
    const result = await this.queryBus.dispatch(new ListCharactersQuery());
    ResultMapper.toResponse(result, res);
  }

  @Post('/')
  @AdminOnly()
  async create(req: Request, res: Response): Promise<void> { /* ... */ }
}

Route decorators: @Get @Post @Put @Delete @Patch @Head @Options. Auth decorators: @Auth(strategy) @AdminOnly() @RolesOnly(roles) @SelfOnly() @Public().

Authentication

Strategies come from @soapjs/soap-auth. Register them on the app, and pass one as auth: in bootstrap() to guard @Auth() routes:

app.registerAuth(soapAuth);            // all HTTP strategies from a soap-auth provider
app.registerAuthStrategy(strategy);    // ...or a single strategy

CQRS & Events

With cqrs: true, bootstrap() binds CommandBus + QueryBus and registers every @CommandHandler / @QueryHandler. Controllers inject the buses and dispatch. Domain events use @EventHandler — note they are registered but not auto-wired; you connect your own event bus. Full details: CQRS & Events.

Errors → HTTP

ResultMapper.toResponse(result, res) maps a Result failure to a status code. Register custom mappings at startup:

ResultMapper.register('ValidationError', 400);
ResultMapper.register('DomainRuleError', 422);

Full reference

A complete app (controllers, CQRS, events, auth, sockets): the Comics Universe demo.