@glandjs/express@1.1.0-beta
@glandjs/express
The Express 5 transport — ExpressBroker, ExpressContext, framework middleware through useRaw, and the one behavioural caveat.
@glandjs/express binds your controllers and channels to a real
Express 5 application. It is the adapter most people start
with, and the reference for how the contract maps onto a framework that is not built
for promises.
pnpm add @glandjs/core @glandjs/common @glandjs/events @glandjs/http @glandjs/express express reflect-metadataAttaching it
Section titled “Attaching it”import { GlandFactory } from '@glandjs/core'import { Controller, Module } from '@glandjs/common'import { Get } from '@glandjs/http'import { ExpressBroker, type ExpressContext } from '@glandjs/express'
@Controller('/products')export class ProductController { @Get('/:id') async find(ctx: ExpressContext) { return { product: await ctx.call('db:product:find', { id: ctx.params.id }) } }}
@Module({ controllers: [ProductController] })export class AppModule {}
const { app, shutdown } = await GlandFactory.create(AppModule)const http = app.connectTo(ExpressBroker, { poweredBy: false })
http.bodyParser({ json: true, urlencoded: { extended: true } })http.listen(3000)await http.ready()Exports
Section titled “Exports”| Symbol | Description |
|---|---|
ExpressBroker<TEvents> |
The broker you pass to connectTo(). |
ExpressContext<TEvents> |
The context your handlers receive. |
ExpressCore<TEvents> |
The application object connectTo() returns. |
ExpressAdapter<TEvents> |
The transport implementation of HttpServerAdapter. |
Route decorators are not exported from here — they come from @glandjs/http, so a
controller never depends on the transport.
The application surface
Section titled “The application surface”connectTo() returns the full HttpCore surface, backed by
a real Express application. Reach the raw app through http.instance when you need
something Express-specific.
http.use(async (ctx, next) => { const started = Date.now() await next() console.log(`${ctx.method} ${ctx.path} ${Date.now() - started}ms`)})
http.useRaw(compression()) // framework middleware, unmolestedhttp.useStaticAssets('public')http.setGlobalPrefix('/api')http.enableCors({ origin: 'https://example.com', credentials: true })
http.listen(3000, { host: '0.0.0.0' })Routes outside a controller work too, which is handy for a health check:
http.get('/ping', (ctx) => ctx.send('pong'))The one caveat: next() is a hand-off
Section titled “The one caveat: next() is a hand-off”Express’s next() does not return a promise, so await next() resolves as soon as
Express moves on — a downstream throw never reaches an upstream catch. Every other
adapter gives you a real onion.
await next() waits |
upstream catch sees a downstream throw |
|
|---|---|---|
@glandjs/express |
no | no |
@glandjs/fastify |
yes | yes |
@glandjs/koa |
yes | yes |
@glandjs/hono |
yes | yes |
@glandjs/node |
yes | yes |
Three ways to live with it: do the work after the response rather than after next(),
move the recovery downstream into the error handler, or measure on
HttpEvent.RequestEnd. Middleware
covers all three.
What Express does better
Section titled “What Express does better”Express is the most complete of the five out of the box, which is why it is often the right first choice:
useRaw()works, socompression(),helmet(),cookie-parser()and friends mount normally.- Signed cookies work when
cookie-parseris mounted. - Views are built in:
setViewEngine()andsetBaseViewsDir()are real. - Static file serving is built in.
- Every extended verb works, including
MKWORKSPACEandUPDATE.
What it cannot do
Section titled “What it cannot do”- Multipart.
bodyParser({ multipart })throws at configuration time. UsemulterthroughuseRaw(), or pick another adapter. poweredBy: falseremovesX-Powered-By, which Express sets itself; Koa has no header to remove and ignores the option.- A single catch-all route.
http.all('*')works, but Express’s ownapp.useorder still decides what a request sees first.
See also
Section titled “See also”- Mirrored adapter documentation
- Adapter matrix
@glandjs/http— the layer this adapter implements