rouzer 5.3.1 → 6.0.1

package/docs/routes.md

@@ -0,0 +1,206 @@
+# Route contracts
+
+> Define each HTTP operation once so its URL, validated input, handler type, and
+> generated client call stay aligned.
+
+Declare route contracts with the `rouzer/http` subpath. A route contract is the
+shared source of truth for server handler types, client action types, URL
+construction, and request validation.
+
+```ts
+import { $type, metadata } from 'rouzer'
+import * as http from 'rouzer/http'
+import * as z from 'zod'
+
+type Profile = {
+  id: string
+  name: string
+}
+
+export const profiles = http.resource('profiles/:id', {
+  ...metadata({ description: 'Profile operations' }),
+  get: http.get({
+    query: z.object({
+      includePosts: z.optional(z.boolean()),
+    }),
+    response: $type<Profile>(),
+  }),
+  update: http.patch({
+    body: z.object({
+      name: z.string().check(z.minLength(1)),
+    }),
+    response: $type<Profile>(),
+  }),
+})
+
+export const routes = { profiles }
+```
+
+## Resources
+
+Use `http.resource(path, children)` when actions share a path prefix or when the
+client API should be namespaced.
+
+```ts
+export const organizations = http.resource('orgs/:orgId', {
+  members: http.resource('members/:memberId', {
+    get: http.get({ response: $type<Member>() }),
+    remove: http.delete({}),
+  }),
+})
+
+await client.organizations.members.get({
+  orgId: 'acme',
+  memberId: '42',
+})
+```
+
+Resource keys are API names. They do not affect the URL. Resource path patterns
+and action-local path patterns are joined to produce the final route path.
+
+## Actions
+
+Use an action for each HTTP operation:
+
+| Helper             | Request schemas                        | Notes                                       |
+| ------------------ | -------------------------------------- | ------------------------------------------- |
+| `http.get(...)`    | `path`, `query`, `headers`, `response` | `GET` actions do not accept request bodies. |
+| `http.post(...)`   | `path`, `body`, `headers`, `response`  | Mutation action. No `query` schema.         |
+| `http.put(...)`    | `path`, `body`, `headers`, `response`  | Mutation action. No `query` schema.         |
+| `http.patch(...)`  | `path`, `body`, `headers`, `response`  | Mutation action. No `query` schema.         |
+| `http.delete(...)` | `path`, `body`, `headers`, `response`  | Mutation action. No `query` schema.         |
+
+Each helper accepts either `(schema)` or `(path, schema)`.
+
+```ts
+export const listProfiles = http.get('profiles', {
+  query: z.object({ page: z.optional(z.number()) }),
+  response: $type<Profile[]>(),
+})
+
+export const getProfile = http.get({
+  response: $type<Profile>(),
+})
+```
+
+The HTTP action API models explicit operations. It does not have an `ALL`
+fallback route. Declare each supported method directly.
+
+## Path Patterns
+
+Rouzer uses `@remix-run/route-pattern` for path patterns. Common patterns
+include:
+
+- `profiles/:id`
+- `v:major.:minor`
+- `api(/v:major(.:minor))`
+- `assets/*path`
+- `search?q`
+
+If you omit a `path` schema, TypeScript infers path params from the route
+pattern and server handlers receive strings. Add a Zod `path` schema when you
+need runtime validation, transforms, or non-string handler types.
+
+```ts
+export const profile = http.get('profiles/:id', {
+  path: z.object({
+    id: z.uuid(),
+  }),
+  response: $type<Profile>(),
+})
+```
+
+Full URL patterns can be used for top-level actions. Keep full URL patterns out
+of resource/base-path composition because resources and router `basePath`
+compose path segments.
+
+## Request Schemas
+
+Request schemas are Zod objects except for `body: http.rawBody()`.
+
+```ts
+export const updateProfile = http.patch('profiles/:id', {
+  path: z.object({ id: z.uuid() }),
+  body: z.object({ name: z.string() }),
+  headers: z.object({
+    'content-type': z.literal('application/json'),
+  }),
+  response: $type<Profile>(),
+})
+```
+
+On the client, path, query, and JSON body fields are flattened into the first
+action argument.
+
+> [!IMPORTANT]
+> Keep field names unique across path, query, and JSON body schemas. A flat
+> client input cannot represent separate values for the same key.
+
+```ts
+await client.updateProfile({
+  id: 'a0f12d72-24e5-4eb0-bb70-6345f574e62a',
+  name: 'Ada',
+})
+```
+
+Per-request `RequestInit` options, including headers and abort signals, are
+passed as the second argument.
+
+## Raw Bodies
+
+Use `http.rawBody()` when an action should pass a `BodyInit` through to `fetch`
+without JSON encoding.
+
+```ts
+export const uploadAvatar = http.post('profiles/:id/avatar', {
+  body: http.rawBody(),
+  headers: z.object({ 'content-type': z.string() }),
+})
+
+await client.uploadAvatar(
+  { id: '42' },
+  { body: file, headers: { 'content-type': file.type } }
+)
+```
+
+> [!NOTE]
+> Raw-body argument placement depends on route input. With path or query input,
+> pass the body as `options.body`; without route input, pass the body as the
+> first argument.
+
+For a raw-body route without path or query input, the generated client accepts
+the body as the first argument.
+
+```ts
+export const upload = http.post('uploads', {
+  body: http.rawBody(),
+})
+
+await client.upload(file, {
+  headers: { 'content-type': file.type },
+})
+```
+
+Server handlers for raw-body routes read from `ctx.request` with Fetch APIs such
+as `arrayBuffer()`, `blob()`, `formData()`, or `text()`. Rouzer does not parse
+or validate raw request bodies.
+
+## Metadata
+
+Use `metadata(...)` to attach optional runtime metadata to resources or actions.
+Metadata does not affect routing, validation, client typing, or handler
+behavior.
+
+```ts
+export const sessions = http.resource('sessions', {
+  ...metadata({ description: 'Session control' }),
+  list: http.post('list', {
+    ...metadata({ description: 'List sessions' }),
+    response: $type<SessionList>(),
+  }),
+})
+```
+
+Constructed route nodes expose metadata through `node.metadata`. Use it for
+generated documentation, CLIs, route inspectors, or application-specific
+tooling.

