55 lines
2.8 KiB
Markdown
55 lines
2.8 KiB
Markdown
# `@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:
|
|
|
|
```ts
|
|
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.
|