rouzer 5.3.1 → 6.0.1

package/docs/migration-v5-to-v6.md

@@ -0,0 +1,205 @@
+# Migrating from v5 to v6
+
+> Move a v5 application from Hattip-compatible server integration to Rouzer's
+> Fetch-compatible handler boundary without rewriting its route contract.
+
+Rouzer v6 moves the server runtime boundary from Hattip-compatible handlers to
+fetch-compatible Rouzer handlers. Route declarations, handler maps, generated
+clients, response maps, response plugins, raw bodies, and NDJSON routes keep the
+same Rouzer shape.
+
+> [!IMPORTANT]
+> Most applications only need to update server mounting code, tests, and any
+> explicit Hattip handler or context types. Keep the shared route tree unchanged
+> unless the application API is changing too.
+
+## Replace Hattip adapters with Fetch handlers
+
+Remove Hattip packages that were used only to mount Rouzer handlers.
+
+```sh
+pnpm remove @hattip/core @hattip/adapter-node @hattip/adapter-test
+pnpm add rouzer zod
+```
+
+Use Rouzer's root `toFetchHandler` helper when a server or test harness expects
+a function that receives a Web `Request` and returns a `Response`.
+
+```ts
+import { createRouter, toFetchHandler } from 'rouzer'
+
+const router = createRouter({ basePath: 'api/' }).use(routes, handlers)
+
+export const fetch = toFetchHandler(router)
+```
+
+If your server already accepts a Fetch API handler, mount `fetch` directly. If
+your server exposes host metadata such as client IP, runtime data, environment
+lookups, or background work, pass it through `toFetchHandler`.
+
+```ts
+const fetch = toFetchHandler(router, {
+  host: request => ({
+    ip: request.headers.get('x-forwarded-for') ?? undefined,
+    runtime: { name: 'node' },
+    env: name => process.env[name],
+    waitUntil: promise => {
+      void promise
+    },
+  }),
+})
+```
+
+## Replace Hattip types
+
+Rouzer no longer requires Hattip types in application code.
+
+```ts
+// v5
+import type { AdapterRequestContext, HattipHandler } from '@hattip/core'
+
+// v6
+import type { RequestContext, RequestHandler } from 'rouzer'
+```
+
+Rouzer routers are `RequestHandler` values. Middleware and route handlers receive
+`RequestContext` plus the route-specific fields that Rouzer infers from your
+route tree.
+
+## Update tests
+
+If tests used `@hattip/adapter-test`, replace it with a small local fetch
+wrapper.
+
+```ts
+// v5
+import { createTestClient } from '@hattip/adapter-test'
+
+const client = createClient({
+  baseURL,
+  routes,
+  fetch: createTestClient({
+    handler,
+    baseUrl: baseURL,
+  }),
+})
+```
+
+```ts
+// v6
+import { createClient, toFetchHandler, type RequestHandler } from 'rouzer'
+
+function createLocalFetch(handler: RequestHandler): typeof fetch {
+  const fetchHandler = toFetchHandler(handler)
+  return (input, init) => fetchHandler(new Request(input, init))
+}
+
+const client = createClient({
+  baseURL,
+  routes,
+  fetch: createLocalFetch(handler),
+})
+```
+
+The wrapper matters because generated clients call `fetch(input, init)`, while a
+Rouzer fetch handler receives one `Request`.
+
+## Use `ctx.host` for host data
+
+Host-provided values now live under `ctx.host`.
+
+```ts
+const ip = ctx.host.ip
+const runtimeName = ctx.host.runtime?.name
+```
+
+If old code read adapter-specific fields directly from the context, move those
+values behind the `host` option when creating the fetch handler.
+
+```ts
+const fetch = toFetchHandler(router, {
+  host: request => ({
+    ip: request.headers.get('x-forwarded-for') ?? undefined,
+    runtime: { name: 'custom' },
+  }),
+})
+```
+
+## Rename runtime filters
+
+If code used the old platform filter helper from Rouzer's root exports, use
+`filterRuntime`.
+
+```ts
+// v5
+import { filterPlatform } from 'rouzer'
+
+const middleware = chain().use(filterPlatform('node'))
+```
+
+```ts
+// v6
+import { filterRuntime } from 'rouzer'
+
+const middleware = chain().use(filterRuntime<{ name: 'node' }>('node'))
+```
+
+`filterRuntime(name)` checks `ctx.host.runtime?.name` and narrows the downstream
+runtime type.
+
+## Update custom contexts
+
+If tests or custom adapters constructed request contexts directly, use
+`createContext` with a Web `Request` and optional `host` data.
+
+```ts
+import { createContext } from 'rouzer'
+
+const context = createContext({
+  request: new Request('https://example.test/api/health'),
+  host: {
+    ip: '127.0.0.1',
+    runtime: { name: 'test' },
+    env: name => process.env[name],
+    waitUntil: promise => {
+      void promise
+    },
+  },
+})
+
+const response = await router(context)
+```
+
+## Update pass-through assumptions
+
+`ctx.passThrough()` is middleware-chain control flow. It skips the rest of the
+current chain and lets the parent chain continue. In a final fetch handler, an
+unresolved request becomes Rouzer's default `404 Not Found` response.
+
+Use `ctx.passThrough()` for optional middleware branches and runtime filters.
+Return a `Response` when you want to stop the request deliberately.
+
+## What stays the same
+
+These Rouzer APIs keep the same shape:
+
+- `rouzer/http` resources and actions
+- `createRouter().use(routes, handlers)` route registration
+- middleware added with `.use(middleware)`
+- generated clients from `createClient({ baseURL, routes })`
+- flat client action input objects
+- `$type<T>()`, `$error<T>()`, and response maps
+- response plugins such as `ndjson.routerPlugin` and `ndjson.clientPlugin`
+- `http.rawBody()` request bodies
+
+## Checklist
+
+1. Remove Hattip packages that were only used for Rouzer serving or tests.
+2. Mount routers with `toFetchHandler(router)`.
+3. Replace Hattip handler/context types with Rouzer `RequestHandler` and
+   `RequestContext`.
+4. Replace test adapters with a local fetch wrapper.
+5. Move host metadata into the `host` option and read it from `ctx.host`.
+6. Replace platform filters with `filterRuntime`.
+7. Keep route trees, handler maps, clients, responses, and plugins unchanged
+   unless your application code was also changing them.

