Event-driven Node.js framework

Node.js · TypeScript · Event-driven

Build modular, testable backends where controllers express intent, channels own side effects, and brokers carry the transport.

Get started Introduction GitHub

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

Built for a domain, not a framework

Keep domain behavior independent from transport, make side effects explicit, and let small primitives compose into the application you actually need.

Event-driven by default

Controllers never call business logic. They emit domain events; channels decide what happens next. Side effects become observable and replaceable.

One core, five transports

The HTTP layer has no server in it. Express, Fastify, Koa, Hono and node:http each implement the same contract, so the same controller, middleware and assertions produce the same results on all five.

Tiny primitives

The emitter is three methods and a couple of kilobytes. The broker adds channels, mesh networking and async watchers on top of it. Nothing is hidden.

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

Assert the events a controller emitted. Call a channel handler with a fake context. Because side effects live in channels, your suites stay small.

Extensible seam

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

How it fits together

One request, four clear responsibilities

Every request follows the same path. Each step has a single job, so you always know where a behavior lives and what to replace when it changes.

01Controller
Receives the context, expresses intent and replies. It performs no side effects.
ctx.call(‘db:product:all’)
02Typed event
The contract between the two sides. A renamed event or payload is a compile error.
EventTypes
03Channel
Owns the side effect: persistence, audit logs, notifications. Easy to fake in tests.
@Channel(‘db’)
04Broker
Carries the transport. Swap HTTP for another protocol without touching the domain.
ExpressBroker

Packages

Install only what you need

The ecosystem is split by responsibility, so the runtime stays small and your dependency graph stays understandable.

Browse packages →

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 generated

Every API reference, the HTTP guides, the adapter matrix and the changelogs are published from the Gland repositories themselves, on every build. A guide is written where the code is, and the site republishes it.

See how →

01HTTP layerOne core, five transports, and the differences between them.→02Event brokerChannels, mesh networking, watchers and every option.→03EmitterThree methods, wildcards, and the listener cache.→04ChangelogsRelease history and the changesets that have not shipped yet.→

The path

From first import to a real application

Start with the mental model, build the smallest working app, then go deeper into controllers, channels, modules and brokers.

01UnderstandWhat Gland is and why it is event-first.→02InstallSet up the runtime and your first module.→03BuildShip a complete product API with channels.→

Build your first Gland app in minutes

Install the packages, declare one event map and ship a complete product API with channels.

Get started Read the tutorial