rouzer 2.0.0 → 2.0.1

package/README.md

@@ -0,0 +1,111 @@
+# Rouzer
+
+Rouzer lets you declare a route once and share its TypeScript types and Zod
+validation between a Hattip-compatible server and a typed fetch client.
+
+## What it does
+
+A Rouzer route declaration defines a URL pattern, method schemas, and optional
+response type 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 shorthand methods such as `client.helloRoute.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 declarations
+- you want Zod request validation on both sides of an HTTP boundary
+- a Hattip-compatible handler fits your server runtime
+- you prefer a small routing/client contract over a full web framework
+
+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 pathname route patterns
+
+## Installation
+
+```sh
+pnpm add rouzer zod
+```
+
+Import the public API from the root package:
+
+```ts
+import { $type, chain, createClient, createRouter, route } from 'rouzer'
+```
+
+`chain` is re-exported from `alien-middleware` for typed server middleware.
+
+## Quick example
+
+This example shows the core loop: one route contract defines validation, server
+handler types, and the typed client call.
+
+```ts
+import * as z from 'zod'
+import { $type, createClient, createRouter, route } from 'rouzer'
+
+export const helloRoute = route('hello/:name', {
+  GET: {
+    query: z.object({
+      excited: z.optional(z.boolean()),
+    }),
+    response: $type<{ message: string }>(),
+  },
+})
+
+export const routes = { helloRoute }
+
+export const handler = createRouter({ basePath: 'api/' }).use(routes, {
+  helloRoute: {
+    GET(ctx) {
+      return {
+        message: `Hello, ${ctx.path.name}${ctx.query.excited ? '!' : '.'}`,
+      }
+    },
+  },
+})
+
+const client = createClient({
+  baseURL: 'https://example.com/api/',
+  routes,
+})
+
+const { message } = await client.helloRoute.GET({
+  path: { name: 'world' },
+  query: { excited: true },
+})
+```
+
+`handler` can be mounted with any Hattip adapter. Client calls validate route
+arguments before `fetch`; server handlers validate matched path, query, headers,
+and JSON bodies before your handler runs.
+
+## Documentation
+
+- [Concepts and API selection](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.
+- Public TSDoc in `src/` owns symbol-level behavior and option details.

package/dist/client/index.d.ts

@@ -1,61 +1,87 @@
 import { Promisable } from '../common.js';
 import { Route } from '../route.js';
 import type { InferRouteResponse, RouteArgs, RouteRequest, RouteSchema } from '../types.js';
+/** Client type inferred from a route map passed to `createClient`. */
 export type RouzerClient<TRoutes extends Record<string, Route> = Record<string, never>> = ReturnType<typeof createClient<TRoutes>>;
+/**
+ * Create a typed fetch client for Rouzer route declarations.
+ *
+ * @remarks The returned client always includes `request(...)` for raw responses
+ * and `json(...)` for parsed JSON. Passing `routes` also attaches shorthand
+ * methods such as `client.helloRoute.GET(...)`.
+ */
 export declare function createClient<TRoutes extends Record<string, Route> = Record<string, never>>(config: {
     /**
-     * Base URL to use for all requests.
+     * Absolute base URL used for pathname route patterns.
+     *
+     * @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.
+     * Route map to attach as shorthand methods on the client.
+     *
      * @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.helloRoute.GET({ path: { name: 'world' } })
      * ```
      */
     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.
+     * Without this hook, `.json()` throws an `Error` and copies JSON error-body
+     * properties onto it when the response has a JSON content type.
      */
     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; } & {
     config: {
         /**
-         * Base URL to use for all requests.
+         * Absolute base URL used for pathname route patterns.
+         *
+         * @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;
         /**
-         * Pass in routes to attach them as methods on the client.
+         * Route map to attach as shorthand methods on the client.
+         *
          * @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.helloRoute.GET({ path: { name: 'world' } })
          * ```
          */
         routes?: TRoutes | undefined;
         /**
-         * 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.
+         * Without this hook, `.json()` throws an `Error` and copies JSON error-body
+         * properties onto it when the response has a JSON content type.
          */
         onJsonError?: ((response: Response) => Promisable<Response>) | undefined;
-        /**
-         * Custom fetch implementation to use for requests.
-         */
+        /** Custom `fetch` implementation to use for requests. */
         fetch?: typeof globalThis.fetch | undefined;
     };
     request: <T extends RouteRequest>({ path: pathBuilder, method, args: { path, query, body, headers }, schema, }: T) => Promise<Response & {
@@ -64,9 +90,11 @@ export declare function createClient<TRoutes extends Record<string, Route> = Rec
     json: <T extends RouteRequest>(props: T) => Promise<T["$result"]>;
 };
 /**
- * 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.
+ * Shorthand client method attached for each route method when `routes` is passed
+ * to `createClient`.
+ *
+ * @remarks Methods whose schema has `response: $type<T>()` return parsed JSON as
+ * `T`. Methods 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;

package/dist/client/index.js

@@ -1,4 +1,11 @@
 import { mapValues, shake } from '../common.js';
+/**
+ * Create a typed fetch client for Rouzer route declarations.
+ *
+ * @remarks The returned client always includes `request(...)` for raw responses
+ * and `json(...)` for parsed JSON. Passing `routes` also attaches shorthand
+ * methods such as `client.helloRoute.GET(...)`.
+ */
 export function createClient(config) {
     const baseURL = config.baseURL.replace(/\/?$/, '/');
     const defaultHeaders = config.headers && shake(config.headers);
@@ -31,9 +38,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);

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/route.d.ts

@@ -1,14 +1,49 @@
 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,9 +1,34 @@
 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 = {}) => {

package/dist/server/router.d.ts

@@ -3,34 +3,36 @@ import { ApplyMiddleware, chain, ExtractMiddleware, MiddlewareChain, MiddlewareT
 import type { Routes } from '../types.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.
@@ -54,4 +60,12 @@ export interface Router<T extends MiddlewareTypes = any> extends HattipHandler<T
      */
     use<TRoutes extends Routes>(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>>;

package/dist/server/router.js

@@ -139,6 +139,14 @@ class RouterObject extends MiddlewareChain {
         });
     }
 }
