rouzer 5.2.1 → 5.3.0

package/README.md

@@ -59,7 +59,7 @@ Import the primary API from the root package and declare routes through the HTTP
 subpath:
 
 ```ts
-import { $error, $type, chain, createClient, createRouter } from 'rouzer'
+import { $error, $type, chain, createClient, createRouter, metadata } from 'rouzer'
 import * as http from 'rouzer/http'
 ```
 
@@ -181,6 +181,29 @@ 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()`.
 
+### Route metadata
+
+Use `metadata(...)` to attach optional runtime metadata to HTTP resources or
+actions. Metadata does not affect routing, validation, client typing, or handler
+behavior; it is preserved on route nodes for generated clients, CLIs, docs, and
+route inspectors.
+
+```ts
+export const sessions = http.resource('sessions', {
+  ...metadata({
+    description: 'Daemon-managed session control.',
+  }),
+  list: http.post('list', {
+    ...metadata({
+      description: 'Lists daemon-managed sessions and pagination state.',
+    }),
+    response: $type<SessionList>(),
+  }),
+})
+```
+
+The constructed nodes expose metadata as `node.metadata`.
+
 ### Client lifecycle hooks
 
 Pass `clientHook` to observe generated client action calls without wrapping the

package/dist/http.d.ts

@@ -1,4 +1,5 @@
 import { RoutePattern } from '@remix-run/route-pattern';
+import { type RouteMetadata, type RouteMetadataMarker } from './metadata.js';
 import type { RawBodySchema, RouteSchema } from './types/schema.js';
 /** HTTP methods supported by Rouzer action declarations. */
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
@@ -17,6 +18,8 @@ export type HttpAction<P extends string = string, T extends RouteSchema = RouteS
     method: M;
     /** Request validation and optional response type schema. */
     schema: T;
+    /** Optional runtime metadata for generated tooling. */
+    metadata?: RouteMetadata;
 };
 /**
  * Path-scoped namespace in an HTTP route tree.
@@ -31,6 +34,8 @@ export type HttpResource<P extends string = string, TChildren extends HttpRouteT
     path: RoutePattern<P>;
     /** Child resources and actions exposed below this resource. */
     children: TChildren;
+    /** Optional runtime metadata for generated tooling. */
+    metadata?: RouteMetadata;
 };
 /** Node type accepted inside an HTTP route tree. */
 export type HttpNode = HttpAction | HttpResource;
@@ -38,6 +43,8 @@ export type HttpNode = HttpAction | HttpResource;
 export type HttpRouteTree = {
     [key: string]: HttpNode;
 };
+type RouteDeclaration<T extends object> = T & Partial<RouteMetadataMarker>;
+type StringKeys<T> = Pick<T, Extract<keyof T, string>>;
 /**
  * Declare an HTTP resource namespace.
  *
@@ -45,22 +52,22 @@ export type HttpRouteTree = {
  * property names are API names only; they do not affect the URL unless the child
  * is another resource or an action with an explicit path.
  */
-export declare function resource<const P extends string, const TChildren extends HttpRouteTree>(path: P, children: TChildren): HttpResource<P, TChildren>;
+export declare function resource<const P extends string, const TChildren extends HttpRouteTree>(path: P, children: RouteDeclaration<TChildren>): HttpResource<P, StringKeys<TChildren>>;
 /** Declare a GET action, optionally with an action-local path segment. */
-export declare function get<const P extends string, const T extends RouteSchema>(path: P, schema: T): HttpAction<P, T, 'GET'>;
-export declare function get<const T extends RouteSchema>(schema: T): HttpAction<'', T, 'GET'>;
+export declare function get<const P extends string, const T extends RouteSchema>(path: P, schema: RouteDeclaration<T>): HttpAction<P, T, 'GET'>;
+export declare function get<const T extends RouteSchema>(schema: RouteDeclaration<T>): HttpAction<'', T, 'GET'>;
 /** Declare a POST action, optionally with an action-local path segment. */
-export declare function post<const P extends string, const T extends RouteSchema>(path: P, schema: T): HttpAction<P, T, 'POST'>;
-export declare function post<const T extends RouteSchema>(schema: T): HttpAction<'', T, 'POST'>;
+export declare function post<const P extends string, const T extends RouteSchema>(path: P, schema: RouteDeclaration<T>): HttpAction<P, T, 'POST'>;
+export declare function post<const T extends RouteSchema>(schema: RouteDeclaration<T>): HttpAction<'', T, 'POST'>;
 /** Declare a PUT action, optionally with an action-local path segment. */
-export declare function put<const P extends string, const T extends RouteSchema>(path: P, schema: T): HttpAction<P, T, 'PUT'>;
-export declare function put<const T extends RouteSchema>(schema: T): HttpAction<'', T, 'PUT'>;
+export declare function put<const P extends string, const T extends RouteSchema>(path: P, schema: RouteDeclaration<T>): HttpAction<P, T, 'PUT'>;
+export declare function put<const T extends RouteSchema>(schema: RouteDeclaration<T>): HttpAction<'', T, 'PUT'>;
 /** Declare a PATCH action, optionally with an action-local path segment. */
-export declare function patch<const P extends string, const T extends RouteSchema>(path: P, schema: T): HttpAction<P, T, 'PATCH'>;
-export declare function patch<const T extends RouteSchema>(schema: T): HttpAction<'', T, 'PATCH'>;
+export declare function patch<const P extends string, const T extends RouteSchema>(path: P, schema: RouteDeclaration<T>): HttpAction<P, T, 'PATCH'>;
+export declare function patch<const T extends RouteSchema>(schema: RouteDeclaration<T>): HttpAction<'', T, 'PATCH'>;
 /** Declare a DELETE action, optionally with an action-local path segment. */
-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'>;
+declare function deleteAction<const P extends string, const T extends RouteSchema>(path: P, schema: RouteDeclaration<T>): HttpAction<P, T, 'DELETE'>;
+declare function deleteAction<const T extends RouteSchema>(schema: RouteDeclaration<T>): HttpAction<'', T, 'DELETE'>;
 export { deleteAction as delete };
 /**
  * Declare a request body that is passed through to `fetch` without JSON encoding.

package/dist/http.js

@@ -1,4 +1,5 @@
 import { RoutePattern } from '@remix-run/route-pattern';
+import { getRouteMetadata, stripRouteMetadata, } from './metadata.js';
 /**
  * Declare an HTTP resource namespace.
  *
@@ -7,10 +8,12 @@ import { RoutePattern } from '@remix-run/route-pattern';
  * is another resource or an action with an explicit path.
  */
 export function resource(path, children) {
+    const metadata = getRouteMetadata(children);
     return {
         kind: 'resource',
         path: RoutePattern.parse(path),
-        children,
+        children: stripRouteMetadata(children),
+        metadata,
     };
 }
 export function get(pathOrSchema, schema) {
@@ -47,5 +50,12 @@ function action(method, pathOrSchema, schema) {
         ? RoutePattern.parse(pathOrSchema)
         : undefined;
     schema ??= typeof pathOrSchema === 'string' ? {} : pathOrSchema;
-    return { kind: 'action', path, method, schema };
+    const metadata = getRouteMetadata(schema);
+    return {
+        kind: 'action',
+        path,
+        method,
+        schema: stripRouteMetadata(schema),
+        metadata,
+    };
 }

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/metadata.d.ts

@@ -0,0 +1,16 @@
+declare const routeMetadataKey: unique symbol;
+/** Runtime metadata attached to Rouzer route nodes. */
+export type RouteMetadata = {
+    /** Short label for generated indexes, clients, CLIs, or docs. */
+    summary?: string;
+    /** Human-readable route description for generated tooling. */
+    description?: string;
+};
+export type RouteMetadataMarker = {
+    readonly [routeMetadataKey]: RouteMetadata;
+};
+/** Attach runtime metadata to a route declaration. */
+export declare function metadata(value: RouteMetadata): RouteMetadataMarker;
+export declare function getRouteMetadata(value: unknown): RouteMetadata | undefined;
+export declare function stripRouteMetadata<T extends object>(value: T): Omit<T, typeof routeMetadataKey>;
+export {};

package/dist/metadata.js

@@ -0,0 +1,14 @@
+const routeMetadataKey = Symbol('rouzer.metadata');
+/** Attach runtime metadata to a route declaration. */
+export function metadata(value) {
+    return { [routeMetadataKey]: value };
+}
+export function getRouteMetadata(value) {
+    return typeof value === 'object' && value !== null
+        ? value[routeMetadataKey]
+        : undefined;
+}
+export function stripRouteMetadata(value) {
+    const { [routeMetadataKey]: _metadata, ...rest } = value;
+    return rest;
+}

package/dist/ndjson.d.ts

@@ -57,5 +57,5 @@ export declare function decodeNdjson<T = unknown>(stream: ReadableStream<Uint8Ar
  * `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 & NdjsonEncodeOptions): Response;
