rouzer 2.0.1 → 3.0.0

package/dist/server/router.js

@@ -1,4 +1,5 @@
 import { RoutePattern } from '@remix-run/route-pattern';
+import { createMatcher } from '@remix-run/route-pattern/match';
 import { chain, MiddlewareChain, } from 'alien-middleware';
 import * as z from 'zod';
 import { mapValues } from '../common.js';
@@ -13,14 +14,14 @@ class RouterObject extends MiddlewareChain {
         this.basePath = config.basePath?.replace(/\/?$/, '/');
         const allowOrigins = config.cors?.allowOrigins?.map(createOriginPattern);
         if (allowOrigins) {
-            super.use((ctx) => {
+            super.use(((ctx) => {
                 const origin = ctx.request.headers.get('Origin');
                 if (origin &&
                     allowOrigins &&
                     !allowOrigins.some(pattern => pattern.test(origin))) {
                     return new Response(null, { status: 403 });
                 }
-            });
+            }));
         }
     }
     use(...args) {
@@ -31,28 +32,13 @@ class RouterObject extends MiddlewareChain {
     /** @internal */
     useRoutes(routeSchemas, handlers) {
         const { config, basePath } = this;
-        const routes = Object.entries(routeSchemas).map(([name, route]) => ({
-            name,
-            path: basePath
-                ? new RoutePattern(route.path.source.replace(/^\/?/, basePath))
-                : route.path,
-            methods: mapValues(route.methods, (schema, method) => {
-                const handler = handlers[name][method];
-                if (!handler && config.debug) {
-                    console.error(`Handler missing for route: ${method} ${name}`);
-                }
-                return {
-                    schema,
-                    handler,
-                };
-            }),
-        }));
+        const routes = flattenRoutes(routeSchemas, handlers, basePath ?? '', config.debug);
         const addDebugHeaders = config.debug
             ? (context, route) => {
                 context.setHeader('X-Route-Name', route.name);
             }
             : null;
-        return super.use(async function (context) {
+        return super.use((async function (context) {
             const request = context.request;
             const origin = request.headers.get('Origin');
             const url = (context.url ??= new URL(request.url));
@@ -65,28 +51,18 @@ class RouterObject extends MiddlewareChain {
                         'GET';
             }
             for (const route of routes) {
-                const props = route.methods.hasOwnProperty(method)
-                    ? route.methods[method]
-                    : route.methods.ALL;
-                if (!props) {
+                if (route.method !== method) {
                     continue;
                 }
-                const { schema, handler } = props;
+                const { schema, handler } = route;
                 if (!handler) {
                     continue;
                 }
-                const match = route.path.match(url);
+                const match = route.matcher.match(url);
                 if (!match) {
                     continue;
                 }
                 if (isPreflight) {
-                    const optionsHandler = handlers[route.name].OPTIONS;
-                    if (optionsHandler) {
-                        const response = await optionsHandler(context);
-                        if (response) {
-                            return response;
-                        }
-                    }
                     return new Response(null, {
                         headers: {
                             'Access-Control-Allow-Origin': origin ?? '',
@@ -136,7 +112,7 @@ class RouterObject extends MiddlewareChain {
                 }
                 return Response.json(result);
             }
-        });
+        }));
     }
 }
 /**
@@ -153,6 +129,32 @@ export function createRouter(config = {}) {
     Object.setPrototypeOf(handler, router);
     return handler;
 }
+function flattenRoutes(tree, handlers, prefix, debug) {
+    const routes = [];
+    for (const [name, node] of Object.entries(tree)) {
+        if (node.kind === 'resource') {
+            routes.push(...flattenRoutes(node.children, handlers[name], joinPaths(prefix, node.path.source), debug));
+        }
+        else {
+            const handler = handlers[name];
+            if (!handler && debug) {
+                console.error(`Handler missing for route: ${node.method} ${name}`);
+            }
+            routes.push({
+                name,
+                path: RoutePattern.parse(joinPaths(prefix, node.path?.source ?? '')),
+                matcher: createMatcher(joinPaths(prefix, node.path?.source ?? '')),
+                method: node.method,
+                schema: node.schema,
+                handler,
+            });
+        }
+    }
+    return routes;
+}
+function joinPaths(left, right) {
+    return [left, right].filter(Boolean).join('/').replace(/\/+/g, '/');
+}
 function httpClientError(error, message, config) {
     return Response.json({
         ...error,

package/dist/server/types.d.ts

@@ -1,46 +1,42 @@
-import type { Params } from '@remix-run/route-pattern';
+import type { MatchParams } from '@remix-run/route-pattern/match';
 import type { AnyMiddlewareChain, MiddlewareChain, MiddlewareContext } from 'alien-middleware';
 import type * as z from 'zod';
 import { Promisable } from '../common.js';
-import type { InferRouteResponse, Routes, RouteSchema } from '../types.js';
+import type { HttpAction, HttpResource, HttpRouteTree } from '../http.js';
+import type { InferRouteResponse, RouteSchema } from '../types.js';
 type RequestContext<TMiddleware extends AnyMiddlewareChain> = MiddlewareContext<TMiddleware>;
 type RouteRequestHandler<TMiddleware extends AnyMiddlewareChain, TArgs extends object, TResult> = (context: RequestContext<TMiddleware> & TArgs) => Promisable<TResult | Response>;
-type InferRouteRequestHandler<TMiddleware extends AnyMiddlewareChain, TSchema extends RouteSchema, TMethod extends string, TPath extends string> = TMethod extends 'GET' ? RouteRequestHandler<TMiddleware, {
-    path: TSchema extends {
+type InferActionHandler<TMiddleware extends AnyMiddlewareChain, TAction extends HttpAction, TPath extends string> = TAction['method'] extends 'GET' ? RouteRequestHandler<TMiddleware, {
+    path: TAction['schema'] extends {
         path: any;
-    } ? z.infer<TSchema['path']> : Params<TPath>;
-    query: TSchema extends {
+    } ? z.infer<TAction['schema']['path']> : MatchParams<TPath>;
+    query: TAction['schema'] extends {
         query: any;
-    } ? z.infer<TSchema['query']> : undefined;
-    headers: TSchema extends {
+    } ? z.infer<TAction['schema']['query']> : undefined;
+    headers: TAction['schema'] extends {
         headers: any;
-    } ? z.infer<TSchema['headers']> : undefined;
-}, InferRouteResponse<TSchema>> : RouteRequestHandler<TMiddleware, {
-    path: TSchema extends {
+    } ? z.infer<TAction['schema']['headers']> : undefined;
+}, InferRouteResponse<Extract<TAction['schema'], RouteSchema>>> : RouteRequestHandler<TMiddleware, {
+    path: TAction['schema'] extends {
         path: any;
-    } ? z.infer<TSchema['path']> : Params<TPath>;
-    body: TSchema extends {
+    } ? z.infer<TAction['schema']['path']> : MatchParams<TPath>;
+    body: TAction['schema'] extends {
         body: any;
-    } ? z.infer<TSchema['body']> : undefined;
-    headers: TSchema extends {
+    } ? z.infer<TAction['schema']['body']> : undefined;
+    headers: TAction['schema'] extends {
         headers: any;
-    } ? z.infer<TSchema['headers']> : undefined;
-}, InferRouteResponse<TSchema>>;
+    } ? z.infer<TAction['schema']['headers']> : undefined;
+}, InferRouteResponse<Extract<TAction['schema'], RouteSchema>>>;
+type Join<A extends string, B extends string> = A extends '' ? B : B extends '' ? A : `${A}/${B}`;
 /**
  * Handler map shape required by `createRouter().use(routes, handlers)`.
  *
- * @remarks Each route key must provide handlers for the methods declared by its
- * route schema. Handler context is inferred from middleware plus the route's
- * path, query/body, and header schemas. An optional `OPTIONS` handler can
- * customize CORS preflight responses for a route.
+ * @remarks The handler object mirrors the HTTP route tree. Resource nodes become
+ * nested handler objects, while action nodes become direct handler functions.
+ * Handler context is inferred from middleware plus accumulated path params,
+ * query/body schemas, and header schemas.
  */
-export type RouteRequestHandlerMap<TRoutes extends Routes = Routes, TMiddleware extends AnyMiddlewareChain = MiddlewareChain> = {
-    [K in keyof TRoutes]: {
-        [TMethod in keyof TRoutes[K]['methods']]: InferRouteRequestHandler<TMiddleware, Extract<TRoutes[K]['methods'][TMethod], RouteSchema>, Extract<TMethod, string>, TRoutes[K]['path']['source']>;
-    } & {
-        OPTIONS?: RouteRequestHandler<TMiddleware, {
-            path: Params<TRoutes[K]['path']['source']>;
-        }, void>;
-    };
+export type RouteRequestHandlerMap<TRoutes extends HttpRouteTree = HttpRouteTree, TMiddleware extends AnyMiddlewareChain = MiddlewareChain, TPrefix extends string = ''> = {
+    [K in keyof TRoutes]: TRoutes[K] extends HttpResource<infer P, infer C> ? RouteRequestHandlerMap<C, TMiddleware, Join<TPrefix, P>> : TRoutes[K] extends HttpAction<infer P, any, any> ? InferActionHandler<TMiddleware, TRoutes[K], Join<TPrefix, P>> : never;
 };
 export {};

package/dist/types.d.ts

@@ -1,4 +1,5 @@
-import { Params, RoutePattern } from '@remix-run/route-pattern';
+import { RoutePattern } from '@remix-run/route-pattern';
+import type { MatchParams } from '@remix-run/route-pattern/match';
 import * as z from 'zod';
 import { Unchecked } from './common.js';
 /**
@@ -35,11 +36,11 @@ export type MutationRouteSchema = {
     response?: Unchecked<any>;
 };
 /**
- * Method schema map accepted by `route(...)`.
+ * Method schema map accepted by the low-level `route(...)` helper.
  *
- * @remarks `GET` validates query input, mutation methods validate JSON body
- * input, and `ALL` acts as a fallback for methods that are not declared
- * explicitly.
+ * @remarks `GET` validates query input and mutation methods validate JSON body
+ * input. Prefer `rouzer/http` actions for route trees registered with
+ * `createRouter().use(...)` or `createClient({ routes })`.
  */
 export type RouteSchemaMap = {
     GET?: QueryRouteSchema;
@@ -62,7 +63,13 @@ export type RouteSchemaMap = {
 };
 /** Any route method schema Rouzer can execute. */
 export type RouteSchema = QueryRouteSchema | MutationRouteSchema;
-/** Route map accepted by `createRouter().use(...)` and `createClient(...)`. */
+/**
+ * Low-level route map shape produced from `route(...)` declarations.
+ *
+ * @remarks The router and client shorthand registration APIs now expect
+ * `HttpRouteTree` values from the `rouzer/http` subpath. Use this type only for
+ * code that still works directly with low-level `route(...)` descriptors.
+ */
 export type Routes = {
     [key: string]: {
         path: RoutePattern;
@@ -78,7 +85,7 @@ type PathArgs<T, P extends string> = T extends {
     [K in keyof T as 'path']?: z.infer<TPath>;
 } : {
     [K in keyof T as 'path']: z.infer<TPath>;
-} : Params<P> extends infer TParams ? {} extends TParams ? {
+} : MatchParams<P> extends infer TParams ? {} extends TParams ? {
     [K in keyof T as 'path']?: TParams;
 } : {
     [K in keyof T as 'path']: TParams;
@@ -100,7 +107,8 @@ type MutationArgs<T> = T extends MutationRouteSchema ? T extends {
     body?: unknown;
 } : unknown;
 /**
- * Arguments accepted by a route request factory such as `route.GET(...)`.
+ * Arguments accepted by a request factory such as an HTTP action's `.request(...)`
+ * or a low-level `route.GET(...)` factory.
  *
  * @remarks The type is derived from a method schema and route pattern. `path`,
  * `query`, `body`, and `headers` are validated by the client before `fetch` when
@@ -117,7 +125,7 @@ export type RouteArgs<T extends RouteSchema = any, P extends string = string> =
     headers?: Record<string, string | undefined>;
 };
 /**
- * Request descriptor produced by a route request factory.
+ * Request descriptor produced by an HTTP action or route request factory.
  *
  * @remarks Pass this object to `client.request(...)` for a raw `Response` or
  * `client.json(...)` for parsed JSON handling.
@@ -149,23 +157,26 @@ type InferRouteArgsBody<TArgs> = TArgs extends {
     body?: infer TBody;
 } ? TBody : never;
 /**
- * Infer the request body type from a mutation schema or route request factory.
+ * Infer the request body type from a schema or request factory.
  *
- * @remarks Route request factories for mutation methods infer their `body`
- * argument type. Mutation schemas without a body schema infer `unknown`.
+ * @remarks HTTP action schemas can be inspected with
+ * `InferRouteBody<typeof action.schema>`. Request factories for mutation methods
+ * infer their `body` argument type. Schemas without a body schema infer
+ * `unknown`.
  */
 export type InferRouteBody<T> = T extends RouteRequestFactory<any, any> ? InferRouteArgsBody<T['$args']> : T extends RouteSchema ? InferRouteSchemaBody<T> : never;
 /**
- * Infer the request body type for a named method on a `Route`.
+ * Infer the request body type for a named method on a low-level `Route`.
  *
  * @remarks `GET` and `ALL` infer `never` because they do not accept request
- * bodies.
+ * bodies. For `rouzer/http` actions, prefer
+ * `InferRouteBody<typeof action.schema>`.
  */
 export type InferRouteMethodBody<TRoute extends {
     methods: RouteSchemaMap;
 }, TMethod extends keyof TRoute['methods']> = TMethod extends 'GET' | 'ALL' ? never : TMethod extends keyof TRoute ? InferRouteBody<TRoute[TMethod]> : InferRouteBody<Extract<TRoute['methods'][TMethod], RouteSchema>>;
 /**
- * Callable factory attached to a `Route` for each declared method.
+ * Callable factory attached to an HTTP action or low-level `Route` method.
  *
  * @remarks Calling a factory validates no data by itself; it creates a typed
  * `RouteRequest` descriptor for `createClient` to validate and send.

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,113 @@ 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.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:
 
-| 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/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
-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:
+
+```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 route schema:
+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 +137,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 +145,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({
@@ -92,12 +165,23 @@ Default headers can be supplied with `headers`, per-request headers are merged o
 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 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 +196,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.helloRoute.GET({ path: { name: 'Ada' } }))
+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
@@ -142,16 +257,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 +327,13 @@ 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.
+- 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.