rouzer 2.0.1 → 3.0.1

package/docs/context.md

@@ -1,8 +1,9 @@
 # Rouzer context
 
-Rouzer is for applications that want one route contract to drive both the HTTP
-server and the client that calls it. A route declaration combines a URL pattern,
-HTTP method schemas, and an optional compile-time response type.
+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
 
@@ -13,7 +14,7 @@ Use Rouzer when:
 - 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 the route definitions instead of being
+- 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
@@ -22,43 +23,112 @@ small client wrapper.
 
 ## Core abstractions
 
-### Route declarations
+### HTTP route trees
 
-Declare routes with `route(pattern, methods)`. The pattern is parsed by
-`@remix-run/route-pattern`, so route params can be inferred from patterns such
-as `hello/:name`, `v:major.:minor`, `api(/v:major(.:minor))`, `assets/*path`,
-`search?q`, or full URL patterns such as
-`https://:store.shopify.com/orders`.
+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.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:
 
-| Method kind                      | Request schemas                        | Notes                                                                                   |
-| -------------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------- |
-| `GET`                            | `path`, `query`, `headers`, `response` | No request body.                                                                        |
-| `POST`, `PUT`, `PATCH`, `DELETE` | `path`, `body`, `headers`, `response`  | No query schema.                                                                        |
-| `ALL`                            | `path`, `query`, `headers`             | Fallback when the incoming method is not explicitly declared. No body or response type. |
+| Action helper                         | Request schemas                        | Notes            |
+| ------------------------------------- | -------------------------------------- | ---------------- |
+| `http.get(...)`                       | `path`, `query`, `headers`, `response` | No request body. |
+| `http.post/put/patch/delete(...)` | `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
-shorthand methods what response payload type to expect, but Rouzer does not
+action functions what response payload type to expect, but Rouzer does not
 validate response bodies at runtime.
 
-Routes without a `response` marker return a raw `Response` from client shorthand
-methods. Routes with a `response` marker use `client.json(...)` under the hood
+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
-route handlers.
+an HTTP route tree.
+
+The handler object mirrors the route tree:
 
-Handlers receive a context typed from middleware plus the route schema:
+```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`
@@ -66,7 +136,7 @@ Handlers receive a context typed from middleware plus the route schema:
 - 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 patterns, `debug` adds matched-route debug
+`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.
 
@@ -74,12 +144,14 @@ requests with an `Origin` header.
 
 `createClient({ baseURL, routes })` creates:
 
