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

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
import type { EventTypes } from './shared/events.interface'
6

7
async function bootstrap() {
8
  const app = await GlandFactory.create(AppModule)
9
  const server = app.connectTo(ExpressBroker<EventTypes>)
10
  server.listen(3000, { message: 'API ready on :3000' })
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.

Protocol-agnostic

Transport lives in brokers. Run the same controllers and channels over HTTP today and over WebSocket or RPC tomorrow — only the adapter wiring changes.

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.

Gradually adoptable

Install only the packages you need and mount Gland channels next to your existing HTTP layer. 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 HTTP layer: route decorators, HttpContext, the HttpCore application surface and the HttpBroker.

Adapter

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

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