rouzer 2.0.0 → 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,15 +112,49 @@ class RouterObject extends MiddlewareChain {
                 }
                 return Response.json(result);
             }
-        });
+        }));
     }
 }
+/**
+ * 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();
     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,38 +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>>;
-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>;
-    };
+    } ? 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 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 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,21 +1,47 @@
-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';
+/**
+ * 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 the low-level `route(...)` helper.
+ *
+ * @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;
     POST?: MutationRouteSchema;
@@ -23,14 +49,27 @@ 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;
+/**
+ * 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;
@@ -46,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;
@@ -67,23 +106,47 @@ type MutationArgs<T> = T extends MutationRouteSchema ? T extends {
 } : {
     body?: unknown;
 } : unknown;
+/**
+ * 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
+ * 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 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.
+ */
 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 +156,35 @@ type InferRouteSchemaBody<TSchema> = TSchema extends MutationRouteSchema ? TSche
 type InferRouteArgsBody<TArgs> = TArgs extends {
     body?: infer TBody;
 } ? TBody : never;
+/**
+ * Infer the request body type from a schema or request factory.
+ *
+ * @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 low-level `Route`.
+ *
+ * @remarks `GET` and `ALL` infer `never` because they do not accept request
+ * 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 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.
+ */
 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>;
 };