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.
The claim being examined
Section titled “The claim being examined”“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.
What it genuinely does better
Section titled “What it genuinely does better”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.
Named capability, resolved at runtime
Section titled “Named capability, resolved at runtime”@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().
The boundary it does not cross
Section titled “The boundary it does not cross”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.
What a service class does instead
Section titled “What a service class does instead”@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”.
Compared to Nest
Section titled “Compared to Nest”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.
What Gland is not for
Section titled “What Gland is not for”- 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.
A decision rule
Section titled “A decision rule”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.
Design commitments
Section titled “Design commitments”These are the rules the codebase is held to. They are the reason the API is small.
- No hidden behaviour. A method does one thing, and the docs can state what that thing is without a caveat.
- Composition over configuration. New capabilities are new packages or channels, never new switches on existing ones.
- Types are the contract. One event map is the single source of truth for what crosses a boundary.
- Fail at startup, not at 3 a.m. Duplicate channel names, unresolvable dependencies and circular references are all detected during bootstrap.
- Boundaries are documented, including the inconvenient ones. That is why this page exists and why the adapter matrix lists what each transport cannot do.
- What is Gland? — the four primitives, precisely
- Channels — the unit of composition
- The event map —
IOEvent, and the broker API including its edges - The HTTP layer — one core, five transports
- The adapter matrix — what each transport cannot do
- Writing a broker — the seam is eleven lines of
abstract