package/docs/patterns.md

@@ -0,0 +1,147 @@
+# Patterns, constraints, and migrations
+
+> Review the stable project patterns and sharp edges that matter when route
+> contracts, middleware, handlers, and clients are composed in one application.
+
+Use this page as a checklist when designing route modules, middleware, and
+client usage.
+
+> [!IMPORTANT]
+> For the v5 server-boundary upgrade, follow
+> [Migration from v5 to v6](migration-v5-to-v6.md) instead of treating this
+> checklist as a migration procedure.
+
+## Preferred Patterns
+
+- Export route trees from small shared modules and import them from server and
+  client code.
+- Keep route declarations close to domain boundaries, not scattered through
+  handler implementations.
+- Use `http.resource(...)` for resource namespaces and shared path params.
+- Name actions after domain operations such as `get`, `list`, `update`,
+  `archive`, and `stream`.
+- Let `http.get`, `http.post`, `http.put`, `http.patch`, and `http.delete` own
+  the transport method.
+- Add Zod schemas when runtime guarantees matter; rely on inferred path params
+  only when string params are enough.
+- Use `$type<T>()` for typed JSON success responses.
+- Use response maps with `$error<T>()` for declared application errors that
+  callers should handle as data.
+- Use `Response` returns for redirects, binary payloads, custom non-JSON error
+  bodies, or unusual headers.
+- Use `ndjson.$type<T>()` only for response streams where each line is a JSON
+  value.
+- Put shared auth, tracing, request IDs, environment bindings, and host-runtime
+  checks in middleware before route registration.
+
+## Constraints And Gotchas
+
+- `$type<T>()`, `$error<T>()`, and `ndjson.$type<T>()` are compile-time type
+  contracts. They do not re-validate handler return values.
+- Client action input is flat across path, query, and JSON body fields. Avoid
+  duplicate field names across those schemas.
+- Per-request `RequestInit` fields belong in the second client action argument.
+  Rouzer reserves `method`.
+- Raw-body actions with path or query input accept `body` in the second
+  argument. Raw-body actions without route input accept the body as the first
+  argument.
+- `GET` actions do not accept request bodies. Mutation actions do not accept
+  query schemas.
+- The action API has no `ALL` fallback route. Declare concrete actions for
+  supported HTTP methods.
+- Pathname route patterns expect an absolute client `baseURL`.
+- Resource and action keys are API names only. URL paths come from the pattern
+  strings passed to resources and actions.
+- Routes that use response plugin markers require matching router and client
+  plugins.
+- Declared `$error<T>()` responses are JSON responses. Use a custom `Response`
+  for non-JSON error payloads.
+- Rouzer CORS support does not set `Access-Control-Allow-Credentials`.
+
+## Middleware Constraints
+
+- Host data is under `ctx.host`, including `ctx.host.ip` and
+  `ctx.host.runtime`.
+- The `env`, `runtime`, and `onResponse` request plugin keys are reserved.
+- `runtime` is a type-level marker for `ctx.host.runtime`; it does not create
+  `ctx.runtime`.
+- Use `ctx.setHeader` from request middleware and `response.headers.set(...)`
+  inside response callbacks.
+- `ctx.passThrough()` skips the rest of the current chain. It is not an adapter
+  pass-through mechanism.
+- Use `.isolate()` when a chain should run without leaking context properties to
+  the parent chain.
+
+## Project Shape
+
+A common layout:
+
+```text
+src/
+  routes/
+    profiles.ts
+  server/
+    middleware.ts
+    router.ts
+  client/
+    api.ts
+```
+
+`routes/profiles.ts` exports route contracts. `server/router.ts` imports those
+contracts and attaches handlers. `client/api.ts` imports the same contracts and
+creates the typed client.
+
+> [!IMPORTANT]
+> Keep shared route modules free of server-only dependencies when browser
+> clients import them.
+
+## v2 To v3 Route Shape
+
+Older Rouzer code used method-map routes. Current Rouzer uses action/resource
+route trees.
+
+```ts
+// Old shape
+export const profileRoute = route('profiles/:id', {
+  GET: { response: $type<Profile>() },
+  PATCH: { body: updateProfileSchema, response: $type<Profile>() },
+})
+```
+
+Use named actions instead:
+
+```ts
+export const profiles = http.resource('profiles/:id', {
+  get: http.get({ response: $type<Profile>() }),
+  update: http.patch({
+    body: updateProfileSchema,
+    response: $type<Profile>(),
+  }),
+})
+
+export const routes = { profiles }
+```
+
+Handler maps and clients mirror those action names.
+
+```ts
+createRouter().use(routes, {
+  profiles: {
+    get(ctx) {
+      return loadProfile(ctx.path.id)
+    },
+    update(ctx) {
+      return updateProfile(ctx.path.id, ctx.body)
+    },
+  },
+})
+
+await client.profiles.get({ id: '42' })
+await client.profiles.update({ id: '42', name: 'Ada' })
+```
+
+## Runtime Context Notes
+
+Use `ctx.host.runtime` for host runtime metadata and `filterRuntime(...)` for
+runtime-specific branches. Keep runtime checks at the middleware boundary so
+route handlers stay focused on request validation and application behavior.

