rouzer 3.0.2 → 3.1.0

package/README.md

@@ -6,12 +6,14 @@ and Zod validation between a Hattip-compatible server and a typed fetch client.
 ## What it does
 
 A Rouzer HTTP route tree defines URL patterns, named actions, method schemas, and
-optional response types once, then reuses that contract to:
+optional JSON or newline-delimited JSON response types once, then reuses that
+contract to:
 
 - validate client arguments before `fetch`
 - match and validate server requests before handlers run
 - type handler context from path, query/body, headers, and middleware
 - attach typed client action functions such as `client.profiles.get(...)`
+- parse typed JSON responses and typed NDJSON response streams
 
 Rouzer optimizes for shared TypeScript route modules over language-agnostic API
 schemas or generated SDKs.
@@ -29,8 +31,8 @@ Consider something else if:
 
 - you need OpenAPI-first workflows, schema files, or generated clients for other
   languages
-- you need runtime response-body validation; `response: $type<T>()` is
-  compile-time only
+- you need runtime response-body validation; `response: $type<T>()` and
+  `response: ndjson.$type<T>()` are compile-time only
 - you want a framework that owns controllers, data loading, rendering, and
   deployment adapters
 - you cannot use ESM or Zod v4+
@@ -101,10 +103,46 @@ const { message } = await client.hello({
 route arguments before `fetch`; server handlers validate matched path, query,
 headers, and JSON bodies before your handler runs.
 
+### NDJSON response streams
+
+Use `response: ndjson.$type<T>()` for endpoints that stream
+newline-delimited JSON. Add `ndjson.routerPlugin` to the router and
+`ndjson.clientPlugin` to the client. Handlers return an `Iterable<T>` or
+`AsyncIterable<T>`; Rouzer wraps it in an `application/x-ndjson` response.
+Client action functions resolve to an `AsyncIterable<T>`.
+
+```ts
+import { createClient, createRouter } from 'rouzer'
+import * as http from 'rouzer/http'
+import * as ndjson from 'rouzer/ndjson'
+
+export const events = http.get('events', {
+  response: ndjson.$type<{ id: number; message: string }>(),
+})
+export const routes = { events }
+
+createRouter({ plugins: [ndjson.routerPlugin] }).use(routes, {
+  async *events() {
+    yield { id: 1, message: 'ready' }
+  },
+})
+
+const client = createClient({
+  baseURL: 'https://example.com/api/',
+  routes,
+  plugins: [ndjson.clientPlugin],
+})
+for await (const event of await client.events()) {
+  console.log(event.message)
+}
+```
+
 ## Documentation
 
-- [Concepts, API selection, and v2.0.1 migration notes](docs/context.md)
+- [Concepts, API selection, and v2->v3 migration notes](docs/context.md)
 - [Runnable shared-route example](examples/basic-usage.ts)
+- [Runnable NDJSON response-stream example](examples/ndjson-stream.ts)
 - Generated declarations in the published package provide the exact signatures
-  for every public export, including the `rouzer/http` subpath.
+  for every public export, including the `rouzer/http` and `rouzer/ndjson`
+  subpaths.
 - Public TSDoc in `src/` owns symbol-level behavior and option details.

package/dist/client/index.d.ts

@@ -1,5 +1,6 @@
 import { Promisable } from '../common.js';
 import type { HttpAction, HttpResource, HttpRouteTree } from '../http.js';
+import { type ClientResponsePlugin } from '../response.js';
 import type { RouteArgs } from '../types/args.js';
 import type { RouteRequest } from '../types/request.js';
 import type { InferRouteResponse } from '../types/response.js';
@@ -38,13 +39,17 @@ export declare function createClient<TRoutes extends HttpRouteTree = Record<stri
      * ```
      */
     routes?: TRoutes;
+    /** Response codec plugins used by generated action functions. */
+    plugins?: readonly ClientResponsePlugin[];
     /**
-     * Custom handler for non-2xx responses from `.json()`.
+     * Custom handler for non-2xx responses from `.json()` and generated response
+     * helpers.
      *
-     * @remarks When provided, the return value is returned from `.json()` as-is;
-     * Rouzer does not automatically parse a `Response` returned by this hook.
+     * @remarks When provided, the return value is returned from the response
+     * helper as-is; Rouzer does not automatically parse a `Response` returned by
+     * this hook.
      */
-    onJsonError?: (response: Response) => Promisable<Response>;
+    onJsonError?: (response: Response) => Promisable<unknown>;
     /** Custom `fetch` implementation to use for requests. */
     fetch?: typeof globalThis.fetch;
 }): ClientTree<TRoutes, ""> & {
@@ -73,13 +78,17 @@ export declare function createClient<TRoutes extends HttpRouteTree = Record<stri
          * ```
          */
         routes?: TRoutes;
+        /** Response codec plugins used by generated action functions. */
+        plugins?: readonly ClientResponsePlugin[];
         /**
-         * Custom handler for non-2xx responses from `.json()`.
+         * Custom handler for non-2xx responses from `.json()` and generated response
+         * helpers.
          *
-         * @remarks When provided, the return value is returned from `.json()` as-is;
-         * Rouzer does not automatically parse a `Response` returned by this hook.
+         * @remarks When provided, the return value is returned from the response
+         * helper as-is; Rouzer does not automatically parse a `Response` returned by
+         * this hook.
          */
-        onJsonError?: (response: Response) => Promisable<Response>;
+        onJsonError?: (response: Response) => Promisable<unknown>;
         /** Custom `fetch` implementation to use for requests. */
         fetch?: typeof globalThis.fetch;
     };
@@ -97,7 +106,9 @@ export type ClientTree<T extends HttpRouteTree, TPrefix extends string = ''> = {
  * Client action function attached for each HTTP action leaf.
  *
  * @remarks Actions whose schema has `response: $type<T>()` return parsed JSON
- * as `T`. Actions without a response marker return the raw `Response`.
+ * as `T`. Actions whose schema has a plugin response marker return the 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 {
     response: any;

package/dist/client/index.js

@@ -1,6 +1,7 @@
 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';
 /**
  * Create a typed fetch client for an HTTP route tree.
  *
@@ -12,6 +13,10 @@ export function createClient(config) {
     const baseURL = config.baseURL.replace(/\/?$/, '/');
     const defaultHeaders = config.headers && shake(config.headers);
     const fetch = config.fetch ?? globalThis.fetch;
+    const responsePlugins = createResponsePluginMap(config.plugins, 'client response');
+    if (config.routes) {
+        validateClientResponsePlugins(config.routes, responsePlugins);
+    }
     async function request({ path: pathBuilder, method, args, schema, }) {
         let { path, query, body, headers, ...init } = args;
         if (schema.path) {
@@ -58,37 +63,58 @@ export function createClient(config) {
     async function json(props) {
         const response = await request(props);
         if (!response.ok) {
-            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 contentType = response.headers.get('content-type');
-            if (contentType?.includes('application/json')) {
-                Object.assign(error, await response.json());
-            }
-            throw error;
+            return handleResponseError(response, props);
         }
         return response.json();
     }
+    async function response(props) {
+        const httpResponse = await request(props);
+        if (!httpResponse.ok) {
+            return handleResponseError(httpResponse, props);
+        }
+        const pluginId = getResponsePluginMarkerId(props.schema.response);
+        if (pluginId) {
+            const plugin = responsePlugins.get(pluginId);
+            if (!plugin) {
+                throw missingClientResponsePlugin(pluginId);
+            }
+            return plugin.decode(httpResponse, {
+                marker: props.schema.response,
+                request: props,
+            });
+        }
+        return httpResponse.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 contentType = response.headers.get('content-type');
+        if (contentType?.includes('application/json')) {
+            Object.assign(error, await response.json());
+        }
+        throw error;
+    }
     return {
         ...(config.routes
-            ? connectTree(config.routes, '', request, json)
+            ? connectTree(config.routes, '', request, response)
             : null),
         config,
         request,
         json,
     };
 }
-function connectTree(tree, prefix, request, json) {
+function connectTree(tree, prefix, request, response) {
     return Object.fromEntries(Object.entries(tree).map(([key, node]) => {
         if (node.kind === 'resource') {
             return [
                 key,
-                connectTree(node.children, joinPaths(prefix, node.path.source), request, json),
+                connectTree(node.children, joinPaths(prefix, node.path.source), request, response),
             ];
         }
         const path = RoutePattern.parse(joinPaths(prefix, node.path?.source ?? ''));
-        const fetch = node.schema.response ? json : request;
+        const fetch = node.schema.response ? response : request;
         return [
             key,
             (args = {}) => fetch({
@@ -101,6 +127,22 @@ function connectTree(tree, prefix, request, json) {
         ];
     }));
 }
+function validateClientResponsePlugins(tree, plugins) {
+    for (const node of Object.values(tree)) {
+        if (node.kind === 'resource') {
+            validateClientResponsePlugins(node.children, plugins);
+        }
+        else {
+            const pluginId = getResponsePluginMarkerId(node.schema.response);
+            if (pluginId && !plugins.has(pluginId)) {
+                throw missingClientResponsePlugin(pluginId);
+            }
+        }
+    }
+}
+function missingClientResponsePlugin(pluginId) {
+    return new Error(`Missing client response plugin for ${pluginId}`);
+}
 function joinPaths(left, right) {
     return [left, right].filter(Boolean).join('/').replace(/\/+/g, '/');
 }

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/ndjson.d.ts

@@ -0,0 +1,54 @@
+import { type ClientResponsePlugin, type ResponsePluginMarker, type RouterResponsePlugin } from './response.js';
+declare const codecId = "rouzer/ndjson";
+/** Values accepted by Rouzer's NDJSON response encoder. */
+export type NdjsonSource<T = unknown> = Iterable<T> | AsyncIterable<T>;
+/**
+ * Create a compile-time marker for newline-delimited JSON response items.
+ *
+ * @remarks The returned marker is handled by `clientPlugin` in clients and
+ * `routerPlugin` in routers. Generated client action functions resolve to an
+ * `AsyncIterable<T>`, while route handlers may return either an `Iterable<T>`
+ * or an `AsyncIterable<T>`. Rouzer does not validate streamed items at runtime.
+ */
+export declare function $type<T>(): ResponsePluginMarker<AsyncIterable<T>, NdjsonSource<T>, typeof codecId>;
+/**
+ * Client plugin that decodes successful NDJSON responses.
+ *
+ * @remarks Register this plugin with `createClient({ plugins })` when the route
+ * tree contains `response: ndjson.$type<T>()` markers.
+ */
+export declare const clientPlugin: ClientResponsePlugin;
+/**
+ * Router plugin that encodes handler results as NDJSON responses.
+ *
+ * @remarks Register this plugin with `createRouter({ plugins })` when the route
+ * tree contains `response: ndjson.$type<T>()` markers. Handler or generator
+ * errors are not encoded as NDJSON items; model application-level errors in the
+ * item type when clients should receive them as data.
+ */
+export declare const routerPlugin: RouterResponsePlugin;
+/**
+ * Encode an iterable of values as a newline-delimited JSON byte stream.
+ *
+ * @remarks Each yielded value is serialized with `JSON.stringify` and followed
+ * by `\n`. Values that cannot be represented as a JSON text, such as
+ * `undefined`, cause the stream to error when read.
+ */
+export declare function encodeNdjson(source: NdjsonSource): ReadableStream<Uint8Array>;
+/**
+ * Decode a newline-delimited JSON byte stream.
+ *
+ * @remarks UTF-8 chunks may split JSON lines. Both `\n` and `\r\n` line endings
+ * are accepted, and a final line does not need a trailing newline. Malformed
+ * lines throw a `SyntaxError` that includes the 1-based line number.
+ */
+export declare function decodeNdjson<T = unknown>(stream: ReadableStream<Uint8Array>): AsyncIterable<T>;
+/**
+ * Create a `Response` whose body is encoded as newline-delimited JSON.
+ *
+ * @remarks The response defaults to
+ * `content-type: application/x-ndjson; charset=utf-8` unless the caller supplies
+ * a content type in `init.headers`.
+ */
+export declare function ndjsonResponse<T>(source: NdjsonSource<T>, init?: ResponseInit): Response;
+export {};

package/dist/ndjson.js

@@ -0,0 +1,161 @@
+import { createResponsePluginMarker, } from './response.js';
+const codecId = 'rouzer/ndjson';
+/**
+ * Create a compile-time marker for newline-delimited JSON response items.
+ *
+ * @remarks The returned marker is handled by `clientPlugin` in clients and
+ * `routerPlugin` in routers. Generated client action functions resolve to an
+ * `AsyncIterable<T>`, while route handlers may return either an `Iterable<T>`
+ * or an `AsyncIterable<T>`. Rouzer does not validate streamed items at runtime.
+ */
+export function $type() {
+    return createResponsePluginMarker(codecId);
+}
+/**
+ * Client plugin that decodes successful NDJSON responses.
+ *
+ * @remarks Register this plugin with `createClient({ plugins })` when the route
+ * tree contains `response: ndjson.$type<T>()` markers.
+ */
+export const clientPlugin = {
+    id: codecId,
+    decode(response) {
+        if (!response.body) {
+            throw new Error('NDJSON response has no body');
+        }
+        return decodeNdjson(response.body);
+    },
+};
+/**
+ * Router plugin that encodes handler results as NDJSON responses.
+ *
+ * @remarks Register this plugin with `createRouter({ plugins })` when the route
+ * tree contains `response: ndjson.$type<T>()` markers. Handler or generator
+ * errors are not encoded as NDJSON items; model application-level errors in the
+ * item type when clients should receive them as data.
+ */
+export const routerPlugin = {
+    id: codecId,
+    encode(value) {
+        return ndjsonResponse(value);
+    },
+};
+/**
+ * Encode an iterable of values as a newline-delimited JSON byte stream.
+ *
+ * @remarks Each yielded value is serialized with `JSON.stringify` and followed
+ * by `\n`. Values that cannot be represented as a JSON text, such as
+ * `undefined`, cause the stream to error when read.
+ */
+export function encodeNdjson(source) {
+    const iterator = getAsyncIterator(source);
+    const encoder = new TextEncoder();
+    return new ReadableStream({
+        async pull(controller) {
+            const { done, value } = await iterator.next();
+            if (done) {
+                controller.close();
+                return;
+            }
+            const line = JSON.stringify(value);
+            if (line === undefined) {
+                throw new TypeError('NDJSON items must serialize to a JSON text; received undefined');
+            }
+            controller.enqueue(encoder.encode(`${line}\n`));
+        },
+        async cancel(reason) {
+            await iterator.return?.(reason);
+        },
+    });
+}
+/**
+ * Decode a newline-delimited JSON byte stream.
+ *
+ * @remarks UTF-8 chunks may split JSON lines. Both `\n` and `\r\n` line endings
+ * are accepted, and a final line does not need a trailing newline. Malformed
+ * lines throw a `SyntaxError` that includes the 1-based line number.
+ */
+export async function* decodeNdjson(stream) {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let lineNumber = 0;
+    let doneReading = false;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+                buffer += decoder.decode();
+                doneReading = true;
+                break;
+            }
+            buffer += decoder.decode(value, { stream: true });
+            let newlineIndex;
+            while ((newlineIndex = buffer.indexOf('\n')) !== -1) {
+                const line = stripCarriageReturn(buffer.slice(0, newlineIndex));
+                buffer = buffer.slice(newlineIndex + 1);
+                lineNumber += 1;
+                yield parseNdjsonLine(line, lineNumber);
+            }
+        }
+        if (buffer.length > 0) {
+            lineNumber += 1;
+            yield parseNdjsonLine(stripCarriageReturn(buffer), lineNumber);
+        }
+    }
+    finally {
+        if (!doneReading) {
+            await reader.cancel().catch(() => { });
+        }
+        reader.releaseLock();
+    }
+}
+/**
+ * Create a `Response` whose body is encoded as newline-delimited JSON.
+ *
+ * @remarks The response defaults to
+ * `content-type: application/x-ndjson; charset=utf-8` unless the caller supplies
+ * a content type in `init.headers`.
+ */
+export function ndjsonResponse(source, init = {}) {
+    const headers = new Headers(init.headers);
+    if (!headers.has('content-type')) {
+        headers.set('content-type', 'application/x-ndjson; charset=utf-8');
+    }
+    return new Response(encodeNdjson(source), {
+        ...init,
+        headers,
+    });
+}
+function getAsyncIterator(source) {
+    const asyncIterator = source[Symbol.asyncIterator]?.();
+    if (asyncIterator) {
+        return asyncIterator;
+    }
+    const iterator = source[Symbol.iterator]?.();
+    if (iterator) {
+        return {
+            next() {
+                return Promise.resolve(iterator.next());
+            },
+            async return() {
+                iterator.return?.();
+                return { done: true, value: undefined };
+            },
+        };
+    }
+    throw new TypeError('NDJSON source must be iterable');
+}
+function stripCarriageReturn(line) {
+    return line.endsWith('\r') ? line.slice(0, -1) : line;
+}
+function parseNdjsonLine(line, lineNumber) {
+    try {
+        return JSON.parse(line);
+    }
+    catch (cause) {
+        const error = new SyntaxError(`Invalid NDJSON at line ${lineNumber}: ${cause instanceof Error ? cause.message : String(cause)}`);
+        error.cause = cause;
+        throw error;
+    }
+}

