rouzer 2.0.0 → 3.0.0

package/docs/context.md

@@ -0,0 +1,339 @@
+# Rouzer context
+
+Rouzer is for applications that want one TypeScript HTTP route tree to drive
+both the server and the client that calls it. A route tree combines URL
+patterns, named actions, HTTP method schemas, and optional compile-time response
+types.
+
+## When to use Rouzer
+
+Use Rouzer when:
+
+- the same TypeScript project, package, or workspace can share route
+  declarations between server and client code
+- request validation should run before server handlers and before client `fetch`
+  calls
+- a Hattip-compatible handler fits your server runtime
+- generated clients should stay close to route definitions instead of being
+  produced by a separate OpenAPI build step
+
+Rouzer is not a response validation library, an OpenAPI generator, or a complete
+server framework. It focuses on typed route contracts, validation, routing, and a
+small client wrapper.
+
+## Core abstractions
+
+### HTTP route trees
+
+Declare shared routes with the `rouzer/http` subpath:
+
+```ts
+import { $type } from 'rouzer'
+import * as http from 'rouzer/http'
+
+export const getProfile = http.get('profiles/:id', {
+  response: $type<Profile>(),
+})
+
+export const routes = { getProfile }
+```
+
+An action is a callable endpoint leaf. Use `http.get`, `http.post`, `http.put`,
+`http.patch`, or `http.del`/`http.delete` to declare one HTTP operation. The key
+you put the action under is the client and handler name; the action path is the
+URL pattern.
+
+Use `http.resource(path, children)` when several actions share a path prefix or
+when you want nested client/handler namespaces:
+
+```ts
+export const profiles = http.resource('profiles/:id', {
+  get: http.get({
+    response: $type<Profile>(),
+  }),
+  update: http.patch({
+    body: updateProfileSchema,
+    response: $type<Profile>(),
+  }),
+  posts: http.resource('posts', {
+    list: http.get({
+      response: $type<Post[]>(),
+    }),
+  }),
+})
+
+export const routes = { profiles }
+```
+
+Resource property names do not affect the URL. Resource paths and action-local
+paths are joined, so the examples above expose `profiles/:id`, `profiles/:id`,
+and `profiles/:id/posts`. Path params from parent resources are accumulated into
+child action types.
+
+Patterns are parsed by `@remix-run/route-pattern` v0.21. Params can be inferred
+from patterns such as `hello/:name`, `v:major.:minor`,
+`api(/v:major(.:minor))`, `assets/*path`, and `search?q`. Full URL patterns such
+as `https://:store.shopify.com/orders` are supported for top-level actions; keep
+them out of resource/base-path composition.
+
+### Method schemas
+
+Method schemas describe the request pieces Rouzer should validate:
+
+| Action helper                         | Request schemas                        | Notes            |
+| ------------------------------------- | -------------------------------------- | ---------------- |
+| `http.get(...)`                       | `path`, `query`, `headers`, `response` | No request body. |
+| `http.post/put/patch/delete/del(...)` | `path`, `body`, `headers`, `response`  | No query schema. |
+
+If you omit a `path` schema, TypeScript infers path params from the pattern and
+server handlers receive them as strings. Add a Zod `path` schema when you need
+runtime validation, transforms, or non-string handler types.
+
+The HTTP action API models explicit operations. It does not expose the old
+method-map `ALL` fallback route shape; declare the concrete methods your client
+and server support.
+
+### `$type<T>()`
+
+`response: $type<T>()` is a TypeScript-only marker. It tells handlers and client
+action functions what response payload type to expect, but Rouzer does not
+validate response bodies at runtime.
+
+Actions without a `response` marker return a raw `Response` from client action
+functions. Actions with a `response` marker use `client.json(...)` under the hood
+and return parsed JSON typed as `T`.
+
+### Router
+
+`createRouter()` returns a Hattip-compatible handler. Use `.use(middleware)` to
+append typed `alien-middleware` middleware and `.use(routes, handlers)` to attach
+an HTTP route tree.
+
+The handler object mirrors the route tree:
+
+```ts
+createRouter().use(routes, {
+  profiles: {
+    get(ctx) {
+      return loadProfile(ctx.path.id)
+    },
+    update(ctx) {
+      return updateProfile(ctx.path.id, ctx.body)
+    },
+    posts: {
+      list(ctx) {
+        return listPosts(ctx.path.id)
+      },
+    },
+  },
+})
+```
+
+Handlers receive a context typed from middleware plus the action schema:
+
+- `GET` handlers receive `ctx.path`, `ctx.query`, and `ctx.headers`
+- mutation handlers receive `ctx.path`, `ctx.body`, and `ctx.headers`
+- handlers may return a plain JSON-serializable value or a `Response`
+- plain values are returned with `Response.json(value)`
+- return a `Response` when you need custom status, headers, or body handling
+
+`basePath` is prepended to route tree paths, `debug` adds matched-route debug
+headers and more detailed validation errors, and `cors.allowOrigins` restricts
+requests with an `Origin` header.
+
+### Client
+
+`createClient({ baseURL, routes })` creates:
+
+- `client.request(action.request(args))` for a raw `Response` when the action
+  request factory contains the full path you want to call
+- `client.json(action.request(args))` for parsed JSON and default non-2xx
+  throwing
+- a client tree that mirrors `routes`, with action functions such as
+  `client.profiles.get(args)` when `routes` is supplied
+
+Prefer an absolute `baseURL` for generated client URLs:
+
+```ts
+const client = createClient({
+  baseURL: new URL('/api/', window.location.origin).href,
+  routes,
+})
+```
+
+Default headers can be supplied with `headers`, per-request headers are merged on
+top, and a custom `fetch` implementation can be supplied for tests or non-browser
+runtimes.
+
+### Low-level `route(...)` descriptors
+
+The root package still exports `route(pattern, methods)`. It creates method-keyed
+request descriptor factories such as `legacyRoute.GET(args)` for explicit
+`client.request(...)` or `client.json(...)` calls.
+
+Prefer `rouzer/http` route trees for shared server/client routing. The router and
+client shorthand registration APIs expect `HttpAction`/`HttpResource` trees, not
+the older method-map objects produced by `route(...)`.
+
+## Lifecycle
+
+1. Define shared HTTP actions/resources with `rouzer/http` and Zod schemas.
+2. Attach that route tree to a server with `createRouter().use(routes, handlers)`.
+3. Create a client with the same route tree.
+4. Client action calls validate `path`, `query`, `body`, and `headers` before
+   `fetch`.
+5. The router matches the request, validates the matched inputs, and calls the
+   handler.
+6. Plain handler results become JSON responses; explicit `Response` objects pass
+   through unchanged.
+
+On the server, `path`, `query`, and `headers` values originate as strings. Rouzer
+coerces Zod `number` schemas with `Number(value)` and Zod `boolean` schemas from
+`"true"` and `"false"`. JSON request bodies are parsed and validated without that
+string-coercion step.
+
+## Common tasks
+
+### Choose a client call style
+
+Use client action functions for normal application calls:
+
+```ts
+await client.profiles.get({ path: { id: '42' } })
+await client.profiles.update({
+  path: { id: '42' },
+  body: { name: 'Ada' },
+})
+```
+
+Use longhand calls when you need to choose response handling explicitly. The
+action request factory must include the full path you want to call, so this style
+is most convenient for top-level actions:
+
+```ts
+export const getProfile = http.get('profiles/:id', {
+  response: $type<Profile>(),
+})
+export const routes = { getProfile }
+
+const response = await client.request(
+  routes.getProfile.request({ path: { id: '42' } })
+)
+
+const json = await client.json(
+  routes.getProfile.request({ path: { id: '42' } })
+)
+```
+
+### Group resource actions
+
+Use resources when the public API reads better as a tree or when actions share
+path params:
+
+```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({
+  path: { orgId: 'acme', memberId: '42' },
+})
+```
+
+### Return custom responses
+
+Return a `Response` from a handler for non-JSON payloads, custom status codes, or
+custom headers. Return a plain value for the default `Response.json(value)` path.
+
+### Customize JSON errors
+
+By default, `client.json(...)` throws for non-2xx responses. If the response body
+is JSON, its properties are copied onto the thrown `Error`.
+
+`onJsonError` can override that behavior. Its return value is returned from
+`client.json(...)` as-is; Rouzer does not automatically parse a returned
+`Response` from `onJsonError`.
+
+### Update code written for v2.0.1
+
+Rouzer now uses action/resource route trees for router registration and client
+shorthands. A v2.0.1 method-map route such as this:
+
+```ts
+export const profileRoute = route('profiles/:id', {
+  GET: { response: $type<Profile>() },
+  PATCH: { body: updateProfileSchema, response: $type<Profile>() },
+})
+
+export const routes = { profileRoute }
+```
+
+becomes a named action tree:
+
+```ts
+import * as http from 'rouzer/http'
+
+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 client calls mirror the new 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({ path: { id: '42' } })
+await client.profiles.update({
+  path: { id: '42' },
+  body: { name: 'Ada' },
+})
+```
+
+## Patterns to prefer
+
+- Export route trees from a small shared module and import that module on both
+  server and client.
+- Use `rouzer/http` actions for routes that are registered with
+  `createRouter().use(...)` or `createClient({ routes })`.
+- Add Zod schemas when you need runtime guarantees; rely on inferred path params
+  only when string params are sufficient.
+- Use `response: $type<T>()` for JSON endpoints that should have typed client
+  action functions.
+- Name actions after domain operations (`get`, `list`, `update`, `archive`) and
+  let `http.get/post/put/patch/delete` own the transport method.
+- Set `content-type: application/json` yourself when your server or middleware
+  depends on that header.
+
+## Constraints and gotchas
+
+- `$type<T>()` is compile-time only and does not validate response payloads.
+- Pathname route patterns expect an absolute client `baseURL`.
+- Resource and action keys are API names only; paths come from the pattern
+  strings passed to `http.resource(...)` and action helpers.
+- Nested action `.request(...)` factories do not include parent resource paths;
+  prefer client action functions for nested resources.
+- Extra `RequestInit` fields in route args, such as `signal` or `credentials`,
+  are accepted by the type surface but are not forwarded by `createClient`.
+- The HTTP action API has no `ALL` fallback route. Declare explicit actions for
+  supported methods.
+- Rouzer does not automatically set `Access-Control-Allow-Credentials`; set it in
+  your handler when credentialed cross-origin requests need it.

