@nifrajs/core 2.1.0 → 2.3.0

package/src/router/router.ts

@@ -1,5 +1,11 @@
 import { RouteConfigError } from "../errors.ts"
-import { type CompiledRoutePattern, compileRoutePattern } from "./pattern.ts"
+import {
+  type CompiledRoutePattern,
+  compareMixedPartsSpecificity,
+  compileRoutePattern,
+  type MixedPart,
+  mixedSegmentSource,
+} from "./pattern.ts"
 
 /** HTTP methods the router accepts. */
 export const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"] as const
@@ -29,7 +35,7 @@ export type RouterMatch<T> =
 /**
  * Payload at a terminal node: per-method handlers plus the ordered param names
  * for this path shape. Bundling them means "a node that has handlers always has
- * param names" is enforced by the type, not by a runtime invariant — which
+ * param names" is enforced by the type, not by a runtime invariant - which
  * removes the otherwise-dead defensive branches in `find`.
  */
 interface Terminal<T> {
@@ -68,16 +74,43 @@ interface RouteNode<T> {
   readonly staticChildren: Map<string, RouteNode<T>>
   /** Single `:param` child, if any. */
   paramChild: RouteNode<T> | undefined
-  /** Catch-all `*` child, if any — always terminal. */
+  /**
+   * Part-literal-part-param children (`:key.txt`), ordered by specificity.
+   *
+   * Unlike `paramChild` there can legitimately be SEVERAL at one level - `/:id.txt` and `/:id.json`
+   * are different shapes, not a conflict - so this is a list rather than a slot, and it must be tried
+   * in specificity order rather than registration order.
+   *
+   * Left `undefined` unless a mixed route is registered, so an app that never uses one pays nothing:
+   * no allocation, and one `undefined` check on the match path.
+   */
+  mixedChildren: MixedChild<T>[] | undefined
+  /** Catch-all `*` child, if any - always terminal. */
   wildcardChild: RouteNode<T> | undefined
   /** Set once this node terminates one or more routes. */
   terminal: Terminal<T> | undefined
 }
 
+interface MixedChild<T> {
+  /** Anchored matcher for ONE segment, with a capture group per parameter. */
+  readonly regex: RegExp
+  /**
+   * How many values this segment pushes. A mixed segment pushes N, not one, so a failed branch must
+   * pop exactly N to keep `paramValues` aligned with `paramNames`.
+   */
+  readonly arity: number
+  /** Parsed shape used by the same total specificity comparator as the browser router. */
+  readonly parts: readonly MixedPart[]
+  readonly node: RouteNode<T>
+  /** The pattern source, so re-registering the same shape reuses its node. */
+  readonly source: string
+}
+
 function createNode<T>(): RouteNode<T> {
   return {
     staticChildren: new Map(),
     paramChild: undefined,
+    mixedChildren: undefined,
     wildcardChild: undefined,
     terminal: undefined,
   }
@@ -96,7 +129,7 @@ function sameNames(a: readonly string[], b: readonly string[]): boolean {
  * instead of pre-splitting it into an array. `start` is the index of the first
  * char of the current segment; the segment runs to the next `/` (or end). Tries
  * static, then param, then wildcard; if a static branch dead-ends, param/wildcard
- * are still attempted — so `/a/b/c` and `/a/:x/d` coexist and `/a/b/d` resolves
+ * are still attempted - so `/a/b/c` and `/a/:x/d` coexist and `/a/b/d` resolves
  * to the param route. Fills `paramValues` along the successful path; abandoned
  * branches are popped. Avoiding the split keeps `find` allocation-light: only the
  * segment substrings needed for map lookups (and matched param values) are cut.
@@ -123,10 +156,32 @@ function matchNode<T>(
     }
   }
 
+  // Mixed sits between static and param: it pins literal text, so it is more specific than a bare
+  // `:param`, and less than an exact segment. Guarded on `undefined` so a mixed-free route table
+  // never enters this branch.
+  const mixedChildren = node.mixedChildren
+  if (mixedChildren !== undefined && seg.length > 0) {
+    for (const child of mixedChildren) {
+      const matched = child.regex.exec(seg)
+      if (matched === null) continue
+      // Push left-to-right, matching the order `paramNames` was built in.
+      for (let i = 1; i <= child.arity; i++) paramValues.push(matched[i] as string)
+      if (isLast) {
+        if (child.node.terminal !== undefined) return child.node.terminal
+      } else {
+        const found = matchNode(child.node, path, end + 1, len, paramValues)
+        if (found !== undefined) return found
+      }
+      // Backtrack: a mixed segment pushed `arity` values, not one, so unwind exactly that many or
+      // every later param reads a value belonging to an abandoned branch.
+      for (let i = 0; i < child.arity; i++) paramValues.pop()
+    }
+  }
+
   const paramChild = node.paramChild
-  // An empty segment (`/users//posts`) never matches a `:param` — matching would hand the handler
+  // An empty segment (`/users//posts`) never matches a `:param` - matching would hand the handler
   // `id: ""` and downstream code a `WHERE id = ''` class of bug. Peers (Hono, Elysia, Next) 404
-  // here too; a static "" child can still match (none is ever registered — INVALID_PATH guards).
+  // here too; a static "" child can still match (none is ever registered - INVALID_PATH guards).
   if (paramChild !== undefined && seg.length > 0) {
     paramValues.push(seg)
     if (isLast) {
@@ -250,6 +305,25 @@ export class Router<T> {
       } else if (segment.kind === "wildcard") {
         node.wildcardChild ??= createNode<T>()
         node = node.wildcardChild
+      } else if (segment.kind === "mixed") {
+        const source = mixedSegmentSource(segment.parts)
+        node.mixedChildren ??= []
+        let child = node.mixedChildren.find((entry) => entry.source === source)
+        if (child === undefined) {
+          child = {
+            regex: new RegExp(`^${source}$`),
+            arity: segment.parts.reduce((n, part) => (part.t === "param" ? n + 1 : n), 0),
+            parts: segment.parts,
+            node: createNode<T>(),
+            source,
+          }
+          node.mixedChildren.push(child)
+          // Most literal text first. Registration order must not decide which of `/:id.txt` and
+          // `/:id.json` wins, and re-sorting on insert (a boot-time cost) keeps the match path a
+          // straight scan.
+          node.mixedChildren.sort((a, b) => compareMixedPartsSpecificity(a.parts, b.parts))
+        }
+        node = child.node
       } else {
         let child = node.staticChildren.get(segment.value)
         if (child === undefined) {

package/src/schema/standard.ts

@@ -1,7 +1,7 @@
 /**
  * The Standard Schema v1 interface (https://standardschema.dev), vendored as
- * types + a tiny runtime helper so any compliant validator — zod, valibot,
- * arktype, … — validates requests without coupling the framework to one lib.
+ * types + a tiny runtime helper so any compliant validator - zod, valibot,
+ * arktype, … - validates requests without coupling the framework to one lib.
  * The spec is MIT-licensed and explicitly designed to be copied.
  */
 

package/src/seo.ts

@@ -1,5 +1,5 @@
 /**
- * `sitemap.xml` + `robots.txt` builders — pure, edge-safe string generators (no I/O, no runtime deps).
+ * `sitemap.xml` + `robots.txt` builders - pure, edge-safe string generators (no I/O, no runtime deps).
  * Wire them to a route on any runtime:
  *
  *   app.get("/sitemap.xml", () =>
@@ -21,7 +21,7 @@ const XML_ESCAPES: Readonly<Record<string, string>> = {
   "'": "&apos;",
 }
 
-/** Escape the five XML metacharacters — `<loc>` and `<lastmod>` carry app- or DB-derived strings. */
+/** Escape the five XML metacharacters - `<loc>` and `<lastmod>` carry app- or DB-derived strings. */
 function escapeXml(value: string): string {
   return value.replace(/[&<>"']/g, (char) => XML_ESCAPES[char] as string)
 }
@@ -48,10 +48,10 @@ const CHANGE_FREQS: ReadonlySet<string> = new Set([
 export interface SitemapEntry {
   /** An absolute URL, or a path that `hostname` will make absolute. */
   readonly url: string
-  /** Last-modified — a `Date` (serialized as ISO 8601) or a pre-formatted W3C-datetime string. */
+  /** Last-modified - a `Date` (serialized as ISO 8601) or a pre-formatted W3C-datetime string. */
   readonly lastmod?: string | Date
   readonly changefreq?: SitemapChangeFreq
-  /** Crawl priority, `0.0`–`1.0`. */
+  /** Crawl priority, `0.0`-`1.0`. */
   readonly priority?: number
 }
 
@@ -67,7 +67,7 @@ const SITEMAP_MAX_URLS = 50_000
 export function sitemap(entries: readonly SitemapEntry[], options: SitemapOptions = {}): string {
   if (entries.length > SITEMAP_MAX_URLS) {
     throw new RangeError(
-      `sitemap: ${entries.length} entries exceeds the ${SITEMAP_MAX_URLS}-URL per-file limit — split into a sitemap index`,
+      `sitemap: ${entries.length} entries exceeds the ${SITEMAP_MAX_URLS}-URL per-file limit - split into a sitemap index`,
     )
   }
   const base = options.hostname?.replace(/\/+$/, "")
@@ -96,7 +96,7 @@ export function sitemap(entries: readonly SitemapEntry[], options: SitemapOption
 
 function resolveLoc(url: string, base: string | undefined): string {
   if (/^https?:\/\//i.test(url)) return url // already absolute
-  if (base === undefined) return url // relative — caller's choice (sitemaps prefer absolute)
+  if (base === undefined) return url // relative - caller's choice (sitemaps prefer absolute)
   return `${base}${url.startsWith("/") ? "" : "/"}${url}`
 }
 

package/src/server/body.ts

@@ -1,5 +1,5 @@
 /**
- * Bounded request-body reading — the single source of truth for nifra's body-size cap. A lying or
+ * Bounded request-body reading - the single source of truth for nifra's body-size cap. A lying or
  * absent `Content-Length` can't force us to buffer an oversized payload: a declared length over the
  * cap is rejected *before* buffering, and a chunked / length-less body is aborted mid-stream once the
  * running byte count exceeds the cap. Shared by the server's schema path, `c.boundedBody`, and
@@ -26,7 +26,7 @@ export function parseContentLength(value: string): number | undefined {
 
 /** The shared streaming byte-cap loop: read until done, or cancel + 413 once over `maxBytes`.
  * A single-chunk body (the common case for small chunked payloads) returns the runtime's own
- * chunk directly — no chunk array, no copy-merge. */
+ * chunk directly - no chunk array, no copy-merge. */
 export async function drainCapped(
   body: ReadableStream<Uint8Array>,
   maxBytes: number,

package/src/server/context.ts

@@ -68,12 +68,12 @@ export interface RouteSchema {
    * Dedupe retries of this (mutating) route on an `Idempotency-Key` header. The first request runs and
    * its response is stored; a retry with the same key replays that response without re-running the
    * handler, and a key reused with a different body is rejected (409). A missing key on an
-   * idempotency-required route fails closed (400). Off the hot path — routes without it are unchanged.
+   * idempotency-required route fails closed (400). Off the hot path - routes without it are unchanged.
    */
   readonly idempotency?: IdempotencyConfig
   /**
    * Highest data-sensitivity this route's response body carries (`public` | `pii` | `secret`). A
-   * declarative, compile-time + introspection fact — never validated at runtime. Reflected for tooling,
+   * declarative, compile-time + introspection fact - never validated at runtime. Reflected for tooling,
    * recorded in the capability lockfile (so a route that starts returning PII is a reviewable change),
    * and read by downstream policy (e.g. a partner-API surface refusing to expose `pii`/`secret`).
    */
@@ -110,20 +110,20 @@ export interface RouteSchema {
   readonly query?: StandardSchemaV1
   /** Optional **response contract**. When declared: the handler's return is type-checked against it
    * (the implementation can't drift from the contract), the typed client sees THIS as the response type
-   * (the contract — not the handler's incidental return), and it's emitted into OpenAPI/JSON-Schema so
+   * (the contract - not the handler's incidental return), and it's emitted into OpenAPI/JSON-Schema so
    * tooling and coding agents can read the exact shape. It is **not** validated at runtime (zero
-   * hot-path cost) — purely a compile-time + introspection contract. */
+   * hot-path cost) - purely a compile-time + introspection contract. */
   readonly response?: StandardSchemaV1
   /**
    * Optional **error-response contract**: a map of HTTP status code → the Standard Schema of that error's
    * body. Declares a route's failure modes so they flow into OpenAPI (as non-2xx `responses`), the
-   * `/llms.txt` context, and other introspection — the whole contract, not just the happy path, is legible
+   * `/llms.txt` context, and other introspection - the whole contract, not just the happy path, is legible
    * to tooling and coding agents. Like `response`, it is **not** validated at runtime (zero hot-path cost);
    * it's a compile-time + introspection contract. Example: `{ 404: NotFound, 409: Conflict }`. */
   readonly errors?: Readonly<Record<number, StandardSchemaV1>>
   /**
    * Optional **SSE event contract**: the Standard Schema of each event's `data` payload on a
-   * streaming route (declared via `app.sse()`). Marks the route as a typed event stream — the
+   * streaming route (declared via `app.sse()`). Marks the route as a typed event stream - the
    * typed client grows a `.subscribe()` for it, and the schema flows into reflection. Like
    * `response`, it is **not** validated at runtime (zero hot-path cost); the server-side
    * `stream.send()` is compile-time-checked against it instead.
@@ -135,7 +135,7 @@ export interface RouteSchema {
    *   - a **`Response`** → returned as-is, short-circuiting the route (custom error envelope, redirect, …).
    *   - **any other value** → treated as a repaired payload and **re-validated once** against the same
    *     schema. If it now passes, the handler runs with it; if it still fails, the original `422` stands.
-   *     Re-validation means a bad return can't bypass the schema — the trust boundary holds.
+   *     Re-validation means a bad return can't bypass the schema - the trust boundary holds.
    *   - **`undefined`** → give up; the original validation `422` is returned unchanged.
    * A route hook **overrides** the app-wide default set via `server({ onValidationError })`; return
    * `undefined` to fall through to the plain `422` even when an app default exists. Typical uses: a custom
@@ -171,8 +171,8 @@ export interface ResponseControls {
   status?: number
   readonly headers: Record<string, string>
   /**
-   * Queue a `Set-Cookie` on the response. Defaults are **secure-by-default** —
-   * `HttpOnly; Secure; SameSite=Lax; Path=/` — overridable per call (pass `{ secure: false }` for
+   * Queue a `Set-Cookie` on the response. Defaults are **secure-by-default** -
+   * `HttpOnly; Secure; SameSite=Lax; Path=/` - overridable per call (pass `{ secure: false }` for
    * local http dev). Multiple calls set multiple cookies (they're merged via a `Headers` object, so
    * they don't collapse the way the plain `headers` Record would). Sign the value with `signValue`
    * for tamper-evidence (what `@nifrajs/auth` sessions do).
@@ -190,7 +190,7 @@ export interface ResponseControls {
  */
 export interface Platform<Env = unknown> {
   /** Platform bindings (KV/D1/secrets on Workers). Typed as `Env` when the app declares them via
-   * `server<Env>()`; otherwise `unknown` — validate before use. */
+   * `server<Env>()`; otherwise `unknown` - validate before use. */
   readonly env?: Env
   /** Extend the response's lifetime for background work (Workers `ctx.waitUntil`). */
   readonly waitUntil?: (promise: Promise<unknown>) => void
@@ -208,7 +208,7 @@ export interface Platform<Env = unknown> {
 export interface Context<Path extends string = string, S extends RouteSchema = RouteSchema> {
   readonly req: Request
   /**
-   * Alias of {@link req} — the same `Request`. Page loaders/actions receive their request as `request`;
+   * Alias of {@link req} - the same `Request`. Page loaders/actions receive their request as `request`;
    * this alias lets route handlers and loaders share one name, so `c.request` and `ctx.req` both work
    * everywhere (no more `c.req` vs `ctx.request` mismatch).
    */
@@ -217,12 +217,12 @@ export interface Context<Path extends string = string, S extends RouteSchema = R
   readonly query: QueryOf<S>
   readonly body: BodyOf<S>
   /** The request's cookies, parsed from the `Cookie` header (values URL-decoded). Parsed lazily on
-   * first access + cached. Signed cookies arrive as `value.signature` — verify with `unsignValue`. */
+   * first access + cached. Signed cookies arrive as `value.signature` - verify with `unsignValue`. */
   readonly cookies: Readonly<Record<string, string>>
   readonly set: ResponseControls
   /**
    * Aborts when the server's `requestTimeoutMs` elapses (and never, when no timeout
-   * is configured). Pass it to cancellation-aware work — DB drivers, `fetch` — so a
+   * is configured). Pass it to cancellation-aware work - DB drivers, `fetch` - so a
    * timed-out request stops doing work instead of running on after the 503.
    */
   readonly signal: AbortSignal
@@ -232,14 +232,14 @@ export interface Context<Path extends string = string, S extends RouteSchema = R
    */
   readonly budget: RequestBudget
   /**
-   * Platform bindings from `app.fetch(request, { env })` — Workers `env` (KV/D1/secrets), etc.
+   * Platform bindings from `app.fetch(request, { env })` - Workers `env` (KV/D1/secrets), etc.
    * `undefined` off-edge (Bun/Node/Deno). Declare the shape with `server<Env>()` to read it typed
    * (`c.env: Env`); otherwise `unknown`. Validate at the trust boundary before use either way.
    */
   readonly env: unknown
   /**
    * The caller's IP. By default the raw socket peer the serving adapter observed (`listen()`,
-   * `@nifrajs/node`, `@nifrajs/deno`) — the one address a client cannot forge — or `undefined` when the
+   * `@nifrajs/node`, `@nifrajs/deno`) - the one address a client cannot forge - or `undefined` when the
    * runtime exposes no socket (Workers) and no trust is declared. Behind a proxy/CDN, set the
    * `clientIp` server option (`{ trustedHops }` or `{ header }`) to derive the real caller from the
    * forwarding chain as far as you trust it; unset, no forwarded header is ever believed. Safe to key
@@ -254,8 +254,8 @@ export interface Context<Path extends string = string, S extends RouteSchema = R
   readonly waitUntil: (promise: Promise<unknown>) => void
   /**
    * Read the raw request body as bytes, **capped** at `maxBytes` (default: the server's
-   * `maxBodyBytes`). For routes with **no body schema** — raw bodies, file uploads,
-   * BYO-validation — where the automatic schema cap doesn't apply. An over-cap body (by
+   * `maxBodyBytes`). For routes with **no body schema** - raw bodies, file uploads,
+   * BYO-validation - where the automatic schema cap doesn't apply. An over-cap body (by
    * `Content-Length` or while streaming) throws a flat `413`; a malformed `Content-Length`
    * throws `400`. Consumes the body stream (call once). Pass a larger `maxBytes` for an
    * upload route, a smaller one to tighten a specific endpoint.
@@ -269,7 +269,7 @@ export interface Context<Path extends string = string, S extends RouteSchema = R
   readonly boundedJson: <T = unknown>(maxBytes?: number) => Promise<T>
   /**
    * Build a JSON `Response`. Pass a status number or a full `ResponseInit` as the second arg. `return` it
-   * from a handler, or `throw` it from `derive`/`beforeHandle` to short-circuit — both work:
+   * from a handler, or `throw` it from `derive`/`beforeHandle` to short-circuit - both work:
    * `throw c.json({ error: "unauthorized" }, 401)`. A terser alternative to
    * `new Response(JSON.stringify(...), { status, headers: { "content-type": "application/json" } })`.
    */

package/src/server/contract.ts

@@ -19,7 +19,7 @@ export interface ResponseDef {
 /**
  * One operation in a contract. Input schemas are any Standard Schema; `response` is optional.
  *
- * The fields below `response` are **optional OpenAPI metadata** — they don't affect runtime
+ * The fields below `response` are **optional OpenAPI metadata** - they don't affect runtime
  * validation or the inferred handler types, they enrich the document `toOpenAPI` emits. A contract is
  * the natural home for them: it's the versionable description of the API, decoupled from the impl.
  */
@@ -101,7 +101,7 @@ type OpErrors<O extends OperationDef> = O extends {
  * RouteInfo as a *decoupled consumer* sees it from the contract alone: the
  * `output` is the declared `response` schema's type, or `unknown` when none is
  * declared (the consumer can't know the response without the server). Path/method
- * levels are mutable and fields are `readonly` — matching the inline registry, so
+ * levels are mutable and fields are `readonly` - matching the inline registry, so
  * the two are mutually assignable.
  */
 type RouteInfoForOp<O extends OperationDef> = {
@@ -109,10 +109,10 @@ type RouteInfoForOp<O extends OperationDef> = {
   readonly query: OpQuery<O>
   readonly body: OpBody<O>
   readonly output: OpResponse<O>
-  // The error union from the op's non-2xx `responses` — so a decoupled contract client sees typed error
+  // The error union from the op's non-2xx `responses` - so a decoupled contract client sees typed error
   // bodies, just like an inline route's `errors`. `unknown` when the op declares no error responses.
   readonly errors: OpErrors<O>
-  // Contract operations cannot declare an SSE event contract (yet) — `never` keeps the contract
+  // Contract operations cannot declare an SSE event contract (yet) - `never` keeps the contract
   // registry mutually assignable with the inline registry's RouteInfoFor (mode conformance).
   readonly sse: never
 }
@@ -132,7 +132,7 @@ type SchemaForOp<O extends OperationDef> = (O extends { body: infer B extends St
   (O extends { params: infer P extends StandardSchemaV1 } ? { params: P } : Record<never, never>)
 
 /**
- * The handler context for an op — identical to the inline `Context<Path, S>`, so a
+ * The handler context for an op - identical to the inline `Context<Path, S>`, so a
  * handler written for an inline route type-checks unchanged under `implement`
  * (the graduation guarantee).
  */
@@ -142,9 +142,9 @@ type MaybePromise<T> = T | Promise<T>
 
 /**
  * What a handler may return for an op. When the op declares a `response`, the return is constrained to
- * that contract shape (or a raw `Response`) — so an `implement`ed backend can't drift from the response
+ * that contract shape (or a raw `Response`) - so an `implement`ed backend can't drift from the response
  * the contract's client was built against. With no `response` it's unconstrained (`unknown`), identical
- * to before. Purely type-level — erased at compile time, zero runtime cost — and mirrors the inline
+ * to before. Purely type-level - erased at compile time, zero runtime cost - and mirrors the inline
  * route's `ResponseOf` constraint, so a handler graduates inline↔contract unchanged.
  */
 type HandlerReturnForOp<O extends OperationDef> = O extends {
@@ -202,7 +202,7 @@ type AnyFn = (...args: never[]) => unknown
 
 /**
  * The registry produced by `implement`: input from the contract op; `output` is the declared `response`
- * contract when present (it wins — exactly as in the inline path), else the bound HANDLER's return — so
+ * contract when present (it wins - exactly as in the inline path), else the bound HANDLER's return - so
  * the implemented server stays route-for-route identical to the equivalent inline server (the
  * mode-conformance guarantee), and a contract-typed client and a `typeof app`-typed client agree.
  */
@@ -221,10 +221,10 @@ export type RegistryFromImpl<
         : H[K] extends AnyFn
           ? OutputOf<H[K]>
           : unknown
-      // The error union from the op's non-2xx `responses` (see OpErrors) — a graduated contract client sees
+      // The error union from the op's non-2xx `responses` (see OpErrors) - a graduated contract client sees
       // the same typed error bodies as the inline `errors` path.
       readonly errors: OpErrors<C[K]>
-      // Mirrors RouteInfoForOp: no SSE contract on contract ops (yet) — mode conformance holds.
+      // Mirrors RouteInfoForOp: no SSE contract on contract ops (yet) - mode conformance holds.
       readonly sse: never
     }
   }
@@ -233,7 +233,7 @@ export type RegistryFromImpl<
 /**
  * Bind handlers to a contract, producing a real {@link Server} you can `.listen()`
  * or `.fetch()`. Each op is registered through the same path as the inline
- * builder, so the result is identical to writing the routes inline — handlers
+ * builder, so the result is identical to writing the routes inline - handlers
  * lift over **unchanged** ("graduation"), and body/query schemas validate at the
  * request boundary exactly as in inline mode.
  *
@@ -259,9 +259,9 @@ export function implement<
   const target = (app ?? new Server()) as Server<R, Ctx>
   const routes = Object.entries(contract).map(([name, op]) => {
     // body/query are validated at the request boundary; `response` is a type + introspection contract
-    // ONLY — never validated at runtime and never read on the request hot path (the lifecycle reads
+    // ONLY - never validated at runtime and never read on the request hot path (the lifecycle reads
     // schema.body/query by name; the `bare`/bodyOnly/queryOnly fast-path gates ignore `response`). Built
-    // once here at bind time, not per request — it just carries a reference to the op's existing schema.
+    // once here at bind time, not per request - it just carries a reference to the op's existing schema.
     // A response-less op still yields `undefined`, byte-identical to before.
     const schema: RouteSchema | undefined =
       op.params !== undefined ||

package/src/server/cookies.ts

@@ -1,5 +1,5 @@
 /**
- * Cookie primitives — parse a request `Cookie` header, serialize a `Set-Cookie`, and sign/verify a
+ * Cookie primitives - parse a request `Cookie` header, serialize a `Set-Cookie`, and sign/verify a
  * value with HMAC-SHA256 via **WebCrypto** (`crypto.subtle`), so they're portable across Bun, Node,
  * Deno, and workerd with no `node:crypto` dependency. Pure + runtime-agnostic: `c.cookies` (read) and
  * `c.set.cookie` (write) build on these, and `@nifrajs/auth` builds sessions on top.
@@ -22,9 +22,9 @@ export interface CookieOptions {
 
 // RFC 6265 cookie-name token: visible ASCII minus separators/whitespace/controls.
 const COOKIE_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/
-const MAX_COOKIE_BYTES = 4096 // browsers cap a cookie near 4 KB — reject oversized before the wire
+const MAX_COOKIE_BYTES = 4096 // browsers cap a cookie near 4 KB - reject oversized before the wire
 
-/** True if `v` contains a character illegal in a cookie attribute (control char or `;` separator) —
+/** True if `v` contains a character illegal in a cookie attribute (control char or `;` separator) -
  * the header-injection guard for dev-supplied `Path`/`Domain`. */
 const hasIllegalChar = (v: string): boolean => {
   for (let i = 0; i < v.length; i++) {
@@ -35,7 +35,7 @@ const hasIllegalChar = (v: string): boolean => {
 }
 
 const safeDecode = (v: string): string => {
-  // No `%` ⇒ nothing to decode — skip the call AND its try frame (profiled: cookie values are
+  // No `%` ⇒ nothing to decode - skip the call AND its try frame (profiled: cookie values are
   // overwhelmingly plain; this was ~3% of a realistic request).
   if (!v.includes("%")) return v
   try {
@@ -46,7 +46,7 @@ const safeDecode = (v: string): string => {
 }
 
 /** Parse a request `Cookie` header into a name→value map (values URL-decoded). Unparseable pairs are
- * skipped rather than throwing — a junk `Cookie` header shouldn't fail the request.
+ * skipped rather than throwing - a junk `Cookie` header shouldn't fail the request.
  *
  * Hand-rolled index walk instead of `split(";")` + `trim()` chains: those allocated an array + up
  * to three substrings per pair and showed up at ~6% of a realistic (auth + cookie) request. Same
@@ -97,9 +97,9 @@ export function parseCookies(header: string | null | undefined): Record<string,
 }
 
 /**
- * Serialize a `Set-Cookie` header value. Pure — applies **no** security defaults (the caller, e.g.
+ * Serialize a `Set-Cookie` header value. Pure - applies **no** security defaults (the caller, e.g.
  * `c.set.cookie`, layers `HttpOnly`/`Secure`/`SameSite` on). Throws on an invalid cookie name, a
- * header-injecting `Path`/`Domain`, a non-integer `maxAge`, or an oversized result — a serialization
+ * header-injecting `Path`/`Domain`, a non-integer `maxAge`, or an oversized result - a serialization
  * bug should fail loudly, not silently emit a cookie the browser drops.
  */
 export function serializeCookie(name: string, value: string, options: CookieOptions = {}): string {
@@ -170,7 +170,7 @@ const fromBase64Url = (s: string): Uint8Array<ArrayBuffer> | null => {
     for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i)
     return bytes
   } catch {
-    return null // not valid base64 — treat as a bad signature
+    return null // not valid base64 - treat as a bad signature
   }
 }
 

package/src/server/edge.ts

@@ -0,0 +1,150 @@
+/**
+ * The edge adapter: a nifra app presented as a Cloudflare-Workers-shaped `ExportedHandler`.
+ *
+ * ## Why this is not in the server kernel
+ *
+ * `toFetchHandler` never touches the `Server` class. It takes a STRUCTURAL app - anything with `fetch`, and
+ * optionally `resolveWebSocketUpgrade` - which is what lets it wrap an app it has no access to the
+ * internals of, and what makes it a separate concern from the kernel rather than a method on it. It sat
+ * in `server.ts` for no reason other than that both were written the same week.
+ *
+ * The types here are all structural too (`ExecutionContext`, `ScheduledController`,
+ * `DurableObjectNamespaceLike`), so `@nifrajs/core` declares the Workers surface it needs instead of
+ * depending on `@cloudflare/workers-types`. The real Workers types satisfy them.
+ *
+ * The `MaybePromise` import is type-only and erased, so there is no runtime cycle back into the kernel.
+ */
+import type { Platform } from "./context.ts"
+import type { MaybePromise } from "./server.ts"
+import type { StandardWebSocket, WebSocketUpgradeOutcome } from "./websocket.ts"
+
+/** A Cloudflare Workers-style execution context (the `fetch` 3rd arg). Structural - only
+ * `waitUntil` is used; declared here so `@nifrajs/core` needs no Workers type dependency. */
+export interface ExecutionContext {
+  waitUntil(promise: Promise<unknown>): void
+}
+
+/** A Cloudflare Workers-style scheduled (cron) controller. Structural - no Workers type dependency. */
+export interface ScheduledController {
+  /** Epoch ms the run was scheduled for. */
+  readonly scheduledTime: number
+  /** The matching cron expression from `wrangler.toml` `[triggers]`. */
+  readonly cron: string
+  /** Tell the platform not to retry this run on failure. */
+  noRetry(): void
+}
+
+/** A nifra cron handler: the platform controller + the same typed `env`/`waitUntil` nifra threads into
+ * request handlers. Schedule background work with `waitUntil` so it outlives the trigger. */
+export type ScheduledHandler<Env = unknown> = (
+  controller: ScheduledController,
+  context: { readonly env: Env; waitUntil(promise: Promise<unknown>): void },
+) => MaybePromise<void>
+
+/** Cloudflare's `WebSocketPair` - feature-detected (absent off Workers). Yields `{ 0: client, 1: server }`. */
+type WebSocketPairCtor = new () => {
+  readonly 0: unknown
+  readonly 1: StandardWebSocket & { accept(): void }
+}
+
+/** Structural view of a Cloudflare Durable Object namespace binding - keeps `@cloudflare/workers-types`
+ * out of `@nifrajs/core`. The real `DurableObjectNamespace` satisfies it. */
+export interface DurableObjectNamespaceLike {
+  idFromName(name: string): unknown
+  get(id: unknown): { fetch(request: Request): Promise<Response> }
+}
+
+/** The single hub Durable Object id nifra routes WS upgrades to (one hub per app - see `@nifrajs/workers`). */
+const NIFRA_WS_HUB_ID = "nifra-ws-hub"
+
+/**
+ * Adapt a nifra app to an edge "ExportedHandler" - use it as a Cloudflare Workers (or any
+ * `fetch(request, env, ctx)` runtime) default export. It threads `env` + `ctx.waitUntil` into the
+ * nifra Context, so handlers read `c.env` and schedule background work via `c.waitUntil`:
+ *
+ *   export default toFetchHandler(app)
+ *
+ * Pass `{ scheduled }` to also export a Workers cron handler (for a `[triggers]` schedule) - it
+ * receives the platform controller plus the same typed `env`/`waitUntil`:
+ *
+ *   export default toFetchHandler(app, {
+ *     scheduled: (controller, { env, waitUntil }) =>
+ *       waitUntil(env.KV.put("last-run", String(controller.scheduledTime))),
+ *   })
+ *
+ * No Workers-only deps - `app.fetch` stays a portable Web-standard handler; this is the thin
+ * shim from the platform's 3-arg `fetch`/`scheduled` to it.
+ */
+export function toFetchHandler<Env = unknown>(
+  app: {
+    fetch(request: Request, platform?: Platform<Env>): MaybePromise<Response>
+    resolveWebSocketUpgrade?(
+      request: Request,
+      platform?: Platform<Env>,
+    ): MaybePromise<WebSocketUpgradeOutcome>
+  },
+  options?: {
+    scheduled?: ScheduledHandler<Env>
+    /**
+     * Route WebSocket upgrades to a Durable Object that holds the connections and runs the app's
+     * pub/sub - enabling cross-connection broadcast (`app.publish`) on Cloudflare Workers, where a
+     * stateless isolate can't. Pass the DO namespace binding from `env`; pair with `@nifrajs/workers`'
+     * `createWebSocketHub(app)` (the DO class) + a `wrangler.toml` binding. Without this, WS upgrades use
+     * a per-connection `WebSocketPair` (no broadcast).
+     */
+    webSocketHub?: (env: Env) => DurableObjectNamespaceLike
+  },
+): {
+  fetch(request: Request, env: Env, ctx: ExecutionContext): MaybePromise<Response>
+  scheduled?(controller: ScheduledController, env: Env, ctx: ExecutionContext): MaybePromise<void>
+} {
+  const scheduled = options?.scheduled
+  const webSocketHub = options?.webSocketHub
+  const resolveWs = app.resolveWebSocketUpgrade?.bind(app)
+  return {
+    fetch: (request, env, ctx) => {
+      const platform: Platform<Env> = { env, waitUntil: (promise) => ctx.waitUntil(promise) }
+      // WebSocket broadcast on Workers: route upgrades to the hub Durable Object (it holds the
+      // connections + runs the app's pub/sub, so `app.publish` reaches every client). The hub itself
+      // resolves the route and rejects non-WS paths. See `@nifrajs/workers`' `createWebSocketHub`.
+      if (
+        webSocketHub !== undefined &&
+        request.headers.get("upgrade")?.toLowerCase() === "websocket"
+      ) {
+        const ns = webSocketHub(env)
+        return ns.get(ns.idFromName(NIFRA_WS_HUB_ID)).fetch(request)
+      }
+      // Workers WebSockets: a WS upgrade for a registered route becomes a `WebSocketPair` + a 101.
+      // Feature-detected, so non-Workers edge runtimes (which lack `WebSocketPair` - e.g. Deno Deploy
+      // uses `@nifrajs/deno`'s `Deno.upgradeWebSocket`) simply fall through to the normal `fetch`.
+      const Pair = (globalThis as { WebSocketPair?: WebSocketPairCtor }).WebSocketPair
+      if (resolveWs !== undefined && Pair !== undefined) {
+        const accept = (outcome: WebSocketUpgradeOutcome): MaybePromise<Response> => {
+          if (outcome.kind === "pass") return app.fetch(request, platform)
+          if (outcome.kind === "reject") return outcome.response
+          const pair = new Pair()
+          const server = pair[1]
+          server.accept()
+          // The outcome carries the installed runtime's `attach`, so `toFetchHandler` (a standalone
+          // function, no access to the app's private runtime) wires the socket without a static WS import.
+          outcome.attach(server, outcome.handler, outcome.data, {
+            openNow: true,
+            pubsub: outcome.pubsub,
+          })
+          // `webSocket` is a Workers-only `ResponseInit` field (absent from the standard type), and a
+          // 101 status is only valid on the Workers runtime - both gated by the `Pair` feature check.
+          return new Response(null, { status: 101, webSocket: pair[0] } as unknown as ResponseInit)
+        }
+        const out = resolveWs(request, platform)
+        return out instanceof Promise ? out.then(accept) : accept(out)
+      }
+      return app.fetch(request, platform)
+    },
+    ...(scheduled !== undefined
+      ? {
+          scheduled: (controller: ScheduledController, env: Env, ctx: ExecutionContext) =>
+            scheduled(controller, { env, waitUntil: (promise) => ctx.waitUntil(promise) }),
+        }
+      : {}),
+  }
+}

package/src/server/install.ts

@@ -26,3 +26,8 @@ export const INSTALL_NODE_DIRECT: unique symbol = Symbol.for("@nifrajs/core/inst
 
 /** @internal Install the WebSocket runtime on a server (called by the `websocket()` plugin). */
 export const INSTALL_WS: unique symbol = Symbol.for("@nifrajs/core/install-ws")
+
+/** @internal Install the response-contract runtime on a server (called by the `responseContract()` plugin). */
+export const INSTALL_RESPONSE_CONTRACT: unique symbol = Symbol.for(
+  "@nifrajs/core/install-response-contract",
+)