+export declare function ndjsonResponse<T>(source: NdjsonSource<T>, { signal, ...init }?: ResponseInit & NdjsonEncodeOptions): Response;
 export {};

package/dist/ndjson.js

@@ -52,107 +52,184 @@ export const routerPlugin = {
  * closed.
  */
 export function encodeNdjson(source, options = {}) {
-    const iterator = getAsyncIterator(source);
-    const encoder = new TextEncoder();
-    const { signal } = options;
-    let cancelled = false;
-    let cleanup;
-    let abortHandler;
-    function removeAbortHandler() {
-        if (signal && abortHandler) {
-            signal.removeEventListener('abort', abortHandler);
-            abortHandler = undefined;
-        }
-    }
-    function cancelIterator(reason) {
-        cancelled = true;
-        removeAbortHandler();
-        cleanup ??= Promise.resolve(iterator.return?.(reason)).then(() => { });
-        return cleanup;
+    return new ReadableStream(new NdjsonEncoder(source, options));
+}
+/**
+ * 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 function decodeNdjson(stream) {
+    return new NdjsonDecoder(stream);
+}
+class NdjsonEncoder {
+    options;
+    iterator;
+    encoder = new TextEncoder();
+    cancelled = false;
+    cleanup;
+    abortHandler;
+    constructor(source, options) {
+        this.options = options;
+        this.iterator = getAsyncIterator(source);
     }
-    return new ReadableStream({
-        start(controller) {
-            if (!signal) {
-                return;
-            }
-            abortHandler = () => {
-                void cancelIterator(signal.reason).catch(() => { });
+    start(controller) {
+        const { signal } = this.options;
+        if (signal) {
+            this.abortHandler = () => {
+                void this.cancel(signal.reason).catch(() => { });
                 try {
                     controller.close();
                 }
                 catch { }
             };
             if (signal.aborted) {
-                abortHandler();
-                return;
+                this.abortHandler();
             }
-            signal.addEventListener('abort', abortHandler, { once: true });
-        },
-        async pull(controller) {
-            if (cancelled) {
-                controller.close();
-                return;
+            else {
+                signal.addEventListener('abort', this.abortHandler, { once: true });
             }
-            const { done, value } = await iterator.next();
-            if (cancelled) {
-                return;
+        }
+    }
+    async pull(controller) {
+        if (this.cancelled) {
+            controller.close();
+            return;
+        }
+        const { done, value } = await this.iterator.next();
+        if (this.cancelled) {
+            return;
+        }
+        if (done) {
+            this.removeAbortHandler();
+            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(this.encoder.encode(`${line}\n`));
+    }
+    async cancel(reason) {
+        if (!this.cancelled) {
+            this.cancelled = true;
+            this.removeAbortHandler();
+            this.cleanup ??= Promise.resolve(this.iterator.return?.(reason)).then(() => { });
+        }
+        await this.cleanup;
+    }
+    removeAbortHandler() {
+        const { signal } = this.options;
+        if (signal && this.abortHandler) {
+            signal.removeEventListener('abort', this.abortHandler);
+            this.abortHandler = undefined;
+        }
+    }
+}
+class NdjsonDecoder {
+    reader;
+    decoder = new TextDecoder();
+    buffer = '';
+    lineNumber = 0;
+    closed = false;
+    doneReading = false;
+    readerReleased = false;
+    constructor(stream) {
+        this.reader = stream.getReader();
+    }
+    [Symbol.asyncIterator]() {
+        return new NdjsonAsyncIterator(this);
+    }
+    releaseReader() {
+        if (!this.readerReleased) {
+            this.readerReleased = true;
+            this.reader.releaseLock();
+        }
+    }
+    async cancelReader(reason) {
+        if (!this.doneReading) {
+            await this.reader.cancel(reason).catch(() => { });
+        }
+        this.releaseReader();
+    }
+    async parseNextLine(line) {
+        try {
+            this.lineNumber += 1;
+            return {
+                done: false,
+                value: parseNdjsonLine(stripCarriageReturn(line), this.lineNumber),
+            };
+        }
+        catch (error) {
+            this.closed = true;
+            await this.cancelReader(error);
+            throw error;
+        }
+    }
+}
+class NdjsonAsyncIterator {
+    decoder;
+    closed = false;
+    constructor(decoder) {
+        this.decoder = decoder;
+    }
+    async next() {
+        if (this.closed || this.decoder.closed) {
+            return { done: true, value: undefined };
+        }
+        while (true) {
+            const newlineIndex = this.decoder.buffer.indexOf('\n');
+            if (newlineIndex !== -1) {
+                const line = this.decoder.buffer.slice(0, newlineIndex);
+                this.decoder.buffer = this.decoder.buffer.slice(newlineIndex + 1);
+                return this.decoder.parseNextLine(line);
             }
-            if (done) {
-                removeAbortHandler();
-                controller.close();
-                return;
+            if (this.decoder.doneReading) {
+                this.close();
+                this.decoder.releaseReader();
+                if (this.decoder.buffer.length > 0) {
+                    const line = this.decoder.buffer;
+                    this.decoder.buffer = '';
+                    return this.decoder.parseNextLine(line);
+                }
+                return { done: true, value: undefined };
             }
-            const line = JSON.stringify(value);
-            if (line === undefined) {
-                throw new TypeError('NDJSON items must serialize to a JSON text; received undefined');
+            let chunk;
+            try {
+                chunk = await this.decoder.reader.read();
             }
-            controller.enqueue(encoder.encode(`${line}\n`));
-        },
-        async cancel(reason) {
-            await cancelIterator(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;
+            catch (error) {
+                this.close();
+                this.decoder.releaseReader();
+                throw error;
+            }
+            if (this.closed || this.decoder.closed) {
+                return { done: true, value: undefined };
             }
-            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 (chunk.done) {
+                this.decoder.buffer += this.decoder.decoder.decode();
+                this.decoder.doneReading = true;
+            }
+            else {
+                this.decoder.buffer += this.decoder.decoder.decode(chunk.value, {
+                    stream: true,
+                });
             }
-        }
-        if (buffer.length > 0) {
-            lineNumber += 1;
-            yield parseNdjsonLine(stripCarriageReturn(buffer), lineNumber);
         }
     }
-    finally {
-        if (!doneReading) {
-            await reader.cancel().catch(() => { });
+    async return(reason) {
+        if (!this.closed) {
+            this.close();
+            await this.decoder.cancelReader(reason);
         }
-        reader.releaseLock();
+        return { done: true, value: undefined };
+    }
+    close() {
+        this.closed = true;
+        this.decoder.closed = true;
     }
 }
 /**
@@ -162,32 +239,28 @@ export async function* decodeNdjson(stream) {
  * `content-type: application/x-ndjson; charset=utf-8` unless the caller supplies
  * a content type in `init.headers`.
  */
-export function ndjsonResponse(source, init = {}) {
-    const { signal, ...responseInit } = init;
+export function ndjsonResponse(source, { signal, ...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, { signal }), {
-        ...responseInit,
+        ...init,
         headers,
     });
 }
 function getAsyncIterator(source) {
-    const asyncIterator = source[Symbol.asyncIterator]?.();
-    if (asyncIterator) {
-        return asyncIterator;
+    if (Symbol.asyncIterator in source) {
+        return source[Symbol.asyncIterator]();
     }
-    const iterator = source[Symbol.iterator]?.();
-    if (iterator) {
+    if (Symbol.iterator in source) {
+        const iterator = source[Symbol.iterator]();
         return {
-            next() {
-                return Promise.resolve(iterator.next());
-            },
-            async return() {
-                iterator.return?.();
-                return { done: true, value: undefined };
-            },
+            next: async (value) => iterator.next(value),
+            return: iterator.return
+                ? async (value) => iterator.return(value)
+                : undefined,
+            throw: iterator.throw ? async (error) => iterator.throw(error) : undefined,
         };
     }
     throw new TypeError('NDJSON source must be iterable');

package/docs/context.md

@@ -72,6 +72,29 @@ paths are joined, so the examples above expose `profiles/:id`, `profiles/:id`,
 and `profiles/:id/posts`. Path params from parent resources are accumulated into
 child action types.
 
+Use the root `metadata(...)` helper to attach optional runtime metadata to
+resources or actions without changing route matching, validation, client typing,
+or handler behavior:
+
+```ts
+import { metadata } from 'rouzer'
+
+export const sessions = http.resource('sessions', {
+  ...metadata({
+    description: 'Daemon-managed session control.',
+  }),
+  list: http.post('list', {
+    ...metadata({
+      description: 'Lists daemon-managed sessions and pagination state.',
+    }),
+    response: $type<SessionList>(),
+  }),
+})
+```
+
+Constructed route nodes expose metadata through `node.metadata` for generated
+clients, CLIs, docs, and route inspectors.
+
 Patterns are parsed by `@remix-run/route-pattern` v0.21. Params can be inferred
 from patterns such as `hello/:name`, `v:major.:minor`,
 `api(/v:major(.:minor))`, `assets/*path`, and `search?q`. Full URL patterns such

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rouzer",
-  "version": "5.2.1",
+  "version": "5.3.0",
   "packageManager": "pnpm@11.5.1",
   "type": "module",
   "exports": {