package/dist/response.d.ts

@@ -0,0 +1,47 @@
+import type { Promisable } from './common.js';
+import type { RouteRequest } from './types/request.js';
+/** Runtime key carried by response plugin markers. */
+export declare const responsePluginMarkerSymbol: unique symbol;
+/**
+ * Compile-time response marker handled by a client/router response plugin pair.
+ *
+ * @remarks `TClient` is the value returned by generated client action
+ * functions. `TRouter` is the non-`Response` value accepted from route handlers.
+ */
+export type ResponsePluginMarker<TClient, TRouter = TClient, TId extends string = string> = {
+    readonly [responsePluginMarkerSymbol]: {
+        readonly id: TId;
+        readonly client: TClient;
+        readonly router: TRouter;
+    };
+};
+/** Client-side response plugin used by `createClient({ plugins })`. */
+export type ClientResponsePlugin = {
+    /** Stable response codec id matched against route response markers. */
+    readonly id: string;
+    /** Decode a successful `Response` into the client action result. */
+    decode(response: Response, context: {
+        marker: ResponsePluginMarker<any, any>;
+        request: RouteRequest;
+    }): Promisable<unknown>;
+};
+/** Router-side response plugin used by `createRouter({ plugins })`. */
+export type RouterResponsePlugin = {
+    /** Stable response codec id matched against route response markers. */
+    readonly id: string;
+    /** Encode a handler result into the HTTP response. */
+    encode(value: unknown, context: {
+        marker: ResponsePluginMarker<any, any>;
+        request: Request;
+    }): Promisable<Response>;
+};
+/** Create a response marker for a response plugin. */
+export declare function createResponsePluginMarker<TClient, TRouter = TClient, const TId extends string = string>(id: TId): ResponsePluginMarker<TClient, TRouter, TId>;
+/** Get the response plugin id from a plugin marker, if present. */
+export declare function getResponsePluginMarkerId(value: unknown): string | undefined;
+/** Return true when a route response marker is handled by a response plugin. */
+export declare function isResponsePluginMarker(value: unknown): value is ResponsePluginMarker<unknown, unknown>;
+/** Create a plugin lookup map and reject duplicate plugin ids. */
+export declare function createResponsePluginMap<TPlugin extends {
+    readonly id: string;
+}>(plugins?: readonly TPlugin[], label?: string): Map<string, TPlugin>;

