rouzer 5.2.2 → 5.3.1

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 } 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,7 @@ export type HttpNode = HttpAction | HttpResource;
 export type HttpRouteTree = {
     [key: string]: HttpNode;
 };
+type StringKeys<T> = Pick<T, Extract<keyof T, string>>;
 /**
  * Declare an HTTP resource namespace.
  *
@@ -45,7 +51,7 @@ 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: 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'>;

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,13 @@
+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;
+};
+/** Attach runtime metadata to a route declaration. */
+export declare function metadata(value: RouteMetadata): object;
+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/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.2",
+  "version": "5.3.1",
   "packageManager": "pnpm@11.5.1",
   "type": "module",
   "exports": {