+/**
+ * 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 function createRouter(config = {}) {
     const router = new RouterObject(config);
     const handler = router.toHandler();

package/dist/server/types.d.ts

@@ -26,6 +26,14 @@ type InferRouteRequestHandler<TMiddleware extends AnyMiddlewareChain, TSchema ex
         headers: any;
     } ? z.infer<TSchema['headers']> : undefined;
 }, InferRouteResponse<TSchema>>;
+/**
+ * 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.
+ */
 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']>;

package/dist/types.d.ts

@@ -1,21 +1,46 @@
 import { Params, RoutePattern } from '@remix-run/route-pattern';
 import * as z from 'zod';
 import { Unchecked } from './common.js';
+/**
+ * Compile-time-only marker used by `$type<T>()` for unchecked response types.
+ *
+ * @remarks Application code should usually call `$type<T>()` instead of naming
+ * this marker directly.
+ */
 export type { Unchecked };
+/** Schema shape for `GET` route methods. */
 export type QueryRouteSchema = {
+    /** Optional Zod object used to validate path params. */
     path?: z.ZodObject<any>;
+    /** Optional Zod object used to validate URL query params. */
     query?: z.ZodObject<any>;
+    /** `GET` routes do not accept request bodies. */
     body?: never;
+    /** Optional Zod object used to validate request headers. */
     headers?: z.ZodObject<any>;
+    /** Optional compile-time-only JSON response type marker. */
     response?: Unchecked<any>;
 };
+/** Schema shape for mutation route methods. */
 export type MutationRouteSchema = {
+    /** Optional Zod object used to validate path params. */
     path?: z.ZodObject<any>;
+    /** Mutation routes do not accept query schemas. */
     query?: never;
+    /** Optional Zod schema used to validate the JSON request body. */
     body?: z.ZodType<any, any>;
+    /** Optional Zod object used to validate request headers. */
     headers?: z.ZodObject<any>;
+    /** Optional compile-time-only JSON response type marker. */
     response?: Unchecked<any>;
 };
