What is Gland?
The four primitives Gland is built from — modules, controllers, channels and brokers — described as they actually work, including the edges.
Gland is a framework for building server-side applications where business logic is addressed by name and the transport is a separate package. That is the whole idea. This page describes what that means in practice, including where it stops.
Read Why Gland? first if you want the honest evaluation — including the parts that should make you hesitate.
The shape of an application
Section titled “The shape of an application”// 1. One map. This is the entire contract.import type { IOEvent } from '@glandjs/events'
type AppEvents = { 'order:created': IOEvent<{ total: number }, Order> // payload in, result out 'order:paid': { orderId: string }}
// 2. A channel owns one named thing and its side effects.@Channel('order')export class OrderChannel { @On('created') // → 'order:created' async create({ total }: { total: number }): Promise<Order> { return this.repo.save({ total }) }}
// 3. A controller translates and replies. It performs no side effects.@Controller('/orders')export class OrderController { @Post() async create(ctx: HttpContext<any, any, AppEvents>) { return ctx.call('order:created', { total: 42 }) // by name, typed both ways }}
// 4. A module registers what exists.@Module({ imports: [OrderModule], controllers: [OrderController], channels: [OrderChannel] })export class AppModule {}OrderChannel imports nothing from the order flow’s other side effects. Adding a fifth
reaction is a new file and one line in @Module.
The four primitives
Section titled “The four primitives”Modules — composition boundaries
Section titled “Modules — composition boundaries”@Module({ imports: [], controllers: [], channels: [] })Exactly three keys. There is no providers, no useFactory, no useValue and no scope —
a class is only constructible if it is a @Channel or a @Controller. Modules group code
and resolve nothing; two modules can register the same channel name only if the second one
fails at startup.
Controllers — translation only
Section titled “Controllers — translation only”A controller reads the request, calls or emits something by name, and replies. It never imports a service and never touches the framework’s response object.
@Get('/:id')async find(ctx) { return ctx.call('order:find', { id: ctx.params.id })}
@Post()async create(ctx) { return ctx.call('order:created', { total: 42 })}Channels — the unit of composition
Section titled “Channels — the unit of composition”@Channel('payment')export class PaymentChannel { @On('order:created') // namespaced: 'payment:order:created' async charge({ orderId }) { /* … */ }}A channel is registered by name, instantiated once as a singleton, and its event names must be globally unique. Both are enforced at startup, not at request time.
Channels are where side effects live, which is what makes them independently testable:
const ctx = app.createContext() // no server involvedconst order = await ctx.call('order:created', { total: 42 })Brokers — the transport seam
Section titled “Brokers — the transport seam”const { app, shutdown } = await GlandFactory.create(AppModule)const http = app.connectTo(ExpressBroker) // or FastifyBroker, KoaBroker, HonoBroker, NodeBroker@glandjs/core has no notion of a request. Routing, the context, body parsing and CORS all
come from @glandjs/http and an adapter. connectTo() takes the broker class, links
its event bus to the core bus, and hands you back the transport application.
How a request flows
Section titled “How a request flows”- The adapter matches a route and builds an
HttpContext— memoised, so middleware and the handler see the same object. http:request:startis emitted with{ id, method, path, url, ip }.- Gland middleware runs in registration order as a promise onion.
- The controller calls
ctx.call('name', payload). The name resolves through a frozen registry — an unknown name is an immediate error listing the valid ones. - The channel handler runs and returns.
ctx.call()hands that value back. - The return value is coerced to a reply by one function shared by all five adapters.
http:request:endfires with{ status, duration }— always, even on failure.
The channel never sees the context. It receives the payload and returns a value, which is
what makes it testable without a server — and also means a channel cannot read
ctx.state, so anything from the request has to be passed in the payload.
The two buses on a context
Section titled “The two buses on a context”This trips people up, so it is worth stating plainly:
ctx.emit('order:created', payload) // → the CORE bus, reaches channelsctx.call('order:created', payload) // → the CORE bus, returns the handler's value
ctx.on('some:event', handler) // → the ADAPTER's lifecycle busctx.on / ctx.off / ctx.once are for framework-level observation — the transport’s
own lifecycle events. They do not reach channel handlers. If you want a listener on an
application event, use @On() in a channel.
ctx.call vs ctx.emit
Section titled “ctx.call vs ctx.emit”call |
emit |
|
|---|---|---|
| Handlers reached | the one registered for that exact name | every listener, including wildcards |
| Returns | the handler’s value | this, for chaining |
| Nothing listening | returns [] |
silently does nothing |
| Throws | the handler’s error | aborts every remaining listener |
Typing it properly
Section titled “Typing it properly”// ✓ a plain type — names and payloads are both enforcedtype AppEvents = { 'order:created': IOEvent<{ total: number }, Order>}
// ✗ a trap: EventRecord is Record<string, any>, so extending it// installs an index signature and nothing is checked any moreinterface AppEvents extends EventRecord { 'order:created': { total: number }}Pass the map to the adapter so it reaches the handler signature:
const http = app.connectTo(ExpressBroker<AppEvents>, { poweredBy: false })Without it the context defaults to an index-signature map and ctx.call('anything', …)
type-checks.
What you must set up yourself
Section titled “What you must set up yourself”Gland is the composition layer. These do not exist and you will write them:
-
Request and response validation.
ctx.bodyisanyand nothing checks it. -
Auth. A middleware on the onion; there are no guards or decorators.
-
Logging. No injection point — the framework constructs its own logger internally.
-
Graceful shutdown. Signal handlers are only installed when
GLAND_DEBUGis set, so in productionSIGTERMdoes nothing until you wire it:process.once('SIGTERM', async () => {await http.close() // drain in-flight requestsawait shutdown('SIGTERM') // run onAppShutdown / onModuleDestroy})
What it is
Section titled “What it is”- A small, typed, event-first way to address side effects by name.
- One HTTP contract with five interchangeable transports behind it, and a contract suite that holds them to it.
- A composition layer that stays out of the way of everything else — no ORM, no config system, no CLI, no admin UI.
What it is not
Section titled “What it is not”- A distributed message bus. Events do not leave the process.
- A batteries-included platform.
- A NestJS replacement with the same feature list. It has different ones.
- Why Gland? — the honest evaluation, and a decision rule
- Architecture — the bootstrap sequence, step by step
- Modules · Controllers · Channels
- Working with the context
- The event map —
IOEvent, wildcards, watchers and the mesh API - The HTTP layer · Writing a broker