skills/docs/api-stack/api/api-ws-bun/src/registry/connection-registry.md

registry

(no submodules)

Purpose

Wraps the api-ws contract's InMemoryConnectionRegistry to give the Bun engine a typed registry surface that the conformance harness can drive. The wrapper does not add data structures of its own — every method delegates to the inner registry — but it does expose the bus-integration helpers recordSubscription and dropSubscription so the Bun-specific subscription bus can keep its topic index hot.

The registry indexes connections by both connection id and tenant id, which is what powers the lookupByTenant fast path used by the broadcast fan-out.

Features

• Drop-in ConnectionRegistry implementation; passes the conformance suite directly.
• recordSubscription / dropSubscription exposed for the bus.
• raw accessor exposes the underlying InMemoryConnectionRegistry for the conformance harness factory.
• Tenant-bucket maps so countByTenant is O(1), powering the per-tenant cap enforcer.

Usage: Basic

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

const registry = new BunConnectionRegistry();
registry.add(conn);
console.log(registry.countByTenant(conn.tenantId));
registry.remove(conn);

Usage: Advanced

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

const registry = new BunConnectionRegistry();
const bus = new InMemorySubscriptionBus(registry.raw);
registry.add(conn);
bus.subscribe(conn, "orders");
// `registry.lookupByTopic("orders", conn.tenantId)` now returns [conn].

API Reference

• new BunConnectionRegistry() — constructor; no options.
• add(conn): void / remove(conn): void — lifecycle bookkeeping.
• lookupByTenant(tenant) / lookupByTopic(topic, tenant?) / countByTenant(tenant) — read-only lookups.
• recordSubscription(conn, topic, tenant) / dropSubscription(conn, topic, tenant) — bus integration.
• raw: InMemoryConnectionRegistry — escape hatch.

Implementation Notes

The wrapper class is deliberately thin: the engine wants to treat the registry as a Bun-engine concept (BunConnectionRegistry) for ergonomics, but at the implementation level the contract's InMemoryConnectionRegistry is the canonical data structure that the conformance harness exercises. Duplicating bookkeeping inside the wrapper would create two sources of truth.

The raw accessor exists for the conformance harness factory — runWsEngineConformance expects a ConnectionRegistry instance, but the in-memory subscription bus needs the concrete InMemoryConnectionRegistry so it can call recordSubscription. Exposing raw lets the factory hand the same underlying registry to both.