rouzer 5.3.1 → 6.0.0

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

@@ -0,0 +1,200 @@
+# Migrating from v5 to v6
+
+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.
+
+Most applications only need to update server mounting code, tests, and any
+explicit Hattip handler/context types.
+
+## 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,139 @@
+# Patterns, constraints, and migrations
+
+Use this page as a checklist when designing route modules, middleware, and
+client usage. For the current server-boundary upgrade, use
+[Migration from v5 to v6](migration-v5-to-v6.md).
+
+## 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.
+
+Keep 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,183 @@
+# Responses, errors, and plugins
+
+Rouzer response schemas shape handler return types and generated client result
+types. They do not automatically validate handler return values at runtime.
+
+## 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],
+})
+```
+
+Rouzer validates plugin registration when routes are attached to a router or
+client. Routes that use an unregistered response marker fail fast 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

package/docs/routes.md

@@ -0,0 +1,195 @@
+# Route contracts
+
+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. Avoid duplicate field names across those schemas because a flat
+object 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 } }
+)
+```
+
+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.