ts-procedures 5.4.0 → 5.5.0

package/README.md

@@ -727,6 +727,27 @@ for (const config of procedures) {
 }
 ```
 
+### DocRegistry — Composing Docs from Multiple Builders
+
+Use `DocRegistry` to compose route documentation from any combination of HTTP builders into a typed envelope:
+
+```typescript
+import { DocRegistry } from 'ts-procedures/http-docs'
+
+const docs = new DocRegistry({
+  basePath: '/api',
+  headers: [{ name: 'Authorization', description: 'Bearer token', required: false }],
+  errors: DocRegistry.defaultErrors(),
+})
+  .from(rpcBuilder)
+  .from(apiBuilder)
+  .from(streamBuilder)
+
+app.get('/docs', (c) => c.json(docs.toJSON()))
+```
+
+`from()` stores a reference — routes are read lazily at `toJSON()` time, so builders can be registered before or after `.build()`. Supports optional `filter` and `transform` options for customizing output.
+
 ## Testing
 
 Procedures return handlers that can be called directly in tests:

package/agent_config/claude-code/skills/guide/SKILL.md

@@ -82,6 +82,7 @@ All errors include `definedAt` (file:line:column) and enhanced stack traces poin
 | `ExpressRPCAppBuilder` | `ts-procedures/express-rpc` | POST JSON |
 | `HonoRPCAppBuilder` | `ts-procedures/hono-rpc` | POST JSON |
 | `HonoStreamAppBuilder` | `ts-procedures/hono-stream` | SSE or newline-delimited JSON |
+| `DocRegistry` | `ts-procedures/http-docs` | Compose route docs from multiple builders |
 
 ### Route Path Format
 

package/agent_config/claude-code/skills/guide/anti-patterns.md

@@ -451,7 +451,40 @@ console.log(builder.docs)
 
 ---
 
-## 16. Using Async Context Factory Without Error Handling
+## 16. Manually Wiring a /docs Endpoint Instead of Using DocRegistry
+
+**Problem:** Building the docs JSON envelope by hand in every app — duplicating basePath, headers, errors, and route assembly.
+
+```typescript
+// BAD — repeated boilerplate in every app
+app.get('/docs', (c) => c.json({
+  basePath: '/api',
+  headers: [{ name: 'Authorization', description: 'Bearer token' }],
+  errors: [],
+  routes: [...rpcBuilder.docs, ...apiBuilder.docs, ...streamBuilder.docs],
+}))
+```
+
+**Fix:** Use `DocRegistry` to compose docs from builders.
+
+```typescript
+// GOOD — declarative, composable, typed
+import { DocRegistry } from 'ts-procedures/http-docs'
+
+const docs = new DocRegistry({
+  basePath: '/api',
+  headers: [{ name: 'Authorization', description: 'Bearer token' }],
+  errors: DocRegistry.defaultErrors(),
+}).from(rpcBuilder).from(apiBuilder).from(streamBuilder)
+
+app.get('/docs', (c) => c.json(docs.toJSON()))
+```
+
+**Why:** `DocRegistry` provides a typed `DocEnvelope`, includes `defaultErrors()` with JSON Schemas for all 4 procedure error types, reads docs lazily (order-independent), and supports filtering and transformation via `toJSON()` options.
+
+---
+
+## 17. Using Async Context Factory Without Error Handling
 
 **Problem:** Async context factories that throw unhandled errors, crashing the request.
 
@@ -480,7 +513,7 @@ new ExpressRPCAppBuilder({
 
 ---
 
-## 17. Using Both schema.params and schema.input
+## 18. Using Both schema.params and schema.input
 
 **Problem:** Defining both `schema.params` and `schema.input` on the same procedure.
 
@@ -523,7 +556,7 @@ Create('GetUser', {
 
 ---
 
-## 18. Mismatched Path Param Names in schema.input
+## 19. Mismatched Path Param Names in schema.input
 
 **Problem:** Path template param names don't match `schema.input.pathParams` property names.
 
@@ -559,7 +592,7 @@ Create('GetUser', {
 
 ---
 
-## 19. Forgetting build() is Async on HonoAPIAppBuilder
+## 20. Forgetting build() is Async on HonoAPIAppBuilder
 
 **Problem:** Not awaiting `build()` on `HonoAPIAppBuilder`.
 

package/agent_config/claude-code/skills/guide/api-reference.md

@@ -665,6 +665,92 @@ type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'head'
 
 ---
 
+## DocRegistry
+
+Composes route documentation from any number of HTTP builders into a typed envelope. Eliminates boilerplate `/docs` endpoint wiring.
+
+```typescript
+import { DocRegistry } from 'ts-procedures/http-docs'
+import type { DocEnvelope, DocRegistryConfig, DocRegistryOutputOptions, HeaderDoc, ErrorDoc, DocSource } from 'ts-procedures/http-docs'
+```
+
+```typescript
+class DocRegistry {
+  constructor(config?: {
+    basePath?: string
+    headers?: HeaderDoc[]
+    errors?: ErrorDoc[]
+  })
+
+  from(source: DocSource<AnyHttpRouteDoc>): this
+
+  toJSON<T = DocEnvelope>(options?: {
+    filter?: (route: AnyHttpRouteDoc) => boolean
+    transform?: (envelope: DocEnvelope) => T
+  }): T
+
+  static defaultErrors(): ErrorDoc[]
+}
+```
+
+### DocSource
+
+Any object with a `readonly docs` array. All four HTTP builders (`HonoRPCAppBuilder`, `HonoAPIAppBuilder`, `HonoStreamAppBuilder`, `ExpressRPCAppBuilder`) satisfy this interface.
+
+```typescript
+interface DocSource<T = AnyHttpRouteDoc> {
+  readonly docs: T[]
+}
+```
+
+### HeaderDoc
+
+```typescript
+interface HeaderDoc {
+  name: string
+  description?: string
+  required?: boolean
+  example?: string
+}
+```
+
+### ErrorDoc
+
+```typescript
+interface ErrorDoc {
+  name: string
+  statusCode: number
+  description: string
+  schema?: Record<string, unknown>
+}
+```
+
+### DocEnvelope
+
+```typescript
+interface DocEnvelope {
+  basePath: string
+  headers: HeaderDoc[]
+  errors: ErrorDoc[]
+  routes: AnyHttpRouteDoc[]
+}
+```
+
+### AnyHttpRouteDoc
+
+```typescript
+type AnyHttpRouteDoc = RPCHttpRouteDoc | APIHttpRouteDoc | StreamHttpRouteDoc
+```
+
+### Key Behaviors
+
+- `from()` stores a **reference** to the builder — routes are read lazily at `toJSON()` time, so builders can be registered before or after `.build()`
+- `toJSON()` collects routes via `flatMap(source => source.docs)`, applies optional `filter`, builds envelope, then applies optional `transform`
+- `defaultErrors()` returns 4 `ErrorDoc` entries describing `ProcedureError` (500), `ProcedureValidationError` (400), `ProcedureYieldValidationError` (500), `ProcedureRegistrationError` (500) — each with a JSON Schema for the error response body shape
+- `JSON.stringify(registry)` works directly (calls `toJSON()` implicitly)
+
+---
+
 ## Stack Utilities
 
 ### captureDefinitionInfo()

package/agent_config/claude-code/skills/guide/patterns.md

@@ -640,6 +640,39 @@ const openApiPaths = app.docs.map(doc => ({
 
 ---
 
+## DocRegistry — Composing Docs from Multiple Builders
+
+```typescript
+import { DocRegistry } from 'ts-procedures/http-docs'
+
+// Compose docs from any combination of builders
+const docs = new DocRegistry({
+  basePath: '/api',
+  headers: [{ name: 'Authorization', description: 'Bearer token', required: false }],
+  errors: DocRegistry.defaultErrors(),
+})
+  .from(rpcBuilder)
+  .from(apiBuilder)
+  .from(streamBuilder)
+
+// Serve as a /docs endpoint
+app.get('/docs', (c) => c.json(docs.toJSON()))
+
+// With filtering and transformation
+app.get('/docs', (c) => c.json(docs.toJSON({
+  filter: (route) => route.name !== 'InternalHealthCheck',
+  transform: (envelope) => ({ ...envelope, generatedAt: new Date().toISOString() }),
+})))
+```
+
+**Key points:**
+- `from()` stores a reference — register builders before or after `.build()`
+- `toJSON()` reads docs lazily, so late-registered procedures are included
+- `DocRegistry.defaultErrors()` provides error schemas for all 4 procedure error types
+- Accepts any object satisfying `{ readonly docs: AnyHttpRouteDoc[] }` — not limited to built-in builders
+
+---
+
 ## Testing Procedures
 
 ```typescript

