`./testing` — RESERVED subpath

(no submodules)

Purpose

@suaveplan/api-host/testing is a reserved subpath in API plugin system. The intent is to populate it with createTestHost + the in-memory adapter wiring (api-router-in-memory, api-auth-in-memory, api-db-sqlite-memory, etc.). Stage 2 ships an intentionally-empty surface so downstream packages can declare a peer-dep on the documented path today, and bundler / TypeScript resolution succeeds before the helper actually exists. The package's primary build does not have to wait on The test harness.

The single named export, STAGE_2_RESERVED, is a sentinel marker — Stage 5 will replace it with the populated createTestHost API while keeping the same subpath. Probes that need to discriminate "reserved-but-empty Stage 2 release" from "Stage 5 populated surface" can branch on STAGE_2_RESERVED === true.

Features

Stable subpath export — @suaveplan/api-host/testing resolves in every release ≥ 0.1.0.
Single named sentinel (STAGE_2_RESERVED) so the surface has zero runtime side effects.
Type-checked at consumer build time without a runtime dependency on the host's drivers.
Documented promotion path — Stage 5 replaces the sentinel with the real harness.

Usage: Basic

import { STAGE_2_RESERVED } from "@suaveplan/api-host/testing";

if (STAGE_2_RESERVED) {
    // Hosting environment is on the reserved-but-empty Stage-2 release.
    throw new Error(
        "api-host/testing requires Stage-5 helpers — install once they ship."
    );
}

Usage: Advanced

A downstream package that wants to consume the helper as soon as Stage 5 ships can declare an optional peer-dep on the subpath and gate-import it at runtime:

// in package.json
// "peerDependencies": { "@suaveplan/api-host": "^0.1.0" }
// "peerDependenciesMeta": { "@suaveplan/api-host": { "optional": true } }

// in code
const { STAGE_2_RESERVED, createTestHost } = (await import(
    "@suaveplan/api-host/testing"
)) as typeof import("@suaveplan/api-host/testing") & {
    createTestHost?: () => unknown;
};

if (!STAGE_2_RESERVED && createTestHost !== undefined) {
    const host = createTestHost();
    // ...
}

API Reference

const STAGE_2_RESERVED: true — sentinel; replaced with false (and populated exports) .
type Stage2Reserved = typeof STAGE_2_RESERVED — kept stable so Stage 5 can layer in real types on the same path.

Implementation Notes

The empty placeholder is not a stub. It is a deliberate subpath reservation documented in the proposal (§What changes → ./testing) so consumers do not race ahead of Stage 5 and re-implement the helper out-of-tree. Replacing it later is a non-breaking change: the runtime surface grows, the type surface widens, and the sentinel flips from true to false. No consumer that wires only on the sentinel needs to update.

2.9 KiB Raw Blame History

./testing — RESERVED subpath