ts-procedures 5.16.0 → 6.0.1

package/build/implementations/http/on-request-error.test.js.map

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

package/build/implementations/http/route-errors.test.d.ts

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

package/build/implementations/http/route-errors.test.js

@@ -0,0 +1,139 @@
+/* eslint-disable @typescript-eslint/no-empty-object-type */
+import { describe, expect, test } from 'vitest';
+import { Type } from 'typebox';
+import { Procedures } from '../../index.js';
+import { HonoAPIAppBuilder } from './hono-api/index.js';
+import { HonoRPCAppBuilder } from './hono-rpc/index.js';
+import { ExpressRPCAppBuilder } from './express-rpc/index.js';
+import { HonoStreamAppBuilder } from './hono-stream/index.js';
+import { DocRegistry } from './doc-registry.js';
+import { defineErrorTaxonomy } from './error-taxonomy.js';
+class UseCaseError extends Error {
+    externalMsg;
+    constructor(externalMsg) {
+        super(externalMsg);
+        this.externalMsg = externalMsg;
+        this.name = 'UseCaseError';
+        Object.setPrototypeOf(this, UseCaseError.prototype);
+    }
+}
+class AuthError extends Error {
+}
+const appErrors = defineErrorTaxonomy({
+    UseCaseError: { class: UseCaseError, statusCode: 422 },
+    AuthError: { class: AuthError, statusCode: 401 },
+});
+describe('per-route errors declaration', () => {
+    test('hono-api copies config.errors onto the route doc', () => {
+        const API = Procedures();
+        API.Create('GetUser', {
+            path: '/users/:id',
+            method: 'get',
+            errors: ['UseCaseError', 'AuthError'],
+            schema: {
+                input: { pathParams: Type.Object({ id: Type.String() }) },
+                returnType: Type.Object({}),
+            },
+        }, async () => ({}));
+        const builder = new HonoAPIAppBuilder().register(API, () => ({}));
+        builder.build();
+        expect(builder.docs[0].errors).toEqual(['UseCaseError', 'AuthError']);
+    });
+    test('hono-api route doc omits errors when not declared', () => {
+        const API = Procedures();
+        API.Create('Health', { path: '/health', method: 'get', schema: { returnType: Type.Object({}) } }, async () => ({}));
+        const builder = new HonoAPIAppBuilder().register(API, () => ({}));
+        builder.build();
+        expect(builder.docs[0].errors).toBeUndefined();
+    });
+    test('hono-rpc copies config.errors onto the route doc', () => {
+        const RPC = Procedures();
+        RPC.Create('DoThing', {
+            scope: 'things',
+            version: 1,
+            errors: ['UseCaseError'],
+            schema: { params: Type.Object({}) },
+        }, async () => ({}));
+        const builder = new HonoRPCAppBuilder().register(RPC, () => ({}));
+        builder.build();
+        expect(builder.docs[0].errors).toEqual(['UseCaseError']);
+    });
+    test('express-rpc copies config.errors onto the route doc', () => {
+        const RPC = Procedures();
+        RPC.Create('DoThing', {
+            scope: 'things',
+            version: 1,
+            errors: ['AuthError'],
+            schema: { params: Type.Object({}) },
+        }, async () => ({}));
+        const builder = new ExpressRPCAppBuilder().register(RPC, () => ({}));
+        builder.build();
+        expect(builder.docs[0].errors).toEqual(['AuthError']);
+    });
+    test('hono-stream copies config.errors onto the route doc', () => {
+        const Stream = Procedures();
+        Stream.CreateStream('Watch', { scope: 'watch', version: 1, errors: ['AuthError'] }, async function* () {
+            yield { ok: true };
+        });
+        const builder = new HonoStreamAppBuilder().register(Stream, () => ({}));
+        builder.build();
+        expect(builder.docs[0].errors).toEqual(['AuthError']);
+    });
+    test('compile-time: errors typed as keyof taxonomy narrows valid keys', () => {
+        const _valid = ['UseCaseError', 'AuthError'];
+        // @ts-expect-error - 'NotRegistered' is not in the taxonomy
+        const _invalid = ['NotRegistered'];
+        expect(_valid).toBeDefined();
+        expect(_invalid).toBeDefined();
+    });
+});
+describe('DocRegistry with taxonomy input', () => {
+    test('seeds envelope errors from the taxonomy + framework defaults', () => {
+        const registry = new DocRegistry({ errors: appErrors, basePath: '/api' });
+        const envelope = registry.toJSON();
+        const names = envelope.errors.map((e) => e.name);
+        expect(names).toContain('UseCaseError');
+        expect(names).toContain('AuthError');
+        expect(names).toContain('ProcedureValidationError');
+        expect(names).toContain('ProcedureRegistrationError');
+        expect(envelope.basePath).toBe('/api');
+    });
+    test('includeDefaults: false omits framework entries', () => {
+        const registry = new DocRegistry({ errors: appErrors, includeDefaults: false });
+        const names = registry.toJSON().errors.map((e) => e.name);
+        expect(names).toEqual(['UseCaseError', 'AuthError']);
+    });
+    test('user entry with same key as default takes precedence (deduped)', () => {
+        const overridden = defineErrorTaxonomy({
+            ProcedureError: {
+                class: Error,
+                statusCode: 418,
+                description: 'custom override',
+            },
+        });
+        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');
+        const count = envelope.errors.filter((e) => e.name === 'ProcedureError').length;
+        expect(count).toBe(1);
+    });
+    test('registered route errors survive DocRegistry composition', () => {
+        const API = Procedures();
+        API.Create('GetUser', {
+            path: '/users/:id',
+            method: 'get',
+            errors: ['UseCaseError'],
+            schema: {
+                input: { pathParams: Type.Object({ id: Type.String() }) },
+                returnType: Type.Object({}),
+            },
+        }, async () => ({}));
+        const app = new HonoAPIAppBuilder().register(API, () => ({}));
+        app.build();
+        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']);
+    });
+});
+//# sourceMappingURL=route-errors.test.js.map

