Skip to content

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.

// 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.

@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.

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 })
}
@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 involved
const order = await ctx.call('order:created', { total: 42 })
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.

  1. The adapter matches a route and builds an HttpContext — memoised, so middleware and the handler see the same object.
  2. http:request:start is emitted with { id, method, path, url, ip }.
  3. Gland middleware runs in registration order as a promise onion.
  4. 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.
  5. The channel handler runs and returns. ctx.call() hands that value back.
  6. The return value is coerced to a reply by one function shared by all five adapters.
  7. http:request:end fires 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.

This trips people up, so it is worth stating plainly:

ctx.emit('order:created', payload) // → the CORE bus, reaches channels
ctx.call('order:created', payload) // → the CORE bus, returns the handler's value
ctx.on('some:event', handler) // → the ADAPTER's lifecycle bus

ctx.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.

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
// ✓ a plain type — names and payloads are both enforced
type 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 more
interface 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.

Gland is the composition layer. These do not exist and you will write them:

  • Request and response validation. ctx.body is any and 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_DEBUG is set, so in production SIGTERM does nothing until you wire it:

    process.once('SIGTERM', async () => {
    await http.close() // drain in-flight requests
    await shutdown('SIGTERM') // run onAppShutdown / onModuleDestroy
    })
  • 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.
  • 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.