ts-procedures 5.16.0 → 6.0.1

package/src/implementations/types.ts

@@ -1,9 +1,21 @@
 import { Procedures } from '../index.js'
+import type { ErrorTaxonomy } from './http/error-taxonomy.js'
 
-export interface RPCConfig {
+/**
+ * @typeParam TErrorKey - Union of valid taxonomy keys. Defaults to `string`
+ * (unconstrained). Narrow it by passing `keyof typeof yourTaxonomy & string`
+ * to get compile-time typo protection on `errors`.
+ */
+export interface RPCConfig<TErrorKey extends string = string> {
   // Scope or scopes (scope segments) required to access the RPC
   scope: string | string[]
   version: number
+  /**
+   * Taxonomy keys for errors this procedure may emit. Purely informational at
+   * runtime (nothing is rejected), but populates the DocEnvelope per-route
+   * error list so generated clients can narrow their catch types.
+   */
+  errors?: TErrorKey[]
 }
 
 export type FactoryItem<C> = {
@@ -20,6 +32,8 @@ export interface RPCHttpRouteDoc extends RPCConfig {
     body?: Record<string, unknown>
     response?: Record<string, unknown>
   }
+  /** Taxonomy keys for errors this route may emit. */
+  errors?: string[]
 }
 
 export type StreamMode = 'sse' | 'text'
@@ -30,7 +44,12 @@ export type StreamMode = 'sse' | 'text'
 
 export type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'head'
 
-export interface APIConfig {
+/**
+ * @typeParam TErrorKey - Union of valid taxonomy keys. Defaults to `string`.
+ * Narrow it by passing `keyof typeof yourTaxonomy & string` for compile-time
+ * typo protection on `errors`.
+ */
+export interface APIConfig<TErrorKey extends string = string> {
   /** HTTP route path (supports Hono path params, e.g., '/users/:id') */
   path: string
   /** HTTP method for this endpoint */
@@ -39,6 +58,12 @@ export interface APIConfig {
   successStatus?: number
   /** Optional scope for grouping API routes in generated client files */
   scope?: string
+  /**
+   * Taxonomy keys for errors this procedure may emit. Purely informational at
+   * runtime (nothing is rejected), but populates the DocEnvelope per-route
+   * error list so generated clients can narrow their catch types.
+   */
+  errors?: TErrorKey[]
 }
 
 export interface APIHttpRouteDoc extends APIConfig {
@@ -53,6 +78,8 @@ export interface APIHttpRouteDoc extends APIConfig {
     headers?: Record<string, unknown>
     response?: Record<string, unknown>
   }
+  /** Taxonomy keys for errors this route may emit. */
+  errors?: string[]
 }
 
 /**
@@ -90,6 +117,8 @@ export interface StreamHttpRouteDoc extends RPCConfig {
     yieldType?: Record<string, unknown> // Schema for each streamed value
     returnType?: Record<string, unknown> // Final return (optional)
   }
+  /** Taxonomy keys for errors this route may emit (pre-stream only). */
+  errors?: string[]
 }
 
 // ================
@@ -158,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> {