@orkestrel/server

A typed HTTP server for the @orkestrel line: a node-bound Server lifecycle entity that composes a middleware onion around a consumed @orkestrel/router dispatcher, beside the HTTPError vocabulary and a shared substrate for cookies, WebCrypto tokens, content negotiation, ETag and Range, security headers, Server-Sent Events, and the body pipeline.

Hand createServer a dispatcher and a per-request state factory, call start(), and call stop() when the process winds down. Built to sit beside @orkestrel/router (routing, matching, and dispatch), @orkestrel/contract (validation), @orkestrel/emitter (observable lifecycle), and @orkestrel/abort (cancellation). Part of the @orkestrel line.

Install

npm install @orkestrel/server

Requirements

• Node.js >= 22.12.0, matching the engines field in package.json
• ESM and CommonJS builds

Usage

import type { MiddlewareHandler } from '@orkestrel/server'
import { createServer } from '@orkestrel/server'
import { createDispatcher } from '@orkestrel/router'

interface State {
	readonly requestId: string
}

const dispatcher = createDispatcher<State>()
dispatcher.add({
	method: 'GET',
	path: '/users/:id',
	handler: (_request, context) =>
		Response.json({ id: context.params.id, requestId: context.state.requestId }),
})

const withRequestId: MiddlewareHandler<State> = async (_request, context, next) => {
	const response = await next()
	response.headers.set('X-Request-ID', context.state.requestId)
	return response
}

const server = createServer<State>({
	dispatcher,
	state: () => ({ requestId: crypto.randomUUID() }),
	middleware: [withRequestId],
})
const port = await server.start()
await server.stop()

A route handler reads context.state exactly as middleware wrote it — the composed onion terminates in the dispatcher, so there is no second plumbing layer between the middleware seam and the router. The package also exports HTTPError and its subclasses, the compose middleware primitive, cookie/token/body helpers, Negotiator for content negotiation, and createStream for Server-Sent Events.

Guide

For the full surface — the middleware seam, HTTPError vocabulary, shared substrate (cookies, tokens, negotiation, ETag/Range, security headers, SSE, body pipeline), and the Server lifecycle entity — see guides/server.md.

Package

Published as a single entry point per the exports field in package.json.

License

MIT © Orkestrel — see LICENSE.