rouzer 2.0.0 → 3.0.0

package/README.md

@@ -0,0 +1,110 @@
+# Rouzer
+
+Rouzer lets you declare an HTTP route tree once and share its TypeScript types
+and Zod validation between a Hattip-compatible server and a typed fetch client.
+
+## What it does
+
+A Rouzer HTTP route tree defines URL patterns, named actions, method schemas, and
+optional response types once, then reuses that contract to:
+
+- validate client arguments before `fetch`
+- match and validate server requests before handlers run
+- type handler context from path, query/body, headers, and middleware
+- attach typed client action functions such as `client.profiles.get(...)`
+
+Rouzer optimizes for shared TypeScript route modules over language-agnostic API
+schemas or generated SDKs.
+
+## Is this for you?
+
+Use Rouzer if:
+
+- your server and client can import the same TypeScript route tree
+- you want Zod request validation on both sides of an HTTP boundary
+- a Hattip-compatible handler fits your server runtime
+- you prefer named resource/action functions over a generated client class
+
+Consider something else if:
+
+- you need OpenAPI-first workflows, schema files, or generated clients for other
+  languages
+- you need runtime response-body validation; `response: $type<T>()` is
+  compile-time only
+- you want a framework that owns controllers, data loading, rendering, and
+  deployment adapters
+- you cannot use ESM or Zod v4+
+
+## Requirements
+
+- ESM runtime and tooling
+- Zod v4 or newer
+- a Hattip adapter when using `createRouter(...)`
+- a Fetch API implementation when using `createClient(...)`
+- an absolute `baseURL` for generated client URLs
+
+## Installation
+
+```sh
+pnpm add rouzer zod
+```
+
+Import the primary API from the root package and declare routes through the HTTP
+subpath:
+
+```ts
+import { $type, chain, createClient, createRouter } from 'rouzer'
+import * as http from 'rouzer/http'
+```
+
+`chain` is re-exported from `alien-middleware` for typed server middleware.
+
+## Quick example
+
+This example shows the core loop: one HTTP action contract defines validation,
+server handler types, and the typed client call.
+
+```ts
+import * as z from 'zod'
+import { $type, createClient, createRouter } from 'rouzer'
+import * as http from 'rouzer/http'
+
+export const hello = http.get('hello/:name', {
+  query: z.object({
+    excited: z.optional(z.boolean()),
+  }),
+  response: $type<{ message: string }>(),
+})
+
+export const routes = { hello }
+
+export const handler = createRouter({ basePath: 'api/' }).use(routes, {
+  hello(ctx) {
+    return {
+      message: `Hello, ${ctx.path.name}${ctx.query.excited ? '!' : '.'}`,
+    }
+  },
+})
+
+const client = createClient({
+  baseURL: 'https://example.com/api/',
+  routes,
+})
+
+const { message } = await client.hello({
+  path: { name: 'world' },
+  query: { excited: true },
+})
+```
+
+`handler` can be mounted with any Hattip adapter. Client action calls validate
+route arguments before `fetch`; server handlers validate matched path, query,
+headers, and JSON bodies before your handler runs.
+
+## Documentation
+
+- [Concepts, API selection, and v2.0.1 migration notes](docs/context.md)
+- [Runnable shared-route example](examples/basic-usage.ts)
+- Generated declarations in the published package provide the exact signatures
+  for every public export, including the `rouzer/http` subpath.
+- Public TSDoc in `src/` owns symbol-level behavior and option details.

package/dist/client/index.d.ts

@@ -1,73 +1,102 @@
 import { Promisable } from '../common.js';
-import { Route } from '../route.js';
+import type { HttpAction, HttpResource, HttpRouteTree } from '../http.js';
 import type { InferRouteResponse, RouteArgs, RouteRequest, RouteSchema } from '../types.js';
