# @suaveplan/api-ws-broker-in-memory - In-memory single-host WebSocket broker for @suaveplan/api-ws. Implements WsBroker via direct in-process fan-out — publish iterates a topic->handlers map and invokes each subscriber's handler. Supports fire-and-forget and await-all delivery modes, idempotent dispose, Zod-validated options, and the WS_BROKER_IN_MEMORY.* error registry (INVALID_OPTIONS, BROKER_DISPOSED). Production-grade for single-host deployments; tests-grade for any plugin manifesting WebSocket endpoints. For multi-host fan-out use @suaveplan/api-ws-broker-redis (Stage 7).

Single-host in-process implementation of the `@suaveplan/api-ws`
`WsBroker` contract. Suitable for production single-host deployments
AND as the default broker wired into `createTestHost` ($2
kit). For multi-host fan-out use `@suaveplan/api-ws-broker-redis`
(Stage 7).

The broker maintains a per-topic `Set<handler>` registry and dispatches
every `publish(topic, envelope)` to every handler currently subscribed
to that topic. There is no network, no message bus, and no persistence —
"in-memory" describes the storage substrate, not the maturity level.

<!-- begin:auto-docs -->
## Documentation tree

- [broker](./src/broker/broker.md) — This module implements the `WsBroker` contract from `@suaveplan/api-ws` by maintaining an in-process `Map<topic, Set<ha…
  - [broker](./src/broker/broker.md) — This module implements the `WsBroker` contract from `@suaveplan/api-ws` by maintaining an in-process `Map<topic, Set<ha…
- [error-codes](./src/error-codes/error-codes.md) — This module defines the stable, namespaced error-code registry for the in-memory WebSocket broker. Every public failure…
  - [error-codes](./src/error-codes/error-codes.md) — This module defines the stable, namespaced error-code registry for the in-memory WebSocket broker. Every public failure…
- [options](./src/options/options.md) — This module owns the Zod-validated option shape consumed by `createInMemoryWsBroker`. Keeping it in a dedicated feature…
  - [options](./src/options/options.md) — This module owns the Zod-validated option shape consumed by `createInMemoryWsBroker`. Keeping it in a dedicated feature…
- [testing](./src/testing/testing.md) — This module exposes a small, opinionated test harness around the in-memory broker. It removes the boilerplate of wiring…
  - [testing](./src/testing/testing.md) — This module exposes a small, opinionated test harness around the in-memory broker. It removes the boilerplate of wiring…
<!-- end:auto-docs -->

## What ships

| Subpath | Module | Doc |
|---|---|---|
| `./broker` | `createInMemoryWsBroker(options?)` factory | [`src/broker/broker.md`](src/broker/broker.md) |
| `./error-codes` | `WS_BROKER_IN_MEMORY_CODES` + `WsBrokerInMemoryError` | [`src/error-codes/error-codes.md`](src/error-codes/error-codes.md) |
| `./testing` | `createInMemoryBrokerHarness(options?)` for tests | [`src/testing/testing.md`](src/testing/testing.md) |

## Surface

- `createInMemoryWsBroker(options?)` — factory returning an
  `InMemoryWsBroker` (the `WsBroker` contract plus
  `subscriberCount(topic)` and `isDisposed()` introspection helpers).
- `InMemoryWsBrokerOptions { deliveryMode? }` — Zod-validated strict
  option shape. `deliveryMode` is `"fire-and-forget"` (default) or
  `"await-all"`.
- `WS_BROKER_IN_MEMORY_CODES` — closed set of two stable codes:
  `INVALID_OPTIONS` and `BROKER_DISPOSED`.
- `createInMemoryBrokerHarness(options?)` — opinionated test harness
  wrapping the broker with a captured-envelope observer + idempotent
  teardown.

## Quickstart

```ts
import { createInMemoryWsBroker } from "@suaveplan/api-ws-broker-in-memory";
import type { TenantId } from "@suaveplan/api-types/tenant";

const broker = createInMemoryWsBroker<{ id: number }>();
const sub = broker.subscribe("orders", (envelope) => {
    console.log("delivered", envelope.payload.id);
});

await broker.publish("orders", {
    topic: "orders",
    tenant: "t1" as unknown as TenantId,
    payload: { id: 1 },
});

await sub.unsubscribe();
broker.dispose();
```

## Single-host vs multi-host

This package is **single-host only**. Two host replicas instantiated
with separate `createInMemoryWsBroker()` calls each see only their own
publishes; there is no shared substrate. For multi-host topologies use
`@suaveplan/api-ws-broker-redis` (Stage 7), which implements the same
`WsBroker` contract over Redis Pub/Sub.

## Quality bars

- 100% line / branch / function / statement coverage (Istanbul).
- 100% docs coverage — every implementation `.ts` has a sibling `.md`
  with the required headings.
- Zero direct imports of `vitest` / `bun:test` — all test files import
  from `@suaveplan/testing/runner`.
- Stable, namespaced error codes (`WS_BROKER_IN_MEMORY.*`).