rouzer 5.3.1 → 6.0.0

package/docs/runtime.md

@@ -0,0 +1,136 @@
+# Runtime and adapters
+
+Rouzer routers are request handlers. Use adapter helpers to turn them into
+functions accepted by your HTTP server, framework, or tests.
+
+## Plain Fetch Handler
+
+For a plain Web `Request`, use the root `toFetchHandler` re-export.
+
+```ts
+import { createRouter, toFetchHandler } from 'rouzer'
+
+const router = createRouter().use(routes, handlers)
+const fetchHandler = toFetchHandler(router)
+
+const response = await fetchHandler(new Request('https://example.test/users'))
+```
+
+`toFetchHandler(handler)` creates a Rouzer request context for each request and
+calls the handler.
+
+## Host Data
+
+Pass host data when middleware or handlers need environment variables, runtime
+metadata, client IP, or background work support.
+
+```ts
+const fetchHandler = toFetchHandler(router, {
+  host: request => ({
+    ip: request.headers.get('x-forwarded-for') ?? undefined,
+    runtime: { name: 'custom' },
+    env: name => process.env[name],
+    waitUntil: promise => {
+      void promise
+    },
+  }),
+})
+```
+
+Handlers read that data from the request context:
+
+```ts
+ctx.host.ip
+ctx.host.runtime?.name
+ctx.env('DATABASE_URL')
+ctx.waitUntil(writeAuditLog())
+```
+
+Host runtime data lives under `ctx.host.runtime`.
+
+## Fetch-Compatible Servers
+
+Many servers and frameworks accept a function that receives a Web `Request` and
+returns a `Response`. Mount `toFetchHandler(router)` in those environments.
+
+```ts
+const router = createRouter().use(routes, handlers)
+const fetch = toFetchHandler(router)
+```
+
+If the server exposes extra request metadata, pass it through the `host` option
+so middleware and handlers can read it from `ctx.host`.
+
+## Custom Contexts
+
+Use `createContext` when writing custom adapters or tests that call a handler
+directly.
+
+```ts
+import { createContext } from 'rouzer'
+
+const context = createContext({
+  request: new Request('https://example.test/api/health'),
+  host: {
+    runtime: { name: 'test' },
+    env: name => process.env[name],
+  },
+})
+
+const response = await router(context)
+```
+
+Most tests should prefer a local fetch wrapper because it exercises URL
+construction and request creation through the client.
+
+```ts
+import { toFetchHandler, type RequestHandler } from 'rouzer'
+
+function createLocalFetch(handler: RequestHandler): typeof fetch {
+  const fetchHandler = toFetchHandler(handler)
+  return (input, init) => fetchHandler(new Request(input, init))
+}
+```
+
+## CORS
+
+Rouzer can restrict requests with an `Origin` header through router config.
+
+```ts
+createRouter({
+  cors: {
+    allowOrigins: [
+      'example.net',
+      'https://*.example.com',
+      '*://localhost:3000',
+    ],
+  },
+})
+```
+
+Origins may contain wildcard protocol and subdomain segments. Origins without a
+protocol default to `https`.
+
+For allowed non-preflight requests, Rouzer sets
+`Access-Control-Allow-Origin`. For preflight requests, Rouzer returns
+`Access-Control-Allow-Origin`, `Access-Control-Allow-Methods`, and
+`Access-Control-Allow-Headers`.
+
+Rouzer does not set `Access-Control-Allow-Credentials`; set it yourself when
+credentialed requests need it.
+
+## Background Work
+
+Use `ctx.waitUntil(promise)` in middleware or handlers when the host supports
+background work.
+
+```ts
+ctx.waitUntil(
+  writeAuditLog({
+    route: ctx.url.pathname,
+    runtime: ctx.host.runtime?.name,
+  })
+)
+```
+
+The adapter delegates to `host.waitUntil` when you provide it.

package/docs/streaming.md

