ts-procedures 6.0.0 → 6.0.2

package/src/implementations/http/doc-registry.ts

@@ -8,9 +8,10 @@ import type {
   HeaderDoc,
 } from '../types.js'
 import {
-  ErrorTaxonomy,
+  PROCEDURE_REGISTRATION_ERROR_DOC,
   defaultErrorTaxonomy,
   taxonomyToErrorDocs,
+  type ErrorTaxonomy,
 } from './error-taxonomy.js'
 
 export type {
@@ -23,37 +24,44 @@ export type {
   HeaderDoc,
 } from '../types.js'
 
+function isTaxonomy(input: ErrorTaxonomy | ErrorDoc[]): input is ErrorTaxonomy {
+  return !Array.isArray(input)
+}
+
 /**
- * `ProcedureRegistrationError` is thrown at procedure-definition time (never at
- * request time), so it doesn't appear in the runtime taxonomy. It is documented
- * here so consumers still see it in the error catalog.
+ * Dedupes ErrorDocs by `name`, last occurrence wins. Map insertion order
+ * preserves the latest position of each name.
  */
-const PROCEDURE_REGISTRATION_ERROR_DOC: ErrorDoc = {
-  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'],
-  },
+function dedupeByName(docs: ErrorDoc[]): ErrorDoc[] {
+  const byName = new Map<string, ErrorDoc>()
+  for (const doc of docs) byName.set(doc.name, doc)
+  return Array.from(byName.values())
 }
 
 export class DocRegistry {
   private readonly basePath: string
   private readonly headers: HeaderDoc[]
-  private readonly errors: ErrorDoc[]
+  private errors: ErrorDoc[]
   private readonly sources: DocSource<AnyHttpRouteDoc>[] = []
 
   constructor(config?: DocRegistryConfig) {
     this.basePath = config?.basePath ?? ''
     this.headers = config?.headers ?? []
-    this.errors = config?.errors ?? []
+
+    const includeDefaults = config?.includeDefaults ?? true
+    const userErrors: ErrorDoc[] = config?.errors
+      ? isTaxonomy(config.errors)
+        ? taxonomyToErrorDocs(config.errors)
+        : config.errors
+      : []
+
+    // Precedence: defaults come first, user errors override via dedupe
+    // (last-write-wins). Matches runtime resolution order.
+    const merged = includeDefaults
+      ? [...DocRegistry.defaultErrors(), ...userErrors]
+      : userErrors
+
+    this.errors = dedupeByName(merged)
   }
 
   from(source: DocSource<AnyHttpRouteDoc>): this {
@@ -61,6 +69,18 @@ export class DocRegistry {
     return this
   }
 
+  /**
+   * Adds one or more {@link ErrorDoc} entries to the envelope. Use for errors
+   * outside your runtime taxonomy — middleware-level errors, infrastructure
+   * errors (502/503/504), or doc-only meta errors.
+   *
+   * Deduped by `name` — last write wins.
+   */
+  documentError(...docs: ErrorDoc[]): this {
+    this.errors = dedupeByName([...this.errors, ...docs])
+    return this
+  }
+
   toJSON<T = DocEnvelope>(options?: DocRegistryOutputOptions<T>): T {
     let routes = this.sources.flatMap((source) => source.docs)
 
@@ -83,11 +103,12 @@ export class DocRegistry {
   }
 
   /**
-   * Framework error defaults for the DocEnvelope — derived from
-   * {@link defaultErrorTaxonomy} so the documented shape cannot drift from what
-   * the HTTP builders actually emit at runtime. `ProcedureRegistrationError` is
-   * appended because it's thrown at registration time (never at request time)
-   * and therefore lives only in the catalog, not the runtime taxonomy.
+   * Framework error defaults — derived from {@link defaultErrorTaxonomy} plus
+   * `ProcedureRegistrationError` (which is thrown only at registration time
+   * and therefore lives in the catalog, not the runtime taxonomy).
+   *
+   * Most consumers do not need to call this directly — the `DocRegistry`
+   * constructor auto-includes these unless `includeDefaults: false` is passed.
    */
   static defaultErrors(): ErrorDoc[] {
     return [
@@ -95,32 +116,4 @@ export class DocRegistry {
       PROCEDURE_REGISTRATION_ERROR_DOC,
     ]
   }
-
-  /**
-   * Convenience constructor that seeds `config.errors` from a taxonomy so the
-   * DocEnvelope automatically documents every error class registered with the
-   * HTTP builders. Framework defaults (including `ProcedureRegistrationError`)
-   * are included unless `includeDefaults: false` is passed.
-   *
-   * @example
-   * const registry = DocRegistry.fromTaxonomy(appErrors, { basePath: '/api' })
-   *   .from(apiApp)
-   */
-  static fromTaxonomy(
-    taxonomy: ErrorTaxonomy,
-    config?: Omit<DocRegistryConfig, 'errors'> & { includeDefaults?: boolean }
-  ): DocRegistry {
-    const { includeDefaults = true, ...rest } = config ?? {}
-    const errors: ErrorDoc[] = [
-      ...taxonomyToErrorDocs(taxonomy),
-      ...(includeDefaults ? DocRegistry.defaultErrors() : []),
-    ]
-    // Dedupe by name — user entries take precedence over defaults with the
-    // same key, matching runtime resolution order.
-    const seen = new Set<string>()
-    const deduped = errors.filter((e) =>
-      seen.has(e.name) ? false : (seen.add(e.name), true)
-    )
-    return new DocRegistry({ ...rest, errors: deduped })
-  }
 }

package/src/implementations/http/error-taxonomy.ts

@@ -182,10 +182,34 @@ export const defaultErrorTaxonomy = defineErrorTaxonomy({
   },
 })
 
+/**
+ * Doc-only entry for `ProcedureRegistrationError`, which is thrown at
+ * procedure-definition time (never at request time) and therefore doesn't
+ * appear in the runtime taxonomy. Consumers still see it in the error catalog
+ * via `DocRegistry.defaultErrors()`.
+ */
+export const PROCEDURE_REGISTRATION_ERROR_DOC: ErrorDoc = {
+  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'],
+  },
+}
+
 /**
  * Converts a taxonomy into {@link ErrorDoc} objects suitable for a DocEnvelope.
- * Single source of truth so the runtime mapping and the documented shape
- * cannot drift apart.
+ *
+ * @internal Used by `DocRegistry` to merge taxonomy entries into the envelope.
+ *   Consumers should pass their taxonomy directly to `new DocRegistry({ errors: taxonomy })`
+ *   rather than calling this helper — the constructor handles the conversion.
  */
 export function taxonomyToErrorDocs(taxonomy: ErrorTaxonomy): ErrorDoc[] {
   return Object.entries(taxonomy).map(([key, entry]) => ({

package/src/implementations/http/express-rpc/README.md

@@ -59,7 +59,7 @@ type ExpressRPCAppBuilderConfig = {
   onRequestStart?: (req: express.Request) => void
   onRequestEnd?: (req: express.Request, res: express.Response) => void
   onSuccess?: (procedure: TProcedureRegistration, req: express.Request, res: express.Response) => void
-  error?: (procedure: TProcedureRegistration, req: express.Request, res: express.Response, error: Error) => void
+  onError?: (procedure: TProcedureRegistration, req: express.Request, res: express.Response, error: Error) => void
 }
 ```
 
@@ -70,7 +70,7 @@ type ExpressRPCAppBuilderConfig = {
 | `onRequestStart` | `(req) => void` | Called at start of each request                      |
 | `onRequestEnd` | `(req, res) => void` | Called after response finishes                       |
 | `onSuccess` | `(proc, req, res) => void` | Called on successful handler execution               |
-| `error` | `(proc, req, res, err) => void` | Custom error handler                                 |
+| `onError` | `(proc, req, res, err) => void` | Imperative error handler (peer of `errors` taxonomy — see Error Handling) |
 
 ## Context Resolution
 

package/src/implementations/http/hono-rpc/README.md

@@ -64,7 +64,7 @@ type HonoRPCAppBuilderConfig = {
   onRequestStart?: (c: Context) => void
   onRequestEnd?: (c: Context) => void
   onSuccess?: (procedure: TProcedureRegistration, c: Context) => void
-  error?: (
+  onError?: (
     procedure: TProcedureRegistration,
     c: Context,
     error: Error
@@ -79,7 +79,7 @@ type HonoRPCAppBuilderConfig = {
 | `onRequestStart` | `(c) => void`                | Called at start of each request                   |
 | `onRequestEnd`   | `(c) => void`                | Called after handler completes                    |
 | `onSuccess`      | `(proc, c) => void`          | Called on successful handler execution            |
-| `error`          | `(proc, c, err) => Response` | Custom error handler (must return Response)       |
+| `onError`        | `(proc, c, err) => Response` | Imperative error handler (peer of `errors` taxonomy — see Error Handling) |
 
 ## Context Resolution
 

package/src/implementations/http/hono-stream/README.md

@@ -221,6 +221,21 @@ builder.register(factory, context, {
 })
 ```
 
+## Using an Existing Hono App
+
+Pass an existing `Hono` instance to mount stream routes alongside other routes — including those registered by `HonoRPCAppBuilder` and `HonoAPIAppBuilder`. One Hono server can host all three builders.
+
+```typescript
+const app = new Hono()
+app.use('*', cors())
+
+new HonoStreamAppBuilder({ app })
+  .register(StreamFactory, contextResolver)
+  .build()
+```
+
+For the full single-server pattern (RPC + API + Stream + `DocRegistry` on one app), see [docs/http-integrations.md § One Hono Server, Multiple Builders](../../../../docs/http-integrations.md#one-hono-server-multiple-builders).
+
 ## Lifecycle Hooks
 
 Hooks execute in the following order:

package/src/implementations/http/route-errors.test.ts

@@ -117,9 +117,9 @@ describe('per-route errors declaration', () => {
   })
 })
 
-describe('DocRegistry.fromTaxonomy', () => {
+describe('DocRegistry with taxonomy input', () => {
   test('seeds envelope errors from the taxonomy + framework defaults', () => {
-    const registry = DocRegistry.fromTaxonomy(appErrors, { basePath: '/api' })
+    const registry = new DocRegistry({ errors: appErrors, basePath: '/api' })
     const envelope = registry.toJSON()
     const names = envelope.errors.map((e) => e.name)
     expect(names).toContain('UseCaseError')
@@ -130,7 +130,7 @@ describe('DocRegistry.fromTaxonomy', () => {
   })
 
   test('includeDefaults: false omits framework entries', () => {
-    const registry = DocRegistry.fromTaxonomy(appErrors, { includeDefaults: false })
+    const registry = new DocRegistry({ errors: appErrors, includeDefaults: false })
     const names = registry.toJSON().errors.map((e) => e.name)
     expect(names).toEqual(['UseCaseError', 'AuthError'])
   })
@@ -143,11 +143,10 @@ describe('DocRegistry.fromTaxonomy', () => {
         description: 'custom override',
       },
     })
-    const envelope = DocRegistry.fromTaxonomy(overridden).toJSON()
+    const envelope = new DocRegistry({ errors: overridden }).toJSON()
     const proc = envelope.errors.find((e) => e.name === 'ProcedureError')
     expect(proc?.statusCode).toBe(418)
     expect(proc?.description).toBe('custom override')
-    // no duplicates
     const count = envelope.errors.filter((e) => e.name === 'ProcedureError').length
     expect(count).toBe(1)
   })
@@ -170,7 +169,7 @@ describe('DocRegistry.fromTaxonomy', () => {
     const app = new HonoAPIAppBuilder().register(API, () => ({}))
     app.build()
 
-    const envelope = DocRegistry.fromTaxonomy(appErrors).from(app).toJSON()
+    const envelope = new DocRegistry({ errors: appErrors }).from(app).toJSON()
     const route = envelope.routes.find((r) => r.kind === 'api' && r.name === 'GetUser')
     expect(route?.errors).toEqual(['UseCaseError'])
   })

package/src/implementations/types.ts

@@ -1,4 +1,5 @@
 import { Procedures } from '../index.js'
+import type { ErrorTaxonomy } from './http/error-taxonomy.js'
 
 /**
  * @typeParam TErrorKey - Union of valid taxonomy keys. Defaults to `string`
@@ -186,7 +187,18 @@ export interface ErrorDoc {
 export interface DocRegistryConfig {
   basePath?: string
   headers?: HeaderDoc[]
-  errors?: ErrorDoc[]
+  /**
+   * Errors to document in the envelope. Accepts either your runtime
+   * {@link ErrorTaxonomy} (from `defineErrorTaxonomy`) — the common case — or
+   * a raw `ErrorDoc[]` for consumers who aren't using a taxonomy.
+   *
+   * Framework defaults (`ProcedureError`, `ProcedureValidationError`,
+   * `ProcedureYieldValidationError`, `ProcedureRegistrationError`) are merged
+   * in automatically and deduped. Opt out via `includeDefaults: false`.
+   */
+  errors?: ErrorTaxonomy | ErrorDoc[]
+  /** Whether to auto-merge framework error defaults. Defaults to `true`. */
+  includeDefaults?: boolean
 }
 
 export interface DocRegistryOutputOptions<TEnvelope = DocEnvelope> {