package/dist/response.js

@@ -0,0 +1,35 @@
+/** Runtime key carried by response plugin markers. */
+export const responsePluginMarkerSymbol = Symbol.for('rouzer.response-plugin');
+/** Create a response marker for a response plugin. */
+export function createResponsePluginMarker(id) {
+    return {
+        [responsePluginMarkerSymbol]: {
+            id,
+            client: undefined,
+            router: undefined,
+        },
+    };
+}
+/** Get the response plugin id from a plugin marker, if present. */
+export function getResponsePluginMarkerId(value) {
+    return isResponsePluginMarker(value)
+        ? value[responsePluginMarkerSymbol].id
+        : undefined;
+}
+/** Return true when a route response marker is handled by a response plugin. */
+export function isResponsePluginMarker(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        responsePluginMarkerSymbol in value);
+}
+/** Create a plugin lookup map and reject duplicate plugin ids. */
+export function createResponsePluginMap(plugins = [], label = 'response') {
+    const map = new Map();
+    for (const plugin of plugins) {
+        if (map.has(plugin.id)) {
+            throw new Error(`Duplicate ${label} plugin: ${plugin.id}`);
+        }
+        map.set(plugin.id, plugin);
+    }
+    return map;
+}

package/dist/server/router.d.ts

@@ -1,6 +1,7 @@
 import type { HattipHandler } from '@hattip/core';
 import { ApplyMiddleware, chain, ExtractMiddleware, MiddlewareChain, MiddlewareTypes } from 'alien-middleware';
 import type { HttpRouteTree } from '../http.js';
