feat: add route metadata helper

Author: aleclarson

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

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

src/http.ts

@@ -1,4 +1,10 @@
 import { RoutePattern } from '@remix-run/route-pattern'
+import {
+  getRouteMetadata,
+  stripRouteMetadata,
+  type RouteMetadata,
+  type RouteMetadataMarker,
+} from './metadata.js'
 import type { RawBodySchema, RouteSchema } from './types/schema.js'
 
 /** HTTP methods supported by Rouzer action declarations. */
@@ -23,6 +29,8 @@ export type HttpAction<
   method: M
   /** Request validation and optional response type schema. */
   schema: T
+  /** Optional runtime metadata for generated tooling. */
+  metadata?: RouteMetadata
 }
 
 /**
@@ -41,6 +49,8 @@ export type HttpResource<
   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. */
@@ -49,6 +59,10 @@ export type HttpNode = HttpAction | HttpResource
 /** Route tree accepted by HTTP clients and routers. */
 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.
  *
@@ -59,85 +73,90 @@ export type HttpRouteTree = { [key: string]: HttpNode }
 export function resource<
   const P extends string,
   const TChildren extends HttpRouteTree,
->(path: P, children: TChildren): HttpResource<P, TChildren> {
+>(
+  path: P,
+  children: RouteDeclaration<TChildren>
+): HttpResource<P, StringKeys<TChildren>> {
+  const metadata = getRouteMetadata(children)
   return {
     kind: 'resource',
     path: RoutePattern.parse(path),
-    children,
+    children: stripRouteMetadata(children) as unknown as StringKeys<TChildren>,
+    metadata,
   }
 }
 
 /** Declare a GET action, optionally with an action-local path segment. */
 export function get<const P extends string, const T extends RouteSchema>(
   path: P,
-  schema: T
+  schema: RouteDeclaration<T>
 ): HttpAction<P, T, 'GET'>
 export function get<const T extends RouteSchema>(
-  schema: T
+  schema: RouteDeclaration<T>
 ): HttpAction<'', T, 'GET'>
 export function get(
-  pathOrSchema: string | RouteSchema,
-  schema?: RouteSchema
+  pathOrSchema: string | RouteDeclaration<RouteSchema>,
+  schema?: RouteDeclaration<RouteSchema>
 ): any {
   return action('GET', pathOrSchema, schema)
 }
 
 /** Declare a POST action, optionally with an action-local path segment. */
 export function post<const P extends string, const T extends RouteSchema>(
   path: P,
-  schema: T
+  schema: RouteDeclaration<T>
 ): HttpAction<P, T, 'POST'>
 export function post<const T extends RouteSchema>(
-  schema: T
+  schema: RouteDeclaration<T>
 ): HttpAction<'', T, 'POST'>
 export function post(
-  pathOrSchema: string | RouteSchema,
-  schema?: RouteSchema
+  pathOrSchema: string | RouteDeclaration<RouteSchema>,
+  schema?: RouteDeclaration<RouteSchema>
 ): any {
   return action('POST', pathOrSchema, schema)
 }
 
 /** Declare a PUT action, optionally with an action-local path segment. */
 export function put<const P extends string, const T extends RouteSchema>(
   path: P,
-  schema: T
+  schema: RouteDeclaration<T>
 ): HttpAction<P, T, 'PUT'>
 export function put<const T extends RouteSchema>(
-  schema: T
+  schema: RouteDeclaration<T>
 ): HttpAction<'', T, 'PUT'>
 export function put(
-  pathOrSchema: string | RouteSchema,
-  schema?: RouteSchema
+  pathOrSchema: string | RouteDeclaration<RouteSchema>,
+  schema?: RouteDeclaration<RouteSchema>
 ): any {
   return action('PUT', pathOrSchema, schema)
 }
 
 /** Declare a PATCH action, optionally with an action-local path segment. */
 export function patch<const P extends string, const T extends RouteSchema>(
   path: P,
-  schema: T
+  schema: RouteDeclaration<T>
 ): HttpAction<P, T, 'PATCH'>
 export function patch<const T extends RouteSchema>(
-  schema: T
+  schema: RouteDeclaration<T>
 ): HttpAction<'', T, 'PATCH'>
 export function patch(
-  pathOrSchema: string | RouteSchema,
-  schema?: RouteSchema
+  pathOrSchema: string | RouteDeclaration<RouteSchema>,
+  schema?: RouteDeclaration<RouteSchema>
 ): any {
   return action('PATCH', pathOrSchema, schema)
 }
 
 /** Declare a DELETE action, optionally with an action-local path segment. */
 function deleteAction<const P extends string, const T extends RouteSchema>(
   path: P,
-  schema: T
+  schema: RouteDeclaration<T>
 ): HttpAction<P, T, 'DELETE'>
 function deleteAction<const T extends RouteSchema>(
-  schema: T
+  schema: RouteDeclaration<T>
 ): HttpAction<'', T, 'DELETE'>
 function deleteAction(
-  pathOrSchema: string | RouteSchema,
-  schema?: RouteSchema
+  pathOrSchema: string | RouteDeclaration<RouteSchema>,
+  schema?: RouteDeclaration<RouteSchema>
 ): any {
   return action('DELETE', pathOrSchema, schema)
 }
@@ -163,13 +182,20 @@ export function isRawBodySchema(schema: unknown): schema is RawBodySchema {
 
 function action(
   method: HttpMethod,
-  pathOrSchema: string | RouteSchema,
-  schema?: RouteSchema
+  pathOrSchema: string | RouteDeclaration<RouteSchema>,
+  schema?: RouteDeclaration<RouteSchema>
 ) {
   const path =
     typeof pathOrSchema === 'string'
       ? 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,
+  }
 }

src/index.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'

src/metadata.ts

@@ -0,0 +1,30 @@
+const routeMetadataKey: unique symbol = Symbol('rouzer.metadata')
+
+/** 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 function metadata(value: RouteMetadata): RouteMetadataMarker {
+  return { [routeMetadataKey]: value }
+}
+
+export function getRouteMetadata(value: unknown): RouteMetadata | undefined {
+  return typeof value === 'object' && value !== null
+    ? (value as Partial<RouteMetadataMarker>)[routeMetadataKey]
+    : undefined
+}
+
+export function stripRouteMetadata<T extends object>(value: T) {
+  const { [routeMetadataKey]: _metadata, ...rest } = value as T &
+    Partial<RouteMetadataMarker>
+  return rest as Omit<T, typeof routeMetadataKey>
+}

test/error-responses.test-d.ts

@@ -1,12 +1,6 @@
 import { $type, $error, createClient, createRouter } from 'rouzer'
 import * as http from 'rouzer/http'
-
-type Equal<A, B> =
-  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
-    ? true
-    : false
-
-type Assert<T extends true> = T
+import { expectTypeOf, test } from 'vitest'
 
 // --- Route with response map ---
 
@@ -30,47 +24,48 @@ const client = createClient({
   routes,
 })
 
-// Client action returns a discriminated tuple
 type GetUserResult = Awaited<ReturnType<typeof client.getUser>>
 
-type _ClientReturnsDiscriminatedTuple = Assert<
-  Equal<
-    GetUserResult,
+test('response maps produce discriminated client tuples', () => {
+  expectTypeOf<GetUserResult>().toEqualTypeOf<
     | [null, User, 200]
     | [null, User, 201]
     | [AuthError, null, 401]
     | [NotFoundError, null, 404]
-  >
->
+  >()
+})
 
-// Handler can return success value or ctx.error(...)
-createRouter().use(routes, {
-  getUser(ctx) {
-    if (ctx.path.id === 'missing') {
-      return ctx.error(404, { code: 'NOT_FOUND', message: 'not found' })
-    }
-    if (ctx.path.id === 'unauthorized') {
-      return ctx.error(401, { code: 'UNAUTHORIZED', message: 'no auth' })
-    }
-    if (ctx.path.id === 'created') {
-      return ctx.success(201, { id: ctx.path.id, name: 'Ada' })
-    }
-    return { id: ctx.path.id, name: 'Ada' }
-  },
+test('response map handlers can return success values and helpers', () => {
+  createRouter().use(routes, {
+    getUser(ctx) {
+      if (ctx.path.id === 'missing') {
+        return ctx.error(404, { code: 'NOT_FOUND', message: 'not found' })
+      }
+      if (ctx.path.id === 'unauthorized') {
+        return ctx.error(401, { code: 'UNAUTHORIZED', message: 'no auth' })
+      }
+      if (ctx.path.id === 'created') {
+        return ctx.success(201, { id: ctx.path.id, name: 'Ada' })
+      }
+      return { id: ctx.path.id, name: 'Ada' }
+    },
+  })
 })
 
-createRouter().use(routes, {
-  getUser(ctx) {
-    // @ts-expect-error 500 is not a declared error status.
-    ctx.error(500, { code: 'NOT_FOUND', message: 'nope' })
-    // @ts-expect-error Error body must match the selected status.
-    ctx.error(404, { code: 'UNAUTHORIZED', message: 'nope' })
-    // @ts-expect-error 404 is not a declared success status.
-    ctx.success(404, { code: 'NOT_FOUND', message: 'nope' })
-    // @ts-expect-error Success body must match the selected status.
-    ctx.success(201, { id: 123, name: 'Ada' })
-    return { id: ctx.path.id, name: 'Ada' }
-  },
+test('response map helpers reject undeclared statuses and mismatched bodies', () => {
+  createRouter().use(routes, {
+    getUser(ctx) {
+      // @ts-expect-error 500 is not a declared error status.
+      ctx.error(500, { code: 'NOT_FOUND', message: 'nope' })
+      // @ts-expect-error Error body must match the selected status.
+      ctx.error(404, { code: 'UNAUTHORIZED', message: 'nope' })
+      // @ts-expect-error 404 is not a declared success status.
+      ctx.success(404, { code: 'NOT_FOUND', message: 'nope' })
+      // @ts-expect-error Success body must match the selected status.
+      ctx.success(201, { id: 123, name: 'Ada' })
+      return { id: ctx.path.id, name: 'Ada' }
+    },
+  })
 })
 
 // --- Verify existing $type<T>() still works ---
@@ -87,6 +82,6 @@ const simpleClient = createClient({
 
 type SimpleResult = Awaited<ReturnType<typeof simpleClient.simpleRoute>>
 
-type _SimpleRouteStillReturnsPlainType = Assert<
-  Equal<SimpleResult, { message: string }>
->
+test('plain response markers still return plain client values', () => {
+  expectTypeOf<SimpleResult>().toEqualTypeOf<{ message: string }>()
+})