rouzer 5.1.0 → 5.2.0

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
@@ -106,7 +107,8 @@ const { message } = await client.hello({
 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.
+client action argument. Routes declared with `body: http.rawBody()` pass a
+`BodyInit` payload through to `fetch` without JSON encoding.
 
 ### Typed status responses
 
@@ -151,6 +153,56 @@ 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()`.
+
+### Client lifecycle hooks
+
+Pass `clientHook` to observe generated client action calls without wrapping the
+client tree:
+
+```ts
+const client = createClient({
+  baseURL: 'https://example.com/api/',
+  routes,
+  clientHook(event) {
+    if (event.type === 'request.success') {
+      console.log(event.routeName, event.durationMs)
+    }
+  },
+})
+```
+
+Rouzer emits `request.start` before client-side validation, then
+`request.success` when the action resolves or `request.error` when it rejects.
+Terminal events include the parsed response or thrown error plus `durationMs`.
+Hook errors are swallowed.
+
 ### NDJSON response streams
 
 Use `response: ndjson.$type<T>()` for endpoints that stream

package/dist/client/index.d.ts

@@ -5,6 +5,37 @@ import type { RouteFetchOptions, RouteInput, RouteOptions } from '../types/args.
 import type { RawBodySchema } from '../types/schema.js';
 import type { InferRouteResponse } from '../types/response.js';
 import type { RouteSchema } from '../types/schema.js';
+/** Lifecycle event emitted by generated client action functions. */
+export type RouzerClientHookEvent = {
+    type: 'request.start';
+    opId: string;
+    routeName: string;
+    method: string;
+    pathPattern: string;
+    payload: unknown;
+} | {
+    type: 'request.success';
+    opId: string;
+    routeName: string;
+    method: string;
+    pathPattern: string;
+    payload: unknown;
+    response: unknown;
+    status?: number;
+    durationMs: number;
+} | {
+    type: 'request.error';
+    opId: string;
+    routeName: string;
+    method: string;
+    pathPattern: string;
+    payload: unknown;
+    error: unknown;
+    status?: number;
+    durationMs: number;
+};
+/** Best-effort observer for generated client action lifecycles. */
+export type RouzerClientHook = (event: RouzerClientHookEvent) => void;
 /** Client type inferred from an HTTP route tree passed to `createClient`. */
 export type RouzerClient<TRoutes extends HttpRouteTree = Record<string, never>> = ReturnType<typeof createClient<TRoutes>>;
 /**
@@ -51,6 +82,12 @@ export declare function createClient<TRoutes extends HttpRouteTree = Record<stri
     onJsonError?: (response: Response) => Promisable<unknown>;
     /** Custom `fetch` implementation to use for requests. */
     fetch?: typeof globalThis.fetch;
+    /**
+     * Best-effort lifecycle observer for generated client action calls.
+     *
+     * @remarks Hook errors are swallowed and never change request behavior.
+     */
+    clientHook?: RouzerClientHook;
 }): ClientTree<TRoutes, ""> & {
     clientConfig: {
         /**
@@ -90,6 +127,12 @@ export declare function createClient<TRoutes extends HttpRouteTree = Record<stri
         onJsonError?: (response: Response) => Promisable<unknown>;
         /** Custom `fetch` implementation to use for requests. */
         fetch?: typeof globalThis.fetch;
+        /**
+         * Best-effort lifecycle observer for generated client action calls.
+         *
+         * @remarks Hook errors are swallowed and never change request behavior.
+         */
+        clientHook?: RouzerClientHook;
     };
 };
 type Join<A extends string, B extends string> = A extends '' ? B : B extends '' ? A : `${A}/${B}`;
@@ -105,7 +148,9 @@ 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> = T extends {
     body: RawBodySchema;

package/dist/client/index.js

@@ -4,6 +4,7 @@ import { shake } from '../common.js';
 import { isRawBodySchema, } from '../http.js';
 import { getResponseMapPluginIds, isErrorMarker, isResponseMap, } from '../response-map.js';
 import { createResponsePluginMap, getResponsePluginMarkerId, } from '../response.js';
+let nextClientOpId = 0;
 /**
  * Create a typed fetch client for an HTTP route tree.
  *
@@ -16,7 +17,10 @@ export function createClient(config) {
     const fetch = config.fetch ?? globalThis.fetch;
     const responsePlugins = createResponsePluginMap(config.plugins, 'client response');
     validateClientResponsePlugins(config.routes, responsePlugins);
-    async function plainRequest({ path: pathPattern, method, input = {}, options: { body: rawBody, headers, ...init } = {}, schema, }) {
+    async function plainRequest(props) {
+        const { path: pathPattern, method, input = {}, schema } = props;
+        const { body: rawBody, ...options } = props.options ?? {};
+        let { headers, ...init } = options;
         const path = schema.path
             ? schema.path.parse(pickObjectSchemaFields(schema.path, input))
             : input;
@@ -48,7 +52,7 @@ export function createClient(config) {
         if (schema.headers) {
             headers = schema.headers.parse(headers);
         }
-        return fetch(url, {
+        return (await fetch(url, {
             ...init,
             method,
             body: isRawBodySchema(schema.body)
@@ -57,10 +61,9 @@ export function createClient(config) {
                     ? JSON.stringify(body)
                     : undefined,
             headers: (headers ?? defaultHeaders),
-        });
+        }));
     }
-    async function parsedRequest(props) {
-        const response = await plainRequest(props);
+    async function parseResponse(response, props) {
         const responseSchema = props.schema.response;
         // Handle status-keyed response maps
         if (isResponseMap(responseSchema)) {
@@ -106,6 +109,25 @@ export function createClient(config) {
         }
         return response.json();
     }
+    async function plainClientRequest(props) {
+        const response = await plainRequest(props);
+        return {
+            value: response,
+            status: response.status,
+        };
+    }
+    async function parsedClientRequest(props) {
+        const response = await plainRequest(props);
+        try {
+            return {
+                value: await parseResponse(response, props),
+                status: response.status,
+            };
+        }
+        catch (error) {
+            throw new ClientRequestFailure(error, response.status);
+        }
+    }
     async function handleResponseError(response, props) {
         if (config.onJsonError) {
             return config.onJsonError(response);
@@ -118,39 +140,118 @@ export function createClient(config) {
         throw error;
     }
     return {
-        ...connectTree(config.routes, '', plainRequest, parsedRequest),
+        ...connectTree(config.routes, '', '', plainClientRequest, parsedClientRequest, config.clientHook),
         clientConfig: config,
     };
 }
-function connectTree(tree, prefix, plainRequest, parsedRequest) {
+class ClientRequestFailure {
+    error;
+    status;
+    constructor(error, status) {
+        this.error = error;
+        this.status = status;
+    }
+}
+function connectTree(tree, prefix, namePrefix, plainRequest, parsedRequest, clientHook) {
     return Object.fromEntries(Object.entries(tree).map(([key, node]) => {
         if (node.kind === 'resource') {
             return [
                 key,
-                connectTree(node.children, joinPaths(prefix, node.path.source), plainRequest, parsedRequest),
+                connectTree(node.children, joinPaths(prefix, node.path.source), joinNames(namePrefix, key), plainRequest, parsedRequest, clientHook),
             ];
         }
         const path = RoutePattern.parse(joinPaths(prefix, node.path?.source ?? ''));
         const fetch = node.schema.response ? parsedRequest : plainRequest;
+        const routeName = joinNames(namePrefix, key);
         return [
             key,
             (input, options) => {
+                const payload = input;
                 if (isRawBodySchema(node.schema.body) && !hasRouteInput(node, path)) {
                     options = { ...options, body: input };
                     input = undefined;
                 }
-                return fetch({
+                return runClientRequest({
                     schema: node.schema,
                     path,
+                    routeName,
                     method: node.method,
                     input,
+                    payload,
                     options,
                     $result: undefined,
-                });
+                }, fetch, clientHook);
             },
         ];
     }));
 }
+async function runClientRequest(request, fetch, clientHook) {
+    if (!clientHook) {
+        try {
+            return (await fetch(request)).value;
+        }
+        catch (error) {
+            throw getClientRequestFailure(error)?.error ?? error;
+        }
+    }
+    const opId = createClientOpId();
+    const startTime = Date.now();
+    const baseEvent = {
+        opId,
+        routeName: request.routeName,
+        method: request.method,
+        pathPattern: request.path.source,
+        payload: request.payload,
+    };
+    emitClientHook(clientHook, {
+        type: 'request.start',
+        ...baseEvent,
+    });
+    try {
+        const result = await fetch(request);
+        emitClientHook(clientHook, {
+            type: 'request.success',
+            ...baseEvent,
+            response: result.value,
+            ...clientRequestStatus(result.status),
+            durationMs: Date.now() - startTime,
+        });
+        return result.value;
+    }
+    catch (error) {
+        const failure = getClientRequestFailure(error);
+        const eventError = failure ? failure.error : error;
+        emitClientHook(clientHook, {
+            type: 'request.error',
+            ...baseEvent,
+            error: eventError,
+            ...clientRequestStatus(failure?.status),
+            durationMs: Date.now() - startTime,
+        });
+        throw eventError;
+    }
+}
+function emitClientHook(clientHook, event) {
+    try {
+        clientHook(event);
+    }
+    catch {
+        // Lifecycle hooks are observability-only and must not affect requests.
+    }
+}
+function createClientOpId() {
+    nextClientOpId += 1;
+    return `rouzer:${Date.now().toString(36)}:${nextClientOpId.toString(36)}`;
+}
+function getClientRequestFailure(error) {
+    return error instanceof ClientRequestFailure ? error : undefined;
+}
+function clientRequestStatus(status) {
+    return status === undefined ? {} : { status };
+}
+function joinNames(left, right) {
+    return [left, right].filter(Boolean).join('.');
+}
 function validateClientResponsePlugins(tree, plugins) {
     for (const node of Object.values(tree)) {
         if (node.kind === 'resource') {

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

@@ -25,10 +25,12 @@ 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`. */

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
@@ -215,7 +215,9 @@ requests with an `Origin` header.
 `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.
+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:
 
@@ -240,6 +242,54 @@ top, and a custom `fetch` implementation can be supplied for tests or non-browse
 runtimes. The returned client exposes the original options as `clientConfig`, so
 route actions named `config` remain available as `client.config(...)`.
 
+### Client lifecycle hooks
+
+`createClient({ clientHook })` observes generated client action calls without
+wrapping the returned client tree:
+
+```ts
+const client = createClient({
+  baseURL: 'https://example.com/api/',
+  routes,
+  clientHook(event) {
+    if (event.type === 'request.success') {
+      console.log({
+        opId: event.opId,
+        routeName: event.routeName,
+        durationMs: event.durationMs,
+      })
+    }
+  },
+})
+```
+
+Rouzer emits:
+
+- `request.start` before client-side validation
+- `request.success` when the generated action resolves
+- `request.error` when the generated action rejects
+
+Each event includes an opaque per-call `opId`, the generated client route name
+such as `session.create`, the HTTP method, the joined route path pattern, and
+the generated action's first argument as `payload`. Terminal events include
+`durationMs`, either the resolved `response` or thrown `error`, and `status` when
+an HTTP response was received.
+
+`request.error` covers client validation failures, transport failures,
+undeclared HTTP errors, JSON parsing failures, response plugin decode failures,
+and rejected `onJsonError` handlers. A declared error response returned as data
+from a response map is a successful generated action and emits
+`request.success`.
+
+Lifecycle hooks are best-effort observability only. If `clientHook` throws,
+Rouzer swallows that hook error and preserves the generated action's original
+behavior.
+
+For response plugins that return streams, such as NDJSON, `request.success` is
+emitted when the generated action resolves to the stream object. Errors that
+happen later while the caller consumes the stream are outside the first lifecycle
+hook surface.
+
 ## Lifecycle
 
 1. Define shared HTTP actions/resources with `rouzer/http` and Zod schemas.
@@ -248,8 +298,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
@@ -259,7 +309,8 @@ 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
 
@@ -412,8 +463,26 @@ await client.uploadAvatar(
 )
 ```
 
-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.
+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
 
@@ -515,8 +584,10 @@ await client.profiles.update({ id: '42', name: 'Ada' })
   strings passed to `http.resource(...)` and action helpers.
 - 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.
+  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,7 @@
 {
   "name": "rouzer",
-  "version": "5.1.0",
+  "version": "5.2.0",
+  "packageManager": "pnpm@11.5.1",
   "type": "module",
   "exports": {
     ".": {
@@ -16,6 +17,12 @@
       "import": "./dist/ndjson.js"
     }
   },
+  "scripts": {
+    "build": "rm -rf dist && tsgo -b tsconfig.json",
+    "format": "prettier --write src test",
+    "test": "vitest run",
+    "prepublishOnly": "pnpm build"
+  },
   "peerDependencies": {
     "zod": ">=4"
   },
@@ -49,10 +56,5 @@
     "examples",
     "README.md",
     "!*.tsbuildinfo"
-  ],
-  "scripts": {
-    "build": "rm -rf dist && tsgo -b tsconfig.json",
-    "format": "prettier --write src test",
-    "test": "vitest run"
-  }
-}
+  ]
+}