+import { type RouterResponsePlugin } from '../response.js';
 import type { RouteRequestHandlerMap } from '../types/server.js';
 export { chain };
 /** Configuration for `createRouter`. */
@@ -25,6 +26,8 @@ export type RouterConfig = {
      * and logs missing route handlers to the console.
      */
     debug?: boolean;
+    /** Response codec plugins used for route handler results. */
+    plugins?: readonly RouterResponsePlugin[];
     /** CORS configuration for requests with an `Origin` header. */
     cors?: {
         /**
@@ -67,8 +70,8 @@ export interface Router<T extends MiddlewareTypes = any> extends HattipHandler<T
 /**
  * Create a Rouzer router that can be mounted by any Hattip adapter.
  *
- * @param config Optional router configuration for base path, debug behavior, and
- * CORS origin restrictions.
+ * @param config Optional router configuration for base path, debug behavior,
+ * response plugins, and CORS origin restrictions.
  * @returns A Hattip-compatible handler with `.use(...)` methods for middleware
  * and route registration.
  */

package/dist/server/router.js

@@ -3,15 +3,18 @@ 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 { createResponsePluginMap, getResponsePluginMarkerId, } from '../response.js';
 export { chain };
 // Internal prototype for the router instance.
 class RouterObject extends MiddlewareChain {
     config;
     basePath;
+    responsePlugins;
     constructor(config) {
         super();
         this.config = config;
         this.basePath = config.basePath?.replace(/\/?$/, '/');
+        this.responsePlugins = createResponsePluginMap(config.plugins, 'router response');
         const allowOrigins = config.cors?.allowOrigins?.map(createOriginPattern);
         if (allowOrigins) {
             super.use(((ctx) => {
@@ -31,14 +34,15 @@ class RouterObject extends MiddlewareChain {
     }
     /** @internal */
     useRoutes(routeSchemas, handlers) {
-        const { config, basePath } = this;
+        const { config, basePath, responsePlugins } = this;
         const routes = flattenRoutes(routeSchemas, handlers, basePath ?? '', config.debug);
+        validateRouterResponsePlugins(routes, responsePlugins);
         const addDebugHeaders = config.debug
             ? (context, route) => {
                 context.setHeader('X-Route-Name', route.name);
             }
             : null;
-        return super.use((async function (context) {
+        return super.use(async function (context) {
             const request = context.request;
             const origin = request.headers.get('Origin');
             const url = (context.url ??= new URL(request.url));
@@ -110,16 +114,27 @@ class RouterObject extends MiddlewareChain {
                 if (result instanceof Response) {
                     return result;
                 }
+                const pluginId = getResponsePluginMarkerId(schema.response);
+                if (pluginId) {
+                    const plugin = responsePlugins.get(pluginId);
+                    if (!plugin) {
+                        throw missingRouterResponsePlugin(pluginId);
+                    }
+                    return plugin.encode(result, {
+                        marker: schema.response,
+                        request,
+                    });
+                }
                 return Response.json(result);
             }
-        }));
+        });
     }
 }
 /**
  * Create a Rouzer router that can be mounted by any Hattip adapter.
  *
- * @param config Optional router configuration for base path, debug behavior, and
- * CORS origin restrictions.
+ * @param config Optional router configuration for base path, debug behavior,
+ * response plugins, and CORS origin restrictions.
  * @returns A Hattip-compatible handler with `.use(...)` methods for middleware
  * and route registration.
  */
@@ -152,6 +167,17 @@ function flattenRoutes(tree, handlers, prefix, debug) {
     }
     return routes;
 }
+function validateRouterResponsePlugins(routes, plugins) {
+    for (const route of routes) {
+        const pluginId = getResponsePluginMarkerId(route.schema.response);
+        if (pluginId && !plugins.has(pluginId)) {
+            throw missingRouterResponsePlugin(pluginId);
+        }
+    }
+}
+function missingRouterResponsePlugin(pluginId) {
+    return new Error(`Missing router response plugin for ${pluginId}`);
+}
 function joinPaths(left, right) {
     return [left, right].filter(Boolean).join('/').replace(/\/+/g, '/');
 }

package/dist/type.d.ts

@@ -1,4 +1,4 @@
-import { Unchecked } from './common.js';
+import type { Unchecked } from './common.js';
 /**
  * Create a compile-time-only marker for an action's JSON response payload type.
  *

package/dist/types/handler.d.ts

@@ -3,7 +3,7 @@ import type { AnyMiddlewareChain, MiddlewareContext } from 'alien-middleware';
 import type * as z from 'zod';
 import { Promisable } from '../common.js';
 import type { HttpAction } from '../http.js';
-import type { InferRouteResponse } from './response.js';
+import type { InferRouteHandlerResult } from './response.js';
 import type { RouteSchema } from './schema.js';
 type RequestContext<TMiddleware extends AnyMiddlewareChain> = MiddlewareContext<TMiddleware>;
 export type RouteRequestHandler<TMiddleware extends AnyMiddlewareChain, TArgs extends object, TResult> = (context: RequestContext<TMiddleware> & TArgs) => Promisable<TResult | Response>;
@@ -17,7 +17,7 @@ export type InferActionHandler<TMiddleware extends AnyMiddlewareChain, TAction e
     headers: TAction['schema'] extends {
         headers: any;
     } ? z.infer<TAction['schema']['headers']> : undefined;
-}, InferRouteResponse<Extract<TAction['schema'], RouteSchema>>> : RouteRequestHandler<TMiddleware, {
+}, InferRouteHandlerResult<Extract<TAction['schema'], RouteSchema>>> : RouteRequestHandler<TMiddleware, {
     path: TAction['schema'] extends {
         path: any;
     } ? z.infer<TAction['schema']['path']> : MatchParams<TPath>;
@@ -27,5 +27,5 @@ export type InferActionHandler<TMiddleware extends AnyMiddlewareChain, TAction e
     headers: TAction['schema'] extends {
         headers: any;
     } ? z.infer<TAction['schema']['headers']> : undefined;
-}, InferRouteResponse<Extract<TAction['schema'], RouteSchema>>>;
+}, InferRouteHandlerResult<Extract<TAction['schema'], RouteSchema>>>;
 export {};

package/dist/types/request.d.ts

@@ -30,6 +30,6 @@ export type RouteRequestFactory<T extends RouteSchema, P extends string> = {
     (...p: RouteArgs<T, P> extends infer TArgs ? {} extends TArgs ? [args?: TArgs] : [args: TArgs] : never): RouteRequest<InferRouteResponse<T>>;
     /** Inferred argument type for this request factory. */
     $args: RouteArgs<T, P>;
-    /** Inferred JSON response type for this request factory. */
+    /** Inferred response type for this request factory. */
     $response: InferRouteResponse<T>;
 };

package/dist/types/response.d.ts

@@ -1,9 +1,17 @@
-import type { Unchecked, RouteSchema } from './schema.js';
+import type { ResponsePluginMarker, RouteSchema, Unchecked } from './schema.js';
 /** `Response` whose `.json()` method resolves to a known payload type. */
 export type RouteResponse<TResult = any> = Response & {
     json(): Promise<TResult>;
 };
-/** Infer the JSON response payload type from an action schema. */
+/** Infer the client response type from an action schema. */
 export type InferRouteResponse<T extends RouteSchema> = T extends {
+    response: ResponsePluginMarker<infer TClient, any>;
+} ? TClient : T extends {
+    response: Unchecked<infer TResponse>;
+} ? TResponse : void;
+/** Infer the non-`Response` handler result type from an action schema. */
+export type InferRouteHandlerResult<T extends RouteSchema> = T extends {
+    response: ResponsePluginMarker<any, infer TRouter>;
+} ? TRouter : T extends {
     response: Unchecked<infer TResponse>;
 } ? TResponse : void;

package/dist/types/schema.d.ts

@@ -1,12 +1,17 @@
 import * as z from 'zod';
-import { Unchecked } from '../common.js';
+import type { Unchecked } from '../common.js';
+import type { ResponsePluginMarker } from '../response.js';
 /**
- * Compile-time-only marker used by `$type<T>()` for unchecked response types.
+ * Compile-time-only marker used by `$type<T>()` for unchecked JSON response
+ * types.
  *
  * @remarks Application code should usually call `$type<T>()` instead of naming
  * this marker directly.
  */
 export type { Unchecked };
+export type { ResponsePluginMarker };
+/** Response marker accepted by HTTP action schemas. */
+export type RouteResponseSchema = Unchecked<any> | ResponsePluginMarker<any, any>;
 /** Schema shape for `GET` route methods. */
 export type QueryRouteSchema = {
     /** Optional Zod object used to validate path params. */
@@ -17,8 +22,8 @@ export type QueryRouteSchema = {
     body?: never;
     /** Optional Zod object used to validate request headers. */
     headers?: z.ZodObject<any>;
-    /** Optional compile-time-only JSON response type marker. */
-    response?: Unchecked<any>;
+    /** Optional compile-time-only JSON or plugin response type marker. */
+    response?: RouteResponseSchema;
 };
 /** Schema shape for mutation route methods. */
 export type MutationRouteSchema = {
@@ -30,8 +35,8 @@ export type MutationRouteSchema = {
     body?: z.ZodType<any, any>;
     /** Optional Zod object used to validate request headers. */
     headers?: z.ZodObject<any>;
-    /** Optional compile-time-only JSON response type marker. */
-    response?: Unchecked<any>;
+    /** Optional compile-time-only JSON or plugin response type marker. */
+    response?: RouteResponseSchema;
 };
 /** Any HTTP action schema Rouzer can execute. */
 export type RouteSchema = QueryRouteSchema | MutationRouteSchema;

package/docs/context.md

@@ -2,8 +2,8 @@
 
 Rouzer is for applications that want one TypeScript HTTP route tree to drive
 both the server and the client that calls it. A route tree combines URL
-patterns, named actions, HTTP method schemas, and optional compile-time response
-types.
+patterns, named actions, HTTP method schemas, and optional compile-time JSON or
+NDJSON response types.
 
 ## When to use Rouzer
 
@@ -18,8 +18,8 @@ Use Rouzer when:
   produced by a separate OpenAPI build step
 
 Rouzer is not a response validation library, an OpenAPI generator, or a complete
-server framework. It focuses on typed route contracts, validation, routing, and a
-small client wrapper.
+server framework. It focuses on typed route contracts, request validation,
+routing, and a small client wrapper.
 
 ## Core abstractions
 
@@ -79,9 +79,9 @@ them out of resource/base-path composition.
 
 Method schemas describe the request pieces Rouzer should validate:
 
-| Action helper                         | Request schemas                        | Notes            |
-| ------------------------------------- | -------------------------------------- | ---------------- |
-| `http.get(...)`                       | `path`, `query`, `headers`, `response` | No request body. |
+| 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. |
 
 If you omit a `path` schema, TypeScript infers path params from the pattern and
@@ -92,15 +92,39 @@ The HTTP action API models explicit operations. It does not expose the old
 method-map `ALL` fallback route shape; declare the concrete methods your client
 and server support.
 
-### `$type<T>()`
+### `$type<T>()` and `ndjson.$type<T>()`
 
-`response: $type<T>()` is a TypeScript-only marker. It tells handlers and client
-action functions what response payload type to expect, but Rouzer does not
-validate response bodies at runtime.
+`response: $type<T>()` is a TypeScript-only marker for JSON response payloads.
+It tells handlers and client action functions what response payload type to
+expect, but Rouzer does not validate response bodies at runtime.
+
+`response: ndjson.$type<T>()` is a TypeScript-only marker for newline-delimited
+JSON response streams from the `rouzer/ndjson` subpath. Register
+`ndjson.routerPlugin` with `createRouter(...)` and `ndjson.clientPlugin` with
+`createClient(...)` for routes that use this marker. Handlers return an
+`Iterable<T>` or `AsyncIterable<T>`; Rouzer serializes each item as one JSON line
+and sets the response content type to `application/x-ndjson; charset=utf-8`.
+Client action functions resolve to an `AsyncIterable<T>` parsed from the
+response body. Streamed items are parsed as JSON but are not validated against a
+Zod schema.
 
 Actions without a `response` marker return a raw `Response` from client action
-functions. Actions with a `response` marker use `client.json(...)` under the hood
-and return parsed JSON typed as `T`.
+functions. Actions with `response: $type<T>()` use `client.json(...)` under the
+hood and return parsed JSON typed as `T`.
+
+### Response plugins
+
+Response plugins add non-JSON response codecs without changing route matching or
+request validation. A plugin package provides a compile-time response marker and
+matching runtime plugins. For NDJSON, those are `ndjson.$type<T>()`,
+`ndjson.routerPlugin`, and `ndjson.clientPlugin`.
+
+The router plugin encodes non-`Response` handler results into an HTTP `Response`.
+The client plugin decodes successful HTTP responses for generated client action
+functions. Rouzer validates plugin registration when routes are attached to a
+router or client, so routes that use an unregistered response marker fail fast
+instead of falling back to JSON. Response plugins do not automatically validate
+response payloads unless the plugin itself implements validation.
 
 ### Router
 
@@ -133,7 +157,10 @@ Handlers receive a context typed from middleware plus the action schema:
 - `GET` handlers receive `ctx.path`, `ctx.query`, and `ctx.headers`
 - mutation handlers receive `ctx.path`, `ctx.body`, and `ctx.headers`
 - handlers may return a plain JSON-serializable value or a `Response`
+- `ndjson.$type<T>()` handlers return an `Iterable<T>` or `AsyncIterable<T>`
+  unless they return a custom `Response`
 - plain values are returned with `Response.json(value)`
+- NDJSON iterables are returned as `application/x-ndjson` streams
 - return a `Response` when you need custom status, headers, or body handling
 
 `basePath` is prepended to route tree paths, `debug` adds matched-route debug
@@ -148,6 +175,8 @@ requests with an `Origin` header.
   request factory contains the full path you want to call
 - `client.json(action.request(args))` for parsed JSON and default non-2xx
   throwing
+- response plugin support for generated client action functions, such as
+  `ndjson.clientPlugin` for NDJSON response streams
 - a client tree that mirrors `routes`, with action functions such as
   `client.profiles.get(args)` when `routes` is supplied
 
@@ -167,14 +196,18 @@ runtimes.
 ## Lifecycle
 
 1. Define shared HTTP actions/resources with `rouzer/http` and Zod schemas.
-2. Attach that route tree to a server with `createRouter().use(routes, handlers)`.
-3. Create a client with the same route tree.
+2. Attach that route tree to a server with `createRouter().use(routes, handlers)`
+   or `createRouter({ plugins }).use(routes, handlers)` when response plugins
+   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`.
 5. The router matches the request, validates the matched inputs, and calls the
    handler.
-6. Plain handler results become JSON responses; explicit `Response` objects pass
-   through unchanged.
+6. Plain handler results become JSON responses, plugin handler results become
+   plugin-encoded responses, and explicit `Response` objects pass through
+   unchanged.
 
 On the server, `path`, `query`, and `headers` values originate as strings. Rouzer
 coerces Zod `number` schemas with `Number(value)` and Zod `boolean` schemas from
@@ -214,6 +247,55 @@ const json = await client.json(
 )
 ```
 
+Response plugins are applied by generated client action functions. For longhand
+calls to plugin-backed routes, use `client.request(...)` for the raw `Response`
+and call the plugin subpath's decoder yourself.
+
+### Stream newline-delimited JSON
+
+Use `ndjson.$type<T>()` when a handler should produce a sequence of JSON values
+without buffering the whole response:
+
+```ts
+import { createClient, createRouter } from 'rouzer'
+import * as http from 'rouzer/http'
+import * as ndjson from 'rouzer/ndjson'
+
+export const events = http.get('events', {
+  response: ndjson.$type<{ id: number; message: string }>(),
+})
+export const routes = { events }
+
+createRouter({ plugins: [ndjson.routerPlugin] }).use(routes, {
+  async *events() {
+    yield { id: 1, message: 'ready' }
+    yield { id: 2, message: 'done' }
+  },
+})
+
+const client = createClient({
+  baseURL: 'https://example.com/api/',
+  routes,
+  plugins: [ndjson.clientPlugin],
+})
+for await (const event of await client.events()) {
+  console.log(event.message)
+}
+```
+
+A complete runnable version lives in
+[`examples/ndjson-stream.ts`](../examples/ndjson-stream.ts).
+
+Rouzer's decoder accepts `\n` and `\r\n`, handles UTF-8 chunk boundaries, and
+throws a `SyntaxError` with a line number for malformed JSON. If a consumer stops
+reading early, the response body is cancelled.
+
+Rouzer does not convert handler or generator failures into extra NDJSON items. If
+an async generator throws after the response starts, the response stream errors
+and the client's `for await` loop throws. Model application-level stream errors
+as part of your item type, for example `{ type: 'error'; message: string }`, when
+clients should receive them as data.
+
 ### Group resource actions
 
 Use resources when the public API reads better as a tree or when actions share
@@ -239,17 +321,18 @@ custom headers. Return a plain value for the default `Response.json(value)` path
 
 ### Customize JSON errors
 
-By default, `client.json(...)` throws for non-2xx responses. If the response body
-is JSON, its properties are copied onto the thrown `Error`.
+By default, `client.json(...)` and generated client action functions throw for
+non-2xx responses. If the response body is JSON, its properties are copied onto
+the thrown `Error`.
 
-`onJsonError` can override that behavior. Its return value is returned from
-`client.json(...)` as-is; Rouzer does not automatically parse a returned
-`Response` from `onJsonError`.
+`onJsonError` can override that behavior. Its return value is returned from the
+response helper as-is; Rouzer does not automatically parse a returned `Response`
+from `onJsonError`.
 
-### Update code written for v2.0.1
+### v2->v3 migration
 
 Rouzer now uses action/resource route trees for router registration and client
-shorthands. A v2.0.1 method-map route such as this:
+shorthands. In the v2->v3 migration, a method-map route such as this:
 
 ```ts
 export const profileRoute = route('profiles/:id', {
@@ -307,6 +390,9 @@ await client.profiles.update({
   only when string params are sufficient.
 - Use `response: $type<T>()` for JSON endpoints that should have typed client
   action functions.
+- Use `response: ndjson.$type<T>()` plus `ndjson.routerPlugin` and
+  `ndjson.clientPlugin` for response streams where each line is a JSON value and
+  the client should consume an `AsyncIterable<T>`.
 - Name actions after domain operations (`get`, `list`, `update`, `archive`) and
   let `http.get/post/put/patch/delete` own the transport method.
 - Set `content-type: application/json` yourself when your server or middleware
@@ -314,7 +400,12 @@ await client.profiles.update({
 
 ## Constraints and gotchas
 
-- `$type<T>()` is compile-time only and does not validate response payloads.
+- `$type<T>()` and `ndjson.$type<T>()` are compile-time only and do not validate
+  response payloads or streamed items.
+- NDJSON support is for response streams; request bodies still use the existing
+  JSON body schema path.
+- Routes that use a response plugin fail fast if the matching client or router
+  plugin is not registered.
 - 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.

package/examples/ndjson-stream.ts

@@ -0,0 +1,68 @@
+import type { HattipHandler } from '@hattip/core'
+import { createClient, createRouter } from 'rouzer'
+import * as http from 'rouzer/http'
+import * as ndjson from 'rouzer/ndjson'
+
+type Event = {
+  id: number
+  message: string
+}
+
+export const events = http.get('events', {
+  response: ndjson.$type<Event>(),
+})
+
+export const routes = { events }
+
+/**
+ * Tiny Hattip adapter used only to keep this example self-contained. Real apps
+ * mount the handler with a Hattip adapter for their runtime.
+ */
+function createLocalFetch(handler: HattipHandler): typeof fetch {
+  return async (input, init) => {
+    const request = new Request(input, init)
+    const response = await handler({
+      request,
+      ip: '127.0.0.1',
+      platform: undefined,
+      env() {
+        return undefined
+      },
+      passThrough() {},
+      waitUntil(promise) {
+        void promise
+      },
+    })
+
+    return response ?? new Response(null, { status: 404 })
+  }
+}
+
+async function collect<T>(source: AsyncIterable<T>) {
+  const values: T[] = []
+  for await (const value of source) {
+    values.push(value)
+  }
+  return values
+}
+
+export async function runNdjsonStreamExample() {
+  const handler = createRouter({
+    basePath: 'api/',
+    plugins: [ndjson.routerPlugin],
+  }).use(routes, {
+    async *events() {
+      yield { id: 1, message: 'ready' }
+      yield { id: 2, message: 'done' }
+    },
+  })
+
+  const client = createClient({
+    baseURL: 'https://example.test/api/',
+    routes,
+    plugins: [ndjson.clientPlugin],
+    fetch: createLocalFetch(handler),
+  })
+
+  return collect(await client.events())
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rouzer",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "type": "module",
   "exports": {
     ".": {
@@ -10,6 +10,10 @@
     "./http": {
       "types": "./dist/http.d.ts",
       "import": "./dist/http.js"
+    },
+    "./ndjson": {
+      "types": "./dist/ndjson.d.ts",
+      "import": "./dist/ndjson.js"
     }
   },
   "peerDependencies": {