Class ServerBuilder

Fluent builder for constructing and starting an HTTP server.

Example

const server = new ServerBuilder();

server
    .services(svc => svc.addSingleton(IDb, () => new Db()))
    .use(loggingMiddleware)
    .handle(GetUser, ({ params }) => db.find(params.id));

await server.listen(3000);

Index

Constructors

constructor

Methods

contentType getAuthenticationConfig getRegistrations getSubscriptionRegistrations getWebhooks handle handleAll listen services use useAuthentication useAuthorization useBatching useCors webhook withHealthcheck

Constructors

constructor

new ServerBuilder(options?: ServerOptions): ServerBuilder
Parameters
- options: ServerOptions = {}
Returns ServerBuilder
- Defined in libs/server/src/Server.ts:129

Methods

contentType

contentType(handler: ContentTypeHandler): this
Register an additional content type handler for content negotiation. JSON is registered by default.
Parameters
- handler: ContentTypeHandler
Returns this
- Defined in libs/server/src/Server.ts:171

getAuthenticationConfig

getAuthenticationConfig(): AuthenticationConfig | null
Returns the authentication configuration, or null if useAuthentication() has not been called.

Returns AuthenticationConfig | null
- Defined in libs/server/src/Server.ts:325

getRegistrations

getRegistrations(): readonly EndpointRegistration[]
Returns a snapshot of all registered endpoints. Useful for generating OpenAPI specs or other documentation.

Returns readonly EndpointRegistration[]
- Defined in libs/server/src/Server.ts:288

getSubscriptionRegistrations

getSubscriptionRegistrations(): readonly SubscriptionRegistration[]
Returns a snapshot of all registered WebSocket subscription endpoints. Consumed by @cleverbrush/server-openapi to emit the AsyncAPI spec.

Returns readonly SubscriptionRegistration[]
- Defined in libs/server/src/Server.ts:296

getWebhooks

getWebhooks(): readonly WebhookDefinition[]
Returns a snapshot of all registered webhook definitions. Consumed by @cleverbrush/server-openapi to emit the webhooks map.

Returns readonly WebhookDefinition[]
- Defined in libs/server/src/Server.ts:317

handle

handle<
    E extends
        EndpointBuilder<any, any, any, any, any, any, any, any, any, false>,
>(
    endpointDef: E,
    handler: Handler<E>,
    options?: EndpointOptions<E>,
): this
Register an endpoint and its handler.
Type Parameters
- E extends EndpointBuilder<any, any, any, any, any, any, any, any, any, false>
Parameters
- endpointDef: E
  An EndpointBuilder instance (e.g. from endpoint.get(...)).
- handler: Handler<E>
  The typed handler function.
- Optionaloptions: EndpointOptions<E>
  Optional per-endpoint middleware.
Returns this
- Defined in libs/server/src/Server.ts:241

handleAll

handleAll(mapping: HandlerMapping): this
Register all endpoints from a HandlerMapping created by mapHandlers. This is the bulk equivalent of calling .handle() for each endpoint individually.
Parameters
- mapping: HandlerMapping
  The mapping produced by mapHandlers(endpoints, handlers).
Returns this
- Defined in libs/server/src/Server.ts:262

listen

listen(port?: number, host?: string): Promise<Server>
Start listening on the given port and host. Resolves with the running Server instance.
Parameters
- Optionalport: number
  TCP port (default: ServerOptions.port ?? 3000).
- Optionalhost: string
  Bind address (default: ServerOptions.host ?? '0.0.0.0').
Returns Promise<Server>
- Defined in libs/server/src/Server.ts:336

services

services(configureFn: (svc: ServiceCollection) => void): this
Configure the DI service collection.
Parameters
- configureFn: (svc: ServiceCollection) => void
  Receives the ServiceCollection for registrations.
Returns this
- Defined in libs/server/src/Server.ts:138

use

use(middleware: Middleware): this
Add middleware to the matched-request pipeline after authentication. Middleware is executed in the order it is added. CORS short-circuits and unmatched routes do not enter this pipeline.
Parameters
- middleware: Middleware
Returns this
- Defined in libs/server/src/Server.ts:148

useAuthentication

useAuthentication(config: AuthenticationConfig): this
Enable authentication with one or more schemes. Registers middleware that authenticates protected requests and sets ctx.principal. CORS preflights are handled before this middleware.
Parameters
- config: AuthenticationConfig
Returns this
- Defined in libs/server/src/Server.ts:181

useAuthorization

useAuthorization(config?: AuthorizationConfig): this
Enable authorization enforcement. Registers a global middleware that checks endpoint authorize() metadata against the authenticated principal. Must be called after useAuthentication().
Parameters
- Optionalconfig: AuthorizationConfig
Returns this
- Defined in libs/server/src/Server.ts:192

useBatching

useBatching(options?: ServerBatchingOptions): this
Enable the server-side request batching endpoint.

Once enabled, the server accepts POST <path> (default /__batch) containing an array of sub-requests and processes each one through the full middleware and handler pipeline, returning an array of sub-responses in a single HTTP reply.

Pair this with the batching() middleware from @cleverbrush/client/batching on the client side.
Parameters
- options: ServerBatchingOptions = {}
  ServerBatchingOptions (all fields optional).
Returns this
Example
```
new ServerBuilder()
    .useBatching()
    .handleAll(mapping)
    .listen(3000);
```
- Defined in libs/server/src/Server.ts:229

useCors

useCors(options: ServerCorsOptions): this
Enable server-wide CORS before routing and authentication. Accepted preflights return 204 without running ordinary middleware. Requests with disallowed origins return 403 before handlers run. Configuration is validated and copied when the server starts listening.
Parameters
- options: ServerCorsOptions
Returns this
- Defined in libs/server/src/Server.ts:159

webhook

webhook(def: WebhookDefinition): this
Register a webhook definition.

Webhooks are recorded for OpenAPI spec generation only — they are not served as HTTP routes by the runtime server.
Parameters
- def: WebhookDefinition
  A WebhookDefinition created with defineWebhook.
Returns this
- Defined in libs/server/src/Server.ts:308

withHealthcheck

withHealthcheck(): this
Enable the GET /health endpoint that returns { ok: true } (200). Useful for load balancer and container readiness probes.

The path is available as HEALTHCHECK_PATH.

Returns this
- Defined in libs/server/src/Server.ts:203

Class ServerBuilder

Example

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns ServerBuilder

Methods

contentType

Parameters

Returns this

getAuthenticationConfig

Returns AuthenticationConfig | null

getRegistrations

Returns readonly EndpointRegistration[]

getSubscriptionRegistrations

Returns readonly SubscriptionRegistration[]

getWebhooks

Returns readonly WebhookDefinition[]

handle

Type Parameters

Parameters

Returns this

handleAll

Parameters

Returns this

listen

Parameters

Returns Promise<Server>

services

Parameters

Returns this

use

Parameters

Returns this

useAuthentication

Parameters

Returns this

useAuthorization

Parameters

Returns this

useBatching

Parameters

Returns this

Example

useCors

Parameters

Returns this

webhook

Parameters

Returns this

withHealthcheck

Returns this

Settings

On This Page