API REFERENCE

ServerApp

import { ServerApp, bootstrap } from '@rasenganjs/server';

Core application class — orchestrates module registration, middleware layering, dependency injection, validation, and compilation into a runtime Futon. Normally configured through bootstrap()'s callback rather than constructed directly.

Modules & Plugins

MethodSignatureDescription
registerModule(mod)(ModuleConfig | (() => ModuleConfig)) => voidRegister a module or module factory
registerPlugin(plugin)(ModulePlugin) => voidClaim a ModuleConfig extension key (e.g. 'gateways')

Middleware

MethodSignatureDescription
use(middleware)(Middleware) => voidRegister global middleware
enableCors(options?)(CORSOptions?) => voidEnable CORS (Futon's cors() options)

Error / 404 Handlers

MethodSignatureDescription
onError(handler)((error: Error, ctx: Context) => Promise<Response>) => voidGlobal error handler (default: 500 response)
notFound(handler)((ctx: Context) => Promise<Response>) => void404 handler (default: plain-text "Not Found")

WebSockets

MethodSignatureDescription
websocket(path, handlers)(string, WebSocketHandlers) => voidRegister a low-level WebSocket route (RFC-0001)
getWebSocketRegistry()() => WebSocketRegistry | nullThe built registry, null until compile() has run

Validation

configureValidation(config: Partial<ValidationConfig>): void

Sets the schema adapter and/or default error handler. Defaults to zodAdapter + a 400 JSON error handler.

App Lifecycle

MethodSignatureDescription
onInit(handler)(() => void | Promise<void>) => voidRuns once before the server accepts requests
onDestroy(handler)(() => void | Promise<void>) => voidRuns during graceful shutdown

Compilation

compile(): Futon
getBuildSummary(): BuildSummary | null
close(): Promise<void>

compile() flattens the module tree, registers providers with module-scoped visibility, registers every controller's routes with the correct middleware nesting, and returns the resulting Futon. Called internally by bootstrap() — you don't normally call it yourself.

BuildSummary
interface BuildSummary {
  modules: ModuleSummary[];
  durationMs: number;
}
 
interface ModuleSummary {
  name: string;
  prefix?: string;
  routes: Array<{ method: string; path: string }>;
  providers: string[];
  pluginGroups: Record<string, string[]>; // keyed by plugin extension key, e.g. "gateways"
  middlewareCount: number;
}

bootstrap()

function bootstrap(
  callback: (app: ServerApp) => void | Promise<void>,
  overrides?: Partial<RasenganServerConfig>
): Promise<ServerHandle>;
 
interface ServerHandle {
  close(): void;
  app: ServerApp;
}

The recommended entry point — creates a ServerApp, loads config, runs your callback, compiles, then selects and starts the matching runtime adapter. Returns a handle for programmatic shutdown.

Database (Drizzle)
Controller