Skip to content

Why Gland?

An honest assessment of Gland against a service class and against NestJS — the four things it genuinely does better, the boundary it does not cross, and a decision rule.

This page exists to be useful, including when the answer is no. Everything below is checked against the source, and the weaknesses are stated before the strengths in the places where the weaknesses are the deciding factor.

“Gland decouples your business logic through events, and lets you swap the transport freely.”

Both halves are true at the type level. Neither is true at the level most people mean, and knowing where the line falls is the whole point of this page.

One reply-coercion function across five transports

Section titled “One reply-coercion function across five transports”

@glandjs/http decides what goes on the wire in exactly one place, toReplyPayload, and every adapter routes through it. Left to the frameworks, return { ok: true } becomes application/json on some adapters and text/html on others, return 42 means three different things, and a 204 is inferred on one and not another.

The repository enforces this with a shared contract suite that runs the same controller against all five adapters. That suite is the most valuable artefact here — more valuable than the adapter layer itself.

Failing at the call site, with the valid names

Section titled “Failing at the call site, with the valid names”
await ctx.call('db:product:creat', { id }) // immediately:
// UnknownEventError: 'db:product:creat' is not a registered event.
// Did you mean: db:product:create, db:product:find?

A name that does not exist is a hard error at the call site, listing up to forty real names. Compare the nearest equivalent elsewhere — a missing dependency reported at boot with no list of what was available. Duplicate channel names also fail at startup, with both owners named.

This is not a small thing. Most of what makes event-driven code painful is the typo you ship on Friday.

A middleware onion that behaves the same everywhere

Section titled “A middleware onion that behaves the same everywhere”

Every adapter inherits one ordering rule from HttpServerAdapter.finalize(): framework configuration, then middleware in call order, then deferred plugins, then routes, then the catch-all 404 behind the routes. That ordering is decided once, by buffering, and it is the reason app.use(auth) behaves identically on all five transports instead of depending on when you called it.

On Koa, Hono and node:http you get a real promise onion. On Express you do not, and the adapter matrix says so rather than pretending.

order.controller.ts
@Post()
async create(ctx) {
return ctx.call('order:created', { total: 42 })
}

OrderChannel imports no other channel. Adding a fifth reaction to an order flow is a new file and one line in @Module — not a constructor edit and a method edit in a class that already knows about four responsibilities.

And the same ctx.call() works from a CLI, a cron job or a queue consumer with no server at all, via app.createContext().

Gland’s events never leave the process. connectTo(broker) takes a broker instance. There is no socket, no serialisation, no acknowledgement. It is a method call over an adjacency map — “mesh” and “hop” are names, not network.

What that means in production:

Deployment What actually happens
1 instance Everything works. emit fans out locally, call resolves locally.
3 instances behind a load balancer An event reaches only the instance that served the request. Two thirds of your listeners never run, chosen at random by the balancer. Nothing is logged.
3 instances ctx.call() on an event whose handler is not on this instance returns [] — an empty result, typed as a successful value. A coin flip that returns an empty array instead of an error.

There is a second consequence nobody documents on emit: a listener that throws stops every listener after it, and prevents the event from reaching connected brokers at all. A try/catch per side effect in a service method isolates failures; emit does not. If you are relying on one side effect failing harmlessly while the others succeed, you need to wrap the handler, not the emitter.

Where the seams are thinner than they look

Section titled “Where the seams are thinner than they look”

The transport swap is real for routing, context shape, middleware ordering and reply coercion. It is not real for these, and they are checked by reading the five adapters rather than by the contract suite:

Divergence
ctx.ip Derived from the socket on Express, Koa, Fastify and node:http. On Hono it reads x-forwarded-for — a client-controlled header. If you rate-limit or audit on ctx.ip, that string is attacker-chosen.
ctx.accepts() Returns false with no Accept header on Express and Koa; '*/*' — a value never passed in — on the other three.
ctx.signedCookies Real on Express only. {} elsewhere. A session check written one way reads as “no session”; written the other, it reads as authorised.
ctx.download() Hono rebuilds the response without headers, so Content-Disposition is dropped. Silent, and it is the most common “send the user a file” call.
https The option is accepted by the interface and ignored by all five adapters, because none receives it. You get a plaintext server on your TLS port.
trustProxy Same cause, same result. Nothing reads X-Forwarded-*.
useRaw() Missing on Fastify and node:http. useRaw(helmet()) warns and does nothing — an app that believes it has Helmet does not.
useStaticAssets() A no-op on node:http right now.

