rouzer 4.0.0 → 5.0.0

package/README.md

@@ -97,8 +97,8 @@ const client = createClient({
 })
 
 const { message } = await client.hello({
-  path: { name: 'world' },
-  query: { excited: true },
+  name: 'world',
+  excited: true,
 })
 ```
 
@@ -143,7 +143,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

package/dist/client/index.d.ts

@@ -1,7 +1,7 @@
 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 { RouteInput, RouteOptions } from '../types/args.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`. */
@@ -106,7 +106,7 @@ 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> = (...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,27 +118,28 @@ 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({
+            (input, options) => fetch({
                 schema: node.schema,
                 path,
                 method: node.method,
-                args,
+                input,
+                options,
                 $result: undefined,
             }),
         ];
@@ -163,6 +165,14 @@ function validateClientResponsePlugins(tree, plugins) {
 function missingClientResponsePlugin(pluginId) {
     return new Error(`Missing client response plugin for ${pluginId}`);
 }
+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.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,42 @@
 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.
+ */
+type RouteBodyOption<T> = T extends {
+    body: RawBodySchema;
+} ? {
+    body: BodyInit | null;
+} : {};
+export type RouteOptions<T extends RouteSchema = any> = Omit<RequestInit, 'method' | 'body' | 'headers'> & RouteBodyOption<T> & {
     /** Headers for this request. Undefined values are removed before `fetch`. */
-    headers?: Record<string, string | undefined>;
+    headers?: HeaderInput<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/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.0.0",
   "type": "module",
   "exports": {
     ".": {