ts-procedures 5.7.0 → 5.7.2

package/README.md

@@ -302,35 +302,6 @@ AJV is configured with:
 
 **Note:** `schema.params` is validated at runtime. `schema.returnType` is for documentation/introspection only.
 
-### Skipping Validation with isPrevalidated
-
-When building framework integrations that validate params before calling procedure handlers, you can pass `isPrevalidated: true` in the context to skip duplicate validation:
-
-```typescript
-// Framework integration example
-app.post('/rpc/:name', async (req, res) => {
-  const procedure = getProcedure(req.params.name)
-
-  // Validate params at the framework level
-  const { errors } = procedure.config.validation?.params?.(req.body)
-  if (errors) {
-    return res.status(400).json({ errors })
-  }
-
-  // Call handler with isPrevalidated to skip redundant validation
-  const result = await procedure.handler(
-    { ...context, isPrevalidated: true },
-    req.body
-  )
-  res.json(result)
-})
-```
-
-This is useful for:
-- Framework integrations (like `HonoStreamAppBuilder`) that validate before starting streams
-- Custom middleware that performs early validation for better error responses
-- Performance optimization when validation has already occurred
-
 ## Streaming Procedures
 
 Streaming procedures use async generators to yield values over time, enabling SSE (Server-Sent Events), HTTP streaming, and real-time data feeds.