package/docs/runtime.md

@@ -0,0 +1,145 @@
+# Runtime and adapters
+
+> Adapt a Rouzer request handler to a Fetch runtime while keeping host-specific
+> data behind the request context boundary.
+
+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`.
+
+> [!WARNING]
+> Rouzer does not set `Access-Control-Allow-Credentials`. Set it yourself before
+> relying on credentialed cross-origin requests.
+
+## 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.
+
+> [!NOTE]
+> Without `host.waitUntil`, the request context has no runtime-specific lifetime
+> extension to delegate to. Provide it when background work must outlive the
+> response.

package/docs/streaming.md

@@ -0,0 +1,139 @@
+# NDJSON streaming
+
+> Stream a sequence of JSON values through a typed route while preserving
+> incremental delivery, cancellation, and explicit error modeling.
+
+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
+
+> [!IMPORTANT]
+> 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.
+
+> [!NOTE]
+> 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()`.
+
+> [!TIP]
+> Make waits for future events abort-aware when cleanup must 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
+
+> [!NOTE]
+> 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 NDJSON example](https://github.com/alloc/rouzer/blob/main/examples/ndjson-stream.ts)
+includes the shared route, router, client, and stream consumption loop.

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.1",
   "packageManager": "pnpm@11.5.1",
   "type": "module",
   "exports": {
@@ -28,9 +28,9 @@
   },
   "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",
+    "lildocs": "^0.1.15",
     "prettier": "^3.8.3",
     "rouzer": "link:.",
     "tsc-lint": "^0.1.9",
@@ -40,9 +40,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",