Read that table as: the seam is in the types, not in the semantics. If your application depends on any of these rows, swapping costs you a real audit, not an import change.

@Injectable()
export class OrderService {
constructor(payment, inventory, notification) {}
async create(dto) {
const order = await this.repo.save(dto)
await this.payment.charge(order)
await this.inventory.reserve(order)
await this.notification.confirm(order)
return order
}
}
Service class Gland
Controller depends on injected instances a name
Adding a side effect edit the constructor and the method add a channel to the module
One side effect throws only that statement, with try/catch every listener after it, and the peers too
Side effect order the order you wrote registration order
Reaching a side effect in a test construct it with fakes call it with a fake context
Failure visible in the request no, by design yes — a 500 from a handler that succeeded

Gland buys addressability by name and compile-time payload checking. It does not buy failure isolation, ordering guarantees, or “fail at startup if nothing calls this”.

Nest is mature, and its @nestjs/event-emitter is genuinely the same primitive — an in-process emitter. If your reason for choosing Gland is “it has events and Nest does not”, that reason is wrong.

Nest Gland
Units are classes, wired by constructor channels, addressed by name
Validation class-validator, ValidationPipe, DTOs none
Extension points guards, interceptors, pipes, exception filters a middleware chain and one replaceable error handler
Logging injectable, nest-scoped no injection point — constructed internally
Graceful shutdown wired by default not installed in production
Ecosystem large, and the reason most people choose it small; you assemble the rest

Read the last four rows carefully. They are the reason most teams should choose Nest, and they are not close.

Where they genuinely differ is narrower than the pitch suggests: Gland’s unit of composition is a named capability, not a class. That is a real difference, and it only matters when your side effects change independently. If your team values Nest’s ecosystem, validation and extension points more than that, Nest is the right answer and nothing here should convince you otherwise.

  • Multi-instance deployments that rely on events reaching every instance. Single-process until you put a real broker behind a channel.
  • Anything needing delivery guarantees, replay or cross-process ordering.
  • Projects where validation, auth guards or logging injection are table stakes. None of the three exist.
  • CRUD-only services. If a controller body is one database read, the channel layer is ceremony and plain handlers are better.
  • Serverless as the primary target. The container builds the module graph on boot.

Use Gland if most of these are true:

  • Side effects are the interesting part of your application, not the plumbing, and they change after launch.
  • You can name what a piece of work does, and it is not doEverything().
  • You are deploying one instance, or you will put a real broker behind the channels.
  • You are willing to write the validation, auth, logging and shutdown layers yourself.
  • You read the adapter matrix and the in-process limitations before depending on it.

Stay with Nest — or with plain route handlers — if any of these are true:

  • You need validation, an ORM, a CLI, queues, caching and a config system in one dependency.
  • You run more than one instance and have not planned for the cross-process problem.
  • Most of your endpoints are read-one-write-one.
  • You want the framework to make cross-cutting concerns (auth, logging, caching) a one-line decorator rather than a project.

Plain route handlers are a legitimate answer and this page is not an argument against them. It is an argument about what to reach for when the domain has more than one moving part — and an argument for reading the table of divergences before you decide.

These are the rules the codebase is held to. They are the reason the API is small.

  1. No hidden behaviour. A method does one thing, and the docs can state what that thing is without a caveat.
  2. Composition over configuration. New capabilities are new packages or channels, never new switches on existing ones.
  3. Types are the contract. One event map is the single source of truth for what crosses a boundary.
  4. Fail at startup, not at 3 a.m. Duplicate channel names, unresolvable dependencies and circular references are all detected during bootstrap.
  5. Boundaries are documented, including the inconvenient ones. That is why this page exists and why the adapter matrix lists what each transport cannot do.