rouzer 5.0.0 → 5.1.1

package/README.md

@@ -14,6 +14,7 @@ that contract to:
 - match and validate server requests before handlers run
 - type handler context from path, query/body, headers, and middleware
 - attach typed client action functions such as `client.profiles.get(...)`
+- send JSON object request bodies or raw `BodyInit` payloads
 - parse typed JSON responses, declared error responses, and NDJSON streams
 
 Rouzer optimizes for shared TypeScript route modules over language-agnostic API
@@ -103,8 +104,11 @@ const { message } = await client.hello({
 ```
 
 `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. Routes declared with `body: http.rawBody()` pass a
+`BodyInit` payload through to `fetch` without JSON encoding.
 
 ### Typed status responses
 
@@ -149,6 +153,34 @@ const [error, user, status] = await client.getUser({ id: '42' })
 Success entries resolve as `[null, value, status]`; declared error entries
 resolve as `[error, null, status]`.
 
+### Raw request bodies
+
+Use `http.rawBody()` when an action needs to send a `BodyInit` payload such as a
+`Blob`, `Uint8Array`, `ReadableStream`, `FormData`, or string without JSON
+encoding.
+
+```ts
+export const uploadAvatar = http.post('profiles/:id/avatar', {
+  body: http.rawBody(),
+})
+
+await client.uploadAvatar({ id: '42' }, { body: file })
+```
+
+For raw-body routes without path or query input, the generated client accepts the
+body as the first argument:
+
+```ts
+export const upload = http.post('upload', {
+  body: http.rawBody(),
+})
+
+await client.upload(file, { headers: { 'content-type': file.type } })
+```
+
+Server handlers for raw-body routes read from `ctx.request` directly with Fetch
+APIs such as `arrayBuffer()`, `blob()`, `formData()`, or `text()`.
+
 ### NDJSON response streams
 
 Use `response: ndjson.$type<T>()` for endpoints that stream
@@ -185,7 +217,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, type HttpResource, type HttpRouteTree } from '../http.js';
 import { type ClientResponsePlugin } from '../response.js';
-import type { RouteInput, RouteOptions } 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;
@@ -104,9 +105,17 @@ export type ClientTree<T extends HttpRouteTree, TPrefix extends string = ''> = {
  * union of `[null, value, status]` success entries and `[error, null, status]`
  * error entries. Actions whose schema has a plugin response marker return the
  * plugin's client result type. Actions without a response marker return the raw
- * `Response`.
+ * `Response`. Raw-body actions with no path or query input accept
+ * `(body, options)`; raw-body actions with route input accept
+ * `(input, { body, ...options })`.
  */
-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 {
+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

@@ -134,14 +134,20 @@ function connectTree(tree, prefix, plainRequest, parsedRequest) {
         const fetch = node.schema.response ? parsedRequest : plainRequest;
         return [
             key,
-            (input, options) => fetch({
-                schema: node.schema,
-                path,
-                method: node.method,
-                input,
-                options,
-                $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,
+                });
+            },
         ];
     }));
 }
@@ -165,6 +171,9 @@ 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;

package/dist/http.d.ts

@@ -62,6 +62,12 @@ 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. */
+/**
+ * Declare a request body that is passed through to `fetch` without JSON encoding.
+ *
+ * @remarks For routes with path or query input, pass the body as
+ * `options.body`. For raw-body routes without input, generated client actions
+ * accept the body as their first argument.
+ */
 export declare function rawBody(): RawBodySchema;
 export declare function isRawBodySchema(schema: unknown): schema is RawBodySchema;

package/dist/http.js

@@ -29,7 +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. */
+/**
+ * Declare a request body that is passed through to `fetch` without JSON encoding.
+ *
+ * @remarks For routes with path or query input, pass the body as
+ * `options.body`. For raw-body routes without input, generated client actions
+ * accept the body as their first argument.
+ */
 export function rawBody() {
     return { __rawBody__: Symbol('rouzer.rawBody') };
 }

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