package/agent_config/claude-code/skills/review/checklist.md

@@ -72,6 +72,7 @@
 
 ### SUGGESTION
 - [ ] Route documentation accessed via `builder.docs` for OpenAPI generation
+- [ ] Uses `DocRegistry` to compose docs from multiple builders instead of manual envelope assembly
 - [ ] Lifecycle hooks used for observability (logging, metrics)
 
 ---
@@ -110,6 +111,7 @@
 
 ### SUGGESTION
 - [ ] Route documentation accessed via `builder.docs` for OpenAPI generation
+- [ ] Uses `DocRegistry` to compose docs across builders instead of manual assembly
 - [ ] Custom `queryParser` provided if complex query string formats needed
 - [ ] Lifecycle hooks used for observability (logging, metrics)
 

package/agent_config/claude-code/skills/scaffold/templates/hono-api.md

@@ -113,7 +113,7 @@ export const {{name}}App = await new HonoAPIAppBuilder({
 // POST   /api/{{name}}     → 201
 // DELETE /api/{{name}}/:id → 204
 
-// Documentation: builder.docs (access before .build() resolves)
+// Documentation: builder.docs or compose with DocRegistry from 'ts-procedures/http-docs'
 ```
 
 ## Test — `{{Name}}.api.test.ts`

package/agent_config/copilot/copilot-instructions.md

@@ -38,6 +38,10 @@ import { HonoStreamAppBuilder, sse } from 'ts-procedures/hono-stream'
 // Hono API (REST-style)
 import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
 import type { APIConfig, APIInput } from 'ts-procedures/hono-api'
+
+// Doc Registry — compose route docs from multiple builders
+import { DocRegistry } from 'ts-procedures/http-docs'
+import type { DocEnvelope, HeaderDoc, ErrorDoc } from 'ts-procedures/http-docs'
 ```
 
 ## Architecture Rules

package/agent_config/cursor/cursorrules

@@ -38,6 +38,10 @@ import { HonoStreamAppBuilder, sse } from 'ts-procedures/hono-stream'
 // Hono API (REST-style)
 import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
 import type { APIConfig, APIInput } from 'ts-procedures/hono-api'
+
+// Doc Registry — compose route docs from multiple builders
+import { DocRegistry } from 'ts-procedures/http-docs'
+import type { DocEnvelope, HeaderDoc, ErrorDoc } from 'ts-procedures/http-docs'
 ```
 
 ## Architecture Rules

package/build/implementations/http/doc-registry.d.ts

@@ -0,0 +1,12 @@
+import type { AnyHttpRouteDoc, DocEnvelope, DocRegistryConfig, DocRegistryOutputOptions, DocSource, ErrorDoc } from '../types.js';
+export type { AnyHttpRouteDoc, DocEnvelope, DocRegistryConfig, DocRegistryOutputOptions, DocSource, ErrorDoc, HeaderDoc, } from '../types.js';
+export declare class DocRegistry {
+    private readonly basePath;
+    private readonly headers;
+    private readonly errors;
+    private readonly sources;
+    constructor(config?: DocRegistryConfig);
+    from(source: DocSource<AnyHttpRouteDoc>): this;
+    toJSON<T = DocEnvelope>(options?: DocRegistryOutputOptions<T>): T;
+    static defaultErrors(): ErrorDoc[];
+}

package/build/implementations/http/doc-registry.js

@@ -0,0 +1,114 @@
+export class DocRegistry {
+    basePath;
+    headers;
+    errors;
+    sources = [];
+    constructor(config) {
+        this.basePath = config?.basePath ?? '';
+        this.headers = config?.headers ?? [];
+        this.errors = config?.errors ?? [];
+    }
+    from(source) {
+        this.sources.push(source);
+        return this;
+    }
+    toJSON(options) {
+        let routes = this.sources.flatMap((source) => source.docs);
+        if (options?.filter) {
+            routes = routes.filter(options.filter);
+        }
+        const envelope = {
+            basePath: this.basePath,
+            headers: [...this.headers],
+            errors: [...this.errors],
+            routes,
+        };
+        if (options?.transform) {
+            return options.transform(envelope);
+        }
+        return envelope;
+    }
+    // Keep in sync with src/errors.ts
+    static defaultErrors() {
+        return [
+            {
+                name: 'ProcedureError',
+                statusCode: 500,
+                description: 'An error thrown from within a procedure handler via ctx.error().',
+                schema: {
+                    type: 'object',
+                    properties: {
+                        name: { type: 'string', const: 'ProcedureError' },
+                        procedureName: { type: 'string' },
+                        message: { type: 'string' },
+                        meta: { type: 'object' },
+                    },
+                    required: ['name', 'procedureName', 'message'],
+                },
+            },
+            {
+                name: 'ProcedureValidationError',
+                statusCode: 400,
+                description: 'Schema validation failed for the procedure input parameters.',
+                schema: {
+                    type: 'object',
+                    properties: {
+                        name: { type: 'string', const: 'ProcedureValidationError' },
+                        procedureName: { type: 'string' },
+                        message: { type: 'string' },
+                        errors: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    instancePath: { type: 'string' },
+                                    message: { type: 'string' },
+                                },
+                            },
+                        },
+                    },
+                    required: ['name', 'procedureName', 'message'],
+                },
+            },
+            {
+                name: 'ProcedureYieldValidationError',
+                statusCode: 500,
+                description: 'Schema validation failed for a yielded value in a streaming procedure.',
+                schema: {
+                    type: 'object',
+                    properties: {
+                        name: { type: 'string', const: 'ProcedureYieldValidationError' },
+                        procedureName: { type: 'string' },
+                        message: { type: 'string' },
+                        errors: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    instancePath: { type: 'string' },
+                                    message: { type: 'string' },
+                                },
+                            },
+                        },
+                    },
+                    required: ['name', 'procedureName', 'message'],
+                },
+            },
+            {
+                name: 'ProcedureRegistrationError',
+                statusCode: 500,
+                description: 'An invalid schema or configuration was detected at procedure registration time.',
+                schema: {
+                    type: 'object',
+                    properties: {
+                        name: { type: 'string', const: 'ProcedureRegistrationError' },
+                        procedureName: { type: 'string' },
+                        message: { type: 'string' },
+                    },
+                    required: ['name', 'procedureName', 'message'],
+                },
+            },
+        ];
+    }
+}
+//# sourceMappingURL=doc-registry.js.map

package/build/implementations/http/doc-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-registry.js","sourceRoot":"","sources":["../../../src/implementations/http/doc-registry.ts"],"names":[],"mappings":"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"}

package/build/implementations/http/doc-registry.test.d.ts

@@ -0,0 +1 @@
+export {};