@suaveplan/api-router — contract package for the Suaveplan API plugin system. Defines the abstract Router interface (verb methods + use + mount + match), Request / Response host-side shapes, Zod-validated RouteOptions schema, Middleware composition helpers with insertion-point guard, RouteMatch shape, BlueGreenSlot interface for hot-reload, the frozen ROUTER_CODES registry, and the runRouterConformance harness every concrete adapter must pass.

Stage-1 contract package for the Suaveplan API plugin system.

This package defines the abstract Router interface, the host-side Request / Response shapes, the Zod-validated RouteOptions schema, the Middleware composition contract with insertion-point guard, the RouteMatch shape, the BlueGreenSlot interface backing hot reload, the frozen ROUTER_CODES registry, and the runRouterConformance harness every concrete adapter must pass.

The reference in-memory Router and InMemoryBlueGreenSlot implementations ship here so the conformance harness is self-checking and Stage-1 consumers have a working router before any concrete adapter lands.

Documentation tree

error-codes — The error-codes module is the single source of truth for every failure class this package surfaces. It exports the fr…
- error-codes — The error-codes module is the single source of truth for every failure class this package surfaces. It exports the fr…
middleware — The middleware module defines the onion-model Middleware contract and the composeMiddleware builder. Every adapte…
- insertion-point — The insertion-point module enforces the security invariant from design doc §6: plugin-supplied middleware is allowed…
- middleware — The middleware module defines the onion-model Middleware contract and the composeMiddleware builder. Every adapte…
request — The request module defines the host-side RouterRequest shape — the post-parse, post-validation view that route hand…
- request — The request module defines the host-side RouterRequest shape — the post-parse, post-validation view that route hand…
response — The response module provides the host-side RouterResponse shape and a fluent ResponseBuilder that adapters serial…
- response — The response module provides the host-side RouterResponse shape and a fluent ResponseBuilder that adapters serial…
route-match — The route-match module defines RouteMatch, the shape every concrete adapter yields after resolving an incoming `(me…
- route-match — The route-match module defines RouteMatch, the shape every concrete adapter yields after resolving an incoming `(me…
route-options — The route-options module is the Zod-validated boundary for every per-route configuration block. It widens the minimal…
- route-options — The route-options module is the Zod-validated boundary for every per-route configuration block. It widens the minimal…
router — The router module defines the abstract Router — the verb-method surface (get / post / put / patch / `delete…
- router — The router module defines the abstract Router — the verb-method surface (get / post / put / patch / `delete…
slot — The slot module defines BlueGreenSlot — the per-plugin atomic mount point that backs hot-reload. It exposes three p…
- slot — The slot module defines BlueGreenSlot — the per-plugin atomic mount point that backs hot-reload. It exposes three p…
testing — The testing/conformance module exports runRouterConformance(factory) — the canonical conformance harness every conc…
- pipeline-router-conformance — runPipelineRouterConformance(factory) is the canonical contract suite every concrete PipelineRouter adapter MUST pa…
  - pipeline-router-conformance — runPipelineRouterConformance(factory) is the canonical contract suite every concrete PipelineRouter adapter MUST pa…
- conformance — The testing/conformance module exports runRouterConformance(factory) — the canonical conformance harness every conc…

Status

Version: 0.1.0
Stage: 1 (Contracts) — see umbrella design.
Dependents: none yet (host wires this in).

Install

bun add @suaveplan/api-router

Modules

router — abstract Router + reference in-memory implementation.
request — host-side RouterRequest + MapHeaders.
response — RouterResponse + fluent builder.
route-options — Zod-validated RouteOptions.
middleware — onion-model Middleware + composeMiddleware.
middleware/insertion-point — pipeline-step guard.
route-match — RouteMatch shape + factory.
slot — BlueGreenSlot interface + in-memory reference impl.
error-codes — ROUTER_CODES + RouterError.
testing/conformance — runRouterConformance adapter harness.

Error codes

The five frozen codes (every one thrown by a production path):

ROUTER.ROUTE_COLLISION
ROUTER.INVALID_PREFIX
ROUTER.MIDDLEWARE_INSERTION_DENIED
ROUTER.SLOT_FLIP_FAILED
ROUTER.SLOT_DISPOSE_TIMEOUT

Subpath exports

Every module has its own subpath export so consumers tree-shake to exactly what they import:

import { Router } from "@suaveplan/api-router/router";
import { composeMiddleware } from "@suaveplan/api-router/middleware";
import { parseRouteOptions } from "@suaveplan/api-router/route-options";
import { runRouterConformance } from "@suaveplan/api-router/testing";

Verification

bunx turbo lint typecheck test --filter=@suaveplan/api-router — green.
bunx turbo test:coverage --filter=@suaveplan/api-router — 100/100/100/100.
bunx turbo build --filter=@suaveplan/api-router — green.

License

MIT