`@suaveplan/api-events-in-memory` — In-memory events bus for tests

Package: @suaveplan/api-events-in-memory Status: PROPOSED Type: new-package Stage: 5 (Testing kit + conformance suites) — see umbrella openspec/changes/api-plugin-foundation/

Why

Per design doc §13.2, the testing kit needs an events bus whose publish calls are recordable so tests can assert side effects:

expect(host.events.published("billing.invoice.created")).toHaveLength(1);

The simplest correct implementation wraps @suaveplan/events (production-grade pub/sub) with a recording layer. Subscribers fire as usual; publish history is queryable; ordering and idempotency invariants from the real bus are preserved. No mocks, no test doubles.

What changes

Net-new package depending on @suaveplan/api-events (contract + ./testing conformance), @suaveplan/api-types, @suaveplan/events (production bus), @suaveplan/error, zod.

ADDED: createInMemoryEventsBus(opts) — factory returning an EventBusLike (per @suaveplan/api-types) wrapping @suaveplan/events's createEventBus.
ADDED: host.events.published(topic) — returns an array of every payload published to topic since reset() (or since construction).
ADDED: host.events.reset() — clears the publish history (subscribers remain registered).
ADDED: InMemoryEventsBusOptions — Zod schema (maxHistoryPerTopic?: number (default 1000 — guard against runaway tests)).
ADDED: EVENTS_IN_MEMORY_* error codes (EVENTS_IN_MEMORY_HISTORY_OVERFLOW, EVENTS_IN_MEMORY_INVALID_OPTIONS).
ADDED: Registered in @suaveplan/api-host/testing's adapter table as events: "in-memory".

Out of scope

Persistence across process restarts — by design, in-memory.
Multi-host fan-out — api-events-redis future work.
Bounded-queue backpressure — @suaveplan/events already provides this; this adapter inherits the behaviour and runs the bounded-queue conformance scenarios from api-events/testing.

Source mapping

Genesis-original. Source of design intent: docs/superpowers/specs/2026-05-13-api-plugin-foundation-design.md.

Requirement	Design doc section
`host.events.published(topic)` query	§13.2
Real bus underneath, not a double	§13.2 (final paragraph)
Registered in `api-host/testing` adapter table	§15 Stage 5

Verification approach

src/factory/create-in-memory-events-bus.test.ts — publish/subscribe, history capture, reset, ordering preserved.
src/factory/create-in-memory-events-bus.spec-conformance.test.ts — runEventsBusConformance("in-memory-direct", ...).
src/history/history.test.ts — overflow protection at maxHistoryPerTopic.
tests/integration/integration.test.ts — via createTestHost; assertion API from §13.2 example works end-to-end.

Migration impact

None — additive only.

2.8 KiB Raw Permalink Blame History

@suaveplan/api-events-in-memory — In-memory events bus for tests

Why