skills/plugins/document-navigator/docs/api-stack/api/api-router/README.md

@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