package/docs/responses.md

@@ -0,0 +1,191 @@
+# Responses, errors, and plugins
+
+> Choose whether callers receive typed JSON, a raw Web `Response`, a declared
+> status tuple, or a plugin-decoded value.
+
+Rouzer response schemas shape handler return types and generated client result
+types.
+
+> [!IMPORTANT]
+> Response markers do not validate handler return values at runtime. They are
+> TypeScript contracts between handlers and generated clients.
+
+## Plain JSON Success
+
+Use `$type<T>()` for JSON responses that should be typed on the server and
+client.
+
+```ts
+export const getProfile = http.get('profiles/:id', {
+  response: $type<Profile>(),
+})
+
+createRouter().use(
+  { getProfile },
+  {
+    getProfile(ctx) {
+      return { id: ctx.path.id, name: 'Ada' }
+    },
+  }
+)
+
+const profile = await client.getProfile({ id: '42' })
+```
+
+Handlers may return a plain JSON-serializable value or a custom `Response`.
+Plain values are sent with `Response.json(value)`.
+
+## Raw Response
+
+If an action has no `response` marker, generated client action functions resolve
+to the raw `Response`.
+
+```ts
+export const download = http.get('exports/:id', {})
+
+const response = await client.download({ id: 'exp_123' })
+const blob = await response.blob()
+```
+
+Return a `Response` from handlers for redirects, custom headers, binary bodies,
+non-JSON content, or custom status handling.
+
+## Declared Error Responses
+
+Use `$error<T>()` inside a response map when an error status is part of the route
+contract and callers should handle it as typed data instead of an exception.
+
+```ts
+type User = { id: string; name: string }
+type NotFound = { code: 'NOT_FOUND'; message: string }
+
+export const getUser = http.get('users/:id', {
+  response: {
+    200: $type<User>(),
+    404: $error<NotFound>(),
+  },
+})
+```
+
+Response-map handlers can return a default success value directly or use helper
+methods.
+
+```ts
+createRouter().use(
+  { getUser },
+  {
+    getUser(ctx) {
+      const user = users.get(ctx.path.id)
+      if (!user) {
+        return ctx.error(404, {
+          code: 'NOT_FOUND',
+          message: 'User not found',
+        })
+      }
+      return user
+    },
+  }
+)
+```
+
+Generated clients resolve declared statuses as tuples:
+
+- success: `[null, value, status]`
+- error: `[error, null, status]`
+
+```ts
+const [error, user, status] = await client.getUser({ id: 'missing' })
+
+if (status === 404) {
+  console.log(error.message)
+} else {
+  console.log(user.name)
+}
+```
+
+Declared error statuses do not reject the client promise. Undeclared statuses
+still go through `onJsonError` or throw the default error.
+
+## Multiple Success Statuses
+
+When a response map declares multiple success statuses, return a plain value for
+the default success status or use `ctx.success(status, body)` to choose a
+specific declared success status.
+
+```ts
+export const createUser = http.post('users', {
+  body: createUserSchema,
+  response: {
+    200: $type<User>(),
+    201: $type<User>(),
+    409: $error<Conflict>(),
+  },
+})
+
+createRouter().use(
+  { createUser },
+  {
+    createUser(ctx) {
+      if (alreadyExists(ctx.body.email)) {
+        return ctx.error(409, {
+          code: 'CONFLICT',
+          message: 'Email already exists',
+        })
+      }
+
+      return ctx.success(201, create(ctx.body))
+    },
+  }
+)
+```
+
+The helpers only accept statuses and bodies declared in the map.
+
+## Response Plugins
+
+Response plugins add non-JSON response codecs without changing route matching or
+request validation. A plugin has:
+
+- a compile-time response marker
+- a router plugin that encodes handler results into `Response` objects
+- a client plugin that decodes successful `Response` objects into client results
+
+NDJSON is the built-in example:
+
+```ts
+export const events = http.get('events', {
+  response: ndjson.$type<Event>(),
+})
+
+createRouter({
+  plugins: [ndjson.routerPlugin],
+})
+
+createClient({
+  baseURL,
+  routes,
+  plugins: [ndjson.clientPlugin],
+})
+```
+
+> [!IMPORTANT]
+> Register the matching response plugin on both the router and client. Rouzer
+> fails fast when attaching routes with an unregistered marker instead of
+> falling back to JSON.
+
+Plugin markers can be used directly as an action response or as success entries
+in a response map. `$error<T>()` entries are JSON error responses.
+
+## Runtime Validation Boundary
+
+`$type<T>()`, `$error<T>()`, and plugin markers are TypeScript contracts. Rouzer
+does not re-check handler return values against those types at the server
+boundary.
+
+Validate untrusted data where it enters your system, such as:
+
+- external API clients
+- database decoders
+- queue/event consumers
+- form-data or file-processing layers
+- UI/client boundaries that consume untrusted responses