-export type RouzerClient<TRoutes extends Record<string, Route> = Record<string, never>> = ReturnType<typeof createClient<TRoutes>>;
-export declare function createClient<TRoutes extends Record<string, Route> = Record<string, never>>(config: {
+/** Client type inferred from an HTTP route tree passed to `createClient`. */
+export type RouzerClient<TRoutes extends HttpRouteTree = Record<string, never>> = ReturnType<typeof createClient<TRoutes>>;
+/**
+ * Create a typed fetch client for an HTTP route tree.
+ *
+ * @remarks The returned client always includes `request(...)` for raw responses
+ * and `json(...)` for parsed JSON. Passing `routes` also mirrors the resource
+ * tree and attaches direct action functions such as `client.users.list(...)`.
+ */
+export declare function createClient<TRoutes extends HttpRouteTree = Record<string, never>>(config: {
     /**
-     * Base URL to use for all requests.
+     * Absolute base URL used for generated request URLs.
+     *
+     * @remarks A trailing slash is added when missing. In browsers, derive a
+     * relative API path with `new URL('/api/', window.location.origin).href`.
      */
     baseURL: string;
     /**
-     * Default headers to send with every request.
+     * Default headers sent with every request.
+     *
+     * @remarks Per-request headers are merged on top of these values. Undefined
+     * per-request headers are removed before `fetch`.
      */
     headers?: Record<string, string>;
     /**
-     * Pass in routes to attach them as methods on the client.
+     * HTTP route tree to attach as direct client action functions.
+     *
      * @example
      * ```ts
-     * const client = createClient({ baseURL: '/api/', routes: { helloRoute } })
-     * client.helloRoute.GET({ path: { name: 'world' } })
+     * const client = createClient({ baseURL: 'https://example.com/api/', routes })
+     * await client.users.list({ query: { page: 1 } })
      * ```
      */
     routes?: TRoutes;
     /**
-     * Custom handler for non-200 response to a `.json()` request. By default, the
-     * response is always parsed as JSON, regardless of the HTTP status code.
+     * Custom handler for non-2xx responses from `.json()`.
+     *
+     * @remarks When provided, the return value is returned from `.json()` as-is;
+     * Rouzer does not automatically parse a `Response` returned by this hook.
      */
     onJsonError?: (response: Response) => Promisable<Response>;
-    /**
-     * Custom fetch implementation to use for requests.
-     */
+    /** Custom `fetch` implementation to use for requests. */
     fetch?: typeof globalThis.fetch;
-}): { [K in keyof TRoutes]: TRoutes[K]["methods"] extends infer TMethods ? { [M in keyof TMethods]: RouteFunction<Extract<TMethods[M], RouteSchema>, TRoutes[K]["path"]["source"]>; } : never; } & {
+}): ClientTree<TRoutes, ""> & {
     config: {
         /**
-         * Base URL to use for all requests.
+         * Absolute base URL used for generated request URLs.
+         *
+         * @remarks A trailing slash is added when missing. In browsers, derive a
+         * relative API path with `new URL('/api/', window.location.origin).href`.
          */
         baseURL: string;
         /**
-         * Default headers to send with every request.
+         * Default headers sent with every request.
+         *
+         * @remarks Per-request headers are merged on top of these values. Undefined
+         * per-request headers are removed before `fetch`.
          */
-        headers?: Record<string, string> | undefined;
+        headers?: Record<string, string>;
         /**
-         * Pass in routes to attach them as methods on the client.
+         * HTTP route tree to attach as direct client action functions.
+         *
          * @example
          * ```ts
-         * const client = createClient({ baseURL: '/api/', routes: { helloRoute } })
-         * client.helloRoute.GET({ path: { name: 'world' } })
+         * const client = createClient({ baseURL: 'https://example.com/api/', routes })
+         * await client.users.list({ query: { page: 1 } })
          * ```
          */
-        routes?: TRoutes | undefined;
+        routes?: TRoutes;
         /**
-         * Custom handler for non-200 response to a `.json()` request. By default, the
-         * response is always parsed as JSON, regardless of the HTTP status code.
+         * Custom handler for non-2xx responses from `.json()`.
+         *
+         * @remarks When provided, the return value is returned from `.json()` as-is;
+         * Rouzer does not automatically parse a `Response` returned by this hook.
          */
-        onJsonError?: ((response: Response) => Promisable<Response>) | undefined;
-        /**
-         * Custom fetch implementation to use for requests.
-         */
-        fetch?: typeof globalThis.fetch | undefined;
+        onJsonError?: (response: Response) => Promisable<Response>;
+        /** Custom `fetch` implementation to use for requests. */
+        fetch?: typeof globalThis.fetch;
     };
     request: <T extends RouteRequest>({ path: pathBuilder, method, args: { path, query, body, headers }, schema, }: T) => Promise<Response & {
-        json(): Promise<T["$result"]>;
+        json(): Promise<T['$result']>;
     }>;
-    json: <T extends RouteRequest>(props: T) => Promise<T["$result"]>;
+    json: <T extends RouteRequest>(props: T) => Promise<T['$result']>;
+};
+type Join<A extends string, B extends string> = A extends '' ? B : B extends '' ? A : `${A}/${B}`;
+/** Client object shape produced from an HTTP route tree. */
+export type ClientTree<T extends HttpRouteTree, TPrefix extends string = ''> = {
+    [K in keyof T]: T[K] extends HttpResource<infer P, infer C> ? ClientTree<C, Join<TPrefix, P>> : T[K] extends HttpAction<infer P, infer S, any> ? RouteFunction<S, Join<TPrefix, P>> : never;
 };
 /**
- * This function sends a request to a route of the same name. Such a function is
- * accessible by setting the `routes` option when creating a Rouzer client,
- * where it will exist as a method on the client.
+ * Client action function attached for each HTTP action leaf.
+ *
+ * @remarks Actions whose schema has `response: $type<T>()` return parsed JSON
+ * as `T`. Actions without a response marker return the raw `Response`.
  */
 export type RouteFunction<T extends RouteSchema, P extends string> = (...p: RouteArgs<T, P> extends infer TArgs ? {} extends TArgs ? [args?: TArgs] : [args: TArgs] : never) => Promise<T extends {
     response: any;
 } ? InferRouteResponse<T> : Response>;
+export {};

package/dist/client/index.js

@@ -1,4 +1,13 @@
-import { mapValues, shake } from '../common.js';
+import { RoutePattern } from '@remix-run/route-pattern';
+import { createHref } from '@remix-run/route-pattern/href';
+import { shake } from '../common.js';
+/**
+ * Create a typed fetch client for an HTTP route tree.
+ *
+ * @remarks The returned client always includes `request(...)` for raw responses
+ * and `json(...)` for parsed JSON. Passing `routes` also mirrors the resource
+ * tree and attaches direct action functions such as `client.users.list(...)`.
+ */
 export function createClient(config) {
     const baseURL = config.baseURL.replace(/\/?$/, '/');
     const defaultHeaders = config.headers && shake(config.headers);
@@ -8,13 +17,13 @@ export function createClient(config) {
             path = schema.path.parse(path);
         }
         let url;
-        const href = pathBuilder.href(path);
+        const href = createHref(pathBuilder, path);
         if (href[0] === '/') {
             url = new URL(baseURL);
             url.pathname += href.slice(1);
         }
         else {
-            url = new URL(href);
+            url = new URL(href, baseURL);
         }
         if (schema.query) {
             query = schema.query.parse(query ?? {});
@@ -31,9 +40,9 @@ export function createClient(config) {
         }
         if (headers) {
             headers = shake(headers);
-            if (defaultHeaders) {
-                headers = { ...defaultHeaders, ...headers };
-            }
+        }
+        if (defaultHeaders) {
+            headers = headers ? { ...defaultHeaders, ...headers } : defaultHeaders;
         }
         if (schema.headers) {
             headers = schema.headers.parse(headers);
@@ -50,7 +59,7 @@ export function createClient(config) {
             if (config.onJsonError) {
                 return config.onJsonError(response);
             }
-            const error = new Error(`Request to ${props.method} ${props.path.href(props.args.path)} failed with status ${response.status}`);
+            const error = new Error(`Request to ${props.method} ${createHref(props.path, props.args.path)} failed with status ${response.status}`);
             const contentType = response.headers.get('content-type');
             if (contentType?.includes('application/json')) {
                 Object.assign(error, await response.json());
@@ -61,19 +70,35 @@ export function createClient(config) {
     }
     return {
         ...(config.routes
-            ? mapValues(config.routes, route => connectRoute(route, request, json))
+            ? connectTree(config.routes, '', request, json)
             : null),
         config,
         request,
         json,
     };
 }
-function connectRoute(route, request, json) {
-    return {
-        ...route,
-        ...mapValues(route.methods, (schema, key) => {
-            const fetch = schema.response ? json : request;
-            return (args) => fetch(route[key](args));
-        }),
-    };
+function connectTree(tree, prefix, request, json) {
+    return Object.fromEntries(Object.entries(tree).map(([key, node]) => {
+        if (node.kind === 'resource') {
+            return [
+                key,
+                connectTree(node.children, joinPaths(prefix, node.path.source), request, json),
+            ];
+        }
+        const path = RoutePattern.parse(joinPaths(prefix, node.path?.source ?? ''));
+        const fetch = node.schema.response ? json : request;
+        return [
+            key,
+            (args = {}) => fetch({
+                schema: node.schema,
+                path,
+                method: node.method,
+                args,
+                $result: undefined,
+            }),
+        ];
+    }));
+}
+function joinPaths(left, right) {
+    return [left, right].filter(Boolean).join('/').replace(/\/+/g, '/');
 }

package/dist/common.d.ts

@@ -1,4 +1,11 @@
 export type Promisable<T> = T | Promise<T>;
+/**
+ * Compile-time-only marker used by `$type<T>()` to carry an unchecked response
+ * type through route declarations.
+ *
+ * @remarks Consumers usually use `$type<T>()` instead of constructing this type
+ * directly.
+ */
 export type Unchecked<T> = {
     __unchecked__: T;
 };

package/dist/http.d.ts

@@ -0,0 +1,67 @@
+import { RoutePattern } from '@remix-run/route-pattern';
+import type { RouteRequestFactory, RouteSchema } from './types.js';
+/** HTTP methods supported by Rouzer action declarations. */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * Callable endpoint leaf in an HTTP route tree.
+ *
+ * @remarks Actions declare one HTTP operation. Their property name becomes the
+ * client/handler name, while their optional `path` contributes URL segments.
+ */
+export type HttpAction<P extends string = string, T extends RouteSchema = RouteSchema, M extends HttpMethod = HttpMethod> = {
+    /** Discriminator used internally when traversing route trees. */
+    kind: 'action';
+    /** Optional action-local path segment appended after parent resources. */
+    path?: RoutePattern<P>;
+    /** HTTP method used when the client sends this action. */
+    method: M;
+    /** Request validation and optional response type schema. */
+    schema: T;
+    /** Low-level request descriptor factory for this action. */
+    request: RouteRequestFactory<T, P>;
+};
+/**
+ * Path-scoped namespace in an HTTP route tree.
+ *
+ * @remarks Resources contribute URL path segments and contain child resources or
+ * actions. They do not have handlers of their own.
+ */
+export type HttpResource<P extends string = string, TChildren extends HttpRouteTree = HttpRouteTree> = {
+    /** Discriminator used internally when traversing route trees. */
+    kind: 'resource';
+    /** Path segment contributed by this resource. */
+    path: RoutePattern<P>;
+    /** Child resources and actions exposed below this resource. */
+    children: TChildren;
+};
+/** Node type accepted inside an HTTP route tree. */
+export type HttpNode = HttpAction | HttpResource;
+/** Route tree accepted by HTTP clients and routers. */
+export type HttpRouteTree = {
+    [key: string]: HttpNode;
+};
+/**
+ * Declare an HTTP resource namespace.
+ *
+ * @remarks The resource `path` is joined with any parent resource path. Child
+ * property names are API names only; they do not affect the URL unless the child
+ * is another resource or an action with an explicit path.
+ */
+export declare function resource<const P extends string, const TChildren extends HttpRouteTree>(path: P, children: TChildren): HttpResource<P, TChildren>;
+/** Declare a GET action, optionally with an action-local path segment. */
+export declare function get<const P extends string, const T extends RouteSchema>(path: P, schema: T): HttpAction<P, T, 'GET'>;
+export declare function get<const T extends RouteSchema>(schema: T): HttpAction<'', T, 'GET'>;
+/** Declare a POST action, optionally with an action-local path segment. */
+export declare function post<const P extends string, const T extends RouteSchema>(path: P, schema: T): HttpAction<P, T, 'POST'>;
+export declare function post<const T extends RouteSchema>(schema: T): HttpAction<'', T, 'POST'>;
+/** Declare a PUT action, optionally with an action-local path segment. */
+export declare function put<const P extends string, const T extends RouteSchema>(path: P, schema: T): HttpAction<P, T, 'PUT'>;
+export declare function put<const T extends RouteSchema>(schema: T): HttpAction<'', T, 'PUT'>;
+/** Declare a PATCH action, optionally with an action-local path segment. */
+export declare function patch<const P extends string, const T extends RouteSchema>(path: P, schema: T): HttpAction<P, T, 'PATCH'>;
+export declare function patch<const T extends RouteSchema>(schema: T): HttpAction<'', T, 'PATCH'>;
+/** Declare a DELETE action, optionally with an action-local path segment. */
+export declare function del<const P extends string, const T extends RouteSchema>(path: P, schema: T): HttpAction<P, T, 'DELETE'>;
+export declare function del<const T extends RouteSchema>(schema: T): HttpAction<'', T, 'DELETE'>;
+/** Alias for `del(...)`, exported for namespace imports as `http.delete(...)`. */
+export { del as delete };

package/dist/http.js

@@ -0,0 +1,44 @@
+import { RoutePattern } from '@remix-run/route-pattern';
+/**
+ * Declare an HTTP resource namespace.
+ *
+ * @remarks The resource `path` is joined with any parent resource path. Child
+ * property names are API names only; they do not affect the URL unless the child
+ * is another resource or an action with an explicit path.
+ */
+export function resource(path, children) {
+    return {
+        kind: 'resource',
+        path: RoutePattern.parse(path),
+        children,
+    };
+}
+export function get(pathOrSchema, schema) {
+    return action('GET', pathOrSchema, schema);
+}
+export function post(pathOrSchema, schema) {
+    return action('POST', pathOrSchema, schema);
+}
+export function put(pathOrSchema, schema) {
+    return action('PUT', pathOrSchema, schema);
+}
+export function patch(pathOrSchema, schema) {
+    return action('PATCH', pathOrSchema, schema);
+}
+export function del(pathOrSchema, schema) {
+    return action('DELETE', pathOrSchema, schema);
+}
+/** Alias for `del(...)`, exported for namespace imports as `http.delete(...)`. */
+export { del as delete };
+function action(method, pathOrSchema, schema) {
+    const path = typeof pathOrSchema === 'string' ? RoutePattern.parse(pathOrSchema) : undefined;
+    schema ??= typeof pathOrSchema === 'string' ? {} : pathOrSchema;
+    const request = ((args = {}) => ({
+        schema,
+        path: path ?? RoutePattern.parse(''),
+        method,
+        args,
+        $result: undefined,
+    }));
+    return { kind: 'action', path, method, schema, request };
+}

package/dist/route.d.ts

@@ -1,14 +1,56 @@
 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 action functions for routes whose
+ * responses are expected to be JSON.
+ *
+ * @example
+ * ```ts
+ * import { $type } from 'rouzer'
+ * import * as http from 'rouzer/http'
+ *
+ * const hello = http.get('hello/:name', {
+ *   response: $type<{ message: string }>(),
+ * })
+ * ```
+ */
 export declare function $type<T>(): Unchecked<T>;
 export declare namespace $type {
     var symbol: symbol;
 }
+/**
+ * Low-level 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. Use those factories with
+ * `client.request(...)` or `client.json(...)` when you need explicit response
+ * handling. For shared server/client route trees, prefer `rouzer/http` actions
+ * and resources; `createRouter().use(...)` and `createClient({ routes })` expect
+ * that HTTP route tree shape.
+ */
 export type Route<P extends string = string, T extends RouteSchemaMap = RouteSchemaMap> = {
+    /** Parsed route pattern used for request URL generation. */
     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.
+ *
+ * @remarks This helper creates low-level request descriptor factories. Prefer
+ * `rouzer/http` action helpers for routes that will be registered with
+ * `createRouter().use(...)` or mirrored by `createClient({ routes })`.
+ *
+ * @param pattern Route pattern parsed by `@remix-run/route-pattern`.
+ * @param methods Method schemas that describe request validation and optional
+ * response typing.
+ * @returns A 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,11 +1,41 @@
 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 action functions for routes whose
+ * responses are expected to be JSON.
+ *
+ * @example
+ * ```ts
+ * import { $type } from 'rouzer'
+ * import * as http from 'rouzer/http'
+ *
+ * const hello = http.get('hello/:name', {
+ *   response: $type<{ message: string }>(),
+ * })
+ * ```
+ */
 export function $type() {
     return $type.symbol;
 }
 $type.symbol = Symbol();
+/**
+ * Declare one URL pattern and its supported HTTP method schemas.
+ *
+ * @remarks This helper creates low-level request descriptor factories. Prefer
+ * `rouzer/http` action helpers for routes that will be registered with
+ * `createRouter().use(...)` or mirrored by `createClient({ routes })`.
+ *
+ * @param pattern Route pattern parsed by `@remix-run/route-pattern`.
+ * @param methods Method schemas that describe request validation and optional
+ * response typing.
+ * @returns A 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 path = RoutePattern.parse(pattern);
     const createFetch = (method, schema) => (args = {}) => {
         return {
             schema,

package/dist/server/router.d.ts

@@ -1,36 +1,38 @@
 import type { HattipHandler } from '@hattip/core';
 import { ApplyMiddleware, chain, ExtractMiddleware, MiddlewareChain, MiddlewareTypes } from 'alien-middleware';
-import type { Routes } from '../types.js';
+import type { HttpRouteTree } from '../http.js';
 import type { RouteRequestHandlerMap } from './types.js';
 export { chain };
+/** Configuration for `createRouter`. */
 export type RouterConfig = {
     /**
-     * Base path to prepend to all routes.
+     * Base path to prepend to all route patterns.
+     *
+     * @remarks Leading and trailing slashes are normalized so `api`, `/api`, and
+     * `api/` all mount routes under `/api/`.
+     *
      * @example
      * ```ts
-     * basePath: 'api/',
+     * createRouter({ basePath: 'api/' })
      * ```
      */
     basePath?: string;
     /**
-     * Enable debugging features.
-     * - When a handler throws an error, include its message in the response body.
-     * - Throw an error if a handler is not found for a route.
-     * @example
-     * ```ts
-     * debug: process.env.NODE_ENV !== 'production',
-     * ```
+     * Enable debug behavior for local development.
+     *
+     * @remarks Debug mode adds an `X-Route-Name` response header for matched
+     * routes, includes specific Zod error messages in `400` validation responses,
+     * and logs missing route handlers to the console.
      */
     debug?: boolean;
-    /**
-     * CORS configuration.
-     */
+    /** CORS configuration for requests with an `Origin` header. */
     cors?: {
         /**
-         * If defined, requests must have an `Origin` header that is in this list.
+         * Allowed origins for CORS requests.
          *
-         * Origins may contain wildcards for protocol and subdomain. The protocol is
-         * optional and defaults to `https`.
+         * @remarks Origins may contain wildcards for protocol and subdomain. The
+         * protocol is optional and defaults to `https`. Requests with an `Origin`
+         * header outside this list receive `403`.
          *
          * @example
          * ```ts
@@ -40,6 +42,10 @@ export type RouterConfig = {
         allowOrigins?: string[];
     };
 };
+/**
+ * Hattip-compatible Rouzer handler with chainable middleware and route
+ * registration.
+ */
 export interface Router<T extends MiddlewareTypes = any> extends HattipHandler<T['platform']>, MiddlewareChain<T> {
     /**
      * Clone this router and add the given middleware to the end of the chain.
@@ -48,10 +54,22 @@ export interface Router<T extends MiddlewareTypes = any> extends HattipHandler<T
      */
     use<const TMiddleware extends ExtractMiddleware<this>>(middleware: TMiddleware | null): Router<ApplyMiddleware<this, TMiddleware>>;
     /**
-     * Clone this router and add the given routes and handlers to the chain.
+     * Clone this router and add the given HTTP route tree and handlers to the
+     * chain.
+     *
+     * @remarks The handler object mirrors the resource tree. Resource nodes are
+     * nested objects, and action nodes are direct handler functions.
      *
      * @returns a new `Router` instance.
      */
-    use<TRoutes extends Routes>(routes: TRoutes, handlers: RouteRequestHandlerMap<TRoutes, this>): Router<T>;
+    use<TRoutes extends HttpRouteTree>(routes: TRoutes, handlers: RouteRequestHandlerMap<TRoutes, this>): Router<T>;
 }
+/**
+ * Create a Rouzer router that can be mounted by any Hattip adapter.
+ *
+ * @param config Optional router configuration for base path, debug behavior, and
+ * CORS origin restrictions.
+ * @returns A Hattip-compatible handler with `.use(...)` methods for middleware
+ * and route registration.
+ */
 export declare function createRouter<TEnv extends object = {}, TProperties extends object = {}, TPlatform = unknown>(config?: RouterConfig): Router<MiddlewareTypes<TEnv, TProperties, TPlatform>>;