WebSocketChannels

class WebSocketChannels extends FlareService

Framework service for publishing to WebSocket channels from OUTSIDE a connection: an HTTP handler, a timer, any code in the same broadcast domain. Inject it like any service; each execution context seeds the instance bound to ITS OWN domain, so the same handler code publishes correctly everywhere:

• Node: the host process’s channel registry (the domain every Node WS connection joins).
• Durable Object instance: that instance’s unified channel index (resident + hibernating connections).
• Plain Cloudflare Worker: NO domain exists (workerd pins each connection to the request that accepted it), so host.build() fails when a front-door route can reach this service, and the seeded backstop throws the same guidance at runtime.

The bytes are sent raw: a cross-context publisher has no route outgoing schema, so a channel’s message shape is the domain-wide convention you own.

How you get one

new WebSocketChannels(container, backend?)

Constructor

new WebSocketChannels(container: Container, backend?: IWsChannelDomain): WebSocketChannels

container Container · The service container for dependency resolution.

backend? IWsChannelDomain · Optional only to satisfy FlareServiceClass's one-argument construct signature; every real instance is seeded by a runtime adapter with its context's broadcast domain, and absence fails loudly at construction rather than silently publishing nowhere.

Properties

config

config: readonly ConfigToken<unknown>[]

Declares the config tokens this class requires.

Parallel to static deps. When declared, this.config(token) validates that the token is in this array before resolving, identical to how this.inject(token) validates static deps.

deps

deps: readonly []

Declares the service tokens this class is allowed to inject().

Tokens not listed here cause inject() to throw at the call site, naming both the class and the offending token.

Methods

config()

config<T>(token: ConfigToken<T>): T

Resolves a typed config section by token.

Mirrors inject() + static deps: the class must declare a static config array, and the requested token must appear in it. Both checks throw a developer-facing error when violated.

token ConfigToken<T>

returns T

Example:

class DbService extends FlareService {
  static config = [DbConfig];

  async onStart() {
    const { url } = this.config(DbConfig);
  }
}

Throws:

When the class has no static config declaration.

Throws:

When the token is not present in static config.

dispose()

dispose(): void | Promise<void>

Called at the end of every request for scoped services, whether the handler succeeded or threw.

This is a correctness boundary: the framework waits for any returned promise before completing the request pipeline. Use it for per-request cleanup that must finish, such as rolling back transactions, releasing locks, or closing cursors.

If a service wants fire-and-forget background work, schedule that work inside dispose() and return void. Implies scoped lifetime: declaring this on a singleton class throws at build() time.

returns void | Promise<void>

inject()

inject<T extends FlareService>(token: ServiceToken<T>): Injected<T>

Resolves a dependency declared on static deps, returning the service with framework members hidden from its static type.

token ServiceToken<T>

returns Injected<T>

Throws:

When the token is not present in this class’s static deps array.

onStart()

onStart(): void | Promise<void>

Called once when a singleton service starts (FlareApp.start()).

Not called for scoped services.

returns void | Promise<void>

onStop()

onStop(): void | Promise<void>

Called once when a singleton service stops (FlareApp.stop()).

Not called for scoped services.

returns void | Promise<void>

publish()

publish(channel: string, message: string | Uint8Array): void

Publishes message to every connection subscribed to channel in this context’s broadcast domain.

channel string

message string | Uint8Array

Throws:

When this context has no broadcast domain (the plain-Worker case above).

Learn: Channels and broadcast