@nextrush/types 3.0.6 → 4.0.0-beta.0

package/README.md

@@ -1,400 +1,388 @@
 # @nextrush/types
 
-> Shared TypeScript type definitions for the NextRush framework.
+> The shared TypeScript contracts every NextRush package is built on — `Context`, `Middleware`, the router, DI, extension, adapter, runtime, and streaming shapes — with zero runtime dependencies.
 
-## The Problem
+[![npm version](https://img.shields.io/npm/v/@nextrush/types.svg)](https://www.npmjs.com/package/@nextrush/types)
+[![downloads](https://img.shields.io/npm/dm/@nextrush/types.svg)](https://www.npmjs.com/package/@nextrush/types)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/@nextrush/types.svg)](https://bundlephobia.com/package/@nextrush/types)
+[![types](https://img.shields.io/npm/types/@nextrush/types.svg)](https://www.npmjs.com/package/@nextrush/types)
+[![ESM only](https://img.shields.io/badge/module-ESM--only-blue.svg)](https://nodejs.org/api/esm.html)
+[![license](https://img.shields.io/npm/l/@nextrush/types.svg)](https://github.com/0xTanzim/nextRush/blob/main/LICENSE)
 
-Backend frameworks often have types scattered across packages. This creates:
+|  |  |
+| --- | --- |
+| **Purpose** | The single source of truth for NextRush's cross-package TypeScript contracts (`Context`, `Middleware`, `Router`, `Container`, `Extension`, adapter/runtime/stream shapes) |
+| **Package type** | Core |
+| **Status** | Stable ✅ |
+| **Included in `nextrush`?** | ✅ Yes — the contracts reach app code transitively (`createApp()` returns a typed `Context`). Install directly only when authoring a package that needs the shapes without a heavier dependency. |
+| **Support tier** | Public — core (stable, semver-guarded) — see [ADR-0005](https://github.com/0xTanzim/nextRush/blob/main/docs/adr/ADR-0005-package-tiers-sealed-surface-deprecation.md) |
+| **Maintenance** | Active |
+| **Runtime** | Universal — Node · Bun · Deno · Edge |
+| **Requires** | Node `>=22` · ESM-only · TypeScript `>=5.x` |
+| **Introduced** | `v3.0.0` |
 
-- Circular dependencies between packages
-- Inconsistent interfaces across the ecosystem
-- Difficulty extending or augmenting types
+## Highlights
 
-## How NextRush Approaches This
+- ✅ **Zero runtime dependencies** — the root of the package graph; it imports nothing
+- ✅ **Near-zero runtime footprint** — only four constant value exports (`HTTP_METHODS`, `HttpStatus`, `ContentType`, `ROUTE_METADATA`); every other export is a type, erased at build
+- ✅ **ESM-only**, tree-shakable, side-effect-free (`"sideEffects": false`)
+- ✅ **Fully typed** — strict TypeScript, zero `any`; structural stream interfaces avoid coupling to any runtime
+- 📦 **Bundle:** ~1 KB min+gzip (the four constants)
 
-`@nextrush/types` is the **single source of truth** for all NextRush types:
+<details>
+<summary><strong>Table of contents</strong></summary>
 
-- **Zero dependencies**: Pure TypeScript definitions
-- **Zero runtime code**: Only exports types and constants
-- **Foundation package**: All NextRush packages depend on this
+[The problem](#the-problem) · [When to use](#when-to-use) · [Installation](#installation) · [Quick start](#quick-start) · [Capabilities](#capabilities) · [Mental model](#mental-model) · [Common tasks](#common-tasks) · [API overview](#api-overview) · [Options](#options) · [Compatibility](#compatibility) · [Troubleshooting](#troubleshooting) · [FAQ](#faq) · [Package relationships](#package-relationships) · [Architecture](#architecture) · [Resources](#resources)
+
+</details>
+
+---
+
+## The problem
+
+In a 30+ package framework, the same `Context` object is read by the core middleware engine, populated by the router, extended by adapters, and consumed by every piece of middleware. If each package declared its own version of that shape, they would drift, packages would import each other only to borrow a type, and the dependency graph would grow cycles.
+
+```ts
+// TODAY, without a shared contract package — each layer redeclares the shape,
+// and the definitions drift the moment one changes:
+
+// in @nextrush/router
+interface Context { params: Record<string, string>; /* … */ }
+
+// in a middleware package
+interface Context { params: object; body: any; /* … slightly different, and now `any` leaked */ }
+
+// the router imports the middleware package (or vice versa) solely to reuse a type → a cycle waiting to happen
+```
+
+`@nextrush/types` fixes this by owning the contracts in one place, at the bottom of the package hierarchy. Every higher package imports the *same* `Context`, `Middleware`, and `Router` shapes; nothing has to import sideways to share a type; and because the package sits below everything else, it can never introduce a cycle.
+
+## When to use
+
+`@nextrush/types` is the foundation layer — you consume its contracts constantly, usually without importing it by name. `createApp()` already hands you a typed `Context`, and `nextrush` / `@nextrush/core` re-export the everyday shapes.
+
+**Use `@nextrush/types` if:**
+
+- ✓ You're authoring a NextRush **package, adapter, or middleware** and need the shared `Context` / `Middleware` / `Router` / `Container` contracts without pulling in a heavier package
+- ✓ You're building an **adapter** and need the `ServerAdapter` / `FetchAdapter` / `AdapterContext` conformance shapes
+- ✓ You're writing a **framework-agnostic** utility that should type against the contract, not a concrete implementation
+- ✓ You want the runtime constants `HttpStatus`, `HTTP_METHODS`, `ContentType`, or the `ROUTE_METADATA` symbol
+
+**Reach for something else if:**
+
+- ✗ You're building an application — you already get these types through [`nextrush`](../nextrush) / [`@nextrush/core`](../core); you rarely import from here directly
+- ✗ You need HTTP **error classes** → use [`@nextrush/errors`](../errors) (it depends on these types)
+- ✗ You need the router **implementation**, not its interface → use [`@nextrush/router`](../router)
+
+---
 
 ## Installation
 
 ```bash
 pnpm add @nextrush/types
+# npm i @nextrush/types · yarn add @nextrush/types · bun add @nextrush/types
 ```
 
-## Quick Start
+> [!NOTE]
+> Already using `nextrush`? The contracts you touch daily — `Context`, `Middleware`, `HttpStatus`,
+> and friends — are reachable transitively; `createApp()` returns a typed `Context` without a direct
+> import. Install `@nextrush/types` only when you're authoring a package/adapter/middleware and want
+> to depend on the contract explicitly.
+
+## Quick start
 
-```typescript
-import type { Context, Middleware, Plugin } from '@nextrush/types';
-import { HttpStatus, ContentType } from '@nextrush/types';
+```ts
+import type { Context, Middleware } from '@nextrush/types';
+import { HttpStatus } from '@nextrush/types';
 
-const middleware: Middleware = async (ctx, next) => {
-  ctx.status = HttpStatus.OK;
+// A framework-agnostic middleware typed against the shared contract.
+// It reads and writes the SAME Context every NextRush package agrees on.
+export const requestId: Middleware = async (ctx: Context, next) => {
+  ctx.set('X-Request-Id', crypto.randomUUID());
   await next();
+  if (!ctx.responded) {
+    ctx.status = HttpStatus.NO_CONTENT; // 204, from the shared constant
+  }
 };
 ```
 
-## Context Types
-
-The `Context` interface is the heart of NextRush:
-
-```typescript
-import type { Context, ContextState, RouteParams, QueryParams } from '@nextrush/types';
-
-const handler = async (ctx: Context) => {
-  // Request (read-only)
-  ctx.method; // HttpMethod
-  ctx.url; // Full URL with query
-  ctx.path; // Path without query
-  ctx.query; // QueryParams
-  ctx.headers; // IncomingHeaders
-  ctx.ip; // Client IP
-  ctx.params; // RouteParams (from router)
-  ctx.body; // unknown (from body parser)
-
-  // Response
-  ctx.status = 201;
-  ctx.json({ created: true });
-  ctx.send('text');
-  ctx.html('<h1>Hello</h1>');
-  ctx.redirect('/new-url');
-
-  // Headers
-  ctx.set('X-Custom', 'value');
-  ctx.get('Authorization');
-
-  // Error helpers
-  ctx.throw(404, 'Not found');
-  ctx.assert(user, 404, 'User not found');
-
-  // State (for middleware data)
-  ctx.state.user = { id: '123' };
-
-  // Middleware flow
-  await ctx.next();
-
-  // Raw access (platform-specific)
-  ctx.raw.req; // Raw request
-  ctx.raw.res; // Raw response
-  ctx.runtime; // 'node' | 'bun' | 'deno' | 'edge'
-  ctx.bodySource; // BodySource for parsers
-};
+`Middleware` is imported with `import type` (it's erased at build); `HttpStatus` is a real value, so it's a plain `import`. That split — types versus the handful of runtime constants — is the whole shape of this package.
+
+## Capabilities
+
+**Request/response contracts**
+- **`Context`** — the unified request/response object (`method`, `url`, `path`, `query`, `params`, `body`, `headers`, `ip`, plus `json()`/`send()`/`html()`/`redirect()`, `throw()`/`assert()`, `set()`/`get()`, `next()`, `state`, `raw`, `runtime`, `bodySource`, and `stream()`/`sse()`/`ndjson()`)
+- **`Middleware` / `Next` / `RouteHandler`** — Koa-style middleware supporting both `(ctx)` and `(ctx, next)` signatures
+- **HTTP primitives** — `HttpMethod`, `HttpStatus`, `ContentType`, `IncomingHeaders`, `OutgoingHeaders`, `ParsedBody`, `ResponseBody`, `RawHttp`
+
+**Framework contracts**
+- **Router** — `Router`, `Route`, `RouteMatch`, `RouterOptions`, `RoutePattern`, `RouteParam`
+- **Route metadata** — `RouteDefinition`, `RouteMetadata`, `RouteEntry`, and the `ROUTE_METADATA` contribution symbol (the source of truth for OpenAPI and future renderers)
+- **Dependency injection** — `Container`, `Provider`, `Scope`, `Token`, `ServiceOptions` (the contract `@nextrush/di` implements)
+- **Extensions** — `Extension`, `ExtensionContext`, `ExtensionHost` (the rare long-lived-service model)
+- **Adapters** — `ServerAdapter`, `FetchAdapter`, `AdapterContext`, `FetchContext`, `ServerAddress`, `ServerHandle`
+- **Runtime & streaming** — `Runtime`, `RuntimeCapabilities`, `BodySource`, and the `TextStreamWriter` / `SSEStreamWriter` / `NDJSONStreamWriter` shapes
+- **Standard Schema** — `StandardSchemaV1` (a vendored, dependency-free copy of the [Standard Schema](https://github.com/standard-schema/standard-schema) v1 contract) so Zod / Valibot / ArkType schemas are accepted structurally
+
+**Developer experience**
+- **Runtime-independent** — no `node:*`, no runtime globals; structural `NodeStreamLike` / `WebStreamLike` interfaces stand in for platform stream types
+- **Fully typed** — strict TypeScript, zero `any`; tree-shakable and side-effect-free
+
+## Mental model
+
+`@nextrush/types` is a **dictionary of shapes**, not a library of behavior. It defines what a request, a route, a container, or an adapter *looks like*; every other package agrees to those shapes and provides the behavior.
+
+```text
+                 ┌─ HTTP primitives   (method · status · headers · body)
+@nextrush/types ─┼─ Context contract  ──▶ read by every handler & middleware
+ (shared shapes) ├─ Router / metadata contracts
+                 ├─ DI · Extension · Logger contracts
+                 └─ Adapter · Runtime · Stream contracts
+        │
+        └─ imported by every package · imports nothing itself (the graph root)
 ```
 
-### Context Options
+**Rule:** a contract shared by two or more packages lives here; a shape used by exactly one package stays in that package. This is the one place allowed to be depended on by everything and to depend on nothing.
 
-```typescript
-import type { ContextOptions } from '@nextrush/types';
+> [!TIP]
+> How these contracts relate, and why `types` sits at the bottom of the hierarchy (with Mermaid
+> diagrams), is in [`ARCHITECTURE.md`](./ARCHITECTURE.md).
 
-// Used by adapters to create contexts
-const options: ContextOptions = {
-  method: 'GET',
-  url: '/users?page=1',
-  headers: { 'content-type': 'application/json' },
-  ip: '127.0.0.1',
-  raw: { req, res },
+---
+
+## Common tasks
+
+### Type a middleware or route handler
+
+```ts
+import type { Context, Middleware, RouteHandler } from '@nextrush/types';
+
+// Both signatures are valid — `ctx.next()` (modern) or the `next` parameter (traditional).
+const logger: Middleware = async (ctx, next) => {
+  const start = Date.now();
+  await next();
+  ctx.state.tookMs = Date.now() - start;
 };
-```
 
-## HTTP Types
+const getUser: RouteHandler = (ctx: Context) => {
+  ctx.json({ id: ctx.params.id });
+};
+```
 
-### Methods
+### Use the HTTP constants and their value types
 
-```typescript
-import type { HttpMethod, CommonHttpMethod } from '@nextrush/types';
-import { HTTP_METHODS } from '@nextrush/types';
+```ts
+import { HttpStatus, HTTP_METHODS, ContentType } from '@nextrush/types';
+import type { HttpStatusCode, HttpMethod, ContentTypeValue } from '@nextrush/types';
 
-const method: HttpMethod = 'GET';
-// 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS' | 'TRACE' | 'CONNECT'
+const status: HttpStatusCode = HttpStatus.CREATED;       // 201
+const ct: ContentTypeValue = ContentType.JSON;           // 'application/json'
 
-const common: CommonHttpMethod = 'POST';
-// 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
+// HTTP_METHODS is a readonly tuple for iteration.
+// Note: TRACE and CONNECT are in the `HttpMethod` type but intentionally
+// excluded from this tuple (XST risk / proxy-only).
+for (const method of HTTP_METHODS) {
+  const m: HttpMethod = method; // 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS'
+}
+```
 
-// Iterate over methods
-for (const m of HTTP_METHODS) {
-  console.log(m);
+### Type an extension (long-lived app-scoped service)
+
+```ts
+import type { Extension, ExtensionContext } from '@nextrush/types';
+
+// The optional generic carries the decorated shape so `app.<name>` infers.
+export function clock(): Extension<{ now: () => number }> {
+  return {
+    name: 'clock',
+    setup(ctx: ExtensionContext) {
+      ctx.decorate('now', () => Date.now()); // throws on name collision
+    },
+    destroy() {
+      /* runs in reverse order at app.close() */
+    },
+  };
 }
 ```
 
-### Status Codes
+### Accept any Standard Schema validator without an adapter
 
-```typescript
-import { HttpStatus } from '@nextrush/types';
-import type { HttpStatusCode } from '@nextrush/types';
-
-ctx.status = HttpStatus.OK; // 200
-ctx.status = HttpStatus.CREATED; // 201
-ctx.status = HttpStatus.BAD_REQUEST; // 400
-ctx.status = HttpStatus.UNAUTHORIZED; // 401
-ctx.status = HttpStatus.FORBIDDEN; // 403
-ctx.status = HttpStatus.NOT_FOUND; // 404
-ctx.status = HttpStatus.INTERNAL_SERVER_ERROR; // 500
-
-// Type for status code values
-const status: HttpStatusCode = 200;
+```ts
+import type { StandardSchemaV1, InferOutput } from '@nextrush/types';
+
+// Works with Zod 3.24+, Valibot 1.0+, ArkType 2.0+ — anything exposing `~standard`.
+async function parse<S extends StandardSchemaV1>(
+  schema: S,
+  input: unknown,
+): Promise<InferOutput<S>> {
+  const result = await schema['~standard'].validate(input);
+  if (result.issues) throw new Error(result.issues[0]?.message);
+  return result.value as InferOutput<S>;
+}
 ```
 
-### Content Types
+### Type an adapter against the conformance contract
 
-```typescript
-import { ContentType } from '@nextrush/types';
-import type { ContentTypeValue } from '@nextrush/types';
+```ts
+import type { ServerAdapter, ServerHandle } from '@nextrush/types';
 
-ctx.set('Content-Type', ContentType.JSON); // 'application/json'
-ctx.set('Content-Type', ContentType.HTML); // 'text/html'
-ctx.set('Content-Type', ContentType.TEXT); // 'text/plain'
-ctx.set('Content-Type', ContentType.FORM); // 'application/x-www-form-urlencoded'
-ctx.set('Content-Type', ContentType.MULTIPART); // 'multipart/form-data'
+// `satisfies` pins the shape so `serve`/`createHandler` can't drift across adapters.
+const nodeAdapter = {
+  async serve(app, options) {
+    /* … */ return {} as ServerHandle;
+  },
+  createHandler(app, options) {
+    /* … */ return () => {};
+  },
+} satisfies ServerAdapter;
 ```
 
-### Headers
+## API overview
 
-```typescript
-import type { IncomingHeaders, OutgoingHeaders } from '@nextrush/types';
+Only four exports carry a runtime value; every other export is a **type** (erased at build). The sealed surface (ADR-0005):
 
-// Request headers (read-only)
-const incoming: IncomingHeaders = ctx.headers;
+| Export | Signature | Since | Stability | Description |
+| ------ | --------- | ----- | --------- | ----------- |
+| `HttpStatus` | `Readonly<Record<string, number>>` | `3.0.0` | Stable ✅ | Named HTTP status codes (`HttpStatus.OK` → `200`). |
+| `HTTP_METHODS` | `readonly HttpMethod[]` | `3.0.0` | Stable ✅ | Iterable tuple of routable methods (excludes `TRACE`/`CONNECT`). |
+| `ContentType` | `Readonly<Record<string, string>>` | `3.0.0` | Stable ✅ | Common content-type strings (`ContentType.JSON`). |
+| `ROUTE_METADATA` | `unique symbol` | `3.1.0` | Stable ✅ | `Symbol.for('nextrush.route.metadata')` — the route-metadata contribution key. |
 
-// Response headers (writable)
-const outgoing: OutgoingHeaders = {
-  'Content-Type': 'application/json',
-  'X-Request-Id': '123',
-};
-```
+### Type exports by domain
 
-### Body Types
+Grouped by the module that owns them (all `import type`).
 
-```typescript
-import type { ParsedBody, ResponseBody } from '@nextrush/types';
+| Domain | Exports |
+| ------ | ------- |
+| **Context** (`context.ts`) | `Context` · `ContextOptions` · `ContextState` · `RouteParams` · `QueryParams` · `Middleware` · `Next` · `RouteHandler` |
+| **HTTP** (`http.ts`) | `HttpMethod` · `CommonHttpMethod` · `HttpStatusCode` · `ContentTypeValue` · `IncomingHeaders` · `OutgoingHeaders` · `ParsedBody` · `ResponseBody` · `RawHttp` · `NodeStreamLike` · `WebStreamLike` |
+| **Router** (`router.ts`) | `Router` · `Route` · `RouteMatch` · `RouterOptions` · `RoutePattern` · `RouteParam` |
+| **Route metadata** (`route-metadata.ts`) | `RouteDefinition` · `RouteMetadata` · `RouteEntry` · `RouteMetaMarker` · `MetadataContribution` |
+| **DI** (`container.ts`) | `Container` · `Provider` · `ClassProvider` · `FactoryProvider` · `ValueProvider` · `Constructor` · `Token` · `Scope` · `ServiceOptions` · `RegisterOptions` |
+| **Extensions** (`extension.ts`) | `Extension` · `ExtensionContext` · `ExtensionHost` |
+| **Adapters** (`adapter.ts`, `adapter-context.ts`) | `ServerAdapter` · `FetchAdapter` · `FetchHandler` · `HandlerOptions` · `FetchHandlerOptions` · `ServerAddress` · `ServerHandle` · `AdapterContext` · `FetchContext` · `AdapterContextFactory` |
+| **Runtime** (`runtime.ts`) | `Runtime` · `RuntimeInfo` · `RuntimeCapabilities` · `BodySource` · `BodySourceOptions` |
+| **Streaming** (`stream.ts`) | `SSEEvent` · `BaseStreamWriter` · `TextStreamWriter` · `SSEStreamWriter` · `NDJSONStreamWriter` · `StreamSource` · `StreamRun` |
+| **Standard Schema** (`standard-schema.ts`) | `StandardSchemaV1` · `StandardSchemaProps` · `StandardSchemaResult` · `StandardSchemaIssue` · `StandardSchemaPathSegment` · `InferOutput` |
+| **Logger** (`logger.ts`) | `Logger` |
 
-// Request body after parsing
-const body: ParsedBody = ctx.body;
-// string | Uint8Array | Record<string, unknown> | unknown[] | null | undefined
+## Options
 
-// Response body types
-const response: ResponseBody = { data: 'value' };
-// string | Uint8Array | ArrayBuffer | NodeStreamLike | WebStreamLike | Record<string, unknown> | unknown[] | null | undefined
-```
+No configuration — `@nextrush/types` exports only type declarations and four constants. There is nothing to instantiate or configure; you import a contract and type against it.
 
-## Middleware Types
+## Compatibility
 
-```typescript
-import type { Middleware, Next, RouteHandler } from '@nextrush/types';
+**Requirements**
 
-// Middleware function
-const middleware: Middleware = async (ctx, next) => {
-  console.log('Before');
-  await next();
-  console.log('After');
-};
+| Requirement | Version |
+| ----------- | ------- |
+| NextRush | `3.x` |
+| Node.js | `>=22` |
+| TypeScript | `>=5.x` |
 
-// Next function type
-const callNext: Next = async () => {
-  // ...
-};
+**Runtimes**
 
-// Route handler (alias for Middleware)
-const handler: RouteHandler = async (ctx) => {
-  ctx.json({ ok: true });
-};
-```
+| Runtime | Supported | Notes |
+| ------- | --------- | ----- |
+| Node.js `>=22` | ✅ | ESM-only |
+| Bun / Deno / Edge | ✅ / ✅ / ✅ | Contracts are compile-time; the only runtime values are plain constants. Stream types are structural (`NodeStreamLike` / `WebStreamLike`), so no runtime is coupled in. |
 
-## Plugin Types
-
-```typescript
-import type {
-  Plugin,
-  PluginFactory,
-  PluginWithHooks,
-  PluginMeta,
-  ApplicationLike,
-} from '@nextrush/types';
-
-// Basic plugin
-const plugin: Plugin = {
-  name: 'my-plugin',
-  version: '1.0.0',
-
-  install(app: ApplicationLike) {
-    app.use(async (ctx, next) => {
-      await next();
-    });
-  },
+**Integration**
+- **Peer dependencies:** none — this is the root of the package graph.
+- **Works with:** every `@nextrush/*` package (they all depend on it) and any Standard Schema validator (Zod / Valibot / ArkType) structurally.
+- **Incompatible with:** none.
 
-  destroy() {
-    // Cleanup on shutdown
-  },
-};
+> [!IMPORTANT]
+> NextRush is **ESM-only, permanently** — no CommonJS build. On Node `>=22`, CommonJS consumers can
+> `require()` this ESM package natively. See the
+> [Module Format Policy](https://github.com/0xTanzim/nextRush#module-format-policy).
 
-// Plugin with lifecycle hooks
-const advancedPlugin: PluginWithHooks = {
-  name: 'advanced',
-  install(app) {},
+---
 
-  onRequest(ctx) {},
-  onResponse(ctx) {},
-  onError(error, ctx) {},
-  extendContext(ctx) {},
-};
+## Troubleshooting
 
-// Plugin factory pattern
-const createPlugin: PluginFactory<{ debug: boolean }> = (options) => ({
-  name: 'configurable',
-  install(app) {
-    if (options?.debug) {
-      // Debug mode
-    }
-  },
-});
+<details>
+<summary><strong>"<code>HttpStatus</code> cannot be used as a value because it was imported using <code>import type</code>"</strong></summary>
+
+**Cause:** `HttpStatus`, `HTTP_METHODS`, `ContentType`, and `ROUTE_METADATA` are runtime **values**, not types — with `verbatimModuleSyntax`, `import type` erases them. **Fix:** import the four constants with a plain `import`, and everything else with `import type`.
+
+```ts
+import { HttpStatus, HTTP_METHODS, ContentType, ROUTE_METADATA } from '@nextrush/types';
+import type { Context, Middleware, Router } from '@nextrush/types';
 ```
 
-## Router Types
-
-```typescript
-import type {
-  Router,
-  Route,
-  RouteMatch,
-  RouterOptions,
-  RoutePattern,
-  RouteParam,
-} from '@nextrush/types';
-
-// Route definition
-const route: Route = {
-  method: 'GET',
-  path: '/users/:id',
-  handler: async (ctx) => ctx.json({ id: ctx.params.id }),
-  middleware: [],
-};
+</details>
 
-// Route match result
-const match: RouteMatch = {
-  handler: route.handler,
-  params: { id: '123' },
-  middleware: [],
-};
+<details>
+<summary><strong>My function isn't accepted where a <code>Middleware</code> is expected</strong></summary>
 
-// Router options
-const options: RouterOptions = {
-  prefix: '/api/v1',
-  caseSensitive: false,
-  strict: false,
-};
+**Cause:** `Middleware` is `(ctx: Context, next: Next) => void | Promise<void>`. A handler returning a value (e.g. `(ctx) => ctx.json(...)` where `json` returns non-`void`) or one with an incompatible `next` still fits, but returning a truthy value from a synchronous handler can mismatch. **Fix:** type the function *as* `Middleware`/`RouteHandler` so inference flows from the contract, and use `async` when awaiting `next()`.
+
+```ts
+const mw: Middleware = async (ctx, next) => { await next(); };
 ```
 
-## Runtime Types
+</details>
 
-```typescript
-import type { Runtime, RuntimeInfo, RuntimeCapabilities, BodySource } from '@nextrush/types';
+<details>
+<summary><strong>My Zod / Valibot schema isn't accepted as <code>StandardSchemaV1</code></strong></summary>
 
-// Supported runtimes
-const runtime: Runtime = 'node';
-// 'node' | 'bun' | 'deno' | 'deno-deploy' | 'cloudflare-workers' | 'vercel-edge' | 'edge' | 'unknown'
+**Cause:** the Standard Schema contract requires the `~standard` property, which older validator versions don't expose. **Fix:** use a version that implements Standard Schema v1 — Zod `3.24+`, Valibot `1.0+`, or ArkType `2.0+`. No adapter is needed; conformance is structural.
 
-// Runtime capabilities
-const caps: RuntimeCapabilities = {
-  nodeStreams: true,
-  webStreams: true,
-  fileSystem: true,
-  webSocket: true,
-  fetch: true,
-  cryptoSubtle: true,
-  workers: true,
-};
+</details>
 
-// Body source for parsers
-const bodySource: BodySource = ctx.bodySource;
-await bodySource.text(); // Read as string
-await bodySource.buffer(); // Read as Uint8Array
-await bodySource.json(); // Read as JSON
-bodySource.stream(); // Get underlying stream
-bodySource.consumed; // Check if already read
-bodySource.contentLength; // Content-Length header
-bodySource.contentType; // Content-Type header
-```
+<details>
+<summary><strong>"Cannot find module '@nextrush/types' or its corresponding type declarations"</strong></summary>
 
-## Raw HTTP Types
+**Cause:** the package is ESM-only and ships `.d.ts` from `dist`; a `moduleResolution` that predates `node16`/`nodenext`/`bundler` won't resolve its `exports` map. **Fix:** set `"moduleResolution": "nodenext"` (or `"bundler"`) and `"module": "nodenext"` in `tsconfig.json`, on Node `>=22`.
 
-```typescript
-import type { RawHttp } from '@nextrush/types';
+</details>
 
-// Generic raw access
-const raw: RawHttp = ctx.raw;
-raw.req; // Platform request
-raw.res; // Platform response
+## FAQ
 
-// Type with generics for platform-specific typing
-import type { IncomingMessage, ServerResponse } from 'http';
-const nodeRaw: RawHttp<IncomingMessage, ServerResponse> = ctx.raw;
-```
+**Do I need to install `@nextrush/types` directly?**
+Usually no. Application code gets `Context`, `Middleware`, and the HTTP constants transitively through `nextrush` / `@nextrush/core`. Install it directly only when you author a package, adapter, or middleware that should depend on the contracts explicitly.
+
+**Why ESM-only?**
+See the [Module Format Policy](https://github.com/0xTanzim/nextRush#module-format-policy).
+
+**Does it work on Bun, Deno, and Edge?**
+Yes. The contracts are compile-time and the only runtime values are plain constant objects and one symbol. Platform stream types are represented structurally (`NodeStreamLike` / `WebStreamLike`), so nothing runtime-specific is imported.
+
+**Is this really "zero runtime"?**
+Zero runtime *dependencies* — yes, always. Zero runtime *code* — almost: it ships four constant value exports (`HttpStatus`, `HTTP_METHODS`, `ContentType`, `ROUTE_METADATA`, ~1 KB gzipped). Every interface and type alias is erased at build.
+
+---
 
-## API Reference
-
-### Exports
-
-```typescript
-import {
-  // Constants (runtime values)
-  HttpStatus,
-  HTTP_METHODS,
-  ContentType,
-} from '@nextrush/types';
-
-import type {
-  // Context
-  Context,
-  ContextOptions,
-  ContextState,
-  RouteParams,
-  QueryParams,
-  Middleware,
-  Next,
-  RouteHandler,
-
-  // HTTP
-  HttpMethod,
-  CommonHttpMethod,
-  HttpStatusCode,
-  ContentTypeValue,
-  IncomingHeaders,
-  OutgoingHeaders,
-  ParsedBody,
-  ResponseBody,
-  RawHttp,
-
-  // Plugin
-  Plugin,
-  PluginWithHooks,
-  PluginFactory,
-  PluginMeta,
-  ApplicationLike,
-
-  // Router
-  Router,
-  Route,
-  RouteMatch,
-  RouterOptions,
-  RoutePattern,
-  RouteParam,
-
-  // Runtime
-  Runtime,
-  RuntimeInfo,
-  RuntimeCapabilities,
-  BodySource,
-  BodySourceOptions,
-} from '@nextrush/types';
+## Package relationships
+
+```text
+                 depends on          (nothing — root of the graph, zero dependencies)
+@nextrush/types ─────────────▶
+                 depended on by      @nextrush/errors · core · router · runtime · di · class · adapter-* · middleware
+                 satisfied by        Zod · Valibot · ArkType   (structurally, via StandardSchemaV1)
 ```
 
-## Package Size
+- **Depends on:** nothing — `@nextrush/types` is the lowest layer and imports no other package (project-rules §1).
+- **Depended on by:** [`@nextrush/errors`](../errors), [`@nextrush/core`](../core), [`@nextrush/router`](../router), [`@nextrush/runtime`](../runtime), [`@nextrush/di`](../di), [`@nextrush/class`](../class), the adapters, and the middleware packages — they all import the same contracts from here.
+- **Satisfied by:** any [Standard Schema](https://github.com/standard-schema/standard-schema) validator (Zod / Valibot / ArkType) conforms to `StandardSchemaV1` structurally, with no adapter.
+- **Alternative:** none — these are the framework's contracts.
+
+## Architecture
+
+Maintaining or contributing to this package? The internal design — how the contracts are grouped
+across modules, how `Context` composes the HTTP / runtime / stream types, why `types` sits at the
+bottom of the hierarchy, and the architectural invariants that keep it dependency-free (with
+diagrams) — is in **[`ARCHITECTURE.md`](./ARCHITECTURE.md)**. Design history:
+[ADR-0005 (package tiers & sealed surface)](https://github.com/0xTanzim/nextRush/blob/main/docs/adr/ADR-0005-package-tiers-sealed-surface-deprecation.md).
+
+## Resources
 
-- **Bundle**: ~1 KB (mostly constants)
-- **Types**: ~22 KB
-- **Dependencies**: None
+- 📖 **Learn** — [Documentation](https://0xtanzim.github.io/nextRush/docs) · [Architecture](./ARCHITECTURE.md) · [RFCs](https://github.com/0xTanzim/nextRush/tree/main/docs/RFC)
+- 📝 **Changelog** — [CHANGELOG.md](./CHANGELOG.md)
+- 🐛 **Report an issue** — [GitHub Issues](https://github.com/0xTanzim/nextRush/issues)
+- 🤝 **Contribute** — [CONTRIBUTING.md](https://github.com/0xTanzim/nextRush/blob/main/CONTRIBUTING.md)
 
-## License
+---
 
-MIT
+MIT © [Tanzim Hossain](https://github.com/0xTanzim)