package/examples/basic-usage.ts

@@ -0,0 +1,116 @@
+import type { HattipHandler } from '@hattip/core'
+import * as z from 'zod'
+import { $type, chain, createClient, createRouter } from 'rouzer'
+import * as http from 'rouzer/http'
+
+type Profile = {
+  id: string
+  name: string
+  includePosts: boolean
+  requestId: string
+}
+
+export const profiles = http.resource('profiles/:id', {
+  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)),
+    }),
+    headers: z.object({
+      'content-type': z.literal('application/json'),
+    }),
+    response: $type<Profile>(),
+  }),
+})
+
+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 })
+  }
+}
+
+export async function runBasicUsageExample() {
+  const profileMap = new Map([['42', { id: '42', name: 'Ada' }]])
+
+  const requestMiddleware = chain().use(ctx => ({
+    requestId: ctx.request.headers.get('x-request-id') ?? 'local',
+  }))
+
+  const handler = createRouter({ basePath: 'api/' })
+    .use(requestMiddleware)
+    .use(routes, {
+      profiles: {
+        get(ctx) {
+          const profile = profileMap.get(ctx.path.id)
+          if (!profile) {
+            return new Response('Profile not found', { status: 404 })
+          }
+          return {
+            ...profile,
+            includePosts: ctx.query.includePosts ?? false,
+            requestId: ctx.requestId,
+          }
+        },
+        update(ctx) {
+          const current = profileMap.get(ctx.path.id)
+          if (!current) {
+            return new Response('Profile not found', { status: 404 })
+          }
+          const profile = { ...current, name: ctx.body.name }
+          profileMap.set(ctx.path.id, profile)
+          return {
+            ...profile,
+            includePosts: false,
+            requestId: ctx.requestId,
+          }
+        },
+      },
+    })
+
+  const client = createClient({
+    baseURL: 'https://example.test/api/',
+    routes,
+    headers: {
+      'content-type': 'application/json',
+    },
+    fetch: createLocalFetch(handler),
+  })
+
+  const fetched = await client.profiles.get({
+    path: { id: '42' },
+    query: { includePosts: false },
+    headers: { 'x-request-id': 'docs' },
+  })
+
+  const updated = await client.profiles.update({
+    path: { id: '42' },
+    body: { name: 'Grace' },
+  })
+
+  return { fetched, updated }
+}

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "rouzer",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "type": "module",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./http": {
+      "types": "./dist/http.d.ts",
+      "import": "./dist/http.js"
     }
   },
   "peerDependencies": {
@@ -14,20 +18,20 @@
   "devDependencies": {
     "@alloc/prettier-config": "^1.0.0",
     "@hattip/adapter-test": "^0.0.49",
-    "@types/node": "^25.0.3",
-    "@typescript/native-preview": "7.0.0-dev.20251208.1",
-    "prettier": "^3.7.4",
+    "@types/node": "^25.8.0",
+    "@typescript/native-preview": "7.0.0-dev.20260515.1",
+    "prettier": "^3.8.3",
     "rouzer": "link:.",
     "tsc-lint": "^0.1.9",
-    "typescript": "^5.9.3",
-    "vite": "^7.3.0",
-    "vitest": "^4.0.16",
-    "zod": "^4.1.13"
+    "typescript": "^6.0.3",
+    "vite": "^8.0.13",
+    "vitest": "^4.1.6",
+    "zod": "^4.4.3"
   },
   "dependencies": {
     "@hattip/core": "^0.0.49",
-    "@remix-run/route-pattern": "^0.15.3",
-    "alien-middleware": "^0.11.4"
+    "@remix-run/route-pattern": "^0.21.1",
+    "alien-middleware": "^0.11.6"
   },
   "prettier": "@alloc/prettier-config",
   "license": "MIT",
@@ -37,6 +41,9 @@
   },
   "files": [
     "dist",
+    "docs",
+    "examples",
+    "README.md",
     "!*.tsbuildinfo"
   ],
   "scripts": {

package/readme.md

@@ -1,176 +0,0 @@
-# rouzer
-
-Type-safe routes shared by your server and client, powered by `zod` (input validation + transforms), `@remix-run/route-pattern` (URL matching), and `alien-middleware` (typed middleware chaining). The router output is intended to be used with `@hattip/core` adapters.
-
-## Install
-
-```sh
-pnpm add rouzer zod
-```
-
-Everything is imported directly from `rouzer`.
-
-## Define routes (shared)
-
-```ts
-// routes.ts
-import * as z from 'zod'
-import { $type, route } from 'rouzer'
-
-export const helloRoute = route('hello/:name', {
-  GET: {
-    query: z.object({
-      excited: z.optional(z.boolean()),
-    }),
-    // The response is only type-checked at compile time.
-    response: $type<{ message: string }>(),
-  },
-})
-```
-
-The following request parts can be validated with Zod:
-
-- `path`
-- `query`
-- `body`
-- `headers`
-
-Zod validation happens on both the server and client.
-
-## Route URL patterns
-
-Rouzer uses `@remix-run/route-pattern` for matching and generation. Patterns can include:
-
-- Pathname-only patterns like `blog/:slug` (default).
-- Full URLs with protocol/hostname/port like `https://:store.shopify.com/orders`.
-- Dynamic segments with `:param` names (valid JS identifiers), including multiple params in one segment like `v:major.:minor`.
-- Optional segments wrapped in parentheses, which can be nested like `api(/v:major(.:minor))`.
-- Wildcards with `*name` (captured) or `*` (uncaptured) for multi-segment paths like `assets/*path` or `files/*`.
-- Query matching with `?` to require parameters or exact values like `search?q` or `search?q=routing`.
-
-## Server router
-
-```ts
-import { chain, createRouter } from 'rouzer'
-import { routes } from './routes'
-
-const middlewares = chain().use(ctx => {
-  // An example middleware. For more info, see https://github.com/alien-rpc/alien-middleware#readme
-  return {
-    db: postgres(ctx.env('POSTGRES_URL')),
-  }
-})
-
-export const handler = createRouter({
-  debug: process.env.NODE_ENV === 'development',
-})
-  .use(middlewares)
-  .use(routes, {
-    helloRoute: {
-      GET(ctx) {
-        const message = `Hello, ${ctx.path.name}${
-          ctx.query.excited ? '!' : '.'
-        }`
-        return { message }
-      },
-    },
-  })
-```
-
-## Router options
-
-```ts
-export const handler = createRouter({
-  basePath: 'api/',
-  cors: {
-    allowOrigins: [
-      'example.net',
-      'https://*.example.com',
-      '*://localhost:3000',
-    ],
-  },
-  debug: process.env.NODE_ENV === 'development',
-}).use(routes, {
-  helloRoute: {
-    GET(ctx) {
-      const message = `Hello, ${ctx.path.name}${ctx.query.excited ? '!' : '.'}`
-      return { message }
-    },
-  },
-})
-```
-
-- `basePath` is prepended to every route (leading/trailing slashes are trimmed).
-- CORS preflight (`OPTIONS`) is handled automatically for matched routes.
-- `cors.allowOrigins` restricts preflight requests to a list of origins (default is to allow any origin).
-  - Wildcards are supported for protocol and subdomain; the protocol is optional and defaults to `https`.
-- If you rely on `Cookie` or `Authorization` request headers, you must set
-  `Access-Control-Allow-Credentials` in your handler.
-
-## Client wrapper
-
-```ts
-import { createClient } from 'rouzer'
-import { helloRoute } from './routes'
-
-const client = createClient({ baseURL: '/api/' })
-
-const { message } = await client.json(
-  helloRoute.GET({ path: { name: 'world' }, query: { excited: true } })
-)
-
-// If you want the Response object, use `client.request` instead.
-const response = await client.request(
-  helloRoute.GET({ path: { name: 'world' } })
-)
-
-const { message } = await response.json()
-```
-
-### Custom fetch
-
-You can also pass a custom fetch implementation:
-
-```ts
-const client = createClient({
-  baseURL: '/api/',
-  fetch: myFetch,
-})
-```
-
-### Shorthand route methods
-
-Optionally pass your routes map to `createClient` to get per-route methods on the client:
-
-```ts
-import * as routes from './routes'
-
-const client = createClient({
-  baseURL: '/api/',
-  routes, // <–– Pass the routes
-})
-
-// Shorthand methods now available:
-await client.fooRoute.GET()
-// …same as the longhand:
-await client.json(routes.fooRoute.GET())
-```
-
-Routes that define a `response` type will call `client.json()` under the hood and return the parsed value; routes without one return the raw `Response`:
-
-```ts
-// helloRoute has a response schema, so you get the parsed payload
-const { message } = await client.helloRoute.GET({
-  path: { name: 'world' },
-})
-
-// imagine pingRoute has no response schema; you get a Response object
-const pingResponse = await client.pingRoute.GET({})
-const pingText = await pingResponse.text()
-```
-
-## Add an endpoint
-
-1. Declare it in `routes.ts` with `route(…)` and `zod` schemas.
-2. Implement the handler in your router assembly with `createRouter(…).use(routes, { … })`.
-3. Call it from the client with the generated helper via `client.json` or `client.request`.