@@ -0,0 +1,131 @@
+# NDJSON streaming
+
+Rouzer includes a response plugin for newline-delimited JSON response streams.
+Use it when a route should send a sequence of JSON values without buffering the
+whole response.
+
+```ts
+import { createClient, createRouter } from 'rouzer'
+import * as http from 'rouzer/http'
+import * as ndjson from 'rouzer/ndjson'
+
+type Event = {
+  id: number
+  message: string
+}
+
+export const events = http.get('events', {
+  response: ndjson.$type<Event>(),
+})
+
+export const routes = { events }
+
+const router = createRouter({
+  plugins: [ndjson.routerPlugin],
+}).use(routes, {
+  async *events() {
+    yield { id: 1, message: 'ready' }
+    yield { id: 2, message: 'done' }
+  },
+})
+
+const client = createClient({
+  baseURL: 'https://example.com/api/',
+  routes,
+  plugins: [ndjson.clientPlugin],
+})
+
+for await (const event of await client.events()) {
+  console.log(event.message)
+}
+```
+
+Handlers return an `Iterable<T>` or `AsyncIterable<T>`. The client action
+resolves to an `AsyncIterable<T>`.
+
+## Plugin Registration
+
+Register both sides when a route tree contains `ndjson.$type<T>()`:
+
+- `ndjson.routerPlugin` in `createRouter({ plugins })`
+- `ndjson.clientPlugin` in `createClient({ plugins })`
+
+Rouzer fails fast if a route uses a response plugin marker and the matching
+plugin is not registered.
+
+## POST Streams
+
+NDJSON is a response codec. Requests still use normal Rouzer request schemas.
+A route can receive a JSON body and return an NDJSON stream.
+
+```ts
+export const streamEvents = http.post('events/stream', {
+  body: z.object({
+    topic: z.string(),
+  }),
+  response: ndjson.$type<Event>(),
+})
+
+createRouter({ plugins: [ndjson.routerPlugin] }).use(
+  { streamEvents },
+  {
+    async *streamEvents(ctx) {
+      yield { id: 1, message: `topic:${ctx.body.topic}` }
+    },
+  }
+)
+```
+
+Use `http.rawBody()` only when the request body itself should pass through as a
+`BodyInit`.
+
+## Encoding And Decoding
+
+`ndjson.routerPlugin` serializes each yielded value with `JSON.stringify` and
+adds a newline. The response content type defaults to
+`application/x-ndjson; charset=utf-8`.
+
+`ndjson.clientPlugin` decodes UTF-8 chunks, accepts `\n` and `\r\n` line endings,
+and parses each line with `JSON.parse`. A final line does not need a trailing
+newline. Malformed JSON throws a `SyntaxError` with the line number.
+
+Streamed items are not validated against a Zod schema. If item validation is
+needed, validate before yielding on the server or while consuming on the client.
+
+## Cancellation
+
+If a client aborts the request signal or stops iteration early by breaking from
+`for await` or calling the iterator's `return()`, Rouzer cancels the response
+body and calls the server source iterator's `return()`.
+
+Sources that wait for future events should make those waits abort-aware when
+cleanup needs to run while an awaited operation is still pending.
+
+```ts
+async function readFirst<T>(source: AsyncIterable<T>) {
+  const iterator = source[Symbol.asyncIterator]()
+  try {
+    return (await iterator.next()).value
+  } finally {
+    await iterator.return?.()
+  }
+}
+```
+
+## Stream Errors
+
+Rouzer does not convert handler or generator failures into extra NDJSON items.
+If an async generator throws after the response starts, the response stream
+errors and the client's `for await` loop throws.
+
+Model application-level stream errors as part of your item type when clients
+should receive them as data.
+
+```ts
+type StreamItem =
+  | { type: 'event'; id: number; message: string }
+  | { type: 'error'; message: string }
+```
+
+The complete runnable version is
+[examples/ndjson-stream.ts](../examples/ndjson-stream.ts).

package/examples/basic-usage.ts

@@ -1,6 +1,11 @@
-import type { HattipHandler } from '@hattip/core'
 import * as z from 'zod'