+/**
+ * Method schema map accepted by `route(...)`.
+ *
+ * @remarks `GET` validates query input, mutation methods validate JSON body
+ * input, and `ALL` acts as a fallback for methods that are not declared
+ * explicitly.
+ */
 export type RouteSchemaMap = {
     GET?: QueryRouteSchema;
     POST?: MutationRouteSchema;
@@ -23,14 +48,21 @@ export type RouteSchemaMap = {
     PATCH?: MutationRouteSchema;
     DELETE?: MutationRouteSchema;
     ALL?: {
+        /** Optional Zod object used to validate path params. */
         path?: z.ZodObject<any>;
+        /** Optional Zod object used to validate URL query params. */
         query?: z.ZodObject<any>;
+        /** `ALL` fallback routes do not accept request bodies. */
         body?: never;
+        /** Optional Zod object used to validate request headers. */
         headers?: z.ZodObject<any>;
+        /** `ALL` fallback routes do not define typed JSON responses. */
         response?: never;
     };
 };
+/** Any route method schema Rouzer can execute. */
 export type RouteSchema = QueryRouteSchema | MutationRouteSchema;
+/** Route map accepted by `createRouter().use(...)` and `createClient(...)`. */
 export type Routes = {
     [key: string]: {
         path: RoutePattern;
@@ -67,23 +99,46 @@ type MutationArgs<T> = T extends MutationRouteSchema ? T extends {
 } : {
     body?: unknown;
 } : unknown;
+/**
+ * Arguments accepted by a route request factory such as `route.GET(...)`.
+ *
+ * @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
+ * a matching schema exists. The client forwards the HTTP method, JSON body, and
+ * headers; extra `RequestInit` fields are accepted by the type surface but are
+ * not forwarded.
+ */
 export type RouteArgs<T extends RouteSchema = any, P extends string = string> = ([T] extends [Any] ? {
     query?: any;
     body?: any;
     path?: any;
 } : QueryArgs<T> & MutationArgs<T> & PathArgs<T, P>) & Omit<RequestInit, 'method' | 'body' | 'headers'> & {
+    /** Headers for this request. Undefined values are removed before `fetch`. */
     headers?: Record<string, string | undefined>;
 };
+/**
+ * Request descriptor produced by a route request factory.
+ *
+ * @remarks Pass this object to `client.request(...)` for a raw `Response` or
+ * `client.json(...)` for parsed JSON handling.
+ */
 export type RouteRequest<TResult = any> = {
+    /** Method schema used for client-side validation. */
     schema: RouteSchema;
+    /** Parsed route pattern used to generate the request URL. */
     path: RoutePattern;
+    /** HTTP method to send. */
     method: string;
+    /** Validated route arguments and request options. */
     args: RouteArgs;
+    /** Phantom result type consumed by `client.json(...)`. */
     $result: TResult;
 };
+/** `Response` whose `.json()` method resolves to a known payload type. */
 export type RouteResponse<TResult = any> = Response & {
     json(): Promise<TResult>;
 };
+/** Infer the JSON response payload type from a method schema. */
 export type InferRouteResponse<T extends RouteSchema> = T extends {
     response: Unchecked<infer TResponse>;
 } ? TResponse : void;
@@ -93,12 +148,32 @@ type InferRouteSchemaBody<TSchema> = TSchema extends MutationRouteSchema ? TSche
 type InferRouteArgsBody<TArgs> = TArgs extends {
     body?: infer TBody;
 } ? TBody : never;
+/**
+ * Infer the request body type from a mutation schema or route request factory.
+ *
+ * @remarks Route request factories for mutation methods infer their `body`
+ * argument type. Mutation 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`.
+ *
+ * @remarks `GET` and `ALL` infer `never` because they do not accept request
+ * bodies.
+ */
 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.
+ *
+ * @remarks Calling a factory validates no data by itself; it creates a typed
+ * `RouteRequest` descriptor for `createClient` to validate and send.
+ */
 export type RouteRequestFactory<T extends RouteSchema, P extends string> = {
     (...p: RouteArgs<T, P> extends infer TArgs ? {} extends TArgs ? [args?: TArgs] : [args: TArgs] : never): RouteRequest<InferRouteResponse<T>>;
+    /** Inferred argument type for this request factory. */
     $args: RouteArgs<T, P>;
+    /** Inferred JSON response type for this request factory. */
     $response: InferRouteResponse<T>;
 };

package/docs/context.md

@@ -0,0 +1,167 @@
+# 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.
+
+## 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 the 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
+
+### Route declarations
+
+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`.
+
+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. |
+
+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.
+
+### `$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
+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
+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.
+
+Handlers receive a context typed from middleware plus the route 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 patterns, `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(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
+
+Prefer an absolute `baseURL` for pathname route patterns:
+
+```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.
+
+## 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`.
+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 shorthand methods for normal application calls:
+
+```ts
+await client.helloRoute.GET({ path: { name: 'Ada' } })
+```
+
+Use longhand calls when you need to choose response handling explicitly:
+
+```ts
+const response = await client.request(
+  routes.helloRoute.GET({ path: { name: 'Ada' } })
+)
+
+const json = await client.json(routes.helloRoute.GET({ path: { name: 'Ada' } }))
+```
+
+### 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`.
+
+## Patterns to prefer
+
+- Export route declarations from a small shared module and import that module on
+  both server and client.
+- 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.
+- 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`.
+- 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.
+- 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,115 @@
+import type { HattipHandler } from '@hattip/core'
+import * as z from 'zod'
+import { $type, chain, createClient, createRouter, route } from 'rouzer'
+
+type Profile = {
+  id: string
+  name: string
+  includePosts: boolean
+  requestId: string
+}
+
+export const profileRoute = route('profiles/:id', {
+  GET: {
+    query: z.object({
+      includePosts: z.optional(z.boolean()),
+    }),
+    response: $type<Profile>(),
+  },
+  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 = { profileRoute }
+
+/**
+ * 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 profiles = 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, {
+      profileRoute: {
+        GET(ctx) {
+          const profile = profiles.get(ctx.path.id)
+          if (!profile) {
+            return new Response('Profile not found', { status: 404 })
+          }
+          return {
+            ...profile,
+            includePosts: ctx.query.includePosts ?? false,
+            requestId: ctx.requestId,
+          }
+        },
+        PATCH(ctx) {
+          const current = profiles.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)
+          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.profileRoute.GET({
+    path: { id: '42' },
+    query: { includePosts: false },
+    headers: { 'x-request-id': 'docs' },
+  })
+
+  const updated = await client.profileRoute.PATCH({
+    path: { id: '42' },
+    body: { name: 'Grace' },
+  })
+
+  return { fetched, updated }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rouzer",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "type": "module",
   "exports": {
     ".": {
@@ -37,6 +37,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`.