-- `client.request(route.GET(args))` for a raw `Response`
-- `client.json(route.GET(args))` for parsed JSON and default non-2xx throwing
-- shorthand methods such as `client.helloRoute.GET(args)` when `routes` is
-  supplied
+- `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 pathname route patterns:
+Prefer an absolute `baseURL` for generated client URLs:
 
 ```ts
 const client = createClient({
@@ -94,10 +166,11 @@ runtimes.
 
 ## Lifecycle
 
-1. Define shared route declarations with `route(...)` and Zod schemas.
-2. Attach those routes to a server with `createRouter().use(routes, handlers)`.
-3. Create a client with the same route map.
-4. Client calls validate `path`, `query`, `body`, and `headers` before `fetch`.
+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
@@ -112,20 +185,51 @@ string-coercion step.
 
 ### Choose a client call style
 
-Use shorthand methods for normal application calls:
+Use client action functions for normal application calls:
 
 ```ts
-await client.helloRoute.GET({ path: { name: 'Ada' } })
+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:
+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.helloRoute.GET({ path: { name: 'Ada' } })
+  routes.getProfile.request({ path: { id: '42' } })
+)
+
+const json = await client.json(
+  routes.getProfile.request({ path: { id: '42' } })
 )
+```
+
+### Group resource actions
 
-const json = await client.json(routes.helloRoute.GET({ path: { name: 'Ada' } }))
+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
@@ -142,16 +246,69 @@ is JSON, its properties are copied onto the thrown `Error`.
 `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 declarations from a small shared module and import that module on
-  both server and client.
+- 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
-  shorthand methods.
-- Use explicit HTTP methods when you want precise handler context types; reserve
-  `ALL` for true fallback behavior.
+  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.
 
@@ -159,9 +316,14 @@ is JSON, its properties are copied onto the thrown `Error`.
 
 - `$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`.
-- `ALL` can declare `query`, but handler context typing is less precise than
-  explicit `GET` handlers.
+  are forwarded by `createClient`; `method`, `body`, and `headers` are reserved
+  for Rouzer's action metadata and validated call arguments.
+- 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

@@ -1,6 +1,7 @@
 import type { HattipHandler } from '@hattip/core'
 import * as z from 'zod'
-import { $type, chain, createClient, createRouter, route } from 'rouzer'
+import { $type, chain, createClient, createRouter } from 'rouzer'
+import * as http from 'rouzer/http'
 
 type Profile = {
   id: string
@@ -9,14 +10,14 @@ type Profile = {
   requestId: string
 }
 
-export const profileRoute = route('profiles/:id', {
-  GET: {
+export const profiles = http.resource('profiles/:id', {
+  get: http.get({
     query: z.object({
       includePosts: z.optional(z.boolean()),
     }),
     response: $type<Profile>(),
-  },
-  PATCH: {
+  }),
+  update: http.patch({
     body: z.object({
       name: z.string().check(z.minLength(1)),
     }),
@@ -24,10 +25,10 @@ export const profileRoute = route('profiles/:id', {
       'content-type': z.literal('application/json'),
     }),
     response: $type<Profile>(),
-  },
+  }),
 })
 
-export const routes = { profileRoute }
+export const routes = { profiles }
 
 /**
  * Tiny Hattip adapter used only to keep this example self-contained. Real apps
@@ -54,7 +55,7 @@ function createLocalFetch(handler: HattipHandler): typeof fetch {
 }
 
 export async function runBasicUsageExample() {
-  const profiles = new Map([['42', { id: '42', name: 'Ada' }]])
+  const profileMap = new Map([['42', { id: '42', name: 'Ada' }]])
 
   const requestMiddleware = chain().use(ctx => ({
     requestId: ctx.request.headers.get('x-request-id') ?? 'local',
@@ -63,9 +64,9 @@ export async function runBasicUsageExample() {
   const handler = createRouter({ basePath: 'api/' })
     .use(requestMiddleware)
     .use(routes, {
-      profileRoute: {
-        GET(ctx) {
-          const profile = profiles.get(ctx.path.id)
+      profiles: {
+        get(ctx) {
+          const profile = profileMap.get(ctx.path.id)
           if (!profile) {
             return new Response('Profile not found', { status: 404 })
           }
@@ -75,13 +76,13 @@ export async function runBasicUsageExample() {
             requestId: ctx.requestId,
           }
         },
-        PATCH(ctx) {
-          const current = profiles.get(ctx.path.id)
+        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 }
-          profiles.set(ctx.path.id, profile)
+          profileMap.set(ctx.path.id, profile)
           return {
             ...profile,
             includePosts: false,
@@ -100,13 +101,13 @@ export async function runBasicUsageExample() {
     fetch: createLocalFetch(handler),
   })
 
-  const fetched = await client.profileRoute.GET({
+  const fetched = await client.profiles.get({
     path: { id: '42' },
     query: { includePosts: false },
     headers: { 'x-request-id': 'docs' },
   })
 
-  const updated = await client.profileRoute.PATCH({
+  const updated = await client.profiles.update({
     path: { id: '42' },
     body: { name: 'Grace' },
   })

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "rouzer",
-  "version": "2.0.1",
+  "version": "3.0.1",
   "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",

package/dist/route.d.ts

@@ -1,49 +0,0 @@
-import { RoutePattern } from '@remix-run/route-pattern';
-import { Unchecked } from './common.js';
-import type { RouteRequestFactory, RouteSchema, RouteSchemaMap } from './types.js';
-/**
- * Create a compile-time-only marker for a route's JSON response payload type.
- *
- * @remarks `$type<T>()` does not perform runtime validation. It lets Rouzer type
- * server handler return values and client shorthand methods for routes whose
- * responses are expected to be JSON.
- *
- * @example
- * ```ts
- * const helloRoute = route('hello/:name', {
- *   GET: {
- *     response: $type<{ message: string }>(),
- *   },
- * })
- * ```
- */
-export declare function $type<T>(): Unchecked<T>;
-export declare namespace $type {
-    var symbol: symbol;
-}
-/**
- * Shared route declaration produced by `route(...)`.
- *
- * @remarks A `Route` stores the parsed URL pattern, the method schema map, and a
- * request factory for each declared method. Pass route maps to both
- * `createRouter().use(...)` and `createClient({ routes })` to share the same
- * contract on both sides of an HTTP boundary.
- */
-export type Route<P extends string = string, T extends RouteSchemaMap = RouteSchemaMap> = {
-    /** Parsed route pattern used for URL generation and server-side matching. */
-    path: RoutePattern<P>;
-    /** Method schemas declared for this route. */
-    methods: T;
-} & {
-    [K in keyof T]: RouteRequestFactory<Extract<T[K], RouteSchema>, P>;
-};
-/**
- * Declare one URL pattern and its supported HTTP method schemas.
- *
- * @param pattern Route pattern parsed by `@remix-run/route-pattern`.
- * @param methods Method schemas that describe request validation and optional
- * response typing.
- * @returns A shared route declaration with request factories such as `.GET(...)`
- * and `.POST(...)` for the declared methods.
- */
-export declare function route<P extends string, T extends RouteSchemaMap>(pattern: P, methods: T): Route<P, T>;

package/dist/route.js

@@ -1,47 +0,0 @@
-import { RoutePattern } from '@remix-run/route-pattern';
-import { mapEntries } from './common.js';
-/**
- * Create a compile-time-only marker for a route's JSON response payload type.
- *
- * @remarks `$type<T>()` does not perform runtime validation. It lets Rouzer type
- * server handler return values and client shorthand methods for routes whose
- * responses are expected to be JSON.
- *
- * @example
- * ```ts
- * const helloRoute = route('hello/:name', {
- *   GET: {
- *     response: $type<{ message: string }>(),
- *   },
- * })
- * ```
- */
-export function $type() {
-    return $type.symbol;
-}
-$type.symbol = Symbol();
-/**
- * Declare one URL pattern and its supported HTTP method schemas.
- *
- * @param pattern Route pattern parsed by `@remix-run/route-pattern`.
- * @param methods Method schemas that describe request validation and optional
- * response typing.
- * @returns A shared route declaration with request factories such as `.GET(...)`
- * and `.POST(...)` for the declared methods.
- */
-export function route(pattern, methods) {
-    const path = new RoutePattern(pattern);
-    const createFetch = (method, schema) => (args = {}) => {
-        return {
-            schema,
-            path,
-            method,
-            args,
-            $result: undefined,
-        };
-    };
-    return Object.assign({ path, methods }, mapEntries(methods, (method, schema) => [
-        method,
-        createFetch(method, schema),
-    ]));
-}