Documentation

Node.js · TypeScript · Event-driven

Learn Gland in three passes — what it is, how to build an application, and how the packages work.

npm install @glandjs/core @glandjs/common @glandjs/events @glandjs/http @glandjs/node

3method emitter
0runtime deps in the emitter
MITlicensed

product.controller.ts

1
import { Controller } from '@glandjs/common'
2
import { Get } from '@glandjs/http'
3
import type { ExpressContext } from '@glandjs/express'
4
import type { EventTypes } from '../shared/events.interface'
5

6
@Controller('products')
7
export class ProductController {
8
  @Get()
9
  async list(ctx: ExpressContext<EventTypes>) {
10
    const products = await ctx.call('db:product:all', {})
11
    return ctx.send({ products })
12
  }
13
}

Controllers reply. They never touch the database.

db.channel.ts

1
import { Channel, On } from '@glandjs/common'
2
import type { Product } from '../shared/events.interface'
3

4
@Channel('db')
5
export class Database {
6
  private products = new Map<string, Product>()
7

8
  @On('product:all')
9
  async allProducts(): Promise<Product[]> {
10
    return Array.from(this.products.values())
11
  }
12
}

Channels own side effects, addressed as db:product:all.

main.ts

1
import 'reflect-metadata'
2
import { GlandFactory } from '@glandjs/core'
3
import { ExpressBroker } from '@glandjs/express'
4
import { AppModule } from './app.module'
5

6
async function bootstrap() {
7
  const { app, shutdown } = await GlandFactory.create(AppModule)
8
  const http = app.connectTo(ExpressBroker)
9
  http.listen(3000)
10
  await http.ready()
11
}
12
void bootstrap()

Brokers carry the transport. Swap the adapter, keep the app.

Why Gland?

Gland separates what your application does from how it is transported. A controller receives an interaction and emits a domain event. A channel subscribes to that event and performs the side effect. A broker connects the two to a real protocol.

That single idea produces a codebase where business logic can be tested without an HTTP server, where the same domain code runs over more than one transport, and where adding a new endpoint never means rewriting a service.

Event-driven by default

Controllers never call business logic directly. They emit a domain event, and channels decide what happens. Side effects become observable, replaceable and testable.

One core, five transports

The HTTP layer contains no server, no router and no framework import. Express, Fastify, Koa, Hono and node:http each implement the same contract, and the same controller runs unchanged on all five.

Tiny primitives

The emitter is three methods and a couple of kilobytes. The broker adds channels, meshes and watchers on top of it. Nothing is hidden from you, and there is nothing to unlearn.

TypeScript-first

Event names and payload shapes live in one typed map. A renamed event or a changed payload is a compile error, not a production incident.

Testable by construction

A controller test asserts the events it emitted. A channel test calls a handler with a fake context. Because side effects are concentrated in channels, test suites stay small.

Extensible seam

Adding a transport means implementing one abstract adapter and its context. Because a broker is just a class, WebSocket or RPC is the same exercise — and there is no big-bang migration.

Start here

New to GlandRead the four primitives, then follow First steps to build a working API.

Migrating an existing appModules and channels map onto the composition boundaries you already have.

Need the referenceOne page per package, with the exact exported surface.

Adding a transportWrite your own protocol adapter by extending BrokerAdapter.

Writing testsTest channels directly, and controllers by asserting emitted events.

Tuning performanceWhere the time actually goes, and the handful of knobs that matter.

The package family

Gland is a set of small, independently installable packages. Adopt only what you need.

Runtime

The dependency-injection container, module bootstrap, lifecycle hooks and the Context base class.

Decorators

The decorators and metadata keys that make up the DSL: Module, Controller, Channel, On and Inject.

Eventing

The namespaced event broker: channels, mesh networking, request/response calls and async watchers.

Primitive

A zero-dependency, tree-routed event emitter with wildcard matching. Three methods, nothing else.

Protocol

The framework-agnostic HTTP core: route decorators, HttpContext, the middleware onion, HttpCore and the HttpBroker.

Adapter

The Express 5 adapter. Wires Gland controllers and channels to a real HTTP server.

Adapter

The Fastify 5 adapter, with the middleware onion composed into a single real hook.

Adapter

The Koa 3 adapter: a native router, native extended verbs and a real promise onion.

Adapter

The Hono 4 adapter, running on Node and on the edge through the Fetch API.

Adapter

The node:http adapter: the reference implementation of the contract, with no framework and no dependencies.

From the repositories

The long documentation is not written here. Every API reference, the HTTP guides, the adapter matrix and the changelogs are published from the Gland repositories themselves on every build, so they cannot disagree with the code.

How the sync worksWhich repository feeds which page, where the text comes from, and how to publish a new document.

HTTP guidesGetting started, the context, middleware, replies, errors and CORS — one core, five transports.

Adapter matrixWhat each of Express, Fastify, Koa, Hono and node:http can and cannot do.

Writing an adapterBuild a sixth transport from the contract.

Recent releases

Versions below are read from each repository’s package.json when this page was built, not typed by hand.

@glandjs/emitter 1.1.5

Tree-based storage, a hot-path LRU cache, and a CommonJS build for broader tooling support. Read the changelog

@glandjs/events 2.0.0

send() carries a payload, a channel’s watch() settles, and the call strategies are 'all' or nothing. Read the changelog

@glandjs/http 2.0.0

One framework-agnostic core and a pluggable adapter per server, so the same controller runs on Express, Fastify, Koa, Hono and node:http. Read the changelog

@glandjs/core 2.0.0

The DI container, module bootstrap, lifecycle hooks and the Context base class. Read the changelog