`subscription`

(no submodules)

Purpose

Builds the per-engine subscription bus instance and binds it to the engine's connection registry. The bus implementation itself is InMemorySubscriptionBus from the contract package — there is no Bun-specific subscription algorithm — but constructing the bus requires the registry's raw accessor so the contract's bookkeeping (registry.recordSubscription) stays in lockstep with bus state.

Concentrating that wiring in a single factory means the engine module reads createBunSubscriptionBus(registry) instead of poking the registry's internal accessor inline.

Features

One-line construction with the correct registry plumb-through.
Generic over the payload type so plugins narrow Payload at engine instantiation time.
Cross-tenant broadcast denial inherited from the contract bus (the ws.broadcast-cross-tenant capability check).

Usage: Basic

import {
    BunConnectionRegistry,
    createBunSubscriptionBus,
} from "@suaveplan/api-ws-bun";

const registry = new BunConnectionRegistry();
const bus = createBunSubscriptionBus<{ ok: true }>(registry);

Usage: Advanced

import {
    BunConnectionRegistry,
    createBunSubscriptionBus,
} from "@suaveplan/api-ws-bun";

const registry = new BunConnectionRegistry();
const bus = createBunSubscriptionBus(registry);
registry.add(conn);
bus.subscribe(conn, "orders", { tenant: conn.tenantId });
const delivered = bus.broadcast(
    { tenant: conn.tenantId, capabilities: new Set() },
    "orders",
    { tenant: conn.tenantId, payload: { ok: true } }
);

API Reference

createBunSubscriptionBus<Payload>(registry): SubscriptionBus<Payload> — builds an InMemorySubscriptionBus bound to the registry.

Implementation Notes

The factory does not currently inject any custom subscribers — every broadcast flows through bus.send(connection, ...) which the contract implements as connection.send(envelope). If a future engine needs per-broadcast OTel instrumentation, the right place to hook it is inside the engine's Connection.send adapter, not by forking the bus.

The return type is the abstract SubscriptionBus interface (not InMemorySubscriptionBus) so consumers cannot rely on bus internals. The engine relies only on the contract surface, and that's what the public type advertises.

2.4 KiB Raw Blame History

subscription