package/build/implementations/http/route-errors.test.js.map

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

package/build/implementations/types.d.ts

@@ -1,7 +1,19 @@
 import { Procedures } from '../index.js';
-export interface RPCConfig {
+import type { ErrorTaxonomy } from './http/error-taxonomy.js';
+/**
+ * @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: 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> = {
     factory: ReturnType<typeof Procedures<C, RPCConfig>>;
@@ -16,10 +28,17 @@ 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';
 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 */
@@ -28,6 +47,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 {
     kind: 'api';
@@ -41,6 +66,8 @@ export interface APIHttpRouteDoc extends APIConfig {
         headers?: Record<string, unknown>;
         response?: Record<string, unknown>;
     };
+    /** Taxonomy keys for errors this route may emit. */
+    errors?: string[];
 }
 /**
  * Constrains schema.input channel names to valid HTTP input sources.
@@ -76,6 +103,8 @@ export interface StreamHttpRouteDoc extends RPCConfig {
         yieldType?: Record<string, unknown>;
         returnType?: Record<string, unknown>;
     };
+    /** Taxonomy keys for errors this route may emit (pre-stream only). */
+    errors?: string[];
 }
 /**
  * Extracts the TContext type from a Procedures factory return type.
@@ -128,7 +157,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> {
     filter?: (route: AnyHttpRouteDoc) => boolean;

package/docs/client-and-codegen.md

@@ -20,14 +20,14 @@ npx ts-procedures-codegen --url http://localhost:3000/docs --out ./src/generated
 
 **Step 3 — Use the client:**
 
+The recommended entrypoint is the generated `create${Service}Client` factory. It calls `createClient` under the hood with the generated error registry pre-wired, so non-2xx responses arrive as typed class instances you can catch with `instanceof`.
+
 ```typescript
-import { createClient, createFetchAdapter } from 'ts-procedures/client'
-import { createApiBindings, Api } from './generated/api'
+import { createApiClient, ApiErrors, createFetchAdapter } from './generated/api'
 
-const client = createClient({
+const api = createApiClient({
   adapter: createFetchAdapter(),
   basePath: 'http://localhost:3000',
-  scopes: createApiBindings,
   hooks: {
     onBeforeRequest(ctx) {
       ctx.request.headers = { ...ctx.request.headers, Authorization: `Bearer ${getToken()}` }
@@ -36,11 +36,32 @@ const client = createClient({
   },
 })
 
-// Fully typed — params and response inferred from server schemas
-const user = await client.users.GetUser({ pathParams: { id: '123' } })
+try {
+  const user = await api.users.GetUser({ pathParams: { id: '123' } })
+} catch (err) {
+  if (err instanceof ApiErrors.UseCaseError) {
+    // err.body, err.status, err.procedureName, err.scope all typed
+  } else if (err instanceof ApiErrors.ApiProcedureError) {
+    // Catch-all for any service error (shared base class)
+  }
+}
 
-// Types live under the service namespace: Api.Users.GetUser.Params, Api.Errors.ProcedureError, etc.
-// Pass --service-name <Name> to rename `Api` → `<Name>` (factory becomes create<Name>Bindings).
+// Types live under the service namespace: Api.Users.GetUser.Params, Api.Errors.UseCaseError, etc.
+// Pass --service-name <Name> to rename `Api` → `<Name>` throughout.
+```
+
+For advanced control (sharing one `ClientInstance` across services, composing with a custom registry), use `createClient` + `create${Service}Bindings` directly:
+
+```typescript
+import { createClient, createFetchAdapter } from 'ts-procedures/client'
+import { createApiBindings, ApiErrors } from './generated/api'
+
+const api = createClient({
+  adapter: createFetchAdapter(),
+  basePath: 'http://localhost:3000',
+  scopes: createApiBindings,
+  errorRegistry: ApiErrors.ApiErrorRegistry,  // opt in to typed dispatch — omit to get the plain ClientRequestError transport shape
+})
 ```
 
 ## Generated File Structure
@@ -54,8 +75,8 @@ generated/
   notifications.ts   # Types + callables for stream procedures
   _types.ts          # Client type definitions (self-contained mode)
   _client.ts         # Client runtime bundle (self-contained mode)
-  _errors.ts         # Typed error classes + ${ServiceName}ProcedureErrorUnion (default: ApiProcedureErrorUnion)
-  index.ts           # Service namespace (`export namespace ${ServiceName}`) + create${ServiceName}Bindings factory (default: Api / createApiBindings)
+  _errors.ts         # Runtime error classes extending ${ServiceName}ProcedureError + static fromResponse + ${ServiceName}ErrorRegistry + ${ServiceName}ProcedureErrorUnion (default: ApiProcedureError / ApiErrorRegistry / ApiProcedureErrorUnion)
+  index.ts           # Service namespace + create${ServiceName}Bindings (manual wiring) and create${ServiceName}Client (convenience; registry pre-wired). Default: Api / createApiBindings / createApiClient.
 ```
 
 ## CLI Reference
@@ -217,6 +238,68 @@ await client.users.GetUser(
 
 If `RequestMeta` declares required fields, the merged meta (defaults + per-call) must contain them at runtime. TypeScript can't statically verify this across the merge boundary, so supply required fields in `defaults.meta` or per-call `options.meta`.
 
+## Typed Error Handling
+
+Non-2xx responses whose body has a `name` field matching a registry key are dispatched into typed class instances. The generated `_errors.ts` exports:
+
+- A shared base class `${ServiceName}ProcedureError<TBody>` — carries `status`, `procedureName`, `scope`, and `body`. Catch any service error with `instanceof ${ServiceName}Errors.${ServiceName}ProcedureError`.
+- One concrete class per taxonomy entry in the envelope, each with a static `fromResponse(body, meta)` factory.
+- `${ServiceName}ErrorRegistry` — a `{ [name]: ErrorClass }` object consumed by the client's `dispatchTypedError`.
+- `${ServiceName}ProcedureErrorUnion` — a type union of every generated class for annotating catch clauses.
+
+```typescript
+import { createApiClient, ApiErrors } from './generated/api'
+
+const api = createApiClient({ adapter, basePath: '...' })
+
+try {
+  await api.users.GetUser({ pathParams: { id: 'x' } })
+} catch (err) {
+  if (err instanceof ApiErrors.UseCaseError) {
+    // err.body is typed to UseCaseErrorBody; err.status, err.procedureName, err.scope available
+  } else if (err instanceof ApiErrors.ApiProcedureError) {
+    // Catch-all for any generated service error
+  } else if (err instanceof ClientRequestError) {
+    // Transport-level error (unmatched body.name, or non-JSON response)
+  }
+}
+```
+
+### Per-route error narrowing
+
+When a server route declares `errors: ['UseCaseError', 'AuthError']` on its config, the generated scope file emits an `Errors` type union inside that route's namespace:
+
+```typescript
+// Generated scope file:
+export namespace Users {
+  export namespace GetUser {
+    export type Params = { /* ... */ }
+    export type Response = { /* ... */ }
+    export type Errors = ApiErrors.UseCaseError | ApiErrors.AuthError
+  }
+}
+
+// Consumer:
+try { await api.users.GetUser({ pathParams: { id: 'x' } }) }
+catch (err) {
+  const e = err as Users.GetUser.Errors | ClientRequestError   // TS has no typed-throws; manual annotation
+  if (e instanceof ApiErrors.UseCaseError) { /* ... */ }
+}
+```
+
+Route-errors that reference keys missing from `_errors.ts` are filtered out at codegen time so generated code never references undefined types.
+
+### How dispatch works
+
+`src/client/error-dispatch.ts` exports a pure `dispatchTypedError(registry, body, meta)` helper. The client's `call.ts` invokes it on non-2xx responses:
+
+1. If no registry, or body isn't an object with a string `name`, or no registry key matches → returns `null`.
+2. Otherwise calls `registry[body.name].fromResponse(body, meta)` and returns the typed `Error` instance.
+
+When the helper returns `null`, the call falls back to `ClientRequestError` — the plain transport-error shape, used for unmatched names, non-JSON bodies, and when no registry is configured.
+
+Stream endpoints get the same treatment for **pre-stream** errors (thrown before the first yield — e.g. validation or auth). The fetch adapter's `stream()` eagerly parses a JSON body when status is non-2xx and exposes it via `AdapterStreamResponse.errorBody`, which `executeStream` passes through the registry. **Mid-stream** SSE error events continue to flow through `onMidStreamError` on the server and re-throw on the client without registry dispatch.
+
 ## Hooks
 
 Hooks let you intercept requests and responses globally or per-procedure call. Global hooks apply to every call made through the client instance; per-procedure hooks run after global ones for a single invocation.
@@ -307,12 +390,22 @@ import { createClient, createFetchAdapter } from './generated/_client'
 import { createClient, createFetchAdapter } from 'ts-procedures/client'
 ```
 