@@ -880,6 +851,191 @@ import type { RPCConfig, RPCHttpRouteDoc, StreamHttpRouteDoc, StreamMode, APICon
 // Hono API (REST-style)
 import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
 import type { APIConfig, APIHttpRouteDoc, APIInput, HttpMethod, QueryParser } from 'ts-procedures/hono-api'
+
+// Client Runtime
+import { createClient, createFetchAdapter } from 'ts-procedures/client'
+import type { ClientAdapter, ClientHooks, TypedStream, ClientInstance } from 'ts-procedures/client'
+
+// Code Generation
+import { generateClient } from 'ts-procedures/codegen'
+```
+
+## Client Code Generation
+
+ts-procedures can generate type-safe client SDKs directly from your server's `DocRegistry` output. Generated files include TypeScript types and callable functions for every registered procedure, organized by scope — no manual type duplication required.
+
+### Quick Start
+
+**Step 1 — Serve your docs endpoint:**
+
+```typescript
+app.get('/docs', (c) => c.json(docs.toJSON()))
+```
+
+**Step 2 — Generate the client:**
+
+```bash
+npx ts-procedures-codegen --url http://localhost:3000/docs --out ./src/generated/api
+```
+
+**Step 3 — Use the client:**
+
+```typescript
+import { createClient, createFetchAdapter } from 'ts-procedures/client'
+import { createScopeBindings } from './generated/api'
+
+const client = createClient({
+  adapter: createFetchAdapter(),
+  basePath: 'http://localhost:3000',
+  scopes: createScopeBindings,
+  hooks: {
+    onBeforeRequest(ctx) {
+      ctx.request.headers = { ...ctx.request.headers, Authorization: `Bearer ${getToken()}` }
+      return ctx
+    },
+  },
+})
+
+// Fully typed — params and response inferred from server schemas
+const user = await client.users.GetUser({ pathParams: { id: '123' } })
+```
+
+### Generated File Structure
+
+Running the codegen command produces one file per scope, plus shared error types and a barrel export:
+
+```
+generated/
+  users.ts           # Types + callables for "users" scope
+  billing.ts         # Types + callables for "billing" scope
+  notifications.ts   # Types + callables for stream procedures
+  _errors.ts         # Typed error classes + ProcedureErrorUnion
+  index.ts           # Barrel exports + createScopeBindings
+```
+
+### CLI Reference
+
+| Flag | Description | Required |
+|------|-------------|----------|
+| `--url <url>` | Fetch DocEnvelope from URL | One of `--url` or `--file` |
+| `--file <path>` | Read DocEnvelope from JSON file | One of `--url` or `--file` |
+| `--out <dir>` | Output directory | Yes |
+| `--watch` | Poll for changes and regenerate | No |
+| `--interval <ms>` | Watch poll interval (default: 3000) | No |
+| `--dry-run` | Preview without writing files | No |
+| `--client-import-path <path>` | Override import path (default: `ts-procedures/client`) | No |
+| `--namespace-types` | Wrap types in nested TypeScript namespaces per scope/route | No |
+| `--config <path>` | Path to config file (default: `ts-procedures-codegen.config.json`) | No |
+| `--enum-style <union\|enum>` | TypeScript enum style (requires `--namespace-types`) | No |
+| `--depluralize` | Singularize array item type names (requires `--namespace-types`) | No |
+| `--array-item-naming <value>` | Postfix for array item type names (requires `--namespace-types`) | No |
+| `--uncountable-words <list>` | Comma-separated words to skip singularization (requires `--namespace-types`) | No |
+| `--jsdoc` | Emit JSDoc comments from JSON Schema descriptions (requires `--namespace-types`) | No |
+| `--self-contained` | Emit `_types.ts` and `_client.ts` — no runtime dependency on `ts-procedures` | No |
+
+> **Note:** ajsc formatting options (`--enum-style enum`, `--depluralize`, `--array-item-naming`, `--uncountable-words`, `--jsdoc`) only take effect with `--namespace-types`. In flat mode, all types are inlined and these options have no effect.
+>
+> You can also use a `ts-procedures-codegen.config.json` file in your project root instead of CLI flags. CLI flags override config values.
+
+### Adapter Interface
+
+The client requires an adapter that handles the actual HTTP transport. A built-in fetch adapter is included, and you can implement your own for any HTTP library:
+
+```typescript
+import { createFetchAdapter } from 'ts-procedures/client'
+
+// Use the built-in fetch adapter
+const adapter = createFetchAdapter({ headers: { 'X-API-Key': 'my-key' } })
+
+// Or implement your own (e.g., for axios)
+const axiosAdapter: ClientAdapter = {
+  async request({ url, method, headers, body }) {
+    const res = await axios({ url, method, headers, data: body })
+    return { status: res.status, headers: res.headers, body: res.data }
+  },
+  async stream({ url, method, headers, body }) {
+    // Return AsyncIterable of SSE events
+  },
+}
+```
+
+### 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 override or extend them for a single invocation.
+
+```typescript
+// Global hooks (apply to all calls)
+const client = createClient({
+  adapter,
+  basePath: 'http://localhost:3000',
+  scopes: createScopeBindings,
+  hooks: {
+    onBeforeRequest(ctx) { /* add auth headers */ return ctx },
+    onAfterResponse(ctx) { /* handle errors, logging */ },
+    onError(ctx) { /* error reporting */ },
+  },
+})
+
+// Per-procedure hook override
+await client.users.GetUser({ pathParams: { id: '123' } }, {
+  onAfterResponse(ctx) {
+    const rateLimit = ctx.response.headers['x-rate-limit-remaining']
+  },
+})
+```
+
+### Streaming
+
+Stream procedures return a `TypedStream` — an async iterable for yield values, with a `.result` promise for the final return value:
+
+```typescript
+const stream = client.events.WatchNotifications({ filter: 'all' })
+
+for await (const event of stream) {
+  console.log(event) // typed as WatchNotificationsYield
+}
+
+const result = await stream.result // typed as WatchNotificationsReturn
+```
+
+### Programmatic API
+
+For build pipelines or custom tooling, `generateClient` can be called directly without the CLI:
+
+```typescript
+import { generateClient } from 'ts-procedures/codegen'
+
+await generateClient({
+  url: 'http://localhost:3000/docs',
+  outDir: './src/generated/api',
+  clientImportPath: '@my-app/procedures-client', // optional
+  namespaceTypes: true, // optional — wrap types in nested namespaces
+  selfContained: true, // optional — emit _types.ts + _client.ts (no ts-procedures runtime dep)
+  dryRun: false, // optional
+  ajsc: { // optional — ajsc TypescriptConverter options
+    enumStyle: 'union',
+    depluralize: true,
+    arrayItemNaming: 'Item',
+    uncountableWords: ['criteria'],
+  },
+})
+```
+
+### Self-Contained Mode
+
+With `--self-contained`, the generated output includes two additional files in the output directory:
+
+- **`_types.ts`** — All client type definitions (`ClientInstance`, `TypedStream`, `ProcedureCallOptions`, hooks, adapters, descriptors)
+- **`_client.ts`** — Full client runtime: `createClient`, `createFetchAdapter`, hook pipeline, and error classes (`ClientRequestError`, `ClientPathParamError`, `ClientStreamError`)
+
+All generated scope files and `index.ts` import from `./_types` instead of `ts-procedures/client`, so app consumers can import everything from the generated directory without needing `ts-procedures` as a runtime dependency. `ts-procedures` becomes a devDependency only.
+
+```typescript
+// Without --self-contained (default)
+import { createClient, createFetchAdapter } from 'ts-procedures/client'
+
+// With --self-contained
+import { createClient, createFetchAdapter } from './generated/_client'
 ```
 
 ## AI Agent Setup

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

@@ -47,7 +47,7 @@ Handlers receive `(ctx, params)` where ctx includes:
 | Base context fields | `TContext` | Always |
 | `error(message, meta?)` | `(string, object?) => ProcedureError` | Always |
 | `signal` | `AbortSignal` | **Guaranteed** in CreateStream; optional in Create (present when HTTP impl provides it) |
-| `isPrevalidated` | `boolean` | Set by HTTP impls to skip redundant validation |
+
 
 ## Schema System
 

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

@@ -110,7 +110,7 @@ function Create<TName extends string, TParams, TReturnType>(
     }
   } & TExtendedConfig,
   handler: (
-    ctx: TContext & TLocalContext & { isPrevalidated?: boolean },
+    ctx: TContext & TLocalContext,
     params: TSchemaLib<TParams>
   ) => Promise<TSchemaLib<TReturnType>>
 ): {
@@ -140,7 +140,7 @@ function Create<TName extends string, TParams, TReturnType>(
 | `...TContext` | varies | All base context fields |
 | `error(message, meta?)` | `Function` | Creates `ProcedureError` — throw this for business logic errors |
 | `signal?` | `AbortSignal` | Present when HTTP implementation injects it (Express/Hono do this automatically) |
-| `isPrevalidated?` | `boolean` | `true` when HTTP impl already validated params — skips AJV validation |
+
 
 ### Return Value
 
@@ -198,7 +198,7 @@ function CreateStream<TName extends string, TParams, TYieldType, TReturnType = v
     validateYields?: boolean  // Default: false
   } & TExtendedConfig,
   handler: (
-    ctx: TContext & TStreamContext & { isPrevalidated?: boolean },
+    ctx: TContext & TStreamContext,
     params: TSchemaLib<TParams>
   ) => AsyncGenerator<TSchemaLib<TYieldType>, TSchemaLib<TReturnType> | void, unknown>
 ): {
@@ -751,6 +751,206 @@ type AnyHttpRouteDoc = RPCHttpRouteDoc | APIHttpRouteDoc | StreamHttpRouteDoc
 
 ---
 
+## createClient(config)
+
+Creates a typed client instance bound to generated scope bindings.
+
+```typescript
+function createClient<TScopes>(config: {
+  adapter: ClientAdapter
+  basePath: string
+  scopes: (client: ClientInstance) => TScopes
+  hooks?: ClientHooks
+}): TScopes
+```
+
+### Parameters
+
+- `config.adapter` — Transport adapter implementing `ClientAdapter`. Use `createFetchAdapter()` for fetch-based transport.
+- `config.basePath` — Base URL prepended to all request paths (e.g., `'http://localhost:3000'`).
+- `config.scopes` — Factory function that receives a raw `ClientInstance` and returns the typed scope object. Typically the `createScopeBindings` export from generated code.
+- `config.hooks` — Optional global hooks applied to every call. Can be overridden per call.
+
+### Return Value
+
+Returns the result of `config.scopes(clientInstance)` — a typed object where each key is a scope and each value is a record of callable procedure functions.
+
+### ClientHooks
+
+```typescript
+interface ClientHooks {
+  onBeforeRequest?: (ctx: { request: ClientRequest }) => { request: ClientRequest } | void
+  onAfterResponse?: (ctx: { request: ClientRequest; response: ClientResponse }) => void
+}
+```
+
+### Example
+
+```typescript
+import { createClient, createFetchAdapter } from 'ts-procedures/client'
+import { createScopeBindings } from './generated/api'
+
+const client = createClient({
+  adapter: createFetchAdapter(),
+  basePath: 'http://localhost:3000',
+  scopes: createScopeBindings,
+  hooks: {
+    onBeforeRequest(ctx) {
+      ctx.request.headers = { ...ctx.request.headers, Authorization: `Bearer ${getToken()}` }
+      return ctx
+    },
+  },
+})
+
+const user = await client.users.GetUser({ pathParams: { id: '123' } })
+```
+
+---
+
+## createFetchAdapter()
+
+Creates a `ClientAdapter` using the global `fetch` API.
+
+```typescript
+function createFetchAdapter(options?: {
+  fetch?: typeof globalThis.fetch
+}): ClientAdapter
+```
+
+### Parameters
+
+- `options.fetch` — Optional custom fetch implementation. Defaults to `globalThis.fetch`.
+
+### Return Value
+
+A `ClientAdapter` that supports both request/response and SSE streaming.
+
+### Example
+
+```typescript
+import { createFetchAdapter } from 'ts-procedures/client'
+
+// Default (uses globalThis.fetch)
+const adapter = createFetchAdapter()
+
+// Custom fetch (e.g., node-fetch, undici)
+const adapter = createFetchAdapter({ fetch: customFetch })
+```
+
+---
+
+## generateClient(options)
+
+Build-time CLI and programmatic API for generating typed client files from a `DocEnvelope`.
+
+```typescript
+// CLI usage (preferred)
+// npx ts-procedures-codegen --url <url> --out <dir> [--namespace-types] [--dry-run]
+
+// Programmatic
+async function generateClient(options: {
+  url?: string
+  file?: string
+  envelope?: DocEnvelope
+  outDir: string
+  ajsc?: AjscOptions
+  clientImportPath?: string
+  dryRun?: boolean
+  namespaceTypes?: boolean
+  selfContained?: boolean
+}): Promise<GeneratedFile[]>
+```
+
+### CLI Options
+
+| Flag | Description |
+|------|-------------|
+| `--url <url>` | URL to fetch the `DocEnvelope` JSON from (e.g., `http://localhost:3000/docs`) |
+| `--file <path>` | Read DocEnvelope from a local JSON file |
+| `--out <dir>` | Output directory for generated files |
+| `--watch` | Poll for changes and regenerate |
+| `--interval <ms>` | Watch poll interval (default: 3000) |
+| `--dry-run` | Preview without writing files |
+| `--namespace-types` | Wrap types in nested TS namespaces (`Scope.Route.Params`) |
+| `--config <path>` | Path to config file (default: `ts-procedures-codegen.config.json`) |
+| `--client-import-path <path>` | Override import path (default: `ts-procedures/client`) |
+| `--enum-style <union\|enum>` | TypeScript enum style (requires `--namespace-types`) |
+| `--depluralize` | Singularize array item type names (requires `--namespace-types`) |
+| `--array-item-naming <value>` | Postfix for array item type names (requires `--namespace-types`) |
+| `--uncountable-words <list>` | Comma-separated words to skip singularization (requires `--namespace-types`) |
+| `--jsdoc` | Emit JSDoc comments from schema descriptions (requires `--namespace-types`) |
+| `--self-contained` | Emit `_types.ts` and `_client.ts` in output dir — no runtime dependency on `ts-procedures` |
+
+### Generated Output
+
+- One `.ts` file per scope (e.g., `users.ts`, `events.ts`)
+- A root `index.ts` exporting `createScopeBindings`
+- Each scope file exports fully-typed callable functions and TypeScript types
+- With `--namespace-types`: types are wrapped in `export namespace Scope { export namespace Route { ... } }`
+
+### Example
+
+```typescript
+// CLI
+// npx ts-procedures-codegen --url http://localhost:3000/docs --out ./src/generated/api --namespace-types
+
+// Programmatic
+import { generateClient } from 'ts-procedures/codegen'
+
+await generateClient({
+  url: 'http://localhost:3000/docs',
+  outDir: './src/generated/api',
+  namespaceTypes: true,
+  selfContained: true, // emit _types.ts + _client.ts (no runtime dep)
+  ajsc: { depluralize: true, arrayItemNaming: 'Item' },
+})
+```
+
+---
+
+## TypedStream\<TYield, TReturn\>
+
+Async iterable returned by stream procedure calls on the generated client. Yields typed values and exposes a `result` promise for the stream's final return value.
+
+```typescript
+interface TypedStream<TYield, TReturn> extends AsyncIterable<TYield> {
+  result: Promise<TReturn>
+  [Symbol.asyncIterator](): AsyncIterator<TYield>
+}
+```
+
+### Type Parameters
+
+- `TYield` — Type of each yielded value (from `schema.yieldType`)
+- `TReturn` — Type of the stream's return value (from `schema.returnType`). Sent as `event: 'return'` SSE message by `HonoStreamAppBuilder`.
+
+### Key Behavior
+
+- Iterating with `for await...of` yields each SSE data event as `TYield`
+- `stream.result` resolves when the stream closes with the final return value
+- If the stream has no return value, `TReturn` is `void` and `result` resolves to `undefined`
+
+### Example
+
+```typescript
+import { createClient, createFetchAdapter } from 'ts-procedures/client'
+import { createScopeBindings } from './generated/api'
+
+const client = createClient({ adapter: createFetchAdapter(), basePath: '...', scopes: createScopeBindings })
+
+const stream = client.events.WatchNotifications({ filter: 'all' })
+
+// Consume yielded values
+for await (const event of stream) {
+  console.log(event) // Typed as WatchNotificationsYield
+}
+
+// Access return value after iteration completes
+const summary = await stream.result // Typed as WatchNotificationsReturn
+```
+
+---
+
 ## Stack Utilities
 
 ### captureDefinitionInfo()

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

@@ -758,3 +758,111 @@ onRequestStart → factoryContext() → params validation
                                   → onStreamStart → handler yields → onStreamEnd → onRequestEnd
                                                   → onMidStreamError (if throw) → onStreamEnd → onRequestEnd
 ```
+
+---
+
+## Client Code Generation Setup
+
+```typescript
+import { DocRegistry } from 'ts-procedures/http-docs'
+
+// Server: serve docs endpoint
+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()))
+
+// Then generate client:
+// npx ts-procedures-codegen --url http://localhost:3000/docs --out ./src/generated/api
+// Optional: --namespace-types --self-contained --depluralize --enum-style union
+```
+
+---
+
+## Type-Safe Client Usage
+
+```typescript
+import { createClient, createFetchAdapter } from 'ts-procedures/client'
+import { createScopeBindings } from './generated/api'
+
+const client = createClient({
+  adapter: createFetchAdapter(),
+  basePath: 'http://localhost:3000',
+  scopes: createScopeBindings,
+  hooks: {
+    onBeforeRequest(ctx) {
+      ctx.request.headers = {
+        ...ctx.request.headers,
+        Authorization: `Bearer ${getToken()}`,
+      }
+      return ctx
+    },
+    onAfterResponse(ctx) {
+      if (ctx.response.status === 401) {
+        redirect('/login')
+      }
+    },
+  },
+})
+
+// Fully typed — params and response inferred from server schemas
+const user = await client.users.GetUser({ pathParams: { id: '123' } })
+```
+
+---
+
+## Streaming Client Usage
+
+```typescript
+const stream = client.events.WatchNotifications({ filter: 'all' })
+
+for await (const event of stream) {
+  console.log(event) // Typed as WatchNotificationsYield
+}
+
+// Access the stream's return value
+const result = await stream.result // Typed as WatchNotificationsReturn
+```
+
+---
+
+## Per-Procedure Hook Override
+
+```typescript
+// Override hooks for a specific call
+await client.users.GetUser({ pathParams: { id: '123' } }, {
+  onAfterResponse(ctx) {
+    const rateLimit = ctx.response.headers['x-rate-limit-remaining']
+    console.log(`Rate limit remaining: ${rateLimit}`)
+  },
+})
+```
+
+---
+
+## Custom Client Adapter (Axios)
+
+```typescript
+import type { ClientAdapter } from 'ts-procedures/client'
+import axios from 'axios'
+
+const axiosAdapter: ClientAdapter = {
+  async request({ url, method, headers, body, signal }) {
+    const res = await axios({ url, method, headers, data: body, signal })
+    return {
+      status: res.status,
+      headers: Object.fromEntries(Object.entries(res.headers).filter(([, v]) => typeof v === 'string')) as Record<string, string>,
+      body: res.data,
+    }
+  },
+  async stream() {
+    throw new Error('Streaming not supported with axios adapter')
+  },
+}
+```

package/agent_config/copilot/copilot-instructions.md

@@ -292,3 +292,90 @@ describe('GetUser', () => {
 - `scope` can be string or string[] (joined as path segments)
 - Procedure name auto-converted to kebab-case
 - Stream routes support both GET (query params) and POST (JSON body)
+
+## Client Code Generation
+
+Generate type-safe client SDKs from a running DocRegistry endpoint.
+
+### Imports
+
+```typescript
+// Client Runtime
+import { createClient, createFetchAdapter } from 'ts-procedures/client'
+import type { ClientAdapter, ClientHooks, TypedStream, ClientInstance } from 'ts-procedures/client'
+
+// Code Generation (build-time only)
+import { generateClient } from 'ts-procedures/codegen'
+```
+
+### CLI
+
+```bash
+npx ts-procedures-codegen --url http://localhost:3000/docs --out ./src/generated/api
+# Optional flags: --namespace-types --jsdoc --depluralize --enum-style union
+#                  --array-item-naming Item --uncountable-words criteria,alumni
+#                  --dry-run --watch --client-import-path @my-app/client
+#                  --config ./codegen.config.json --self-contained
+```
+
+Generates one `.ts` file per scope plus a root `index.ts` exporting `createScopeBindings`.
+Use `--namespace-types` to wrap types in nested TS namespaces (`Scope.Route.Params` instead of flat `RouteParams`).
+Note: ajsc formatting options (`--enum-style enum`, `--depluralize`, `--jsdoc`, etc.) only take effect with `--namespace-types`.
+Supports config file: `ts-procedures-codegen.config.json` (auto-loaded from CWD) or `--config <path>`.
+
+### createClient Example
+
+```typescript
+import { createClient, createFetchAdapter } from 'ts-procedures/client'
+import { createScopeBindings } from './generated/api'
+
+const client = createClient({
+  adapter: createFetchAdapter(),
+  basePath: 'http://localhost:3000',
+  scopes: createScopeBindings,
+  hooks: {
+    onBeforeRequest(ctx) {
+      ctx.request.headers = { ...ctx.request.headers, Authorization: `Bearer ${getToken()}` }
+      return ctx
+    },
+    onAfterResponse(ctx) {
+      if (ctx.response.status === 401) redirect('/login')
+    },
+  },
+})
+
+// Fully typed — params and response inferred from server schemas
+const user = await client.users.GetUser({ pathParams: { id: '123' } })
+
+// Per-call hook override
+await client.users.GetUser({ pathParams: { id: '123' } }, {
+  onAfterResponse(ctx) {
+    console.log(ctx.response.headers['x-rate-limit-remaining'])
+  },
+})
+```
+
+### Hook Types
+
+```typescript
+interface ClientHooks {
+  onBeforeRequest?: (ctx: { request: ClientRequest }) => { request: ClientRequest } | void
+  onAfterResponse?: (ctx: { request: ClientRequest; response: ClientResponse }) => void
+}
+```
+
+### TypedStream Usage
+
+```typescript
+const stream = client.events.WatchNotifications({ filter: 'all' })
+
+for await (const event of stream) {
+  console.log(event) // Typed as WatchNotificationsYield
+}
+
+const result = await stream.result // Typed as WatchNotificationsReturn
+```
+
+- `TypedStream<TYield, TReturn>` extends `AsyncIterable<TYield>`
+- `stream.result` resolves with the final return value sent as `event: 'return'` SSE message
+- Stream procedures that return `void` have `result` resolve to `undefined`