`@suaveplan/api-router-in-memory` — In-memory Router for tests

Package: @suaveplan/api-router-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 host testing-utility kit (@suaveplan/api-host/testing) ships REAL, in-memory implementations of every capability — production-grade adapters that happen to keep state in process memory, not test doubles. api-router-in-memory is the router slot of that kit: a Router that dispatches via a fetch-shaped function call rather than a real HTTP listener. Tests run with zero network setup, deterministic timing, and the full pipeline (auth → tenant → validation → handler → response validation → telemetry close) exercised in-process.

The package is also a load-bearing reference: every adapter in Stage 4 runs the same runRouterConformance suite (§13.4); this adapter is the canonical in-memory pass — if it fails the suite, the suite itself is suspect.

What changes

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

ADDED: createInMemoryRouter(opts) — direct-surface factory returning a Router whose dispatch(request) runs the full pipeline synchronously-ish (Promise-returning) without binding a socket.
ADDED: host.fetch(method, path, init?) integration — the Router exposes a fetch-shaped entry point compatible with the createTestHost test ergonomics shown in §13.2.
ADDED: InMemoryRouterOptions — Zod schema (basePath?: string, trackRequests?: boolean (default true — record every request for assertion)).
ADDED: ROUTER_IN_MEMORY_* error codes (ROUTER_IN_MEMORY_NO_MATCH, ROUTER_IN_MEMORY_DUPLICATE_ROUTE, ROUTER_IN_MEMORY_INVALID_OPTIONS).
ADDED: Test-recording surface — router.requests returns an array of every request that landed (for assertions); router.reset() clears the history.
ADDED: Registration in @suaveplan/api-host/testing's adapter table as the default router adapter when callers pass router: "in-memory".

Out of scope

HTTP listener — by design.
Worker-proxy surface — Stage 5 adapters are direct-only; the conformance suite that lives in api-router/testing is also run against api-router-hono (which DOES ship both surfaces) so the proxy invariants are still pinned.
Streaming over network — the in-memory router supports ReadableStream body/response but no socket-level flushing semantics.

Source mapping

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

Requirement	Design doc section
Real in-memory impl, not a double	§13.2
`host.fetch` integration	§13.2
Request recording for assertions	§13.2 (implicit via `host.events.published` pattern)
Registered in `api-host/testing` adapter table	§15 Stage 5

Verification approach

src/factory/create-in-memory-router.test.ts — register routes, dispatch, recording, reset.
src/factory/create-in-memory-router.spec-conformance.test.ts — runRouterConformance("in-memory-direct", ...).
src/fetch-shape/fetch-shape.test.ts — host.fetch("POST", "/x", { body }) returns Response-shaped result with status / headers / body.
tests/integration/integration.test.ts — booted by createTestHost's default adapter table; end-to-end pipeline executed.

Migration impact

None — additive only.

3.5 KiB Raw Permalink Blame History

@suaveplan/api-router-in-memory — In-memory Router for tests

Why