@@ -25,18 +25,21 @@ type HeaderInput<T> = T extends {
  */
 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.
+ * Fetch options accepted by a generated client action.
  *
  * @remarks `headers` remains optional because required route headers may be
- * supplied by `createClient({ headers })` defaults.
+ * supplied by `createClient({ headers })` defaults. Raw-body routes with path or
+ * query input accept `body` here; raw-body routes without input accept the body
+ * as the first client action argument and these options as the second.
  */
+export type RouteFetchOptions<T extends RouteSchema = any> = Omit<RequestInit, 'method' | 'body' | 'headers'> & {
+    /** Headers for this request. Undefined values are removed before `fetch`. */
+    headers?: HeaderInput<T>;
+};
 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?: HeaderInput<T>;
-};
+export type RouteOptions<T extends RouteSchema = any> = RouteFetchOptions<T> & RouteBodyOption<T>;
 export {};

package/docs/context.md

@@ -85,7 +85,7 @@ Method schemas describe the request pieces Rouzer should validate:
 | Action helper                     | Request schemas                        | Notes            |
 | --------------------------------- | -------------------------------------- | ---------------- |
 | `http.get(...)`                   | `path`, `query`, `headers`, `response` | No request body. |
-| `http.post/put/patch/delete(...)` | `path`, `body`, `headers`, `response`  | No query schema. |
+| `http.post/put/patch/delete(...)` | `path`, `body`, `headers`, `response`  | No query schema. `body` is a Zod object for JSON or `http.rawBody()` for pass-through payloads. |
 
 If you omit a `path` schema, TypeScript infers path params from the pattern and
 server handlers receive them as strings. Add a Zod `path` schema when you need
@@ -213,6 +213,12 @@ 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. For
+`http.rawBody()` routes, the raw `BodyInit` payload is passed through to `fetch`
+without JSON encoding.
+
 Generated action functions include:
 
 - raw `Response` results for actions without a response schema
@@ -244,8 +250,8 @@ route actions named `config` remain available as `client.config(...)`.
    are needed.
 3. Create a client with the same route tree, plus matching client response
    plugins when needed.
-4. Client action calls validate `path`, `query`, `body`, and `headers` before
-   `fetch`.
+4. Client action calls validate `path`, `query`, JSON object `body`, and
+   `headers` before `fetch`. Raw bodies are passed through without validation.
 5. The router matches the request, validates the matched inputs, and calls the
    handler.
 6. Plain handler results become JSON responses, response-map helpers choose
@@ -255,22 +261,29 @@ route actions named `config` remain available as `client.config(...)`.
 On the server, `path`, `query`, and `headers` values originate as strings. Rouzer
 coerces Zod `number` schemas with `Number(value)` and Zod `boolean` schemas from
 `"true"` and `"false"`. JSON request bodies are parsed and validated without that
-string-coercion step.
+string-coercion step. Raw request bodies declared with `http.rawBody()` are not
+parsed by Rouzer.
 
 ## Common tasks
 
 ### 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 +321,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 +395,47 @@ 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 } }
+)
+```
+
+When a raw-body route has path or query input, path/query 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.
+
+For raw-body routes without path or query input, the generated client action
+accepts the body as the first argument and fetch options as the second:
+
+```ts
+export const upload = http.post('uploads', {
+  body: http.rawBody(),
+})
+
+await client.upload(file, {
+  headers: { 'content-type': file.type },
 })
 ```
 
+Server handlers for raw-body routes read from `ctx.request` directly with Fetch
+APIs such as `arrayBuffer()`, `blob()`, `formData()`, or `text()`. Rouzer does
+not parse or validate raw request bodies.
+
 ### Return custom responses
 
 Return a `Response` from a handler for non-JSON payloads, custom status codes, or
@@ -434,7 +481,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 +496,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 +525,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 +534,12 @@ 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.
+  For `http.rawBody()` actions, `body` is accepted in the second argument when
+  the route has path or query input; raw-body actions without route input accept
+  the body as the first argument.
 - 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/package.json

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