+- **`_client.ts`** also bundles `error-dispatch.ts`, so registry-based typed error dispatch works without importing `ts-procedures/client` at runtime.
+
 ## Type Exports
 
 ```typescript
 // Client Runtime
-import { createClient, createFetchAdapter } from 'ts-procedures/client'
-import type { ClientAdapter, ClientHooks, TypedStream, ClientInstance } from 'ts-procedures/client'
+import { createClient, createFetchAdapter, dispatchTypedError } from 'ts-procedures/client'
+import type {
+  ClientAdapter,
+  ClientHooks,
+  TypedStream,
+  ClientInstance,
+  ErrorRegistry,
+  ErrorFactory,
+  ErrorResponseMeta,
+} from 'ts-procedures/client'
 
 // Code Generation
 import { generateClient } from 'ts-procedures/codegen'

package/docs/core.md

@@ -31,7 +31,7 @@ Create(name, config, handler)
 **Returns:**
 - `{ [name]: handler }` - Named export for the handler
 - `procedure` - Generic reference to the handler
-- `info` - Procedure meta (name, description, schema, `TExtendedConfig` properties, etc.)
+- `info` - Procedure metadata (name, description, schema, `TExtendedConfig` properties, etc.)
 
 ## Structured Input with schema.input
 
@@ -234,7 +234,8 @@ Create(
   async (ctx, params) => {
     const resource = await db.find(params.id)
     if (!resource) {
-      throw ctx.error(404, 'Resource not found', { id: params.id })
+      // Signature: ctx.error(message: string, meta?: object) => ProcedureError
+      throw ctx.error('Resource not found', { code: 'NOT_FOUND', id: params.id })
     }
     return resource
   },
@@ -249,6 +250,7 @@ Create(
 | ProcedureValidationError | Schema validation failure (params) |
 | ProcedureYieldValidationError | Yield validation failure (streaming with `validateYields: true`) |
 | ProcedureRegistrationError | Invalid schema at registration |
+| `${Service}ProcedureError` (client-side) | Base class for every generated error class on the client — see [Client & Codegen → Typed Error Handling](./client-and-codegen.md#typed-error-handling) |
 
 ### Error Properties
 
@@ -264,6 +266,12 @@ try {
 }
 ```
 
