rouzer 4.0.0 → 5.1.0

package/README.md

@@ -97,14 +97,16 @@ const client = createClient({
 })
 
 const { message } = await client.hello({
-  path: { name: 'world' },
-  query: { excited: true },
+  name: 'world',
+  excited: true,
 })
 ```
 
 `handler` can be mounted with any Hattip adapter. Generated client action calls
-validate route arguments before `fetch`; server handlers validate matched path,
-query, headers, and JSON bodies before your handler runs.
+validate flat route arguments before `fetch`; server handlers validate matched
+path, query, headers, and JSON bodies before your handler runs. Per-request
+headers, abort signals, and other `RequestInit` options are passed as a second
+client action argument.
 
 ### Typed status responses
 
@@ -143,7 +145,7 @@ const client = createClient({
   routes,
 })
 
-const [error, user, status] = await client.getUser({ path: { id: '42' } })
+const [error, user, status] = await client.getUser({ id: '42' })
 ```
 
 Success entries resolve as `[null, value, status]`; declared error entries
@@ -185,7 +187,7 @@ for await (const event of await client.events()) {
 
 ## Documentation
 
-- [Concepts, API selection, and v2->v3 migration notes](docs/context.md)
+- [Concepts, API selection, v5 client input notes, and migration notes](docs/context.md)
 - [Runnable shared-route example](examples/basic-usage.ts)
 - [Runnable typed error response example](examples/error-responses.ts)
 - [Runnable NDJSON response-stream example](examples/ndjson-stream.ts)

package/dist/client/index.d.ts

@@ -1,7 +1,8 @@
 import { Promisable } from '../common.js';
-import type { HttpAction, HttpResource, HttpRouteTree } from '../http.js';
+import { type HttpAction, type HttpResource, type HttpRouteTree } from '../http.js';
 import { type ClientResponsePlugin } from '../response.js';
-import type { RouteArgs } from '../types/args.js';
+import type { RouteFetchOptions, RouteInput, RouteOptions } from '../types/args.js';
+import type { RawBodySchema } from '../types/schema.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`. */
@@ -33,7 +34,7 @@ export declare function createClient<TRoutes extends HttpRouteTree = Record<stri
      * @example
      * ```ts
      * const client = createClient({ baseURL: 'https://example.com/api/', routes })
-     * await client.users.list({ query: { page: 1 } })
+     * await client.users.list({ page: 1 })
      * ```
      */
     routes: TRoutes;
@@ -72,7 +73,7 @@ export declare function createClient<TRoutes extends HttpRouteTree = Record<stri
          * @example
          * ```ts
          * const client = createClient({ baseURL: 'https://example.com/api/', routes })
-         * await client.users.list({ query: { page: 1 } })
+         * await client.users.list({ page: 1 })
          * ```
          */
         routes: TRoutes;
@@ -106,7 +107,13 @@ export type ClientTree<T extends HttpRouteTree, TPrefix extends string = ''> = {
  * plugin's client result type. 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 {
+export type RouteFunction<T extends RouteSchema, P extends string> = T extends {
+    body: RawBodySchema;
+} ? RouteInput<T, P> extends infer TInput ? {} extends TInput ? (body: BodyInit | null, options?: RouteFetchOptions<T>) => Promise<T extends {
+    response: any;
+} ? InferRouteResponse<T> : Response> : (input: TInput, options: RouteOptions<T>) => Promise<T extends {
+    response: any;
+} ? InferRouteResponse<T> : Response> : never : (...p: RouteInput<T, P> extends infer TInput ? {} extends TInput ? [input?: TInput, options?: RouteOptions<T>] : [input: TInput, options?: RouteOptions<T>] : never) => Promise<T extends {
     response: any;
 } ? InferRouteResponse<T> : Response>;
 export {};

package/dist/client/index.js

@@ -1,8 +1,9 @@
 import { RoutePattern } from '@remix-run/route-pattern';
 import { createHref } from '@remix-run/route-pattern/href';
 import { shake } from '../common.js';
-import { createResponsePluginMap, getResponsePluginMarkerId, } from '../response.js';
+import { isRawBodySchema, } from '../http.js';
 import { getResponseMapPluginIds, isErrorMarker, isResponseMap, } from '../response-map.js';
+import { createResponsePluginMap, getResponsePluginMarkerId, } from '../response.js';
 /**
  * Create a typed fetch client for an HTTP route tree.
  *
@@ -15,13 +16,12 @@ export function createClient(config) {
     const fetch = config.fetch ?? globalThis.fetch;
     const responsePlugins = createResponsePluginMap(config.plugins, 'client response');
     validateClientResponsePlugins(config.routes, responsePlugins);
-    async function request({ path: pathBuilder, method, args, schema, }) {
-        let { path, query, body, headers, ...init } = args;
-        if (schema.path) {
-            path = schema.path.parse(path);
-        }
+    async function plainRequest({ path: pathPattern, method, input = {}, options: { body: rawBody, headers, ...init } = {}, schema, }) {
+        const path = schema.path
+            ? schema.path.parse(pickObjectSchemaFields(schema.path, input))
+            : input;
         let url;
-        const href = createHref(pathBuilder, path);
+        const href = createHref(pathPattern, path);
         if (href[0] === '/') {
             url = new URL(baseURL);
             url.pathname += href.slice(1);
@@ -30,17 +30,14 @@ export function createClient(config) {
             url = new URL(href, baseURL);
         }
         if (schema.query) {
-            query = schema.query.parse(query ?? {});
+            const query = schema.query.parse(pickObjectSchemaFields(schema.query, input));
             url.search = new URLSearchParams(shake(query)).toString();
         }
-        else if (query) {
-            throw new Error('Unexpected query parameters');
-        }
+        let body;
         if (schema.body) {
-            body = schema.body.parse(body !== undefined ? body : {});
-        }
-        else if (body !== undefined) {
-            throw new Error('Unexpected body');
+            body = isRawBodySchema(schema.body)
+                ? rawBody
+                : schema.body.parse(pickObjectSchemaFields(schema.body, input));
         }
         if (headers) {
             headers = shake(headers);
@@ -54,20 +51,24 @@ export function createClient(config) {
         return fetch(url, {
             ...init,
             method,
-            body: body !== undefined ? JSON.stringify(body) : undefined,
+            body: isRawBodySchema(schema.body)
+                ? body
+                : body !== undefined
+                    ? JSON.stringify(body)
+                    : undefined,
             headers: (headers ?? defaultHeaders),
         });
     }
-    async function response(props) {
-        const httpResponse = await request(props);
+    async function parsedRequest(props) {
+        const response = await plainRequest(props);
         const responseSchema = props.schema.response;
         // Handle status-keyed response maps
         if (isResponseMap(responseSchema)) {
-            const status = httpResponse.status;
+            const status = response.status;
             if (status in responseSchema) {
                 const marker = responseSchema[status];
                 if (isErrorMarker(marker)) {
-                    return [await httpResponse.json(), null, status];
+                    return [await response.json(), null, status];
                 }
                 const pluginId = getResponsePluginMarkerId(marker);
                 if (pluginId) {
@@ -77,20 +78,20 @@ export function createClient(config) {
                     }
                     return [
                         null,
-                        await plugin.decode(httpResponse, {
+                        await plugin.decode(response, {
                             marker: marker,
                             request: props,
                         }),
                         status,
                     ];
                 }
-                return [null, await httpResponse.json(), status];
+                return [null, await response.json(), status];
             }
             // Undeclared status — reject
-            return handleResponseError(httpResponse, props);
+            return handleResponseError(response, props);
         }
-        if (!httpResponse.ok) {
-            return handleResponseError(httpResponse, props);
+        if (!response.ok) {
+            return handleResponseError(response, props);
         }
         const pluginId = getResponsePluginMarkerId(responseSchema);
         if (pluginId) {
@@ -98,18 +99,18 @@ export function createClient(config) {
             if (!plugin) {
                 throw missingClientResponsePlugin(pluginId);
             }
-            return plugin.decode(httpResponse, {
+            return plugin.decode(response, {
                 marker: responseSchema,
                 request: props,
             });
         }
-        return httpResponse.json();
+        return response.json();
     }
     async function handleResponseError(response, props) {
         if (config.onJsonError) {
             return config.onJsonError(response);
         }
-        const error = new Error(`Request to ${props.method} ${createHref(props.path, props.args.path)} failed with status ${response.status}`);
+        const error = new Error(`Request to ${props.method} ${createHref(props.path, props.input)} failed with status ${response.status}`);
         const contentType = response.headers.get('content-type');
         if (contentType?.includes('application/json')) {
             Object.assign(error, await response.json());
@@ -117,29 +118,36 @@ export function createClient(config) {
         throw error;
     }
     return {
-        ...connectTree(config.routes, '', request, response),
+        ...connectTree(config.routes, '', plainRequest, parsedRequest),
         clientConfig: config,
     };
 }
-function connectTree(tree, prefix, request, response) {
+function connectTree(tree, prefix, plainRequest, parsedRequest) {
     return Object.fromEntries(Object.entries(tree).map(([key, node]) => {
         if (node.kind === 'resource') {
             return [
                 key,
-                connectTree(node.children, joinPaths(prefix, node.path.source), request, response),
+                connectTree(node.children, joinPaths(prefix, node.path.source), plainRequest, parsedRequest),
             ];
         }
         const path = RoutePattern.parse(joinPaths(prefix, node.path?.source ?? ''));
-        const fetch = node.schema.response ? response : request;
+        const fetch = node.schema.response ? parsedRequest : plainRequest;
         return [
             key,
-            (args = {}) => fetch({
-                schema: node.schema,
-                path,
-                method: node.method,
-                args,
-                $result: undefined,
-            }),
+            (input, options) => {
+                if (isRawBodySchema(node.schema.body) && !hasRouteInput(node, path)) {
+                    options = { ...options, body: input };
+                    input = undefined;
+                }
+                return fetch({
+                    schema: node.schema,
+                    path,
+                    method: node.method,
+                    input,
+                    options,
+                    $result: undefined,
+                });
+            },
         ];
     }));
 }
@@ -163,6 +171,17 @@ function validateClientResponsePlugins(tree, plugins) {
 function missingClientResponsePlugin(pluginId) {
     return new Error(`Missing client response plugin for ${pluginId}`);
 }
+function hasRouteInput(node, path) {
+    return Boolean(node.schema.path || node.schema.query || /(^|\/)[:*]/.test(path.source));
+}
+function pickObjectSchemaFields(schema, input) {
+    if (typeof input !== 'object' || input === null) {
+        return input;
+    }
+    return Object.fromEntries(Object.keys(schema.shape)
+        .filter(key => key in input)
+        .map(key => [key, input[key]]));
+}
 function joinPaths(left, right) {
     return [left, right].filter(Boolean).join('/').replace(/\/+/g, '/');
 }

package/dist/http.d.ts

@@ -1,5 +1,5 @@
 import { RoutePattern } from '@remix-run/route-pattern';
-import type { RouteSchema } from './types/schema.js';
+import type { RawBodySchema, RouteSchema } from './types/schema.js';
 /** HTTP methods supported by Rouzer action declarations. */
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 /**
@@ -62,3 +62,6 @@ export declare function patch<const T extends RouteSchema>(schema: T): HttpActio
 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 };
+/** Declare a request body that is passed through to `fetch` without JSON encoding. */
+export declare function rawBody(): RawBodySchema;
+export declare function isRawBodySchema(schema: unknown): schema is RawBodySchema;

package/dist/http.js

@@ -29,6 +29,13 @@ function deleteAction(pathOrSchema, schema) {
     return action('DELETE', pathOrSchema, schema);
 }
 export { deleteAction as delete };
+/** Declare a request body that is passed through to `fetch` without JSON encoding. */
+export function rawBody() {
+    return { __rawBody__: Symbol('rouzer.rawBody') };
+}
+export function isRawBodySchema(schema) {
+    return Boolean(schema && typeof schema === 'object' && '__rawBody__' in schema);
+}
 function action(method, pathOrSchema, schema) {
     const path = typeof pathOrSchema === 'string'
         ? RoutePattern.parse(pathOrSchema)

package/dist/response-map.js

@@ -1,4 +1,4 @@
-import { getResponsePluginMarkerId, responsePluginMarker, } from './response.js';
+import { getResponsePluginMarkerId, responsePluginMarker } from './response.js';
 import { $error } from './type.js';
 /** Return true when the response schema is a status-keyed response map. */
 export function isResponseMap(response) {

package/dist/response.d.ts

@@ -1,6 +1,6 @@
 import type { Promisable } from './common.js';
 import type { RoutePattern } from '@remix-run/route-pattern';
-import type { RouteArgs } from './types/args.js';
+import type { RouteOptions } from './types/args.js';
 import type { RouteSchema } from './types/schema.js';
 /** Runtime key carried by response plugin markers. */
 export declare const responsePluginMarker: unique symbol;
@@ -34,7 +34,8 @@ export type ClientResponsePluginRequest = {
     schema: RouteSchema;
     path: RoutePattern;
     method: string;
-    args: RouteArgs;
+    input?: unknown;
+    options?: RouteOptions;
 };
 /** Router-side response plugin used by `createRouter({ plugins })`. */
 export type RouterResponsePlugin = {

package/dist/server/router.d.ts

@@ -1,6 +1,6 @@
 import type { HattipHandler } from '@hattip/core';
 import { ApplyMiddleware, chain, ExtractMiddleware, MiddlewareChain, MiddlewareTypes } from 'alien-middleware';
-import type { HttpRouteTree } from '../http.js';
+import { type HttpRouteTree } from '../http.js';
 import { type RouterResponsePlugin } from '../response.js';
 import type { RouteRequestHandlerMap } from '../types/server.js';
 export { chain };

package/dist/server/router.js

@@ -3,6 +3,7 @@ import { createMatcher } from '@remix-run/route-pattern/match';
 import { chain, MiddlewareChain, } from 'alien-middleware';
 import * as z from 'zod';
 import { mapValues } from '../common.js';
+import { isRawBodySchema } from '../http.js';
 import { createResponsePluginMap, getResponsePluginMarkerId, } from '../response.js';
 import { getDefaultSuccessStatus, getResponseMapPluginIds, isErrorMarker, isResponseMap, } from '../response-map.js';
 export { chain };
@@ -103,7 +104,7 @@ class RouterObject extends MiddlewareChain {
                         return httpClientError(error, 'Invalid query string', config);
                     }
                 }
-                if (schema.body) {
+                if (schema.body && !isRawBodySchema(schema.body)) {
                     const error = await parseRequestBody(context, schema.body);
                     if (error) {
                         addDebugHeaders?.(context, route);

package/dist/types/args.d.ts

@@ -1,51 +1,43 @@
 import type { MatchParams } from '@remix-run/route-pattern/match';
 import type * as z from 'zod';
-import type { MutationRouteSchema, QueryRouteSchema, RouteSchema } from './schema.js';
+import type { MutationRouteSchema, QueryRouteSchema, RawBodySchema, RouteSchema } from './schema.js';
 declare class Any {
     private isAny;
 }
-type PathArgs<T, P extends string> = T extends {
+type PathInput<T, P extends string> = T extends {
     path: infer TPath;
-} ? {} extends z.infer<TPath> ? {
-    [K in keyof T as 'path']?: z.infer<TPath>;
-} : {
-    [K in keyof T as 'path']: z.infer<TPath>;
-} : MatchParams<P> extends infer TParams ? {} extends TParams ? {
-    [K in keyof T as 'path']?: TParams;
-} : {
-    [K in keyof T as 'path']: TParams;
-} : unknown;
-type QueryArgs<T> = T extends QueryRouteSchema & {
+} ? z.infer<TPath> : MatchParams<P>;
+type QueryInput<T> = T extends QueryRouteSchema & {
     query: infer TQuery;
-} ? {} extends z.infer<TQuery> ? {
-    [K in keyof T as 'query']?: z.infer<TQuery>;
-} : {
-    [K in keyof T as 'query']: z.infer<TQuery>;
-} : unknown;
-type MutationArgs<T> = T extends MutationRouteSchema ? T extends {
+} ? z.infer<TQuery> : unknown;
+type BodyInput<T> = T extends MutationRouteSchema ? T extends {
     body: infer TBody;
-} ? {} extends z.infer<TBody> ? {
-    [K in keyof T as 'body']?: z.infer<TBody>;
-} : {
-    [K in keyof T as 'body']: z.infer<TBody>;
-} : {
-    body?: unknown;
-} : unknown;
+} ? TBody extends RawBodySchema ? unknown : z.infer<TBody> : unknown : unknown;
+type HeaderInput<T> = T extends {
+    headers: infer THeaders;
+} ? Partial<z.infer<THeaders>> : Record<string, string | undefined>;
 /**
- * Arguments accepted by a generated client action function.
+ * Semantic input accepted by a generated client action function.
  *
- * @remarks The type is derived from an action schema and route pattern. `path`,
- * `query`, `body`, and `headers` are validated by the client before `fetch` when
- * a matching schema exists. Other `RequestInit` fields are forwarded to `fetch`,
- * except `method`, `body`, and `headers`, which Rouzer derives from the action
- * schema and call arguments.
+ * @remarks Path params, query params, and JSON body fields are flattened into a
+ * single object. Avoid declaring duplicate keys across path/query/body schemas,
+ * since a flat input cannot distinguish their source.
  */
-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'> & {
+export type RouteInput<T extends RouteSchema = any, P extends string = string> = [T] extends [Any] ? any : PathInput<T, P> & QueryInput<T> & BodyInput<T>;
+/**
+ * Fetch options accepted as the second argument to a generated client action.
+ *
+ * @remarks `headers` remains optional because required route headers may be
+ * supplied by `createClient({ headers })` defaults.
+ */
+export type RouteFetchOptions<T extends RouteSchema = any> = Omit<RequestInit, 'method' | 'body' | 'headers'> & {
     /** Headers for this request. Undefined values are removed before `fetch`. */
-    headers?: Record<string, string | undefined>;
+    headers?: HeaderInput<T>;
 };
+type RouteBodyOption<T> = T extends {
+    body: RawBodySchema;
+} ? {
+    body: BodyInit | null;
+} : {};
+export type RouteOptions<T extends RouteSchema = any> = RouteFetchOptions<T> & RouteBodyOption<T>;
 export {};

package/dist/types/handler.d.ts

@@ -4,7 +4,10 @@ import type * as z from 'zod';
 import { Promisable } from '../common.js';
 import type { HttpAction } from '../http.js';
 import type { InferRouteHandlerResult, InferResponseMapErrors, InferResponseMapSuccesses } from './response.js';
-import type { RouteResponseMap, RouteSchema } from './schema.js';
+import type { RawBodySchema, RouteResponseMap, RouteSchema } from './schema.js';
+type InferHandlerBody<T> = T extends {
+    body: infer TBody;
+} ? TBody extends RawBodySchema ? undefined : z.infer<TBody> : undefined;
 type RequestContext<TMiddleware extends AnyMiddlewareChain> = MiddlewareContext<TMiddleware>;
 /**
  * Error response returned by `ctx.error(status, body)` in route handlers.
@@ -51,9 +54,7 @@ export type InferActionHandler<TMiddleware extends AnyMiddlewareChain, TAction e
     path: TAction['schema'] extends {
         path: any;
     } ? z.infer<TAction['schema']['path']> : MatchParams<TPath>;
-    body: TAction['schema'] extends {
-        body: any;
-    } ? z.infer<TAction['schema']['body']> : undefined;
+    body: InferHandlerBody<TAction['schema']>;
     headers: TAction['schema'] extends {
         headers: any;
     } ? z.infer<TAction['schema']['headers']> : undefined;
@@ -71,9 +72,7 @@ export type InferActionHandler<TMiddleware extends AnyMiddlewareChain, TAction e
     path: TAction['schema'] extends {
         path: any;
     } ? z.infer<TAction['schema']['path']> : MatchParams<TPath>;
-    body: TAction['schema'] extends {
-        body: any;
-    } ? z.infer<TAction['schema']['body']> : undefined;
+    body: InferHandlerBody<TAction['schema']>;
     headers: TAction['schema'] extends {
         headers: any;
     } ? z.infer<TAction['schema']['headers']> : undefined;

package/dist/types/schema.d.ts

@@ -36,14 +36,18 @@ export type QueryRouteSchema = {
     /** Optional compile-time-only JSON or plugin response type marker. */
     response?: RouteResponseSchema;
 };
+/** Marker for request bodies passed through to `fetch` without JSON encoding. */
+export type RawBodySchema = {
+    readonly __rawBody__: unique symbol;
+};
 /** 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 schema used to validate the JSON request body, or raw body marker. */
+    body?: z.ZodObject<any> | RawBodySchema;
     /** Optional Zod object used to validate request headers. */
     headers?: z.ZodObject<any>;
     /** Optional compile-time-only JSON or plugin response type marker. */

package/dist/types/server.d.ts

@@ -1,4 +1,4 @@
-import type { AnyMiddlewareChain, MiddlewareChain } from 'alien-middleware';
+import type { AnyMiddlewareChain } from 'alien-middleware';
 import type { HttpAction, HttpResource, HttpRouteTree } from '../http.js';
 import type { InferActionHandler } from './handler.js';
 import type { Join } from './path.js';
@@ -10,6 +10,6 @@ import type { Join } from './path.js';
  * 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 = ''> = {
+export type RouteRequestHandlerMap<TRoutes extends HttpRouteTree = HttpRouteTree, TMiddleware extends AnyMiddlewareChain = never, 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;
 };

package/docs/context.md

@@ -213,6 +213,10 @@ requests with an `Origin` header.
 
 `createClient({ baseURL, routes })` creates a client tree that mirrors
 `routes`, with action functions such as `client.profiles.get(args)`.
+Generated action functions accept a flattened first argument containing path,
+query, and JSON body fields. Per-request `RequestInit` options, including
+headers and abort signals, are passed as the optional second argument.
+
 Generated action functions include:
 
 - raw `Response` results for actions without a response schema
@@ -261,16 +265,22 @@ string-coercion step.
 
 ### Call client actions
 
-Use generated client action functions for application calls:
+Use generated client action functions for application calls. The first argument
+is a flat object containing all path, query, and JSON body fields. The optional
+second argument is for per-request `RequestInit` options such as headers or an
+abort signal.
 
 ```ts
-await client.profiles.get({ path: { id: '42' } })
-await client.profiles.update({
-  path: { id: '42' },
-  body: { name: 'Ada' },
-})
+await client.profiles.get({ id: '42', includePosts: true })
+await client.profiles.update(
+  { id: '42', name: 'Ada' },
+  { headers: { 'x-request-id': 'docs' } }
+)
 ```
 
+Avoid duplicate field names across an action's path, query, and body schemas;
+the client input is flat, so duplicate keys cannot represent separate values.
+
 ### Handle declared error responses
 
 Use `$error<T>()` inside a response map when an error status is part of the route
@@ -308,9 +318,7 @@ const client = createClient({
   routes,
 })
 
-const [error, user, status] = await client.getUser({
-  path: { id: 'missing' },
-})
+const [error, user, status] = await client.getUser({ id: 'missing' })
 
 if (status === 404) {
   console.log(error.message)
@@ -384,11 +392,29 @@ export const organizations = http.resource('orgs/:orgId', {
   }),
 })
 
-await client.organizations.members.get({
-  path: { orgId: 'acme', memberId: '42' },
+await client.organizations.members.get({ orgId: 'acme', memberId: '42' })
+```
+
+### Send raw request bodies
+
+Use `http.rawBody()` for mutation actions whose client should pass a `BodyInit`
+through to `fetch` without JSON encoding or Zod body parsing:
+
+```ts
+export const uploadAvatar = http.post('profiles/:id/avatar', {
+  body: http.rawBody(),
+  headers: z.object({ 'content-type': z.string() }),
 })
+
+await client.uploadAvatar(
+  { id: '42' },
+  { body: file, headers: { 'content-type': file.type } }
+)
 ```
 
+Path fields still live in the flat first argument. The raw body itself is passed
+as `body` in the second argument because it is a `RequestInit` value.
+
 ### Return custom responses
 
 Return a `Response` from a handler for non-JSON payloads, custom status codes, or
@@ -434,7 +460,8 @@ export const profiles = http.resource('profiles/:id', {
 export const routes = { profiles }
 ```
 
-Handler maps and client calls mirror the new action names:
+Handler maps mirror the action names, while v5 client calls use flat input
+objects:
 
 ```ts
 createRouter().use(routes, {
@@ -448,11 +475,8 @@ createRouter().use(routes, {
   },
 })
 
-await client.profiles.get({ path: { id: '42' } })
-await client.profiles.update({
-  path: { id: '42' },
-  body: { name: 'Ada' },
-})
+await client.profiles.get({ id: '42' })
+await client.profiles.update({ id: '42', name: 'Ada' })
 ```
 
 ## Patterns to prefer
@@ -480,8 +504,8 @@ await client.profiles.update({
 - `$type<T>()`, `$error<T>()`, and `ndjson.$type<T>()` are compile-time-only type
   contracts. Rouzer does not re-validate handler return values at the server
   boundary.
-- NDJSON support is for response streams; request bodies still use the existing
-  JSON body schema path.
+- NDJSON support is for response streams; request bodies use JSON body schemas
+  unless an action declares `body: http.rawBody()`.
 - Declared `$error<T>()` responses are JSON responses. Use a custom `Response`
   for non-JSON error payloads.
 - Routes that use a response plugin fail fast if the matching client or router
@@ -489,10 +513,10 @@ await client.profiles.update({
 - Pathname route patterns expect an absolute client `baseURL`.
 - Resource and action keys are API names only; paths come from the pattern
   strings passed to `http.resource(...)` and action helpers.
-- Extra `RequestInit` fields in route args, such as `signal` or `credentials`,
-  are forwarded by `createClient`; `method` and `body` are reserved for Rouzer's
-  action metadata and validated call arguments. Use route args or client defaults
-  for request headers.
+- Path, query, and JSON body fields are flattened into the first client action
+  argument. Per-request `RequestInit` fields, such as `signal`, `credentials`,
+  and `headers`, belong in the second argument. `method` is reserved by Rouzer;
+  `body` is only accepted in the second argument for `http.rawBody()` actions.
 - The HTTP action API has no `ALL` fallback route. Declare explicit actions for
   supported methods.
 - Rouzer does not automatically set `Access-Control-Allow-Credentials`; set it in

package/examples/basic-usage.ts

@@ -101,16 +101,9 @@ export async function runBasicUsageExample() {
     fetch: createLocalFetch(handler),
   })
 
-  const fetched = await client.profiles.get({
-    path: { id: '42' },
-    query: { includePosts: false },
-    headers: { 'x-request-id': 'docs' },
-  })
+  const fetched = await client.profiles.get({ id: '42', includePosts: false }, { headers: { 'x-request-id': 'docs' } })
 
-  const updated = await client.profiles.update({
-    path: { id: '42' },
-    body: { name: 'Grace' },
-  })
+  const updated = await client.profiles.update({ id: '42', name: 'Grace' })
 
   return { fetched, updated }
 }

package/examples/error-responses.ts

@@ -89,10 +89,10 @@ export async function runErrorResponsesExample() {
     fetch: createLocalFetch(handler),
   })
 
-  const found = await client.getUser({ path: { id: '42' } })
-  const created = await client.getUser({ path: { id: 'created' } })
-  const missing = await client.getUser({ path: { id: 'missing' } })
-  const unauthorized = await client.getUser({ path: { id: 'unauthorized' } })
+  const found = await client.getUser({ id: '42' })
+  const created = await client.getUser({ id: 'created' })
+  const missing = await client.getUser({ id: 'missing' })
+  const unauthorized = await client.getUser({ id: 'unauthorized' })
 
   return { found, created, missing, unauthorized }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rouzer",
-  "version": "4.0.0",
+  "version": "5.1.0",
   "type": "module",
   "exports": {
     ".": {