FlareHost

class FlareHost<TAdapter extends HostRuntimeAdapter<IFlareApp, LoggerTransportClass, HostRuntimeLifecycle, {}>, E extends readonly HostExtension<Record<never, never>>[] = readonly []>

Composition root of a Flare application. new FlareHost(adapter) returns the host plus any members the adapter stamps via extendHost.

How you get one

new FlareHost(adapter, extensions?)

Constructor

new FlareHost(adapter: TAdapter, extensions?: E): FlareHost

adapter TAdapter

extensions? E

Properties

http

http: HttpArc<AdapterLifecycle<TAdapter>>

logging

logging: Logging<AdapterTransportClass<TAdapter>>

ws

ws: WebSocketArc

WebSocket authoring surface: host.ws.route(path, opts?) and host.ws.controller(path, Class).

Accessors

config

get config(): Readonly<FlareConfig>

Resolved configuration produced from HostRuntimeAdapter.flareJsonFile, environment variables, and registered descriptor defaults.

returns Readonly<FlareConfig>

logger

get logger(): Logger

Framework logger, bootstrapped during build before any user-land service is instantiated.

returns Logger

Throws:

If accessed before build has compiled the logger.

runtime

get runtime(): HostRuntime

Runtime this host’s adapter targets.

returns HostRuntime

scopedServices

get scopedServices(): ScopedServicesView

Read-only view of the per-request service registry compiled from scoped registrations.

returns ScopedServicesView

singletonServices

get singletonServices(): ReadonlyMap<ServiceToken<FlareService>, FlareService>

Read-only view of the singleton service instances compiled from singleton registrations.

returns ReadonlyMap<ServiceToken<FlareService>, FlareService>

state

get state(): HostState

Current lifecycle state of the host. Use in health-check / readiness routes instead of probing framework internals.

returns HostState

Example:

host.http.get("/ready", () => {
  return host.state === "ready"
    ? new FlareResponse(200, { state: host.state })
    : new FlareResponse(503, { state: host.state });
});

Methods

build()

build(): FlareApp<TAdapter>

Compiles config, logger, validators, and DI registrations, then returns the runtime-specific app produced by HostRuntimeAdapter.createApp. Idempotent: a second call returns the cached app.

returns FlareApp<TAdapter>

Throws:

If any composite validator reports an error.

TODO(public-app-interface): Export a minimal public app interface (run/export/test entrypoints) so consumers can annotate host.build() without relying on inferred internal app classes.

cfg()

cfg(...tokens: ConfigToken<unknown>[]): this

Registers one or more config tokens with the host.

Every token declared in a class’s static config array must be registered here, or build will throw. Pre-defined framework tokens (HOST_CONFIG, LOG_CONFIG) are registered automatically.

...tokens ConfigToken<unknown>[]

returns this

scoped()

scoped<T extends FlareService>(service: ServiceClass<T>): void

Registers a per-request (scoped) service in the DI container.

The service is instantiated fresh for each request and disposed after the request completes. Use singleton for long-lived services.

service ServiceClass<T> · The service class to register.

Throws:

If the class is missing the required static deps array.

whenState()

whenState(state: HostState): Promise<void>

Resolves when the host reaches (or has already passed) the given lifecycle state.

States advance one way (starting -> ready -> draining -> stopped), so a waiter for a state the host is already past resolves immediately. Useful for graceful-shutdown coordination, e.g. deregistering from a load balancer the moment draining begins. On a runtime whose lifecycle never leaves "ready" (Cloudflare Workers), a "draining"/"stopped" waiter never resolves.

state HostState

returns Promise<void>

Example:

void host.whenState("draining").then(() => registry.deregister(instanceId));

Learn: Host