+### Error Taxonomy (HTTP builders)
+
+For structured HTTP error responses, declare an error taxonomy once with `defineErrorTaxonomy` and pass it to any HTTP builder via the `errors` option — handlers `throw` their classes and the builder serializes to the configured status + body. `ctx.error()` continues to work as the ad-hoc ProcedureError path.
+
+The taxonomy also drives typed `catch` blocks on generated clients and per-route error documentation. See [HTTP Integrations → Error Handling](./http-integrations.md#error-handling) for the full contract, and [Client & Codegen → Typed Error Handling](./client-and-codegen.md#typed-error-handling) for the client-side surface.
+
 ## Abort Signal
 
 For regular procedures, `ctx.signal` is available when the server implementation provides it. The built-in HTTP integrations (Hono RPC, Express RPC) inject the request's abort signal automatically:
@@ -394,10 +402,11 @@ describe('GetUser', () => {
   })
 
   test('has correct schema', () => {
+    // `info.schema.params` is the JSON Schema derived from the TypeBox
+    // definition above: `Type.Object({ hideName: Type.Optional(Type.Boolean()) })`.
     expect(info.schema.params).toEqual({
       type: 'object',
-      properties: { id: { type: 'string' } },
-      required: ['id'],
+      properties: { hideName: { type: 'boolean' } },
     })
   })
 })
@@ -431,7 +440,7 @@ Defines a procedure.
 **Returns:**
 - `{ [name]: handler }` - Named handler export
 - `procedure` - Generic handler reference
-- `info` - Procedure metareturnType
+- `info` - Procedure metadata (name, description, schema, extended-config properties)
 
 ### Type Exports