rouzer 2.0.1 → 3.0.1

package/README.md

@@ -1,17 +1,17 @@
 # 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.
+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 route declaration defines a URL pattern, method schemas, and optional
-response type once, then reuses that contract to:
+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 shorthand methods such as `client.helloRoute.GET(...)`
+- 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.
@@ -20,10 +20,10 @@ schemas or generated SDKs.
 
 Use Rouzer if:
 
-- your server and client can import the same TypeScript route declarations
+- 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 a small routing/client contract over a full web framework
+- you prefer named resource/action functions over a generated client class
 
 Consider something else if:
 
@@ -41,7 +41,7 @@ Consider something else if:
 - Zod v4 or newer
 - a Hattip adapter when using `createRouter(...)`
 - a Fetch API implementation when using `createClient(...)`
-- an absolute `baseURL` for pathname route patterns
+- an absolute `baseURL` for generated client URLs
 
 ## Installation
 
@@ -49,41 +49,40 @@ Consider something else if:
 pnpm add rouzer zod
 ```
 
-Import the public API from the root package:
+Import the primary API from the root package and declare routes through the HTTP
+subpath:
 
 ```ts
-import { $type, chain, createClient, createRouter, route } from 'rouzer'
+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 route contract defines validation, server
-handler types, and the typed client call.
+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, route } from 'rouzer'
-
-export const helloRoute = route('hello/:name', {
-  GET: {
-    query: z.object({
-      excited: z.optional(z.boolean()),
-    }),
-    response: $type<{ message: string }>(),
-  },
+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 = { helloRoute }
+export const routes = { hello }
 
 export const handler = createRouter({ basePath: 'api/' }).use(routes, {
-  helloRoute: {
-    GET(ctx) {
-      return {
-        message: `Hello, ${ctx.path.name}${ctx.query.excited ? '!' : '.'}`,
-      }
-    },
+  hello(ctx) {
+    return {
+      message: `Hello, ${ctx.path.name}${ctx.query.excited ? '!' : '.'}`,
+    }
   },
 })
 
@@ -92,20 +91,20 @@ const client = createClient({
   routes,
 })
 
-const { message } = await client.helloRoute.GET({
+const { message } = await client.hello({
   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.
+`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 and API selection](docs/context.md)
+- [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.
+  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,18 +1,21 @@
 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>>;
+import type { HttpAction, HttpResource, HttpRouteTree } from '../http.js';
+import type { RouteArgs } from '../types/args.js';
+import type { RouteRequest } from '../types/request.js';
+import type { InferRouteResponse } from '../types/response.js';
+import type { RouteSchema } from '../types/schema.js';
+/** 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 Rouzer route declarations.
+ * 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 attaches shorthand
- * methods such as `client.helloRoute.GET(...)`.
+ * 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 Record<string, Route> = Record<string, never>>(config: {
+export declare function createClient<TRoutes extends HttpRouteTree = Record<string, never>>(config: {
     /**
-     * Absolute base URL used for pathname route patterns.
+     * 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`.
@@ -26,12 +29,12 @@ export declare function createClient<TRoutes extends Record<string, Route> = Rec
      */
     headers?: Record<string, string>;
     /**
-     * Route map to attach as shorthand methods on the client.
+     * HTTP route tree to attach as direct client action functions.
      *
      * @example
      * ```ts
      * const client = createClient({ baseURL: 'https://example.com/api/', routes })
-     * await client.helloRoute.GET({ path: { name: 'world' } })
+     * await client.users.list({ query: { page: 1 } })
      * ```
      */
     routes?: TRoutes;
@@ -40,16 +43,14 @@ export declare function createClient<TRoutes extends Record<string, Route> = Rec
      *
      * @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. */
     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: {
         /**
-         * Absolute base URL used for pathname route patterns.
+         * 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`.
@@ -61,41 +62,44 @@ export declare function createClient<TRoutes extends Record<string, Route> = Rec
          * @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>;
         /**
-         * Route map to attach as shorthand methods on the client.
+         * HTTP route tree to attach as direct client action functions.
          *
          * @example
          * ```ts
          * const client = createClient({ baseURL: 'https://example.com/api/', routes })
-         * await client.helloRoute.GET({ path: { name: 'world' } })
+         * await client.users.list({ query: { page: 1 } })
          * ```
          */
-        routes?: TRoutes | undefined;
+        routes?: TRoutes;
         /**
          * 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;
+        onJsonError?: (response: Response) => Promisable<Response>;
         /** Custom `fetch` implementation to use for requests. */
-        fetch?: typeof globalThis.fetch | undefined;
+        fetch?: typeof globalThis.fetch;
     };
-    request: <T extends RouteRequest>({ path: pathBuilder, method, args: { path, query, body, headers }, schema, }: T) => Promise<Response & {
-        json(): Promise<T["$result"]>;
+    request: <T extends RouteRequest>({ path: pathBuilder, method, args, schema, }: T) => Promise<Response & {
+        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;
 };
 /**
- * Shorthand client method attached for each route method when `routes` is passed
- * to `createClient`.
+ * Client action function attached for each HTTP action leaf.
  *
- * @remarks Methods whose schema has `response: $type<T>()` return parsed JSON as
- * `T`. Methods without a response marker return the raw `Response`.
+ * @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,27 +1,30 @@
-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 Rouzer route declarations.
+ * 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 attaches shorthand
- * methods such as `client.helloRoute.GET(...)`.
+ * 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);
     const fetch = config.fetch ?? globalThis.fetch;
-    async function request({ path: pathBuilder, method, args: { path, query, body, headers }, schema, }) {
+    async function request({ path: pathBuilder, method, args, schema, }) {
+        let { path, query, body, headers, ...init } = args;
         if (schema.path) {
             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 ?? {});
@@ -46,6 +49,7 @@ export function createClient(config) {
             headers = schema.headers.parse(headers);
         }
         return fetch(url, {
+            ...init,
             method,
             body: body !== undefined ? JSON.stringify(body) : undefined,
             headers: (headers ?? defaultHeaders),
@@ -57,7 +61,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());
@@ -68,19 +72,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/http.d.ts

@@ -0,0 +1,67 @@
+import { RoutePattern } from '@remix-run/route-pattern';
+import type { RouteRequestFactory } from './types/request.js';
+import type { RouteSchema } from './types/schema.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. */
+declare function deleteAction<const P extends string, const T extends RouteSchema>(path: P, schema: T): HttpAction<P, T, 'DELETE'>;
+declare function deleteAction<const T extends RouteSchema>(schema: T): HttpAction<'', T, 'DELETE'>;
+export { deleteAction as delete };

package/dist/http.js

@@ -0,0 +1,43 @@
+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);
+}
+function deleteAction(pathOrSchema, schema) {
+    return action('DELETE', pathOrSchema, schema);
+}
+export { deleteAction 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/index.d.ts

@@ -1,5 +1,5 @@
 export * from './client/index.js';
-export * from './route.js';
+export * from './type.js';
 export * from './server/router.js';
-export type * from './types.js';
+export type * from './types/index.js';
 export * from 'alien-middleware';

package/dist/index.js

@@ -1,4 +1,4 @@
 export * from './client/index.js';
-export * from './route.js';
+export * from './type.js';
 export * from './server/router.js';
 export * from 'alien-middleware';

package/dist/internal.d.ts

@@ -0,0 +1,17 @@
+import type { RoutePattern } from '@remix-run/route-pattern';
+import type { RouteRequestFactory, RouteSchema } from './types.js';
+/** @internal */
+export type RouteSchemaMap = {
+    GET?: RouteSchema;
+    POST?: RouteSchema;
+    PUT?: RouteSchema;
+    PATCH?: RouteSchema;
+    DELETE?: RouteSchema;
+};
+/** @internal */
+export type Route<P extends string = string, T extends RouteSchemaMap = RouteSchemaMap> = {
+    path: RoutePattern<P>;
+    methods: T;
+} & {
+    [K in keyof T]: RouteRequestFactory<Extract<T[K], RouteSchema>, P>;
+};

package/dist/internal.js

@@ -0,0 +1 @@
+export {};

package/dist/server/router.d.ts

@@ -1,7 +1,7 @@
 import type { HattipHandler } from '@hattip/core';
 import { ApplyMiddleware, chain, ExtractMiddleware, MiddlewareChain, MiddlewareTypes } from 'alien-middleware';
-import type { Routes } from '../types.js';
-import type { RouteRequestHandlerMap } from './types.js';
+import type { HttpRouteTree } from '../http.js';
+import type { RouteRequestHandlerMap } from '../types/server.js';
 export { chain };
 /** Configuration for `createRouter`. */
 export type RouterConfig = {
@@ -54,11 +54,15 @@ 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.