-import { $type, chain, createClient, createRouter } from 'rouzer'
+import {
+  $type,
+  chain,
+  createClient,
+  createRouter,
+  toFetchHandler,
+} from 'rouzer'
 import * as http from 'rouzer/http'
 
 type Profile = {
@@ -30,28 +35,11 @@ export const profiles = http.resource('profiles/:id', {
 
 export const routes = { profiles }
 
-/**
- * Tiny Hattip adapter used only to keep this example self-contained. Real apps
- * mount the handler with a Hattip adapter for their runtime.
- */
-function createLocalFetch(handler: HattipHandler): typeof fetch {
-  return async (input, init) => {
-    const request = new Request(input, init)
-    const response = await handler({
-      request,
-      ip: '127.0.0.1',
-      platform: undefined,
-      env() {
-        return undefined
-      },
-      passThrough() {},
-      waitUntil(promise) {
-        void promise
-      },
-    })
-
-    return response ?? new Response(null, { status: 404 })
-  }
+function createLocalFetch(
+  handler: ReturnType<typeof createRouter>
+): typeof fetch {
+  const fetchHandler = toFetchHandler(handler)
+  return (input, init) => fetchHandler(new Request(input, init))
 }
 
 export async function runBasicUsageExample() {
@@ -101,7 +89,10 @@ export async function runBasicUsageExample() {
     fetch: createLocalFetch(handler),
   })
 
-  const fetched = await client.profiles.get({ id: '42', includePosts: false }, { headers: { 'x-request-id': 'docs' } })
+  const fetched = await client.profiles.get(
+    { id: '42', includePosts: false },
+    { headers: { 'x-request-id': 'docs' } }
+  )
 
   const updated = await client.profiles.update({ id: '42', name: 'Grace' })
 

package/examples/error-responses.ts

@@ -1,5 +1,10 @@
-import type { HattipHandler } from '@hattip/core'
-import { $error, $type, createClient, createRouter } from 'rouzer'
+import {
+  $error,
+  $type,
+  createClient,
+  createRouter,
+  toFetchHandler,
+} from 'rouzer'
 import * as http from 'rouzer/http'
 
 type User = {
@@ -28,28 +33,11 @@ export const getUser = http.get('users/:id', {
 
 export const routes = { getUser }
 
-/**
- * Tiny Hattip adapter used only to keep this example self-contained. Real apps
- * mount the handler with a Hattip adapter for their runtime.
- */
-function createLocalFetch(handler: HattipHandler): typeof fetch {
-  return async (input, init) => {
-    const request = new Request(input, init)
-    const response = await handler({
-      request,
-      ip: '127.0.0.1',
-      platform: undefined,
-      env() {
-        return undefined
-      },
-      passThrough() {},
-      waitUntil(promise) {
-        void promise
-      },
-    })
-
-    return response ?? new Response(null, { status: 404 })
-  }
+function createLocalFetch(
+  handler: ReturnType<typeof createRouter>
+): typeof fetch {
+  const fetchHandler = toFetchHandler(handler)
+  return (input, init) => fetchHandler(new Request(input, init))
 }
 
 export async function runErrorResponsesExample() {

package/examples/ndjson-stream.ts

@@ -1,5 +1,4 @@
-import type { HattipHandler } from '@hattip/core'
-import { createClient, createRouter } from 'rouzer'
+import { createClient, createRouter, toFetchHandler } from 'rouzer'
 import * as http from 'rouzer/http'
 import * as ndjson from 'rouzer/ndjson'
 import { z } from 'zod'
@@ -31,28 +30,11 @@ export const stream = http.post('events/stream', {
 
 export const routes = { events, stream }
 
-/**
- * Tiny Hattip adapter used only to keep this example self-contained. Real apps
- * mount the handler with a Hattip adapter for their runtime.
- */
-function createLocalFetch(handler: HattipHandler): typeof fetch {
-  return async (input, init) => {
-    const request = new Request(input, init)
-    const response = await handler({
-      request,
-      ip: '127.0.0.1',
-      platform: undefined,
-      env() {
-        return undefined
-      },
-      passThrough() {},
-      waitUntil(promise) {
-        void promise
-      },
-    })
-
-    return response ?? new Response(null, { status: 404 })
-  }
+function createLocalFetch(
+  handler: ReturnType<typeof createRouter>
+): typeof fetch {
+  const fetchHandler = toFetchHandler(handler)
+  return (input, init) => fetchHandler(new Request(input, init))
 }
 
 async function collect<T>(source: AsyncIterable<T>) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rouzer",
-  "version": "5.3.1",
+  "version": "6.0.0",
   "packageManager": "pnpm@11.5.1",
   "type": "module",
   "exports": {
@@ -28,7 +28,6 @@
   },
   "devDependencies": {
     "@alloc/prettier-config": "^1.0.0",
-    "@hattip/adapter-test": "^0.0.49",
     "@types/node": "^25.8.0",
     "@typescript/native-preview": "7.0.0-dev.20260515.1",
     "prettier": "^3.8.3",
@@ -40,9 +39,8 @@
     "zod": "^4.4.3"
   },
   "dependencies": {
-    "@hattip/core": "^0.0.49",
     "@remix-run/route-pattern": "^0.22.1",
-    "alien-middleware": "^0.11.6"
+    "alien-middleware": "^0.12.0"
   },
   "prettier": "@alloc/prettier-config",
   "license": "MIT",